4.0 KiB
CommandKit public facade implementation
Status: accepted facade and adapter boundary; implementation pending.
Date: 2026-10-06.
ADR 0003 owns the root facade, internal adapter, alternatives, and rationale. The architecture policy owns normative dependency and public-surface rules. This roadmap tracks exact API work, illustrative package organization, and implementation evidence.
The dispatcher roadmap tracks registry and typed inputs; the backend roadmap tracks Cobra/pflag translation. The CLI plan retains command and operator-contract proposals and their approval status.
1. Current status
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.
2. API and internal representation design
- Design root-owned registration, binding, provider, invocation, and outcome contracts around demonstrated consumer needs. Application input types remain application-owned.
- 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.
- Use private state and explicit forwarding/conversions, preserving ownership, callback lifetime, presence, supported error identity, and cancellation.
- 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.
- Select any public dependency types deliberately. Standard context/stream contracts are appropriate; ConfigKit/PromptKit types require an API choice.
Illustrative package layout
| 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. |
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.
3. Boundary protection and consumer evidence
With implementation, introduce proportionate checks for:
- 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.