base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Adopt shared policies and record CommandKit architecture

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 16:32:59 +00:00
parent 42d9b361cb
commit 88fb3f19b0
21 changed files with 3116 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/roadmap/04-facade.md Normal file
View File

@@ -0,0 +1,77 @@
# 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.