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

Reconcile module docs and release materials

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-11 02:06:06 +00:00
parent 18e81a5579
commit d2b5b0f3a8
45 changed files with 2380 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/internal/overview.md
View File

@@ -1,51 +1,70 @@
# Internal package overview
CommandKit ships one public package, `commandkit`, and one internal package,
`internal/cobra`. This inventory describes the current implementation; the
[architecture policy](../policy/architecture.md) owns normative boundaries and
[ADR 0003](../adr/0003-public-facade.md) records the original facade decision.
[ADR 0010](../adr/0010-optional-integration-modules.md) now scopes that decision to
the core and optional integrations; the [module roadmap](../roadmap/modules.md)
tracks the pending transition. The inventory below describes the prototype.
CommandKit's core module contains the public `commandkit` facade, the private
neutral metadata package, and the internal Cobra adapter. Two nested Go modules
own the optional ConfigKit and PromptKit integrations. The
[architecture policy](../policy/architecture.md) owns normative boundaries;
this page inventories the implemented owners.
## `commandkit`
## Root `commandkit`
The root package declares the public API and owns the instance registry, typed
command input preparation, invocation coordination, standard handlers, and
provider adapters. Configuration reports adapt ConfigKit's public records and
writers. PromptKit scope and definition handlers use PromptKit's public
inspection methods and map their results to CommandKit-owned reports.
The root facade owns captured command declarations, binding conversion,
invocation coordination, the per-App registry, standard help/version commands,
and outcome/diagnostic delivery. Its dependency graph has no ConfigKit or
PromptKit integration dependency. Applications provide typed callbacks and
choose when to install declarations.
The root lazily caches one immutable neutral bridge tree per `App`, invalidating
it after successful nonempty registration. For each `Execute`, it prepares one
adapter session and reuses that session for parsing, help, and usage. If a
callback registers commands during execution, metadata-dependent presentation
refreshes without repeating input callbacks. The root still prepares typed
input, invokes application/standard handlers, and coordinates outcomes and
diagnostic delivery. Application callbacks and their supported error identity
are handled in the root through its typed contracts.
The shared command compiler prepares supplied values before constructing input.
The batch installer validates retained issues, placement, and collisions before
mutating the registry. Each invocation uses one routing snapshot and backend
session; a successful registration invalidates the snapshot for a later
invocation. The root package owns app input and callback execution, not provider
configuration semantics.
Configuration registration owns and normalizes its declarations, then prepares
ordered scopes, name lookup, installed operations, and a discovery DTO. Command
handlers reuse that private metadata; each invocation still creates its context
and invokes acquisition only for selected scopes.
## `internal/commandmeta`
This package owns the private neutral command, flag, argument, parsed-value, and
failure records shared between the public facade and backend adapter. It does
not import Cobra or optional integration modules. The facade and adapter
exchange these records without exporting backend-specific types.
## `internal/cobra`
This package owns the Cobra-specific command tree, argument/flag parsing,
and help rendering. A session owns one mutable backend tree for an invocation;
parsing and presentation reuse it. Backend commands map directly to neutral
declarations, and Cobra parent links reconstruct only the selected command path.
The adapter returns raw parsed values and neutral syntax-failure data consumed
by the root package. It does not import `commandkit` and does not own registry
policy, public command declarations, provider loading, or standard inspection
report rendering.
This package owns the Cobra command tree, argument/flag parsing, and help
rendering. A session owns the mutable backend tree for one invocation; parsing
and presentation reuse that session. The adapter returns raw values and neutral
syntax failures to core. It does not own the registry, typed input preparation,
integration declarations, provider acquisition, or native report rendering.
Cobra and pflag imports remain inside this package.
## External implementation boundaries
## Optional modules
ConfigKit owns typed configuration loading, source history, validation,
resolution, and path explanations. PromptKit owns captured engine
configuration, prompt definitions, profile inheritance, and named inspections.
CommandKit depends on their public module APIs and does not maintain parallel
schemas. Cobra and pflag are confined behind the internal adapter; YAML report
encoding is performed by the root package.
`integrations/ckconfig` owns ConfigKit adaptation, scope capture, the standard
`config` command family, and native validate/show/sources/explain reports. It
depends on the public core facade and ConfigKit; it does not depend on PromptKit.
Each selected scope receives an independently initialized input, while one
suite-owned state value is shared by selected acquisitions in that invocation.
`integrations/ckprompt` owns PromptKit engine loading, configuration-scope
adaptation, and optional named prompt/profile inspection. It uses public core
and ckconfig contracts plus PromptKit's public APIs. It does not add a
configuration family when its declaration is installed; callers compose
`ckprompt.ConfigScope` with `ckconfig.Command` separately when they want both.
The three maintained consumers live at `examples/core`,
`integrations/ckconfig/examples/simple`, and
`integrations/ckprompt/examples/composed`. The
[consumer guide](../consumers/guide.md) links to those examples and explains the
public wiring. Run tests from each module; root `./...` does not traverse the
nested module directories. The [development guide](../development.md) gives the
workspace test commands. Workspace builds do not establish independent module
graph isolation.
## Upstream implementation boundaries
ConfigKit owns configuration decoding, validation, source history, and path
explanations. PromptKit owns its captured engine configuration, prompt
definitions, profile inheritance, and named inspection semantics. CommandKit
adapts those public contracts without maintaining parallel schemas or invoking
prompt execution. Application loaders and domain behavior remain application
owned.