Skip to content

Commit 6ebe6a4

Browse files
ToolboxAidToolboxAid
committed
PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration
1 parent 943a91b commit 6ebe6a4

7 files changed

Lines changed: 224 additions & 76 deletions

File tree

toolbox/game-journey/game-journey.js renamed to assets/toolbox/game-journey/js/index.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ import {
66
GAME_JOURNEY_SUGGESTED_TOOLS,
77
createGameJourneyApiRepository,
88
readGameJourneyCompletionMetrics,
9-
} from "./game-journey-api-client.js";
9+
} from "../../../../toolbox/game-journey/game-journey-api-client.js";
1010
import {
1111
getActiveToolRegistry,
1212
getToolRegistryApiDiagnostic,
13-
} from "../tool-registry-api-client.js";
13+
} from "../../../../toolbox/tool-registry-api-client.js";
1414

1515
const repository = createGameJourneyApiRepository();
1616
const registryDiagnostic = getToolRegistryApiDiagnostic();

‎docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration
2+
3+
## Summary
4+
5+
Status: PASS.
6+
7+
The Game Journey browser entrypoint was moved from the active legacy toolbox path to the canonical tool asset path:
8+
9+
- From: `toolbox/game-journey/game-journey.js`
10+
- To: `assets/toolbox/game-journey/js/index.js`
11+
12+
The Game Journey API client was retained for PR_035 review.
13+
14+
## Files Reviewed
15+
16+
- `docs_build/dev/ProjectInstructions/README.txt`
17+
- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
18+
- `docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md`
19+
- `toolbox/game-journey/index.html`
20+
- `toolbox/game-journey/game-journey.js`
21+
- `toolbox/game-journey/game-journey-api-client.js`
22+
- `tests/playwright/tools/GameJourneyTool.spec.mjs`
23+
- `scripts/validate-canonical-repository-structure.mjs`
24+
25+
## Files Changed
26+
27+
- `assets/toolbox/game-journey/js/index.js`
28+
- `toolbox/game-journey/index.html`
29+
- `scripts/validate-canonical-repository-structure.mjs`
30+
- `tests/playwright/tools/GameJourneyTool.spec.mjs`
31+
- `docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md`
32+
- `docs_build/dev/reports/codex_review.diff`
33+
- `docs_build/dev/reports/codex_changed_files.txt`
34+
35+
## Migration Notes
36+
37+
- Updated the Game Journey page module script to load `assets/toolbox/game-journey/js/index.js`.
38+
- Updated the moved module imports to continue using:
39+
- `toolbox/game-journey/game-journey-api-client.js`
40+
- `toolbox/tool-registry-api-client.js`
41+
- Removed `toolbox/game-journey/game-journey.js` from the approved legacy JS exception list.
42+
- Updated the Game Journey source separation test to read the canonical entrypoint path.
43+
44+
## Retained Exception
45+
46+
- `toolbox/game-journey/game-journey-api-client.js`
47+
- Reason: reviewed separately in PR_035.
48+
- Risk: the canonical guardrail currently approves the tool `index.js` entrypoint path but does not approve additional tool JS files under the same folder.
49+
50+
## Validation Lane Report
51+
52+
- `node --check assets/toolbox/game-journey/js/index.js`
53+
- Result: PASS
54+
- `git diff --check`
55+
- Result: PASS
56+
- `npm run validate:canonical-structure`
57+
- Result: PASS
58+
- Blocking violations: 0
59+
- Approved legacy exceptions: 481
60+
- Active stale reference check for `toolbox/game-journey/game-journey.js`
61+
- Result: PASS
62+
- Only historical `docs_build/pr` references remain.
63+
- Targeted Game Journey Playwright validation:
64+
- Command: `npx playwright test tests/playwright/tools/GameJourneyTool.spec.mjs --grep "Game Journey summary table uses inline notes" --workers=1 --reporter=line --timeout=90000`
65+
- Result: PASS
66+
67+
## Completion Metrics Note
68+
69+
The targeted Playwright route test uses the existing Postgres completion-metrics stub and passed. The known local legacy SQLite preservation failure documented in PR_26172_CHARLIE_006A did not appear in this validation lane.
70+
71+
## Branch Validation
72+
73+
- Current branch: `PR_26172_CHARLIE_repository-compliance-stack`
74+
- Expected branch: `PR_26172_CHARLIE_repository-compliance-stack`
75+
- Local/origin sync before PR: `0 0`
76+
- Branch validation: PASS
77+
78+
## Requirement Checklist
79+
80+
- Use PR_033 audit: PASS
81+
- Move only `game-journey.js` to canonical path: PASS
82+
- Update `toolbox/game-journey/index.html`: PASS
83+
- Update tests/references for old path: PASS
84+
- Preserve behavior: PASS
85+
- Do not move API client unless PR_033 proves safe: PASS, retained.
86+
- No feature changes: PASS
87+
- Run targeted Game Journey validation: PASS
88+
- Run canonical structure guardrail: PASS
89+
- Document known SQLite preservation blocker separately if encountered: PASS, not encountered.
90+
- Confirm ZIP exists: PASS after artifact creation.
91+
92+
## Manual Validation Notes
93+
94+
The entrypoint migration is isolated and validated. The retained API client should be resolved in PR_035 without changing completion-metrics behavior.
95+
96+
## Recommendation
97+
98+
Continue to PR_035 and keep `toolbox/game-journey/game-journey-api-client.js` as an exception unless a safe guardrail-compliant placement is available.

‎docs_build/dev/reports/codex_changed_files.txt‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1-
A docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md
1+
R099 toolbox/game-journey/game-journey.js assets/toolbox/game-journey/js/index.js
2+
A docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md
3+
M scripts/validate-canonical-repository-structure.mjs
4+
M tests/playwright/tools/GameJourneyTool.spec.mjs
5+
M toolbox/game-journey/index.html

‎docs_build/dev/reports/codex_review.diff‎

Lines changed: 117 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,99 @@
1-
diff --git a/docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md b/docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md
1+
diff --git a/toolbox/game-journey/game-journey.js b/assets/toolbox/game-journey/js/index.js
2+
similarity index 99%
3+
rename from toolbox/game-journey/game-journey.js
4+
rename to assets/toolbox/game-journey/js/index.js
5+
index c2b2f876c..0ebc4f2ca 100644
6+
--- a/toolbox/game-journey/game-journey.js
7+
+++ b/assets/toolbox/game-journey/js/index.js
8+
@@ -6,11 +6,11 @@ import {
9+
GAME_JOURNEY_SUGGESTED_TOOLS,
10+
createGameJourneyApiRepository,
11+
readGameJourneyCompletionMetrics,
12+
-} from "./game-journey-api-client.js";
13+
+} from "../../../../toolbox/game-journey/game-journey-api-client.js";
14+
import {
15+
getActiveToolRegistry,
16+
getToolRegistryApiDiagnostic,
17+
-} from "../tool-registry-api-client.js";
18+
+} from "../../../../toolbox/tool-registry-api-client.js";
19+
20+
const repository = createGameJourneyApiRepository();
21+
const registryDiagnostic = getToolRegistryApiDiagnostic();
22+
diff --git a/docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md b/docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md
223
new file mode 100644
3-
index 000000000..5ca46e8ab
24+
index 000000000..c03cd09f5
425
--- /dev/null
5-
+++ b/docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md
6-
@@ -0,0 +1,110 @@
7-
+# PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit
26+
+++ b/docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md
27+
@@ -0,0 +1,98 @@
28+
+# PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration
829
+
930
+## Summary
1031
+
1132
+Status: PASS.
1233
+
13-
+This audit reviewed Game Journey for canonical JS migration readiness without implementation changes.
34+
+The Game Journey browser entrypoint was moved from the active legacy toolbox path to the canonical tool asset path:
35+
+
36+
+- From: `toolbox/game-journey/game-journey.js`
37+
+- To: `assets/toolbox/game-journey/js/index.js`
38+
+
39+
+The Game Journey API client was retained for PR_035 review.
1440
+
1541
+## Files Reviewed
1642
+
1743
+- `docs_build/dev/ProjectInstructions/README.txt`
1844
+- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
19-
+- `docs_build/dev/reports/PR_26172_CHARLIE_006A-game-journey-validation-failure-investigation.md`
45+
+- `docs_build/dev/reports/PR_26172_CHARLIE_033-game-journey-canonical-js-migration-audit.md`
2046
+- `toolbox/game-journey/index.html`
2147
+- `toolbox/game-journey/game-journey.js`
2248
+- `toolbox/game-journey/game-journey-api-client.js`
2349
+- `tests/playwright/tools/GameJourneyTool.spec.mjs`
2450
+- `scripts/validate-canonical-repository-structure.mjs`
25-
+- `src/dev-runtime/server/local-api-router.mjs`
26-
+- `src/api/game-journey-completion-api-client.js`
27-
+
28-
+## Current Active JS Entrypoints
2951
+
30-
+| Current path | Role | Current status | Target path |
31-
+| --- | --- | --- | --- |
32-
+| `toolbox/game-journey/game-journey.js` | Browser entrypoint | Active legacy JS | `assets/toolbox/game-journey/js/index.js` |
33-
+| `toolbox/game-journey/game-journey-api-client.js` | Tool API client and completion metrics re-export | Active legacy JS | Temporary exception unless guardrail/shared-client placement is approved |
34-
+
35-
+## HTML Script References
52+
+## Files Changed
3653
+
54+
+- `assets/toolbox/game-journey/js/index.js`
3755
+- `toolbox/game-journey/index.html`
38-
+ - Current: `toolbox/game-journey/game-journey.js`
39-
+ - Proposed PR_034 value: `assets/toolbox/game-journey/js/index.js`
40-
+
41-
+## API Client References
42-
+
43-
+- `toolbox/game-journey/game-journey.js` imports:
44-
+ - `./game-journey-api-client.js`
45-
+ - `../tool-registry-api-client.js`
46-
+- After moving the entrypoint, imports should become:
47-
+ - `../../../../toolbox/game-journey/game-journey-api-client.js`
48-
+ - `../../../../toolbox/tool-registry-api-client.js`
49-
+
50-
+## Completion Metrics Risk
51-
+
52-
+PR_26172_CHARLIE_006A determined that `/api/game-journey/completion-metrics` can return HTTP 500 when local legacy SQLite preservation protection is triggered by:
53-
+
54-
+- `tmp/local-api/game-journey-completion-metrics.sqlite`
55-
+
56-
+That behavior is intentional and prevents silent data loss. It is not caused by prior Charlie JS/CSS migrations. PR_034 validation must document this separately if it appears and must not misattribute the known HTTP 500 to the entrypoint move without direct evidence.
57-
+
58-
+## Migration Decision
59-
+
60-
+### `game-journey.js`
61-
+
62-
+Decision: safe to migrate in PR_034 with targeted import and HTML updates.
63-
+
64-
+Reason:
65-
+
66-
+- It is a single browser entrypoint.
67-
+- It is referenced directly by the Game Journey page.
68-
+- It can keep existing behavior by importing the retained API client and tool registry client through adjusted relative paths.
69-
+- No CSS move is required.
56+
+- `scripts/validate-canonical-repository-structure.mjs`
57+
+- `tests/playwright/tools/GameJourneyTool.spec.mjs`
58+
+- `docs_build/dev/reports/PR_26172_CHARLIE_034-game-journey-safe-entrypoint-migration.md`
59+
+- `docs_build/dev/reports/codex_review.diff`
60+
+- `docs_build/dev/reports/codex_changed_files.txt`
7061
+
71-
+### `game-journey-api-client.js`
62+
+## Migration Notes
7263
+
73-
+Decision: do not move in PR_034. Review in PR_035.
64+
+- Updated the Game Journey page module script to load `assets/toolbox/game-journey/js/index.js`.
65+
+- Updated the moved module imports to continue using:
66+
+ - `toolbox/game-journey/game-journey-api-client.js`
67+
+ - `toolbox/tool-registry-api-client.js`
68+
+- Removed `toolbox/game-journey/game-journey.js` from the approved legacy JS exception list.
69+
+- Updated the Game Journey source separation test to read the canonical entrypoint path.
7470
+
75-
+Reason:
71+
+## Retained Exception
7672
+
77-
+- The canonical guardrail currently approves the tool entrypoint path `assets/toolbox/{tool}/js/index.js`.
78-
+- Adding a second JS file under `assets/toolbox/game-journey/js/` would require either guardrail expansion or a folded/shared-client migration.
79-
+- The API client re-exports completion metrics helpers, so it should not be moved in the same PR as the entrypoint unless validation proves it is safe.
73+
+- `toolbox/game-journey/game-journey-api-client.js`
74+
+ - Reason: reviewed separately in PR_035.
75+
+ - Risk: the canonical guardrail currently approves the tool `index.js` entrypoint path but does not approve additional tool JS files under the same folder.
8076
+
81-
+## Validation Plan for PR_034
77+
+## Validation Lane Report
8278
+
8379
+- `node --check assets/toolbox/game-journey/js/index.js`
80+
+ - Result: PASS
8481
+- `git diff --check`
82+
+ - Result: PASS
8583
+- `npm run validate:canonical-structure`
84+
+ - Result: PASS
85+
+ - Blocking violations: 0
86+
+ - Approved legacy exceptions: 481
8687
+- Active stale reference check for `toolbox/game-journey/game-journey.js`
87-
+- Targeted Game Journey Playwright validation, with any known completion-metrics legacy SQLite HTTP 500 documented separately.
88+
+ - Result: PASS
89+
+ - Only historical `docs_build/pr` references remain.
90+
+- Targeted Game Journey Playwright validation:
91+
+ - Command: `npx playwright test tests/playwright/tools/GameJourneyTool.spec.mjs --grep "Game Journey summary table uses inline notes" --workers=1 --reporter=line --timeout=90000`
92+
+ - Result: PASS
93+
+
94+
+## Completion Metrics Note
95+
+
96+
+The targeted Playwright route test uses the existing Postgres completion-metrics stub and passed. The known local legacy SQLite preservation failure documented in PR_26172_CHARLIE_006A did not appear in this validation lane.
8897
+
8998
+## Branch Validation
9099
+
@@ -95,22 +104,60 @@ index 000000000..5ca46e8ab
95104
+
96105
+## Requirement Checklist
97106
+
98-
+- Review `game-journey.js`: PASS
99-
+- Review `game-journey-api-client.js`: PASS
100-
+- Review `index.html`: PASS
101-
+- Review Game Journey tests: PASS
102-
+- Review Local API completion metrics route: PASS
103-
+- Review prior PR_006A findings: PASS
104-
+- Determine whether `game-journey.js` can safely move: PASS
105-
+- Determine whether API client should move, remain, or become shared: PASS
106-
+- Define validation that avoids confusing known SQLite preservation behavior with migration failure: PASS
107-
+- No implementation changes: PASS
108-
+- ZIP artifact exists: PASS after artifact creation.
107+
+- Use PR_033 audit: PASS
108+
+- Move only `game-journey.js` to canonical path: PASS
109+
+- Update `toolbox/game-journey/index.html`: PASS
110+
+- Update tests/references for old path: PASS
111+
+- Preserve behavior: PASS
112+
+- Do not move API client unless PR_033 proves safe: PASS, retained.
113+
+- No feature changes: PASS
114+
+- Run targeted Game Journey validation: PASS
115+
+- Run canonical structure guardrail: PASS
116+
+- Document known SQLite preservation blocker separately if encountered: PASS, not encountered.
117+
+- Confirm ZIP exists: PASS after artifact creation.
109118
+
110119
+## Manual Validation Notes
111120
+
112-
+The next safe implementation step is a focused entrypoint move only. The API client should remain an exception until PR_035 because the guardrail does not currently allow a second canonical tool JS file.
121+
+The entrypoint migration is isolated and validated. The retained API client should be resolved in PR_035 without changing completion-metrics behavior.
113122
+
114123
+## Recommendation
115124
+
116-
+Continue to PR_034 and migrate only `game-journey.js` to `assets/toolbox/game-journey/js/index.js`.
125+
+Continue to PR_035 and keep `toolbox/game-journey/game-journey-api-client.js` as an exception unless a safe guardrail-compliant placement is available.
126+
diff --git a/scripts/validate-canonical-repository-structure.mjs b/scripts/validate-canonical-repository-structure.mjs
127+
index 62ef269c2..ef3cfd8db 100644
128+
--- a/scripts/validate-canonical-repository-structure.mjs
129+
+++ b/scripts/validate-canonical-repository-structure.mjs
130+
@@ -12,7 +12,6 @@ export const APPROVED_LEGACY_JS_PATHS = Object.freeze(new Set([
131+
"toolbox/game-hub/game-hub-api-client.js",
132+
"toolbox/game-hub/game-hub.js",
133+
"toolbox/game-journey/game-journey-api-client.js",
134+
- "toolbox/game-journey/game-journey.js",
135+
"toolbox/messages/message-tts-service-registry.js",
136+
"toolbox/messages/messages-api-client.js",
137+
"toolbox/messages/messages.js",
138+
diff --git a/tests/playwright/tools/GameJourneyTool.spec.mjs b/tests/playwright/tools/GameJourneyTool.spec.mjs
139+
index 390d1cc89..4d8f05378 100644
140+
--- a/tests/playwright/tools/GameJourneyTool.spec.mjs
141+
+++ b/tests/playwright/tools/GameJourneyTool.spec.mjs
142+
@@ -1531,7 +1531,7 @@ test("Toolbox registration exposes Game Journey navigation", async ({ page }) =>
143+
test("Game Journey source stays separate from notes files and browser persistence", async () => {
144+
const sourcePaths = [
145+
"toolbox/game-journey/index.html",
146+
- "toolbox/game-journey/game-journey.js",
147+
+ "assets/toolbox/game-journey/js/index.js",
148+
"src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js"
149+
];
150+
const banned = [
151+
diff --git a/toolbox/game-journey/index.html b/toolbox/game-journey/index.html
152+
index aa1a408aa..2965e2b19 100644
153+
--- a/toolbox/game-journey/index.html
154+
+++ b/toolbox/game-journey/index.html
155+
@@ -195,7 +195,7 @@
156+
<div data-partial="footer"></div>
157+
<script src="assets/theme-v2/js/gamefoundry-partials.js"></script>
158+
<script src="assets/theme-v2/js/tool-display-mode.js"></script>
159+
- <script type="module" src="toolbox/game-journey/game-journey.js"></script>
160+
+ <script type="module" src="assets/toolbox/game-journey/js/index.js"></script>
161+
</body>
162+
163+
</html>

‎scripts/validate-canonical-repository-structure.mjs‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ export const APPROVED_LEGACY_JS_PATHS = Object.freeze(new Set([
1212
"toolbox/game-hub/game-hub-api-client.js",
1313
"toolbox/game-hub/game-hub.js",
1414
"toolbox/game-journey/game-journey-api-client.js",
15-
"toolbox/game-journey/game-journey.js",
1615
"toolbox/messages/message-tts-service-registry.js",
1716
"toolbox/messages/messages-api-client.js",
1817
"toolbox/messages/messages.js",

‎tests/playwright/tools/GameJourneyTool.spec.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1531,7 +1531,7 @@ test("Toolbox registration exposes Game Journey navigation", async ({ page }) =>
15311531
test("Game Journey source stays separate from notes files and browser persistence", async () => {
15321532
const sourcePaths = [
15331533
"toolbox/game-journey/index.html",
1534-
"toolbox/game-journey/game-journey.js",
1534+
"assets/toolbox/game-journey/js/index.js",
15351535
"src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js"
15361536
];
15371537
const banned = [

‎toolbox/game-journey/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ <h2>Journey Inspector</h2>
195195
<div data-partial="footer"></div>
196196
<script src="assets/theme-v2/js/gamefoundry-partials.js"></script>
197197
<script src="assets/theme-v2/js/tool-display-mode.js"></script>
198-
<script type="module" src="toolbox/game-journey/game-journey.js"></script>
198+
<script type="module" src="assets/toolbox/game-journey/js/index.js"></script>
199199
</body>
200200

201201
</html>

0 commit comments

Comments
 (0)