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

Align architecture policy with revised ADRs

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 02:47:46 +00:00
parent 7e453a2df2
commit ff1b1b1a3e
1 changed files with 49 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/policy/architecture.md
View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-10-06 **Last Updated**: 2026-10-07
**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
@@ -59,6 +59,17 @@ returns invocation outcomes and must not terminate the process. Its common
mechanics apply to custom commands without taking ownership of their domain mechanics apply to custom commands without taking ownership of their domain
semantics or success-report formats. semantics or success-report formats.
CommandKit's grammar applies to commands using its dispatcher and binding APIs.
Its documentation recommends the same grammar and vocabulary for application-owned
commands, including those outside its dispatcher, under
[ADR 0006](../adr/0006-command-grammar.md).
CommandKit preserves application-supplied outcome classifications and supported
error identity. It assigns responsibility for its diagnostics, avoids duplicate
presentation through its own paths, and reports write failures. Caller callbacks
retain control of their own output. [ADR 0005](../adr/0005-invocation-outcomes.md)
describes the outcome and delivery model.
Use explicit instance construction and composable command registration, not Use explicit instance construction and composable command registration, not
package-global or import-time registries. One definition supplies routing, package-global or import-time registries. One definition supplies routing,
parsing, and help metadata. Duplicate paths and attempts to replace reserved parsing, and help metadata. Duplicate paths and attempts to replace reserved
@@ -91,10 +102,11 @@ Use presence-aware fields where omission matters; preserve explicitly supplied
empty, false, and zero values independently of parser defaults. Context, streams, empty, false, and zero values independently of parser defaults. Context, streams,
and execution dependencies are separate from CLI inputs. and execution dependencies are separate from CLI inputs.
CommandKit creates fresh input and backend command/flag state per invocation, CommandKit keeps parsed values, collections, and presence from one invocation out
keeping its parsed values, collections, and presence out of subsequent runs. of subsequent runs. Storage allocation and safe reuse are implementation choices;
Caller-owned closures and runtime state retain their own lifecycle. Concurrent rebuilding backend state is the initial strategy under
dispatch is a separate contract. [ADR 0002](../adr/0002-cobra-backend.md). Caller-owned closures and runtime state
retain their own lifecycle. Concurrent dispatch is a separate contract.
Applications may interpret parsed domain values and provide domain value parsers Applications may interpret parsed domain values and provide domain value parsers
through the binding system. Raw-argument parsing is not the primary handler model. through the binding system. Raw-argument parsing is not the primary handler model.
@@ -108,22 +120,27 @@ and defines CommandKit's public named types. Additional public packages require
deliberate decision based on a durable consumer responsibility. deliberate decision based on a durable consumer responsibility.
Public handles retain private implementation state and expose explicitly selected Public handles retain private implementation state and expose explicitly selected
methods. Use explicit forwarding and conversions that preserve type identity, methods. Any forwarding and conversions must preserve type identity, value
value ownership, callback lifetime, presence, and public error semantics. Do not ownership, callback lifetime, presence, and supported public error semantics. Do
alias or anonymously embed implementation types into the public API, promote not alias public types to internal or backend types, anonymously embed those types
internal methods, or expose backend bridge methods. to promote methods, or expose implementation bridge methods.
Implementation belongs under Go's `internal/` boundary. Dependencies run from the Straightforward implementation may live in the root package without expanding
facade inward; internal production packages do not import the root. Shared its exports. Introduce internal packages, interfaces, and conversions where they
implementation contracts belong inside the internal boundary. Public signatures, simplify implementation or protect the backend boundary. Package organization and
fields, callbacks, constraints, and method sets must not expose internal or the amount of internal layering follow implementation needs.
Cobra/pflag types. Backend objects must not escape through loosely typed values
or returned errors. Public signatures, fields, callbacks, constraints, and method sets must not expose
internal or Cobra/pflag types. CommandKit does not expose its internal backend
objects or backend-specific syntax errors through its public API, including
through loosely typed values or returned errors. Caller-supplied values and errors
retain their documented handling; this boundary does not require inspecting or
transforming arbitrary application objects.
Standard contracts such as `context.Context` and `io.Writer` remain appropriate. Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
Other public dependency types require deliberate API selection. Application-owned Public types from integration libraries, such as ConfigKit and PromptKit, may be
input types remain application-owned. Do not expand exports merely to simplify selected as deliberate dependencies. Application-owned input types remain
internal assembly. application-owned. Do not expand exports merely to simplify internal assembly.
## Backend And Library Integration ## Backend And Library Integration
@@ -145,12 +162,24 @@ inspection providers. CommandKit exposes those capabilities without implementing
a parallel configuration or prompt engine. Use independently released public a parallel configuration or prompt engine. Use independently released public
contracts; do not import sibling internal packages or depend on adjacent checkouts. contracts; do not import sibling internal packages or depend on adjacent checkouts.
Use narrow integration contracts, reusing upstream public types where useful and
introducing CommandKit-owned abstractions where they simplify integration.
Concrete integration needs guide provider representations under
[ADR 0009](../adr/0009-configuration-scopes.md).
Native report writers and safe inspection data preserve owning-library semantics.
Loading all selected views before report output is a `config show` decision under
[ADR 0007](../adr/0007-native-yaml-reports.md); other inspection operations define
their own output timing. Semantic comparison uses supported safe snapshots and
reports sensitivity gaps under [ADR 0008](../adr/0008-semantic-configuration-diff.md).
## Scope And Non-goals ## Scope And Non-goals
Keep packages and abstractions proportionate to cohesive responsibilities. The Keep packages and abstractions proportionate to cohesive responsibilities. The
library is not a general application runtime, dependency-injection framework, library is not a general application runtime, dependency-injection framework,
logging system, hosted service, or standalone application. It does not prescribe logging system, hosted service, or standalone application. Shared vocabulary is
domain execution vocabulary outside the standard suite. recommended for application-owned commands; their names and domain behavior
remain application choices.
The [CLI roadmap](../roadmap/01-cli-plan.md) distinguishes accepted operator The [CLI roadmap](../roadmap/01-cli-plan.md) distinguishes accepted operator
choices from remaining command and grammar proposals. Backend defaults and choices from remaining command and grammar proposals. Backend defaults and