Skip to content

Commit 3602131

Browse files
author
DavidQ
committed
PLAN_BUILD_PR_DEV_CONSOLE_COMMAND_PACKS
- Added command pack system - Introduced command registry - Replaced flat command handling
1 parent 5b77e11 commit 3602131

14 files changed

Lines changed: 1321 additions & 39 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,20 @@
1-
Toolbox Aid
2-
David Quesenberry
3-
04/05/2026
4-
codex_commands.md
5-
61
MODEL: GPT-5.4-codex
72
REASONING: high
83

94
COMMAND:
10-
Create BUILD_PR_DEV_CONSOLE_COMMAND_PACKS as a docs-only, repo-structured delta.
5+
Implement command pack system.
6+
7+
- Create registry: tools/dev/devConsoleCommandRegistry.js
8+
- Create command packs under tools/dev/commandPacks/
9+
- Update devConsoleIntegration.js to use registry
10+
- Implement help system
11+
- Use standardized output format
12+
- Do NOT modify engine core
13+
- Keep combo keys unchanged
14+
- Package result to:
15+
<project>/tmp/PLAN_BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip
1116

12-
Requirements:
13-
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
14-
- Docs-first only
15-
- No implementation code in this bundle
16-
- Plan namespaced command packs for the existing dev console
17-
- Define command registry shape, help behavior, output contract, and validation conventions
18-
- Keep implementation future scope limited to tools/dev and optional tests only
19-
- Do not modify engine core
20-
- Keep commit_comment.txt header-free
21-
- Package output to:
22-
<project folder>/tmp/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip
17+
Report:
18+
- files created
19+
- files updated
20+
- commands implemented

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1-
docs: define dev console command-pack contracts, help behavior, and validation conventions
1+
PLAN_BUILD_PR_DEV_CONSOLE_COMMAND_PACKS
2+
3+
- Added command pack system
4+
- Introduced command registry
5+
- Replaced flat command handling

‎docs/dev/NEXT_COMMAND.txt‎

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

‎docs/pr/PLAN_BUILD_PR_DEV_CONSOLE_COMMAND_PACKS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
PLAN_BUILD_PR_DEV_CONSOLE_COMMAND_PACKS.md
5+
6+
# PLAN + BUILD PR
7+
Dev Console Command Packs (Combined)
8+
9+
## Objective
10+
Define AND implement a namespaced command-pack system for the dev console in a single PR cycle to reduce iteration overhead.
11+
12+
---
13+
14+
## What This Will Deliver
15+
- Namespaced commands (scene.*, render.*, entity.*, etc.)
16+
- Central command registry
17+
- Pack-based modular structure
18+
- Improved help system
19+
- Standard output format
20+
- No engine core changes
21+
22+
---
23+
24+
## Implementation (Codex MUST do)
25+
26+
### Create
27+
tools/dev/devConsoleCommandRegistry.js
28+
29+
Responsibilities:
30+
- register command packs
31+
- resolve commands
32+
- expose:
33+
- execute(command, context)
34+
- getHelp(topic)
35+
36+
---
37+
38+
### Create command packs
39+
tools/dev/commandPacks/
40+
41+
- sceneCommandPack.js
42+
- renderCommandPack.js
43+
- entityCommandPack.js
44+
- debugCommandPack.js
45+
- hotReloadCommandPack.js
46+
- validationCommandPack.js
47+
48+
Each pack:
49+
- id
50+
- commands[]
51+
- handler functions
52+
- help metadata
53+
54+
---
55+
56+
### Update
57+
tools/dev/devConsoleIntegration.js
58+
59+
- route all commands through registry
60+
- remove any flat command handling
61+
- keep input system unchanged
62+
63+
---
64+
65+
### Help System
66+
Must support:
67+
- help
68+
- help scene
69+
- help scene.info
70+
71+
---
72+
73+
### Output Contract
74+
Each command returns:
75+
{
76+
status: "ok" | "error",
77+
title: string,
78+
lines: string[]
79+
}
80+
81+
---
82+
83+
## Constraints
84+
- NO engine core changes
85+
- Sample-level only
86+
- No UI rewrite
87+
- Keep combo keys unchanged
88+
- Keep commit_comment.txt header-free
89+
90+
---
91+
92+
## Acceptance Criteria
93+
- Commands grouped and working
94+
- help system functional
95+
- no regression in console
96+
- clean separation of packs
97+
98+
---
99+
100+
## Output
101+
<project>/tmp/PLAN_BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip

‎tools/dev/commandPacks/debugCommandPack.js‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
/*
2+
Toolbox Aid
3+
David Quesenberry
4+
04/05/2026
5+
debugCommandPack.js
6+
*/
7+
8+
import {
9+
requireNoArgs,
10+
safeSection,
11+
standardDetails,
12+
toLinePair
13+
} from "./packUtils.js";
14+
15+
export function createDebugCommandPack() {
16+
return {
17+
packId: "debug",
18+
label: "Debug",
19+
description: "Debug surface controls and state commands.",
20+
commands: [
21+
{
22+
name: "debug.toggle",
23+
summary: "Toggle debug overlay visibility.",
24+
usage: "debug.toggle",
25+
validate({ args, commandName }) {
26+
return requireNoArgs({ args, commandName });
27+
},
28+
handler(context) {
29+
const runtime = context?.consoleRuntime;
30+
if (!runtime || typeof runtime.getState !== "function") {
31+
return {
32+
status: "failed",
33+
title: "Debug Toggle",
34+
lines: ["Console runtime is unavailable."],
35+
code: "MISSING_COMMAND_CONTEXT"
36+
};
37+
}
38+
39+
const state = runtime.getState();
40+
if (state.overlayVisible) {
41+
runtime.hideOverlay();
42+
} else {
43+
runtime.showOverlay();
44+
}
45+
const next = runtime.getState();
46+
return {
47+
title: "Debug Toggle",
48+
lines: [toLinePair("overlayVisible", Boolean(next.overlayVisible))],
49+
details: standardDetails({ state: next }),
50+
code: "DEBUG_TOGGLE"
51+
};
52+
}
53+
},
54+
{
55+
name: "debug.reset",
56+
summary: "Reset interactive console UI buffers.",
57+
usage: "debug.reset",
58+
validate({ args, commandName }) {
59+
return requireNoArgs({ args, commandName });
60+
},
61+
handler(context) {
62+
if (typeof context?.resetConsoleUiState === "function") {
63+
context.resetConsoleUiState();
64+
}
65+
return {
66+
title: "Debug Reset",
67+
lines: ["Console UI buffers reset."],
68+
code: "DEBUG_RESET"
69+
};
70+
}
71+
},
72+
{
73+
name: "debug.state",
74+
summary: "Show debug runtime surface state.",
75+
usage: "debug.state",
76+
validate({ args, commandName }) {
77+
return requireNoArgs({ args, commandName });
78+
},
79+
handler(context) {
80+
const runtime = context?.consoleRuntime;
81+
const state = runtime && typeof runtime.getState === "function"
82+
? runtime.getState()
83+
: {};
84+
const overlay = safeSection(context, "render");
85+
return {
86+
title: "Debug State",
87+
lines: [
88+
toLinePair("consoleVisible", Boolean(state.consoleVisible)),
89+
toLinePair("overlayVisible", Boolean(state.overlayVisible)),
90+
toLinePair("reloadGeneration", state.reloadGeneration ?? 0),
91+
toLinePair("renderStages", Array.isArray(overlay.stages) ? overlay.stages.length : 0)
92+
],
93+
details: standardDetails({ state }),
94+
code: "DEBUG_STATE"
95+
};
96+
}
97+
}
98+
]
99+
};
100+
}

‎tools/dev/commandPacks/entityCommandPack.js‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/*
2+
Toolbox Aid
3+
David Quesenberry
4+
04/05/2026
5+
entityCommandPack.js
6+
*/
7+
8+
import {
9+
requireAtLeastArgs,
10+
requireNoArgs,
11+
safeSection,
12+
standardDetails,
13+
toLinePair
14+
} from "./packUtils.js";
15+
16+
export function createEntityCommandPack() {
17+
return {
18+
packId: "entity",
19+
label: "Entities",
20+
description: "Entity counts and inspection commands.",
21+
commands: [
22+
{
23+
name: "entity.count",
24+
summary: "Show active entity count.",
25+
usage: "entity.count",
26+
validate({ args, commandName }) {
27+
return requireNoArgs({ args, commandName });
28+
},
29+
handler(context) {
30+
const entities = safeSection(context, "entities");
31+
return {
32+
title: "Entity Count",
33+
lines: [
34+
toLinePair("count", entities.count ?? 0),
35+
toLinePair("heroState", entities.heroState ?? "unknown")
36+
],
37+
details: standardDetails({ entities }),
38+
code: "ENTITY_COUNT"
39+
};
40+
}
41+
},
42+
{
43+
name: "entity.list",
44+
summary: "List available entity summary fields.",
45+
usage: "entity.list",
46+
validate({ args, commandName }) {
47+
return requireNoArgs({ args, commandName });
48+
},
49+
handler(context) {
50+
const entities = safeSection(context, "entities");
51+
const keys = Object.keys(entities).sort((left, right) => left.localeCompare(right));
52+
return {
53+
title: "Entity List",
54+
lines: keys.length > 0
55+
? keys.map((key) => `${key}: ${String(entities[key])}`)
56+
: ["No entity summary data available."],
57+
details: standardDetails({ entities }),
58+
code: "ENTITY_LIST"
59+
};
60+
}
61+
},
62+
{
63+
name: "entity.inspect",
64+
summary: "Inspect a specific entity summary field.",
65+
usage: "entity.inspect <field>",
66+
arguments: ["field"],
67+
validate({ args, commandName }) {
68+
return requireAtLeastArgs(1, { args, commandName });
69+
},
70+
handler(context, args) {
71+
const entities = safeSection(context, "entities");
72+
const key = String(args[0] || "");
73+
const value = entities[key];
74+
if (value === undefined) {
75+
return {
76+
status: "failed",
77+
title: "Entity Inspect",
78+
lines: [`Field "${key}" not found.`],
79+
details: standardDetails({ entities, key }),
80+
code: "ENTITY_FIELD_NOT_FOUND"
81+
};
82+
}
83+
return {
84+
title: "Entity Inspect",
85+
lines: [`${key}: ${String(value)}`],
86+
details: standardDetails({ key, value }),
87+
code: "ENTITY_INSPECT"
88+
};
89+
}
90+
}
91+
]
92+
};
93+
}

0 commit comments

Comments
 (0)