From 6c04dceb85aa3aca2ca8fe0977caf979bbcde626 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 7 Oct 2026 18:26:04 +0000 Subject: [PATCH] Reconcile the completed facade planning record --- docs/roadmap/04-facade.md | 105 +++++++++++++++--------------------- docs/roadmap/remediation.md | 10 ++-- 2 files changed, 48 insertions(+), 67 deletions(-) diff --git a/docs/roadmap/04-facade.md b/docs/roadmap/04-facade.md index 0a84ae3..d74a9d4 100644 --- a/docs/roadmap/04-facade.md +++ b/docs/roadmap/04-facade.md @@ -1,77 +1,56 @@ -# CommandKit public facade implementation +# CommandKit facade planning record -Status: accepted facade and adapter boundary; implementation pending. +Status: initial public facade and internal adapter implemented. -Date: 2026-10-06. +Original planning: 2026-10-06. Reconciled: 2026-10-07. -[ADR 0003](../adr/0003-public-facade.md) owns the root facade, internal adapter, -alternatives, and rationale. The [architecture policy](../policy/architecture.md) -owns normative dependency and public-surface rules. This roadmap tracks exact API -work, illustrative package organization, and implementation evidence. +## Authority and current owners -The [dispatcher roadmap](02-dispatch.md) tracks registry and typed inputs; the -[backend roadmap](03-backend.md) tracks Cobra/pflag translation. The CLI plan -retains command and operator-contract proposals and their approval status. +[ADR 0003](../adr/0003-public-facade.md) owns the facade/adapter decision and its +rationale. The [architecture policy](../policy/architecture.md) owns normative +dependency and public-surface boundaries. -## 1. Current status +Root public declarations, private implementation state, and the internal +Cobra/pflag adapter exist. Exact contracts belong in Go declarations and GoDoc; +the [consumer guide](../consumers/guide.md) explains their use. The +[internal overview](../internal/overview.md) owns the actual package inventory, +and [go.mod](../../go.mod) owns dependency versions. -The root `commandkit` facade and internal Cobra/pflag isolation are accepted. -No public declarations, implementation packages, adapter, dependency versions, -or boundary checker exist yet. There is no public backend selection facility. +The [initial target](initial.md) and [completed implementation plan](implementation.md) +record the chosen layout and delivered API work. The initial implementation +requires no further facade package construction. -## 2. API and internal representation design +## Retired package exploration -1. Design root-owned registration, binding, provider, invocation, and outcome - contracts around demonstrated consumer needs. Application input types remain - application-owned. -2. Identify internal definitions and private callbacks that let implementation - invoke typed handlers without importing the root facade or exposing backend - structures. Separate fresh input lifetime from registration and dependencies. -3. Use private state and explicit forwarding/conversions, preserving ownership, - callback lifetime, presence, supported error identity, and cancellation. -4. Translate backend-owned failures without returning backend objects, including - through errors or loosely typed values. Preserve useful application error - identity according to the selected invocation contract. -5. Select any public dependency types deliberately. Standard context/stream - contracts are appropriate; ConfigKit/PromptKit types require an API choice. +Early illustrations considered an `internal/engine` for registration and +coordination and an `internal/command` for shared declarations, with a root +limited mainly to forwarding. Those were possible layouts, not required +packages, and are superseded as active implementation targets. -### Illustrative package layout +The selected root contains straightforward private implementation alongside its +public contracts; the internal adapter isolates backend machinery. Consult the +internal overview for current responsibilities instead of treating the early +package table as an inventory or expansion checklist. -| Package | Possible responsibility | -| --- | --- | -| Root `commandkit` | Consumer facade, selected contracts, and conversions. | -| `internal/engine` | Registry, ownership checks, capability installation, and invocation coordination. | -| `internal/command`, if needed | Shared definitions and contracts independent of the backend. | -| `internal/cobra` | Cobra/pflag integration, bindings, and diagnostic translation. | +## Completed boundary work -These names and splits are illustrative, not an implemented inventory or required -package-per-concern layout. Select cohesive packages during implementation. A -narrow internal engine/adapter interface may be useful where actual interaction -justifies it. Do not require a public backend interface or a second implementation. +The initial work established root-owned public named types and handles, selected +integration dependencies, typed callback/value semantics, backend-neutral bridge +metadata/results, and adaptation of backend-owned failures. API design, +package-selection, and initial documentation tasks are complete. -## 3. Boundary protection and consumer evidence +The completed plan records review of public declarations and dependency direction, +plus consumer behavior through the real adapter. Earlier suggestions to adopt +ConfigKit/ReleaseKit-style automated export scanners were validation possibilities, +not a requirement to add a checker. Future automation remains a maintenance +choice under the [testing policy](../policy/testing.md) when its protection +justifies its cost. -With implementation, introduce proportionate checks for: +## Future backend replacement -- Compiled public exports, including aliases, fields, signatures, constraints, - callbacks, and promoted methods exposing internal or backend types. -- Import direction: internal production code must not import root, and Cobra/pflag - types and operations belong in the adapter. -- Consumer behavior through the actual adapter, including conversions, fresh - state, public error identity, and selected invocation semantics. - -ConfigKit and ReleaseKit provide precedents for compiled API and import checks; -reuse the approach where it protects this boundary without copying their entire -validation suites or domain restrictions. - -## 4. Completion and later replacement - -Introduce GoDoc, consumer guidance, implemented CLI reference, and internal -inventory with their corresponding code. Those become canonical owners of exact -API and current behavior; ADRs retain decision rationale. - -A later backend replacement should preserve the public Go API and selected CLI -behavior, or follow the release policy for deliberate incompatible behavior. -Protecting signatures alone is insufficient evidence for parsing, help, -diagnostics, report, and status compatibility. This is future maintenance scope, -not an instruction to implement or exercise a replacement now. +A later replacement remains possible behind the accepted boundary. It must +preserve the public API and selected CLI behavior or follow the +[release policy](../policy/release.md) for deliberate incompatible changes. +Signature isolation alone does not prove behavioral compatibility; parsing, +help, diagnostic delivery, reports, and outcomes remain relevant to that review. +Replacement and public backend selection are outside the initial delivered scope. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index c203a91..4863958 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -105,16 +105,18 @@ Owner: [03-backend.md](03-backend.md). Owner: [04-facade.md](04-facade.md). -- [ ] Remove the pending status and claims that public declarations, +- [x] Remove the pending status and claims that public declarations, implementation packages, the adapter, and dependency versions do not exist. -- [ ] Retire the illustrative `internal/engine` and `internal/command` layout as +- [x] Retire the illustrative `internal/engine` and `internal/command` layout as an active implementation target. Link to the actual root and internal adapter inventory without creating another maintained package reference. -- [ ] Retire completed API/boundary design and documentation tasks. Preserve +- [x] Retire completed API/boundary design and documentation tasks. Preserve legitimate future backend replacement considerations. -- [ ] Keep old automated boundary-checker suggestions clearly historical or +- [x] Keep old automated boundary-checker suggestions clearly historical or optional; do not turn them into a new implementation requirement. +**Completion:** Recorded facade completion, retired illustrative extra packages, and preserved backend replacement and proportionate-check considerations. + ## D-05: close the preparation checklist Owner: [initial-plan.md](initial-plan.md).