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