Skip to content

Architecture cleanup: split CLI entrypoint into command and recipe subsystems #342

@chubes4

Description

@chubes4

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

  1. Extract recipe evidence/finalization.
  2. Extract recipe source preparation.
  3. Extract recipe dry-run and validation helpers.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions