119 lines
6.5 KiB
Markdown
119 lines
6.5 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 canonical command declarations, application-owned
|
|
routing rules, binding conversion, invocation coordination, the per-App
|
|
registries, standard help/version commands, invocation reporting, and outcome
|
|
finalization.
|
|
Its dependency graph has no ConfigKit or PromptKit integration dependency.
|
|
Applications provide typed callbacks and install routing rules alongside the
|
|
complete canonical command tree through the same batch API.
|
|
|
|
Canonical commands own handlers and parsing/help metadata; routing rules resolve
|
|
entered command paths and flag spellings to those canonical records without
|
|
adding command nodes or handlers. The shared command compiler prepares supplied
|
|
values before constructing input. The batch installer validates retained
|
|
issues, placement, and collisions across both registries before publishing
|
|
either. 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.
|
|
|
|
Each execution creates one reporter backed by the caller's result and diagnostic
|
|
writers. The Cobra adapter returns parsed values, flag spellings, and reporting
|
|
flag occurrences. Core reduces those occurrences in entered order after route
|
|
resolution, applies the final mode and progress selection, and presents any
|
|
collected parser events through that selection. The selected mode therefore
|
|
applies to command execution, help, and version; routing and parsing failures
|
|
remain visible in every mode.
|
|
|
|
The reporter owns invocation-scoped visibility, message formatting, managed
|
|
report rendering, delivery observations, and finalization. It presents queued
|
|
messages after the handler returns, then a failed outcome's explanation, and
|
|
closes its handles before `Execute` returns. It records rendering and write
|
|
errors separately for result and diagnostic destinations; the returned
|
|
`Outcome.Presentation` exposes those observations independently from the
|
|
operation cause. The reporter does not retain a transcript and does not close
|
|
or flush caller-owned writers.
|
|
|
|
Internally, one reporting-state mutex guards visibility, queued messages,
|
|
destination state, and delivery errors while serializing reporter operations
|
|
and writes. Rendering callbacks execute within that coordination boundary, so
|
|
they must not recursively submit or render through the same reporter. This is
|
|
an implementation detail supporting the callback contract; the mutex does not
|
|
coordinate writes made outside the reporter.
|
|
|
|
## `internal/alias` and `internal/commandpath`
|
|
|
|
`internal/commandpath` provides shared path parsing and token operations used by
|
|
declaration capture, routing, and backend selection. `internal/alias` compiles
|
|
application routing rules, resolves command prefixes while retaining token
|
|
provenance, and validates command-route termination. Neither package owns
|
|
handlers, application factories, or backend types.
|
|
|
|
## `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.
|