82 lines
4.3 KiB
Markdown
82 lines
4.3 KiB
Markdown
# Internal package overview
|
|
|
|
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.
|
|
|
|
## Root `commandkit`
|
|
|
|
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 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.
|
|
|
|
## `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 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.
|
|
|
|
## Optional modules
|
|
|
|
`integrations/ckconfig` owns ConfigKit adaptation, scope capture, the standard
|
|
`config` command family, and native validate/show/sources/explain/diff behavior.
|
|
It depends on the public core facade and ConfigKit; it does not depend on
|
|
PromptKit. Each selected scope or comparison side receives an independently
|
|
initialized input, while one suite-owned state value is shared by an invocation's
|
|
acquisitions or comparison callback.
|
|
|
|
`integrations/ckprompt` owns PromptKit engine loading, configuration-scope
|
|
adaptation and native comparison, plus optional prompt/profile/backend/namespace/
|
|
collection catalogs, named inspection, native requirements discovery,
|
|
concrete request validation, and native smoke testing. Validation and smoke
|
|
testing delegate to PromptKit and are independently opted into a suite. Smoke
|
|
operations use the application's native engine and its configured client or
|
|
probes. The integration 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 configuration operations alongside PromptKit
|
|
commands.
|
|
|
|
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, named inspection, requirements discovery,
|
|
and concrete request validation, and native smoke-test semantics. CommandKit
|
|
adapts those public contracts without maintaining parallel schemas. Explicit
|
|
native smoke operations may use the configured client or probes; other
|
|
inspection, catalog, and request-validation paths do not make model calls.
|
|
Native request validation may load resources and artifacts, render messages,
|
|
and perform applicable configuration or credential checks through PromptKit.
|
|
Application loaders and domain behavior remain application owned.
|