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, ## Authority and current owners
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 [ADR 0003](../adr/0003-public-facade.md) owns the facade/adapter decision and its
[backend roadmap](03-backend.md) tracks Cobra/pflag translation. The CLI plan rationale. The [architecture policy](../policy/architecture.md) owns normative
retains command and operator-contract proposals and their approval status. 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. The [initial target](initial.md) and [completed implementation plan](implementation.md)
No public declarations, implementation packages, adapter, dependency versions, record the chosen layout and delivered API work. The initial implementation
or boundary checker exist yet. There is no public backend selection facility. 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 Early illustrations considered an `internal/engine` for registration and
contracts around demonstrated consumer needs. Application input types remain coordination and an `internal/command` for shared declarations, with a root
application-owned. limited mainly to forwarding. Those were possible layouts, not required
2. Identify internal definitions and private callbacks that let implementation packages, and are superseded as active implementation targets.
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 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 | ## Completed boundary work
| --- | --- |
| 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 The initial work established root-owned public named types and handles, selected
package-per-concern layout. Select cohesive packages during implementation. A integration dependencies, typed callback/value semantics, backend-neutral bridge
narrow internal engine/adapter interface may be useful where actual interaction metadata/results, and adaptation of backend-owned failures. API design,
justifies it. Do not require a public backend interface or a second implementation. 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, A later replacement remains possible behind the accepted boundary. It must
callbacks, and promoted methods exposing internal or backend types. preserve the public API and selected CLI behavior or follow the
- Import direction: internal production code must not import root, and Cobra/pflag [release policy](../policy/release.md) for deliberate incompatible changes.
types and operations belong in the adapter. Signature isolation alone does not prove behavioral compatibility; parsing,
- Consumer behavior through the actual adapter, including conversions, fresh help, diagnostic delivery, reports, and outcomes remain relevant to that review.
state, public error identity, and selected invocation semantics. Replacement and public backend selection are outside the initial delivered scope.
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.

10
docs/roadmap/remediation.md
View File

@@ -105,16 +105,18 @@ Owner: [03-backend.md](03-backend.md).
Owner: [04-facade.md](04-facade.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. 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 an active implementation target. Link to the actual root and internal adapter
inventory without creating another maintained package reference. 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. 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. 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 ## D-05: close the preparation checklist
Owner: [initial-plan.md](initial-plan.md). Owner: [initial-plan.md](initial-plan.md).