Skip to content

Define one typed command catalog for CLI and desk surface parity #100

Description

@clintecker

Problem

The public command surface is split between USAGE, a large conditional router, artifact-format derivation, documentation generation, and the proposed desk palette. Adding a TUI by copying that surface would violate the repository law that facts are stated once.

Direction

Introduce a typed command catalog that is authoritative for command identity and discoverability while leaving command execution in the existing CLI application boundary. The CLI usage text, generated reference, desk target picker, and command palette must project from the catalog. Argument-bearing families such as publish, art, and operator commands must have explicit schemas rather than prose parsing.

This should align with the typed-boundary work in #82: #82.

Invariants

  • No public target name is duplicated as a desk string literal.
  • Every cataloged command is routed, documented, and classifies whether it reads or mutates book state.
  • Hidden/internal actions cannot become palette entries accidentally.
  • Existing command syntax and exit behavior remain compatible in v1.
  • Catalog ordering is deterministic and contains no clock-derived data.

Acceptance

  • A typed command descriptor and catalog exist behind both CLI help and desk discovery.
  • Self-tests fail for unrouted, undocumented, duplicated, or unclassified commands.
  • Property tests cover catalog uniqueness, stable ordering, and route/help/palette parity.
  • docs/REFERENCE.md generation consumes the catalog.
  • The issue includes migration notes for the existing conditional router without requiring an all-at-once rewrite.

Links

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:build-graphArtifact registry, build dependencies, and target orchestrationarea:dxContributor tooling, tests, maintainability, and development workflowarea:tuiTerminal UI, operator desk, and interactive run controlarea:uxUser-facing command behavior and diagnosticsenhancementNew feature or requestpriority:P1High: required for a trustworthy supported workflowtest-layer:L1Pure unit and property-based proofs

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions