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

Record ownership and Go-native principles in architecture policy

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 02:49:13 +00:00
parent 5d90d59996
commit e908213318
9 changed files with 106 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
docs/policy/architecture.md
View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-11-07
**Last Updated**: 2026-11-06
**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
@@ -23,6 +23,22 @@ Exact exported contracts belong in Go declarations and GoDoc; implemented
operator behavior belongs in the CLI reference. Do not describe planned packages
or APIs as existing implementation.
## Ownership Boundaries
Applications and integration handlers choose the operation and report content;
CommandKit core supplies the shared CLI mechanics. Integrated libraries retain
ownership of their domain behavior. These boundaries govern current and planned
capabilities; they do not imply that a planned API is implemented.
| Area | CommandKit Owns | CommandKit Does Not Own |
| --- | --- | --- |
| **CLI output — core** | Format selection, serialization, template execution, and output delivery | Choosing report content or detail level; authoring application-specific text templates |
| **PromptKit/ConfigKit integrations** | Standard commands, flags, and report content that expose useful operator tasks through upstream public APIs | Helpers or convenience interfaces for application-internal use of upstream APIs |
| **CLI inputs** | CLI syntax, parsing, typed bindings, presence tracking, and usage diagnostics | Application business rules or upstream domain-validation semantics |
| **Upstream behavior** | Selecting and invoking supported capabilities, adapting their results, and preserving their meaning | Reimplementing upstream configuration resolution, prompt preparation, validation, or other domain algorithms |
| **Outcomes and errors — core** | Carrying and presenting selected outcomes; handling CommandKit's own parsing, rendering, and delivery failures | Deciding application recovery policy or terminating the process |
| **Application lifecycle** | Command dispatch and invocation reporting lifecycle | Application startup, engine construction, credential provisioning, signal handling, or long-lived application state |
## Success Criteria
Evaluate designs and adoption against both criteria:
@@ -42,11 +58,29 @@ Replacing parsing and dispatch plumbing with equally repetitive registration or
callback bookkeeping does not satisfy infrastructure reduction. Keep enough
flexibility to express genuine application requirements within one command model.
## Go Types And Facilities
CommandKit is a Go library for Go applications. Its APIs and implementation use
ordinary Go types, language features, and standard-library facilities. Their
documented semantics and representational limits are accepted design constraints.
CommandKit does not introduce substitute type systems or compatibility machinery
merely to circumvent those limits.
Ordinary parsing, application-defined domain types, and necessary serialization
adapters remain appropriate. Preserve values that the selected Go types can
represent; accepting their limits does not justify accidental rounding or
truncation during conversion. Keep CLI boundary conversions small and focused,
without turning them into general-purpose type-conversion frameworks.
Specific numeric parsing and report serialization contracts remain separate.
A CLI parser's selected numeric types do not establish a blanket restriction on
application-supplied values or silently redefine their serialization contracts.
GoDoc and CLI documentation own implemented behavior; roadmaps own pending work.
## Command And Application Ownership
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) records the selected
dispatcher, captured declarations, installation boundary, and typed-input model.
The [ADR index](../adr/README.md) records the alpha consolidation and renumbering.
CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax
diagnostics, and the handlers and CLI contracts of its standard families.
@@ -67,7 +101,7 @@ Applications own their executable entry points, context creation, signals,
stream selection, runtime construction, and final process exit. CommandKit
returns invocation outcomes and must not terminate the process. Its common
mechanics apply to custom commands without taking ownership of their domain
semantics or success-report formats.
semantics or report content.
CommandKit's grammar applies to commands using its dispatcher and binding APIs.
Its documentation recommends the same grammar and vocabulary for application-owned
@@ -130,6 +164,21 @@ messages; callers choose the destinations.
ownership model. Its accepted structured-report extension remains planned in the
[adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite).
For that shared report handoff, core owns format selection, serialization,
template execution, and delivery. Applications and integrations select logical
report content and detail level, and author any report-specific text templates.
Changing format must not implicitly change that content or detail level.
Representations and encoders are core implementation choices; commands should
not maintain parallel rendering pipelines or a separate report tree per format.
Use ordinary Go report values and thin projections where upstream data needs
adaptation. Prefer standard serialization and template facilities to a new public
document model, tag convention, or template language. Shared rendering serves
both invocation reporting and direct writer use, while invocation delivery keeps
the existing visibility, outcome, and presentation-failure lifecycle. Exact
serialization conventions, format options, and API signatures belong in the
roadmap until implemented, then in their API and CLI contracts.
Applications decide how to respond to domain-specific errors. CommandKit may
provide shared helpers for carrying, inspecting, and presenting errors while
leaving those decisions with the application. Supplying an error cause alone
@@ -139,9 +188,10 @@ handles its own errors, including routing, parsing, and presentation failures.
Preserve application-defined domain classifications and supplied error identity.
Report rendering and delivery failures separately from the command's explanation
and cause, applying the [CLI reporting contract](../cli.md#presentation-failures).
Intentionally suppressed output is not a delivery failure. Present terminal failure explanations
after normal reporting finishes, avoid duplicate presentation through core's own
paths, and retain the explanation and any supplied cause in the returned outcome.
Intentionally suppressed output is not a delivery failure. Present terminal
failure explanations after normal reporting finishes, avoid duplicate presentation
through core's own paths, and retain the explanation and any supplied cause in
the returned outcome.
Keep reporting state scoped to the invocation's presentation and returned outcome.
Logging and message history remain application concerns.
@@ -207,9 +257,11 @@ backend isolation principles in
boundaries.
The core owns command declarations, registration, bindings, dispatch, help/version,
shared syntax, diagnostics, and outcomes. Each integration owns its standard
handlers, provider contracts, reports, adapters, and integration-specific public
types. Dependencies point from integrations toward the core; an integration may
shared syntax, reporting mechanics, diagnostics, and outcomes. Each integration
owns its standard handlers, provider contracts, report content, adapters, and
integration-specific public types. Integrations expose operator-facing CLI tasks;
they do not provide convenience interfaces for application-internal upstream APIs.
Dependencies point from integrations toward the core; an integration may
depend on another integration when its responsibility requires that relationship.
Document those dependencies. Core public signatures, implementation imports, and
module requirements remain independent of optional integration libraries,
@@ -245,10 +297,10 @@ without exporting private assembly or backend structures.
## Backend And Library Integration
[ADR 0002](../adr/0002-public-facade-and-cli-backend.md) selects Cobra with pflag
as the sole initial backend. Their types and operations stay inside an internal adapter that
translates CommandKit-owned definitions into backend machinery. Registry logic,
standard handlers, and shared internal representations remain independent of
backend-specific structures.
as the sole initial backend. Their types and operations stay inside an internal
adapter that translates CommandKit-owned definitions into backend machinery.
Registry logic, standard handlers, and shared internal representations remain
independent of backend-specific structures.
Reuse backend routing and parsing mechanisms, adapting them to selected
CommandKit semantics. Do not replicate Cobra's entire API through renamed
@@ -256,9 +308,9 @@ wrappers. Introduce narrow internal interfaces where actual interactions justify
them; a public backend selection or plugin framework is not part of the design.
ConfigKit and PromptKit own configuration composition, provenance, inspection
semantics, secret classification, and native rendering. Applications provide
schemas, acquisition, domain resolution and validation, and construction of
inspection providers. CommandKit exposes those capabilities through supported
semantics, secret classification, and their native inspection representations.
Applications provide schemas, acquisition, domain resolution and validation,
and construction of inspection providers. CommandKit exposes those capabilities through supported
upstream APIs. The public contract of the adopted library version governs their
meaning and disclosure rules. When CommandKit adopts an upstream revision,
changes to those semantics flow through its integration. Adaptation and
@@ -282,6 +334,18 @@ Concrete integration needs guide provider representations under
Use upstream safe inspection data to preserve owning-library meaning and
disclosure rules under [ADR 0004](../adr/0004-optional-integration-modules.md).
Do not reconstruct inspection reports from mutable runtime configuration or source
files when the upstream inspection API supplies captured, safe evidence. Explicit
adaptation into ordinary report values must preserve the selected evidence and
report conversion failures rather than silently changing its meaning.
CommandKit parses and forwards supplied CLI selections and overrides through the
declared acquisition boundary. Upstream libraries retain path validity,
resolution, precedence, conflict handling, and domain validation. Preserve their
errors instead of inventing a parallel override policy or retrying with altered
values. Application loading and application-owned overrides retain their own
responsibilities.
The [CLI reference](../cli.md#show-effective-configuration) owns current native
report formats and operation-specific preparation and delivery timing. Semantic
comparison exposes the adopted upstream comparison API and carries its evidence