Skip to content

Commit 5e4be9c

Browse files
author
DavidQ
committed
BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING
Adds a focused PowerShell scripting lane for switching between Pay-as-you-go and Codex plan modes, inputting/updating API key configuration, validating configured key state, and updates the roadmap with the newly requested scripting and asset-conversion work items.
1 parent 0b81e1f commit 5e4be9c

14 files changed

Lines changed: 613 additions & 50 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 74 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,74 @@
1-
MODEL: GPT-5.4
2-
REASONING: high
3-
COMMAND:
4-
- add caching to asset lookup
5-
- optimize manifest access
6-
- avoid redundant loads
7-
- roadmap status only update
1+
# MODEL
2+
GPT-5.4
3+
4+
# REASONING
5+
high
6+
7+
# COMMAND
8+
Create BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
9+
10+
## Mission
11+
Add a small PowerShell-based repo automation slice that:
12+
- switches between Pay-as-you-go and Codex plan modes
13+
- inputs/updates API key configuration
14+
- validates the configured API key state safely
15+
16+
## Required scope
17+
- add PowerShell scripts for plan switching
18+
- add PowerShell scripts for API key input/update
19+
- add PowerShell scripts for API key validation
20+
- keep the scripts local-repo/operator focused
21+
- document usage and guardrails
22+
- add focused validation or smoke checks where practical
23+
24+
## Preferred implementation style
25+
- PowerShell first
26+
- obvious operator-facing script names
27+
- outputs/helper artifacts routed to the project folder when applicable
28+
- keep scripts lightweight, deterministic, and easy to inspect
29+
30+
## Hard rules
31+
- do not change engine code
32+
- do not add gameplay/runtime features
33+
- do not redesign tools
34+
- do not expand into broad deployment automation in this PR
35+
- do not implement the website prep/update/delete scripts in this PR
36+
- do not implement the game-template asset conversion scripts in this PR
37+
- keep this PR surgical and purpose-specific
38+
39+
## Roadmap instruction
40+
Update roadmap status where this PR clearly advances tracked work.
41+
42+
Also add these new roadmap items as explicitly requested:
43+
1. Existing games asset folders should be updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates.
44+
2. Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools.
45+
3. Add scripts to prep / update / delete the repo so it can be placed on a website.
46+
4. Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it.
47+
48+
These roadmap additions are allowed text additions for this PR.
49+
50+
## Deliverables
51+
Return a single repo-structured ZIP at:
52+
`<project folder>/tmp/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.zip`
53+
54+
Include:
55+
- docs/pr/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.md
56+
- docs/dev/codex_commands.md
57+
- docs/dev/commit_comment.txt
58+
- docs/dev/next_command.txt
59+
- docs/dev/reports/change_summary.txt
60+
- docs/dev/reports/validation_checklist.txt
61+
62+
## Validation
63+
Run focused checks only:
64+
- PowerShell parse/readiness checks on touched scripts
65+
- focused smoke checks for plan switching logic
66+
- focused smoke checks for API key input/update path
67+
- focused smoke checks for API key validation path
68+
69+
## Success definition
70+
- repo has clear scripts for plan switching
71+
- repo has clear scripts for API key input/update
72+
- repo has clear scripts for API key validation
73+
- roadmap includes the requested new items
74+
- final output is one ZIP in `<project folder>/tmp/`

‎docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Codex Plan And API Key Scripting
2+
3+
This repo includes a focused operator scripting surface in `scripts/PS` for:
4+
- switching active Codex billing/plan workflow mode
5+
- setting/updating local API key configuration
6+
- validating API key readiness safely
7+
8+
## Scripts
9+
- `scripts/PS/Switch-CodexPlanMode.ps1`
10+
- `scripts/PS/Set-CodexApiKey.ps1`
11+
- `scripts/PS/Validate-CodexApiKey.ps1`
12+
- `scripts/PS/Get-CodexOperatorState.ps1`
13+
14+
## State File
15+
- Default state file: `.codex/local/codex-operator-state.json`
16+
- Purpose: stores operator metadata only (mode and API key fingerprint)
17+
- Raw API key is not written to disk by these scripts
18+
19+
## Usage
20+
Switch to Pay-as-you-go mode:
21+
22+
```powershell
23+
.\scripts\PS\Switch-CodexPlanMode.ps1 -Mode payg
24+
```
25+
26+
Switch to Codex mode:
27+
28+
```powershell
29+
.\scripts\PS\Switch-CodexPlanMode.ps1 -Mode codex
30+
```
31+
32+
Set or update API key for current process only (safe for smoke checks):
33+
34+
```powershell
35+
.\scripts\PS\Set-CodexApiKey.ps1 -ApiKey "sk-your-key" -Scope Process
36+
```
37+
38+
Set or update API key for current user profile:
39+
40+
```powershell
41+
.\scripts\PS\Set-CodexApiKey.ps1 -Scope User
42+
```
43+
44+
Validate configured key state:
45+
46+
```powershell
47+
.\scripts\PS\Validate-CodexApiKey.ps1 -EnvVarName OPENAI_API_KEY -RequireStateRecord
48+
```
49+
50+
Inspect current mode + metadata:
51+
52+
```powershell
53+
.\scripts\PS\Get-CodexOperatorState.ps1
54+
```
55+
56+
## Guardrails
57+
- Use `-Scope Process` for temporary sessions and script smoke checks.
58+
- Use `-Scope User` only when you intentionally want persistent user configuration.
59+
- Validation checks local readiness and metadata consistency without printing raw secrets.
60+
- Keep the state file local to the repo; do not commit generated secret material.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
BUILD_PR_LEVEL_09_17_ASSET_PERFORMANCE_OPTIMIZATION
1+
BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING
22

3-
Adds runtime asset lookup caching, optimizes manifest/binding access patterns, avoids redundant resolution work in touched layers, and applies a roadmap status-only bracket update.
3+
Adds a focused PowerShell operator automation slice with repo-local plan mode switching, API key input/update, and API key validation scripts (`scripts/PS/*Codex*.ps1`). Includes usage/guardrails documentation and roadmap updates with the four requested scripting/asset-conversion items.

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_LEVEL_09_18_ASSET_BUNDLE_PREPARATION
1+
BUILD_PR_LEVEL_09_19_TEMPLATE_GAME_CREATION_SCRIPTING

‎docs/dev/reports/change_summary.txt‎

Lines changed: 13 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,15 @@
11
Summary
2-
- Added caching to runtime asset lookup resolution to avoid redundant repeated resolution/validation work.
3-
- Optimized manifest and binding access patterns by pre-indexing lookup data and reusing manifest snapshot state.
4-
- Reduced redundant per-call cloning/lookup overhead in touched runtime asset consumers through shared lookup improvements.
2+
- Added focused operator scripts under `scripts/PS`:
3+
- `Switch-CodexPlanMode.ps1`
4+
- `Set-CodexApiKey.ps1`
5+
- `Validate-CodexApiKey.ps1`
6+
- `Get-CodexOperatorState.ps1`
7+
- shared helper: `CodexOperatorState.ps1`
8+
- Added usage + guardrails documentation at `docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md`.
9+
- Implemented repo-local metadata state at `.codex/local/codex-operator-state.json` (generated at runtime), with no raw key persisted to disk by scripts.
10+
- Updated roadmap with the four requested new items and marked the plan/API-key scripting item as completed by this PR.
511

6-
Implementation
7-
- Updated `tools/shared/pipeline/runtimeAssetLookup.js`:
8-
- adds per-asset resolution cache (`hits/misses/size`) to avoid redundant loads/resolution
9-
- adds static source cache to avoid repeated deep clone work per request
10-
- pre-indexes binding records by domain+asset id for faster access
11-
- reuses manifest snapshot for debug state to avoid repeated manifest recomputation
12-
- exposes cache stats via `getDebugState().lookup.cache`
13-
- Updated `tools/shared/pipeline/runtimeAssetBinding.js`:
14-
- adds WeakMap-backed indexed resolution in `resolveRuntimeAsset` for efficient repeated lookup
15-
- Updated `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`:
16-
- validates cache hit/miss behavior and cache size
17-
- validates optimized lookup still preserves existing error/visibility behavior
18-
19-
Roadmap (status-only)
20-
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
21-
- `content pipeline tools after asset complexity justifies them` moved from `[.]` to `[x]`
22-
- No roadmap prose/text/order edits.
12+
Behavior implemented
13+
- Plan mode switching between `payg` and `codex` with explicit persisted state metadata.
14+
- API key input/update for `Process` and `User` scopes via environment variable configuration.
15+
- Safe API key validation (presence + format + metadata fingerprint consistency check) without printing raw secret values.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 30 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,37 @@
1-
Validation Checklist - BUILD_PR_LEVEL_09_17_ASSET_PERFORMANCE_OPTIMIZATION
1+
Validation Checklist - BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING
22

33
Scope
4-
[x] Caching added to shared asset lookup path
5-
[x] Manifest access optimized in touched lookup flow
6-
[x] Redundant resolution/load work avoided where touched
7-
[x] No engine redesign
8-
[x] No UI changes
4+
[x] PR remains in the repo scripting lane only
5+
[x] No engine changes introduced
6+
[x] No gameplay/runtime feature changes introduced
7+
[x] No tool UI redesign introduced
8+
[x] No broad deployment automation introduced in this PR
9+
[x] No asset conversion automation introduced in this PR
910

10-
Code
11-
[x] Updated `tools/shared/pipeline/runtimeAssetLookup.js`
12-
[x] Updated `tools/shared/pipeline/runtimeAssetBinding.js`
13-
[x] Updated `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
11+
Scripts
12+
[x] PowerShell plan-switch script(s) added
13+
[x] Active mode is clear and inspectable
14+
[x] API key input/update script(s) added
15+
[x] API key validation script(s) added
16+
[x] Script usage is documented clearly
17+
[x] Script outputs/errors are actionable
1418

1519
Validation
16-
[x] `node --check tools/shared/pipeline/runtimeAssetLookup.js`
17-
[x] `node --check tools/shared/pipeline/runtimeAssetBinding.js`
18-
[x] `node --check tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
19-
[x] `node --check tests/tools/RuntimeAssetBinding.test.mjs`
20-
[x] `node --check tests/tools/AssetPipelineTooling.test.mjs`
21-
[x] Focused tests pass: RuntimeAssetLookupConsolidation, RuntimeAssetBinding, AssetPipelineTooling
22-
[x] Existing regression tests pass: RuntimeAssetValidation, GameAssetManifestCoordinator, ProjectToolDataContracts
23-
[x] Existing consumer tests pass: AsteroidsAssetReferenceAdoption, AsteroidsPlatformDemo, VectorNativeTemplate, VectorTemplateSampleGame, VectorAssetSystem
20+
[x] Touched PowerShell files parse/read cleanly
21+
[x] Focused plan-switch smoke checks pass
22+
[x] Focused API key input/update smoke checks pass
23+
[x] Focused API key validation smoke checks pass
2424

2525
Roadmap
26-
[x] Status-only update applied
27-
[x] No roadmap prose/text/order changes
26+
[x] Existing roadmap status updated where applicable
27+
[x] Requested new roadmap items added
28+
[x] Added roadmap items are limited to the explicitly requested scripting/asset items
29+
30+
Packaging
31+
[x] docs/pr document included
32+
[x] docs/dev/codex_commands.md included
33+
[x] docs/dev/commit_comment.txt included
34+
[x] docs/dev/next_command.txt included
35+
[x] docs/dev/reports/change_summary.txt included
36+
[x] docs/dev/reports/validation_checklist.txt included
37+
[x] Single ZIP produced at `<project folder>/tmp/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.zip`

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -597,6 +597,12 @@
597597
- [x] Normalize assets/data ownership
598598
- [x] Expand testing/validation structure
599599

600+
### Repo Operator + Asset Conversion Scripting Lanes
601+
- [ ] Existing games asset folders updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates
602+
- [ ] Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools
603+
- [ ] Add scripts to prep / update / delete the repo so it can be placed on a website
604+
- [x] Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it
605+
600606
### Later Capability Lanes
601607
- [ ] FEATURE: Fullscreen Bezel Overlay System - Render game in full screen with optional bezel artwork layer (static or animated) surrounding the active playfield, preserving aspect ratio and supporting per-game/theme bezel assets without modifying core engine rendering.
602608

‎docs/pr/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# BUILD_PR — LEVEL 09_18 — CODEX PLAN SWITCH AND API KEY SCRIPTING
2+
3+
## Objective
4+
Create the next surgical scripting PR for repo operations by introducing scripts that switch between Pay-as-you-go and Codex plan modes, plus scripts that accept an API key, store it appropriately for local repo workflows, and validate it safely.
5+
6+
This PR also updates the roadmap to add the newly requested future scripting and asset-conversion lanes.
7+
8+
## Why This PR Exists
9+
The current asset/tooling lane is far enough along to justify a small repo-automation scripting lane.
10+
11+
The immediate need is operational:
12+
- switch between Pay-as-you-go and Codex plan modes
13+
- provide a repeatable API key input path
14+
- validate the configured API key before use
15+
16+
These scripts should reduce operator friction and make repo setup safer and more repeatable.
17+
18+
## In Scope
19+
- add PowerShell scripts for switching between Pay-as-you-go and Codex plan modes
20+
- add PowerShell script(s) to input/configure API key material for local workflow use
21+
- add PowerShell script(s) to validate the configured API key safely
22+
- document expected local usage, inputs, outputs, and guardrails
23+
- keep scripts local-repo/operator focused
24+
- add focused validation or smoke checks for script behavior where practical
25+
26+
## Out of Scope
27+
- no engine changes
28+
- no gameplay/runtime changes
29+
- no broad deployment automation
30+
- no website publishing automation in this PR
31+
- no game/template asset conversion automation in this PR
32+
- no destructive repo cleanup scripts in this PR unless explicitly required for the selected scripting slice
33+
34+
## Required Script Behavior
35+
### 1. Plan Mode Switching
36+
Provide a clear script surface that can switch the repo workflow between:
37+
- Pay-as-you-go mode
38+
- Codex plan mode
39+
40+
The implementation should make the active mode explicit and easy to inspect.
41+
42+
### 2. API Key Input / Update
43+
Provide a safe local script path to:
44+
- accept or set the API key
45+
- store/configure it in the intended local repo workflow location
46+
- avoid noisy manual editing steps
47+
48+
### 3. API Key Validation
49+
Provide a validation script that:
50+
- checks whether key/config state is present
51+
- validates format/basic readiness
52+
- performs safe validation logic appropriate to the repo workflow
53+
- reports actionable success/failure output
54+
55+
## Preferred Implementation Style
56+
- PowerShell first, to reduce Codex token usage where possible
57+
- scripts placed in a clear repo-local scripts location
58+
- outputs and helper artifacts routed to the project folder in line with repo conventions
59+
- keep script naming obvious and operator-friendly
60+
61+
## Roadmap Update Instruction
62+
This PR must update the roadmap in two ways:
63+
64+
### A. Status updates
65+
Continue updating existing roadmap status where this PR clearly advances tracked work.
66+
67+
### B. New roadmap items to add
68+
Add the following roadmap items as new tracked work. Keep wording tight and consistent with the existing roadmap style.
69+
70+
1. Existing games asset folders should be updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates.
71+
2. Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools.
72+
3. Add scripts to prep / update / delete the repo so it can be placed on a website.
73+
4. Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it.
74+
75+
These roadmap additions are explicitly requested and are allowed text additions for this PR.
76+
77+
## Validation Expectations
78+
At minimum:
79+
- touched PowerShell files parse cleanly
80+
- plan-switch behavior is testable/inspectable
81+
- API key input/update path is documented and deterministic
82+
- API key validation reports clear outcomes
83+
- no unrelated runtime/engine/tool UI work is introduced
84+
85+
## Acceptance Criteria
86+
- repo contains a clear script path for plan switching
87+
- repo contains a clear script path for API key input/update
88+
- repo contains a clear script path for API key validation
89+
- focused checks/documentation are included
90+
- roadmap is updated with the requested new items plus any relevant status updates
91+
- PR remains small and purpose-specific
92+
93+
## Deliverables
94+
Return a repo-structured ZIP at:
95+
`<project folder>/tmp/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.zip`
96+
97+
Include:
98+
- docs/pr/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.md
99+
- docs/dev/codex_commands.md
100+
- docs/dev/commit_comment.txt
101+
- docs/dev/next_command.txt
102+
- docs/dev/reports/change_summary.txt
103+
- docs/dev/reports/validation_checklist.txt

0 commit comments

Comments
 (0)