commandkit/docs/internal/overview.md

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 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 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 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 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.