Skip to content

Finish descriptor-derived command exposure lists #1136

Description

@thymikee

Context

The capabilities command was small but touched many public-surface files. The design review afterwards converged on a narrower conclusion: this is not a new CommandManifest problem yet. ADR 0008 is already partially implemented through src/core/command-descriptor/registry.ts; the next step is to finish the remaining live drift between command descriptors and hand-maintained command exposure lists.

Current drift:

  • CommandDescriptor.mcpExposed exists, but src/core/command-descriptor/registry.ts still computes it from listMcpExposedCommandNames() in src/command-catalog.ts.
  • src/command-catalog.ts still owns MCP_UNEXPOSED_CLI_COMMANDS.
  • src/command-catalog.ts still owns CAPABILITY_EXEMPT_CLI_COMMANDS.
  • listCapabilityCheckedCommandNames() should be derivable from descriptor capability entries, but is still maintained as an inverse hand list.

This keeps two live sources for the same command facts and is exactly the kind of drift ADR 0008 is meant to remove.

Scope

Finish the next descriptor-registry strangler step without introducing a new manifest layer and without changing daemon/platform behavior.

Acceptance Criteria

  • CommandDescriptor/descriptor registry is the live source for MCP exposure.
  • listMcpExposedCommandNames() no longer depends on a hand-maintained MCP_UNEXPOSED_CLI_COMMANDS set.
  • listCapabilityCheckedCommandNames() derives from descriptor capability entries instead of CAPABILITY_EXEMPT_CLI_COMMANDS.
  • The exported public command constants and command-name types remain stable for existing callers.
  • Descriptor/catalog projection tests pin MCP exposure and capability-check lists so future commands cannot drift silently.
  • Existing command descriptor parity/timeout/batch tests remain meaningful and non-tautological where possible.
  • ADR/design docs are updated only where needed to describe this completed step; do not duplicate CLI manuals or narrative docs.
  • No daemon handler behavior, platform backend behavior, client normalizers, or narrative docs are generated in this PR.

Out of Scope

  • Capability profile inversion (semantic-read, semantic-interaction, etc.) for many-platform scaling. That is a separate migration and should be parity-tested against the current command x device capability matrix before deleting the family/kind buckets.
  • Full defineCommand / CommandManifest rewrite. This issue should finish the live drift already identified by ADR 0008.
  • Public/client API behavior changes.

Validation

At minimum:

  • pnpm exec vitest run src/core/command-descriptor/__tests__ src/utils/__tests__/command-schema-guards.test.ts src/commands/__tests__/command-surface-metadata.test.ts
  • pnpm check:quick
  • pnpm format

Run broader checks if the implementation touches shared command metadata, CLI schema, or descriptor derivation beyond these projections.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions