From 2595a7726d5670e3fb777b93824969f9f2ca64e9 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 7 Oct 2026 18:25:13 +0000 Subject: [PATCH] Reconcile the completed dispatcher planning record --- docs/roadmap/02-dispatch.md | 128 ++++++++++++------------------------ docs/roadmap/remediation.md | 8 ++- 2 files changed, 48 insertions(+), 88 deletions(-) diff --git a/docs/roadmap/02-dispatch.md b/docs/roadmap/02-dispatch.md index 56ae0ca..efe1d20 100644 --- a/docs/roadmap/02-dispatch.md +++ b/docs/roadmap/02-dispatch.md @@ -1,98 +1,56 @@ -# CommandKit dispatcher implementation +# CommandKit dispatcher planning record -Status: accepted architecture; implementation pending. +Status: initial dispatcher implementation complete. -Date: 2026-10-06. +Original planning: 2026-10-06. Reconciled: 2026-10-07. -[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. +## Authority and current owners -## 1. Current status +[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) owns the dispatcher, +registry, and typed-input decisions and rationale. The +[architecture policy](../policy/architecture.md) owns responsibility boundaries. +This document records completion of the initial dispatcher design; the +[implementation plan](implementation.md) preserves its execution history. -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 registry, typed inputs, command/group APIs, invocation coordination, and +outcomes are implemented. Their exact contracts are owned by Go declarations +and GoDoc, rather than the early illustrations formerly maintained here. -The [backend roadmap](03-backend.md) tracks Cobra/pflag integration, and the -[facade roadmap](04-facade.md) tracks the accepted public/internal boundary. +| API area | Current owner | +| --- | --- | +| Application construction and registration | [App/New](../../app.go) and [App.Register](../../registry.go) | +| Typed command declarations, groups, and presence | [CommandSpec, NewCommand, Group, WithChildren, Supplied](../../command.go) | +| Typed flag and operand bindings | [Binding helpers](../../binding.go) | +| Invocation and result delivery | [App.Execute](../../execute.go), [Invocation/Streams](../../identity.go), and [Outcome](../../outcome.go) | +| Standard integration registration | [Configuration suite](../../config.go) and [PromptKit suite](../../promptkit.go) | -## 2. Public API design +The [consumer guide](../consumers/guide.md) explains assembly and callback usage. +The [CLI reference](../cli.md) owns syntax and operator behavior; the +[internal overview](../internal/overview.md) owns implemented package mechanics. -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. +## Completed design and evidence -### Illustrative presence and inputs +The initial work delivered instance registration, composable nested groups, +typed handlers and bindings, presence-aware input, capability-based installation, +lazy acquisition, and distinct shared/domain outcomes. The original `Supplied` +illustration is now a public declaration; application-specific restore inputs +remain consumer examples rather than proposed CommandKit types. -The selected model keeps presence alongside values where omission matters. One -possible shape remains: +The [simple](../../examples/simple/README.md) and +[composed](../../examples/composed/README.md) consumers demonstrate the API with +configuration inspection and a custom session command. The completed plan +records behavioral evidence for routing, ownership conflicts, help, invocation +state, cancellation, output failures, and domain outcome preservation. -```go -// Illustration only; these are not established public API declarations. -type Supplied[T any] struct { - Value T - Set bool -} +Completed constructor/binding/outcome design tasks and implementation assignments +have been retired from this roadmap. Concurrent dispatch remains outside the +initial target under the [feature roadmap](initial.md#explicit-deferrals). -type RestoreInput struct { - SessionID string - DryRun bool - Force bool - Overlay Supplied[string] -} -``` +## Remaining adoption work -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. +Applications can migrate their routers and repeated standard handlers to the +implemented API, update documentation and subprocess consumers for breaking +changes, and retain their domain command behavior. Migration is separate from +library completion; this record does not claim that the sibling applications +have adopted CommandKit. Deferred standard capabilities are tracked in the +[feature roadmap](initial.md#deferred-capability-targets). diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 4161416..ef2111c 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -74,16 +74,18 @@ Owner: [01-cli-plan.md](01-cli-plan.md). Owner: [02-dispatch.md](02-dispatch.md). -- [ ] Remove the pending status and claims that the registry, typed inputs, +- [x] Remove the pending status and claims that the registry, typed inputs, constructors, binding/group APIs, handler signatures, and outcomes are absent or unresolved. -- [ ] Retire completed API design, implementation sequence, and evidence tasks. +- [x] Retire completed API design, implementation sequence, and evidence tasks. Clearly label retained illustrations as historical; the public `Supplied` type is now implemented. -- [ ] Link current API usage to Go declarations/GoDoc and the +- [x] Link current API usage to Go declarations/GoDoc and the [consumer guide](../consumers/guide.md), and current mechanics to the internal overview. Preserve application migration work as separate future work. +**Completion:** Replaced pending dispatcher work with a completed planning record and links to implemented API, consumer, and internal owners. + ## D-03: reconcile backend planning Owner: [03-backend.md](03-backend.md).