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

Reconcile the completed facade planning record

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 18:26:04 +00:00
parent 20b646e005
commit 6c04dceb85
2 changed files with 48 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/roadmap/04-facade.md
View File

@@ -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.