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

Cleaned up documentation language

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 19:36:02 -05:00
parent 84234275eb
commit a722bc1505
11 changed files with 40 additions and 696 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/adr/0003-public-facade.md
View File

@@ -10,20 +10,20 @@ Accepted.
## Context
CommandKit needs room to change implementation while consumers retain stable
registration, input, and invocation contracts. Exposing backend assembly or
extension structures would let applications depend on details that maintainers
may later replace.
CommandKit needs room to change its internal implementation details while
consumers retain access to a stable external API. Exposing backend assembly or
extension structures would let applications ossify around implementation
details that maintainers may later decide to replace.
ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types and
delegate through private state and explicit conversion. ConfigKit also translates
upstream YAML parser structures into an independent internal document model.
ReleaseKit has a second facade for a distinct lightweight runtime responsibility;
CommandKit has no corresponding requirement for another public package initially.
ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types
and delegate through private state and explicit conversion. ConfigKit also
translates upstream YAML parser structures into an independent internal document
model.
The Cobra selection is compatible with dependency isolation. Public API
independence needs a genuine contract boundary, and keeping backend structures
out of shared internal representations also makes future replacement easier.
The selection of Cobra as an internal dependency is compatible with this
decision. Public API independence needs a genuine contract boundary, and
keeping backend structures out of shared internal representations also makes
future replacement easier.
## Decision
@@ -46,8 +46,8 @@ values and returned errors must not provide indirect backend-object access.
Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
Public types from integration libraries, such as ConfigKit and PromptKit, may
be selected as deliberate dependencies. Application input types remain application-owned. Go declarations
and GoDoc own exact exported contracts.
be selected as deliberate dependencies. Application input types remain application-owned.
Go declarations and GoDoc own exact exported contracts.
Confine Cobra/pflag types and operations to an internal adapter. Registry logic,
standard handlers, and shared definitions use CommandKit-owned representations.
@@ -61,10 +61,6 @@ backend state per invocation. Introduce narrow internal interfaces where actual
engine/adapter interaction justifies them; exact package names and splits remain
implementation choices.
Use one concrete backend initially. There is no public backend interface, plugin
registry, or requirement for a second implementation. Replacement is a future
maintainer change.
Translate backend-owned syntax failures into CommandKit diagnostics and outcomes.
Preserve useful public identity for application handler errors and cancellation
according to the invocation contract. Explicit conversions must preserve value