99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# CommandKit dispatcher implementation
|
|
|
|
Status: accepted architecture; implementation pending.
|
|
|
|
Date: 2026-10-06.
|
|
|
|
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) owns the accepted dispatcher,
|
|
registry, and handler-input decisions, their alternatives, and rationale. The
|
|
[architecture policy](../policy/architecture.md) owns normative boundaries.
|
|
This roadmap owns pending API design, implementation status, and sequencing.
|
|
The [CLI plan](01-cli-plan.md) 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](03-backend.md) tracks Cobra/pflag integration, and the
|
|
[facade roadmap](04-facade.md) 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:
|
|
|
|
```go
|
|
// 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](../adr/0003-public-facade.md). 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.
|