78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
|
# CommandKit public facade implementation
|
||
|
|
|
||
|
|
Status: accepted facade and adapter boundary; implementation pending.
|
||
|
|
|
||
|
|
Date: 2026-10-06.
|
||
|
|
|
||
|
|
[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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
## 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
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### 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.
|