Skip to content

Commit 8af9355

Browse files
author
DavidQ
committed
BUILD_PR: auto-generate samples index from canonical sample folders
- define minimal, testable BUILD for generated samples index - preserve readable UI labels while using canonical paths - require representative runtime validation - enforce Windows-safe execution and exact ZIP output path No gameplay or engine-core scope included
1 parent c015ad5 commit 8af9355

466 files changed

Lines changed: 142868 additions & 15 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 77 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,83 @@
1+
# Codex command for BUILD_PR_SAMPLES_INDEX_AUTOGENERATION
2+
13
MODEL: GPT-5.4-codex
24
REASONING: high
35

46
COMMAND:
5-
Execute BUILD_PR_SAMPLES_DIRECTORY_NORMALIZATION
7+
Execute BUILD_PR_SAMPLES_INDEX_AUTOGENERATION exactly as written.
8+
9+
EXECUTION ENVIRONMENT (MANDATORY):
10+
- Target platform: Windows
11+
- Prefer Node.js for path discovery, generation, and validation
12+
- Python is allowed if Node.js is not the best fit
13+
- DO NOT use PowerShell for:
14+
- path construction
15+
- directory scanning
16+
- bulk file moves
17+
- ZIP path generation
18+
19+
POWERSHELL PROHIBITION (CRITICAL):
20+
The following patterns are NOT allowed:
21+
- "$var/path"
22+
- "${var}/path"
23+
- "$base\$child"
24+
- "$($var)/path"
25+
26+
If any of these appear:
27+
- STOP
28+
- report the violation
29+
- do not silently retry
30+
31+
PR PURPOSE:
32+
Auto-generate the samples index from canonical sample folders in a testable way.
33+
34+
EXPECTED TARGETS:
35+
- `samples/index.html`
36+
- exact generator/helper files required for sample index generation
37+
- minimal supporting config/data files only if required
38+
- reporting docs under `docs/`
39+
40+
DO NOT:
41+
- modify gameplay code
42+
- modify engine core
43+
- perform unrelated cleanup
44+
- broaden scope beyond sample index generation
45+
- modify `docs/dev/start_of_day/chatGPT/`
46+
- modify `docs/dev/start_of_day/codex/`
47+
48+
REQUIRED IMPLEMENTATION SHAPE:
49+
1. Discover canonical sample folders under `samples/phaseXX/XXYY/`
50+
2. Build or update the minimal generation path needed for `samples/index.html`
51+
3. Preserve human-readable labels in UI
52+
4. Fail fast on:
53+
- malformed sample paths
54+
- duplicate sample numbers
55+
- missing sample entry points
56+
- ambiguous phase/sample metadata
57+
5. Keep changed-file count minimal
58+
59+
VALIDATION (REQUIRED):
60+
- load `samples/index.html`
61+
- verify generated tiles render
62+
- open representative sample links:
63+
- first sample in a populated phase
64+
- last sample in a populated phase
65+
- Phase 13 samples 1316, 1317, 1318
66+
- confirm console is clean for tested pages
67+
- report exact files changed
68+
- report exact validation performed
669

7-
OUTPUT REQUIREMENT:
8-
- Produce ZIP at:
9-
<project folder>/tmp/BUILD_PR_SAMPLES_DIRECTORY_NORMALIZATION.zip
70+
ZIP OUTPUT REQUIREMENT (HARD RULE):
71+
- MUST produce ZIP:
72+
<project folder>/tmp/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.zip
73+
- ZIP must contain only repo-relevant delta output for this PR
74+
- Do not stage ZIP files from `<project folder>/tmp/`
75+
- Task is NOT complete until the ZIP exists at the exact requested path
1076

11-
FAIL IF ZIP NOT PRODUCED
77+
FAIL FAST:
78+
- vague BUILD doc
79+
- conflicting target files
80+
- generator path would require broad repo analysis
81+
- malformed canonical sample directories
82+
- PowerShell parse issue before execution
83+
- missing ZIP output at exact path

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
BUILD_PR: normalize sample directories to phasexx/xxyy structure
1+
BUILD_PR: auto-generate samples index from canonical sample folders
2+
3+
- define minimal, testable BUILD for generated samples index
4+
- preserve readable UI labels while using canonical paths
5+
- require representative runtime validation
6+
- enforce Windows-safe execution and exact ZIP output path
7+
8+
No gameplay or engine-core scope included

‎docs/dev/reports/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION_validation.txt‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
BUILD_PR_SAMPLES_INDEX_AUTOGENERATION VALIDATION REPORT
2+
3+
Build output summary:
4+
- Generator added: scripts/generate-samples-index.mjs
5+
- samples/index.html now contains an auto-generated section block bounded by markers
6+
- Generator source of truth: canonical folders under samples/phaseXX/XXYY/index.html
7+
8+
Fail-fast checks enforced by generator:
9+
- malformed phase folders (phaseXX format)
10+
- malformed sample folders (XXYY format)
11+
- sample/phase number mismatch
12+
- duplicate sample numbers
13+
- missing sample entrypoints
14+
- missing phase/sample metadata labels in index source
15+
16+
Validation executed:
17+
1) node scripts/generate-samples-index.mjs
18+
- result: OK phases=15 samples=197 mode=write
19+
2) node scripts/generate-samples-index.mjs --check
20+
- result: OK phases=15 samples=197 mode=check
21+
3) Link/coverage check against generated index:
22+
- index markers present: true
23+
- live links counted: 197
24+
- representative links found:
25+
- first sample in populated phase: 0101 -> ./phase01/0101/index.html
26+
- last sample in populated phase: 1506 -> ./phase15/1506/index.html
27+
- phase13: 1316, 1317, 1318 -> present
28+
4) Browser smoke/console validation (headless chromium via Playwright):
29+
- loaded pages:
30+
- /samples/index.html
31+
- /samples/phase01/0101/index.html
32+
- /samples/phase15/1506/index.html
33+
- /samples/phase13/1316/index.html
34+
- /samples/phase13/1317/index.html
35+
- /samples/phase13/1318/index.html
36+
- result: BROWSER_VALIDATION_PASS pages=6
37+
- console/pageerror events: none
38+
39+
Scope check:
40+
- gameplay code untouched
41+
- engine core untouched
42+
- scope limited to sample index generation path

‎docs/dev/reports/change_summary.txt‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,9 @@
1-
TYPE: STRUCTURE ONLY
2-
Normalize samples directories and paths
1+
PR TYPE: BUILD
2+
PURPOSE: testable samples index autogeneration
3+
4+
SUMMARY:
5+
- introduces a docs-first BUILD bundle for replacing manual samples index maintenance
6+
- requires generation from canonical `samples/phaseXX/XXYY/` structure
7+
- requires runtime-visible validation of generated tiles and links
8+
- preserves readable labels in UI
9+
- keeps scope narrow and Windows-safe

‎docs/dev/reports/file_tree_delta.txt‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,16 @@
1-
All samples directories will be renamed to phasexx/xxyy
1+
EXPECTED DELTA (implementation-dependent, keep minimal)
2+
3+
MODIFIED:
4+
- samples/index.html
5+
- minimal generator/helper files directly used by sample index generation
6+
7+
ADDED (only if required):
8+
- minimal generation utility or data file supporting samples index generation
9+
10+
REPORT ONLY:
11+
- docs/pr/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.md
12+
- docs/dev/codex_commands.md
13+
- docs/dev/commit_comment.txt
14+
- docs/dev/reports/change_summary.txt
15+
- docs/dev/reports/validation_checklist.txt
16+
- docs/dev/reports/file_tree_delta.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
[ ] All samples map to /samples/phasexx/xxyy/index.html
2-
[ ] No spaces in directories
3-
[ ] Links updated
4-
[ ] No broken paths
1+
[ ] samples/index.html uses generated or generation-backed sample tile data
2+
[ ] generated tiles render correctly
3+
[ ] first sample in a populated phase opens successfully
4+
[ ] last sample in a populated phase opens successfully
5+
[ ] Phase 13 samples 1316, 1317, 1318 open successfully
6+
[ ] console clean for tested pages
7+
[ ] no gameplay changes
8+
[ ] no engine-core changes
9+
[ ] changed-file count stayed minimal
10+
[ ] ZIP exists at <project folder>/tmp/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.zip

‎docs/pr/BUILD_PR_SAMPLES_INDEX_AUTOGENERATION.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# BUILD_PR_SAMPLES_INDEX_AUTOGENERATION
2+
3+
## Objective
4+
Create a testable, minimal-scope BUILD PR that replaces manual `samples/index.html` maintenance with generated sample tiles derived from the normalized samples directory structure.
5+
6+
Canonical structure assumed:
7+
- `samples/phaseXX/XXYY/index.html`
8+
9+
This BUILD must produce a testable result:
10+
- `samples/index.html` remains usable
11+
- generated output is visible at runtime
12+
- sample tiles resolve correctly
13+
- representative phases/samples can be smoke-tested
14+
15+
## PR Purpose
16+
One purpose only:
17+
- auto-generate the samples index from canonical sample folders
18+
19+
## In Scope
20+
- implement a generator or build-time/update-time utility that derives sample tile/link data from `samples/phaseXX/XXYY/`
21+
- update `samples/index.html` integration so generated data is actually used
22+
- preserve human-readable labels in UI
23+
- keep existing sample behavior unchanged
24+
- include only exact target files and immediate dependencies
25+
- provide a testable result
26+
27+
## Out of Scope
28+
- no gameplay changes
29+
- no engine-core changes
30+
- no tool rewrites
31+
- no broad sample content rewrites
32+
- no repo-wide cleanup
33+
- no APPLY instructions
34+
35+
## Required Behavior
36+
Generated index behavior must:
37+
1. discover phases from `samples/phaseXX/`
38+
2. discover samples from `samples/phaseXX/XXYY/`
39+
3. link each tile to `samples/phaseXX/XXYY/index.html`
40+
4. preserve readable phase/sample text in the UI
41+
5. fail fast on malformed sample paths or duplicate sample numbers
42+
6. remain testable in the repo’s normal workflow
43+
44+
## Testability Gate
45+
This BUILD is valid only if the result can be meaningfully validated.
46+
47+
Minimum validation:
48+
- open `samples/index.html`
49+
- verify generated tiles render
50+
- verify representative links load:
51+
- first sample in a populated phase
52+
- last sample in a populated phase
53+
- Phase 13 samples including 1316–1318
54+
- verify no stale manual-only references remain in the active generation path
55+
- verify console is clean for tested pages
56+
57+
## Target Files (expected)
58+
Codex must keep file reads narrow and stop if the actual required targets differ materially.
59+
60+
Expected targets:
61+
- `samples/index.html`
62+
- generator/helper file(s) directly used for sample index generation
63+
- minimal supporting data/config file(s), if needed
64+
- BUILD doc support files under `docs/` for reporting only
65+
66+
If the implementation would require broader repo analysis or unrelated targets, STOP and report.
67+
68+
## Windows Execution Constraint
69+
Target platform is Windows.
70+
71+
For discovery, path normalization, and file generation:
72+
- prefer Node.js
73+
- Python allowed if clearly safer
74+
- do not use PowerShell for path-building, rename-heavy work, or ZIP path generation
75+
76+
## Acceptance Criteria
77+
- sample index is generated from canonical sample folders
78+
- runtime result is testable
79+
- `samples/index.html` stays usable and readable
80+
- links resolve to canonical normalized sample paths
81+
- Phase 13 samples 1316–1318 are reachable
82+
- no gameplay behavior changes
83+
- changed-file count stays minimal
84+
- repo-structured delta ZIP is produced under `<project folder>/tmp/`
85+
86+
## Validation Checklist Summary
87+
- generated index renders
88+
- representative tiles open correct sample pages
89+
- malformed paths fail fast instead of silently corrupting output
90+
- exact ZIP exists at requested path

‎node_modules/.bin/playwright‎

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎node_modules/.bin/playwright-core‎

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎node_modules/.bin/playwright-core.cmd‎

Lines changed: 17 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)