Move shared tool behavior under contracts/tools and separate platform contracts - PR_26152_076-tool-contract-location-correction

Author: ToolboxAid

docs/dev/reports/tool_contract_coverage.md

@@ -0,0 +1,97 @@
+# Tool Contract Location Correction Validation
+
+PR: PR_26152_076-tool-contract-location-correction
+Date: 2026-06-02
+
+## Scope
+
+- Updated contract ownership/location structure only.
+- Touched `src/shared/contracts/`, `tests/shared/`, and required reports.
+- No runtime, UI, CSS, HTML, database, or authentication changes were made.
+
+## Location Corrections
+
+- Moved shared tool behavior out of the top-level contracts folder and into `src/shared/contracts/tools/toolContract.js`.
+- Kept top-level `src/shared/contracts/` as platform/object contract ownership:
+  - `assetContract.js`
+  - `identityPermissionsContract.js`
+  - `paletteContract.js`
+  - `projectContract.js`
+  - `replayContracts.js`
+  - `sharedStateContracts.js`
+  - `toolStateContract.js`
+  - `vectorAssetContract.js`
+- Kept shared tool behavior under `src/shared/contracts/tools/toolContract.js`.
+- Kept per-tool declarations under `src/shared/contracts/tools/*Contract.js`.
+- Renamed V2-flavored tool declaration file names to requested tool declaration names while preserving tool IDs:
+  - `assetManagerContract.js`
+  - `audioSfxPlaygroundContract.js`
+  - `collisionInspectorContract.js`
+  - `inputMappingContract.js`
+  - `midiStudioContract.js`
+  - `objectVectorStudioContract.js`
+  - `paletteManagerContract.js`
+  - `previewGeneratorContract.js`
+  - `storageInspectorContract.js`
+  - `textToSpeechContract.js`
+  - `workspaceManagerContract.js`
+  - `worldVectorStudioContract.js`
+- Did not create `src/shared/contracts/tools/paletteContract.js`; the platform Palette object contract remains `src/shared/contracts/paletteContract.js`.
+- Did not create a standalone `vectorStudioContract.js`; registered vector tools are covered by `objectVectorStudioContract.js` and `worldVectorStudioContract.js`.
+
+## Behavior Ownership
+
+- `src/shared/contracts/tools/toolContract.js` owns shared tool behavior:
+  - owner/project/visibility/status/version rules
+  - import/export format rules
+  - produced output rules
+  - supported asset type rules
+  - source tool state rules
+  - archive/permission behavior
+  - portable export behavior
+- Per-tool declaration modules own tool-specific data only:
+  - `toolId`
+  - `toolType`
+  - `grouping`
+  - `requiredInputs`
+  - `producedOutputs`
+  - `supportedAssetTypes`
+  - `importFormats`
+  - `exportFormats`
+  - tool-specific metadata
+
+## Validation
+
+Targeted contract tests:
+
+```powershell
+$rootContractTests = Get-ChildItem -Path tests/shared -Filter '*Contract.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName }
+$toolContractTests = Get-ChildItem -Path tests/shared/tools -Filter '*.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName }
+node ./scripts/run-node-test-files.mjs $rootContractTests $toolContractTests
+```
+
+Result: PASS, `41/41 targeted node test file(s) passed`.
+
+Static checks:
+
+```powershell
+git diff --check -- src/shared/contracts tests/shared docs/dev/reports/tool_contract_coverage.md docs/dev/commit_comment.txt
+git diff --name-only -- '*.css' '*.html'
+# Targeted rg check for stale top-level tool behavior path and renamed V2 module filename patterns, scoped to source, tests, and the current coverage report.
+Get-ChildItem -Path src/shared/contracts -File | Select-Object -ExpandProperty Name | Sort-Object
+```
+
+Results:
+
+- PASS: no whitespace errors from `git diff --check`.
+- PASS: no CSS or HTML files changed.
+- PASS: no stale old tool behavior path or renamed V2 module references remain in source, tests, or the current coverage report.
+- PASS: top-level `src/shared/contracts/` contains platform/object contract files only.
+- PASS: shared tool behavior lives under `src/shared/contracts/tools/toolContract.js`.
+- PASS: every registered visible first-class tool still has matching coverage in `docs/dev/reports/tool_contract_coverage.md`.
+
+## Skipped
+
+- Repo-wide tests were not run.
+- Samples tests were not run.
+- Runtime, UI, CSS, and HTML validation were not run because they are outside this PR scope.

docs/dev/reports/tool_contract_location_correction_validation.md

@@ -9,11 +9,12 @@ import {
   TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
   createDraftToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const AI_ASSISTANT_TOOL_CONTRACT = createDraftToolContract({
   toolId: "ai-assistant",
   toolType: TOOL_CONTRACT_TYPES.UTILITY,
+  grouping: "AI",
   requiredInputs: [TOOL_CONTRACT_FORMATS.TEXT],
   producedOutputs: [TOOL_CONTRACT_FORMATS.TEXT],
   supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.NONE,

src/shared/contracts/tools/aiAssistantContract.js

@@ -11,11 +11,12 @@ import {
   TOOL_CONTRACT_FORMATS,
   TOOL_CONTRACT_TYPES,
   createDraftToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const ANIMATION_STUDIO_TOOL_CONTRACT = createDraftToolContract({
   toolId: "animation-studio",
   toolType: TOOL_CONTRACT_TYPES.STUDIO,
+  grouping: "Animation",
   requiredInputs: [TOOL_CONTRACT_FORMATS.IMAGE_FILE],
   producedOutputs: [TOOL_CONTRACT_FORMATS.ANIMATION_JSON],
   supportedAssetTypes: [ASSET_TYPES.IMAGE],

src/shared/contracts/tools/animationStudioContract.js

@@ -2,18 +2,19 @@
 Toolbox Aid
 David Quesenberry
 06/02/2026
-assetManagerV2Contract.js
+assetManagerContract.js
 */
 import {
   TOOL_CONTRACT_FORMATS,
   TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
   createToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const ASSET_MANAGER_V2_TOOL_CONTRACT = createToolContract({
   toolId: "asset-manager-v2",
   toolType: TOOL_CONTRACT_TYPES.MANAGER,
+  grouping: "Assets",
   requiredInputs: [TOOL_CONTRACT_FORMATS.PALETTE_JSON, TOOL_CONTRACT_FORMATS.METADATA_JSON],
   producedOutputs: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
   supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL,

…ontracts/tools/assetManagerV2Contract.js …/contracts/tools/assetManagerContract.jssrc/shared/contracts/tools/assetManagerV2Contract.js renamed to src/shared/contracts/tools/assetManagerContract.js src/shared/contracts/tools/assetManagerV2Contract.js renamed to src/shared/contracts/tools/assetManagerContract.js

@@ -9,11 +9,12 @@ import {
   TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
   createToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const ASSET_PIPELINE_TOOL_CONTRACT = createToolContract({
   toolId: "asset-pipeline",
   toolType: TOOL_CONTRACT_TYPES.PIPELINE,
+  grouping: "Pipeline",
   requiredInputs: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.ASSET],
   producedOutputs: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
   supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL,

src/shared/contracts/tools/assetPipelineContract.js

@@ -11,11 +11,12 @@ import {
   TOOL_CONTRACT_FORMATS,
   TOOL_CONTRACT_TYPES,
   createDraftToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const ASSET_STUDIO_TOOL_CONTRACT = createDraftToolContract({
   toolId: "asset-studio",
   toolType: TOOL_CONTRACT_TYPES.STUDIO,
+  grouping: "Assets",
   requiredInputs: [TOOL_CONTRACT_FORMATS.PALETTE_JSON],
   producedOutputs: [TOOL_CONTRACT_FORMATS.IMAGE_FILE, TOOL_CONTRACT_FORMATS.VECTOR_JSON, TOOL_CONTRACT_FORMATS.PALETTE_JSON],
   supportedAssetTypes: [ASSET_TYPES.IMAGE, ASSET_TYPES.VECTOR, ASSET_TYPES.PALETTE],

src/shared/contracts/tools/assetStudioContract.js

@@ -2,7 +2,7 @@
 Toolbox Aid
 David Quesenberry
 06/02/2026
-audioSfxPlaygroundV2Contract.js
+audioSfxPlaygroundContract.js
 */
 import {
   ASSET_TYPES,
@@ -11,11 +11,12 @@ import {
   TOOL_CONTRACT_FORMATS,
   TOOL_CONTRACT_TYPES,
   createToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const AUDIO_SFX_PLAYGROUND_V2_TOOL_CONTRACT = createToolContract({
   toolId: "audio-sfx-playground-v2",
   toolType: TOOL_CONTRACT_TYPES.STUDIO,
+  grouping: "Audio",
   requiredInputs: [],
   producedOutputs: [TOOL_CONTRACT_FORMATS.AUDIO_FILE],
   supportedAssetTypes: [ASSET_TYPES.AUDIO],

…ts/tools/audioSfxPlaygroundV2Contract.js …acts/tools/audioSfxPlaygroundContract.jssrc/shared/contracts/tools/audioSfxPlaygroundV2Contract.js renamed to src/shared/contracts/tools/audioSfxPlaygroundContract.js src/shared/contracts/tools/audioSfxPlaygroundV2Contract.js renamed to src/shared/contracts/tools/audioSfxPlaygroundContract.js

@@ -9,11 +9,12 @@ import {
   TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
   createDraftToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const CODE_STUDIO_TOOL_CONTRACT = createDraftToolContract({
   toolId: "code-studio",
   toolType: TOOL_CONTRACT_TYPES.EDITOR,
+  grouping: "Code",
   requiredInputs: [TOOL_CONTRACT_FORMATS.CODE_FILE],
   producedOutputs: [TOOL_CONTRACT_FORMATS.CODE_FILE],
   supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.NONE,

src/shared/contracts/tools/codeStudioContract.js

@@ -2,7 +2,7 @@
 Toolbox Aid
 David Quesenberry
 06/02/2026
-collisionInspectorV2Contract.js
+collisionInspectorContract.js
 */
 import {
   ASSET_TYPES,
@@ -11,11 +11,12 @@ import {
   TOOL_CONTRACT_FORMATS,
   TOOL_CONTRACT_TYPES,
   createToolContract,
-} from "../toolContract.js";
+} from "./toolContract.js";
 
 export const COLLISION_INSPECTOR_V2_TOOL_CONTRACT = createToolContract({
   toolId: "collision-inspector-v2",
   toolType: TOOL_CONTRACT_TYPES.INSPECTOR,
+  grouping: "Debug",
   requiredInputs: [TOOL_CONTRACT_FORMATS.VECTOR_JSON, TOOL_CONTRACT_FORMATS.IMAGE_FILE],
   producedOutputs: [TOOL_CONTRACT_FORMATS.COLLISION_REPORT],
   supportedAssetTypes: [ASSET_TYPES.VECTOR, ASSET_TYPES.IMAGE],