2.8 KiB
Internal package overview
CommandKit ships one public package, commandkit, and one internal package,
internal/cobra. This inventory describes the current implementation; the
architecture policy owns normative boundaries and
ADR 0003 records the original facade decision.
ADR 0010 now scopes that decision to
the core and optional integrations; the module roadmap
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.