commandkit/docs/roadmap/02-dispatch.md

CommandKit dispatcher implementation

Status: accepted architecture; implementation pending.

Date: 2026-10-06.

ADR 0001 owns the accepted dispatcher, registry, and handler-input decisions, their alternatives, and rationale. The architecture policy owns normative boundaries. This roadmap owns pending API design, implementation status, and sequencing. The CLI plan retains operator-contract proposals and their individual approval status.

1. Current status

The registry and typed-input model are selected but have no Go implementation. Exact constructors, registration/group APIs, bindings, factories, handler signatures, and application outcome/error interfaces remain open. No illustrative API declaration is a supported contract.

The backend roadmap tracks Cobra/pflag integration, and the facade roadmap tracks the accepted public/internal boundary.

2. Public API design

1. Design explicit instance construction, individual command registration, composable groups, and invocation using application context and streams.
2. Express nested paths, descriptions, typed flags and defaults, repeatable inputs, presence, operands, and typed handlers in one definition.
3. Define capability-provider registration that assembles supported standard operations and help from declared capabilities, leaving acquisition callbacks uninvoked. Design wiring diagnostics separately from loading failures.
4. Specify the outcome/error interface so common usage errors, standard-command failures, and application-specific domain outcomes remain distinguishable.
5. Demonstrate bindings against the proposed config show, promptkit show profile, and Narratio's application-owned session restore. These examples exercise standard selectors, resource operands, and application flags without approving unresolved command details.
6. Evaluate simple and complex consumers against consistency and removed infrastructure. Constructor options or initial command collections can be conveniences over the same registry if they reduce assembly work.

Illustrative presence and inputs

The selected model keeps presence alongside values where omission matters. One possible shape remains:

// Illustration only; these are not established public API declarations.
type Supplied[T any] struct {
    Value T
    Set   bool
}

type RestoreInput struct {
    SessionID string
    DryRun    bool
    Force     bool
    Overlay   Supplied[string]
}

Select exact public types, binding functions, and input factories during API work. Keep context, streams, and execution dependencies separate from CLI fields. Design domain value parsing within shared bindings without returning the complete argv to handlers.

3. Implementation sequence

1. Implement the root facade and internal command definitions under ADR 0003. Add the per-instance registry and conflict checks without global or import-time registration.
2. Translate definitions through the internal Cobra/pflag adapter. Allocate fresh input and backend state per invocation; do not bind registrations permanently to shared mutable inputs.
3. Implement help/version and capability installation without configuration or runtime construction. Providers load only when the selected operation needs their results.
4. Resolve remaining grammar and outcome proposals in the CLI plan before implementing them. Do not adopt parser defaults as accidental contracts.
5. Implement the selected standard handlers through owning-library inspection APIs, following the upstream dependencies and delivery sequence in the CLI plan.
6. Replace application routers and parser plumbing with registration and handlers. Coordinate the intentional breaking changes with application docs and subprocess consumers. Supported capability subsets can be integrated and released independently, with their actual availability exposed in metadata.

4. Implementation evidence

As behavior lands, select meaningful checks under the testing policy for nested routing and collisions, help without configuration, flag placement and --, explicit empty/false/zero input, repetition, fresh values and presence across invocations, cancellation, output errors, and preserved application outcomes. Fresh state alone does not promise concurrent dispatch.

Update exact API GoDoc, consumer guidance, implemented CLI reference, and internal inventory with their corresponding implementation. Keep rationale in the ADR; retire completed implementation tasks without losing pending proposals.