52 lines
2.8 KiB
Markdown
52 lines
2.8 KiB
Markdown
# 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`
|
|
|
|
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 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.
|
|
|
|
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/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.
|
|
|
|
## External implementation boundaries
|
|
|
|
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.
|