Problem
packages/cli/src/index.ts is currently over 5,000 lines and mixes unrelated responsibilities:
- executable entrypoint and top-level command routing
- CLI option parsing
- runtime boot/run command wrappers
- recipe validation, dry-run planning, and execution
- recipe source preparation, downloads, extraction, scaffolding, staged files
- recipe artifact/evidence finalization
- agent sandbox helpers
- JSON/human output shaping
That makes WP Codebox feel like a black box even when the behavior works. New reviewers have to understand the entire CLI file before they can safely change one subsystem.
Target Shape
Move toward a CLI package that is navigable by responsibility:
index.ts: thin bin entrypoint only
cli-router.ts: top-level command dispatch and JSON/human output wrappers
run-command.ts / boot-command.ts: direct runtime command handlers
recipe-runner.ts: recipe execution lifecycle
recipe-dry-run.ts: dry-run planning
recipe-validation.ts: validation command logic
recipe-policy.ts: recipe policy and command capability resolution
recipe-sources.ts: downloads, extraction, scaffold generation, staged file prep
recipe-evidence.ts: attestation, artifact verification, workspace policy, transcript/agent result evidence
agent-sandbox.ts: agent-runtime-probe and sandbox run/batch helpers
option-parsing.ts: reusable CLI option parsing helpers
Acceptance Criteria
packages/cli/src/index.ts becomes a small executable shim or top-level dispatcher.
- Each extracted module has one obvious reason to change.
- Public CLI behavior is preserved.
- PRs are reviewable by subsystem, not one giant file move.
npm run build passes.
- Relevant non-Playground smoke checks pass where applicable.
Suggested PR Slices
- Extract recipe evidence/finalization.
- Extract recipe source preparation.
- Extract recipe dry-run and validation helpers.
- Extract command routing and option parsing once large recipe chunks are gone.
Notes
This issue is part of the architecture cleanup campaign to make Codebox readable and pitchable as a product architecture, not just a working runtime blob.
Problem
packages/cli/src/index.tsis currently over 5,000 lines and mixes unrelated responsibilities:That makes WP Codebox feel like a black box even when the behavior works. New reviewers have to understand the entire CLI file before they can safely change one subsystem.
Target Shape
Move toward a CLI package that is navigable by responsibility:
index.ts: thin bin entrypoint onlycli-router.ts: top-level command dispatch and JSON/human output wrappersrun-command.ts/boot-command.ts: direct runtime command handlersrecipe-runner.ts: recipe execution lifecyclerecipe-dry-run.ts: dry-run planningrecipe-validation.ts: validation command logicrecipe-policy.ts: recipe policy and command capability resolutionrecipe-sources.ts: downloads, extraction, scaffold generation, staged file preprecipe-evidence.ts: attestation, artifact verification, workspace policy, transcript/agent result evidenceagent-sandbox.ts: agent-runtime-probe and sandbox run/batch helpersoption-parsing.ts: reusable CLI option parsing helpersAcceptance Criteria
packages/cli/src/index.tsbecomes a small executable shim or top-level dispatcher.npm run buildpasses.Suggested PR Slices
Notes
This issue is part of the architecture cleanup campaign to make Codebox readable and pitchable as a product architecture, not just a working runtime blob.