8.5 KiB
CLI Internals
internal/cli is the production composition root. CLI Reference
owns syntax, reports, and outcome codes; Configuration owns
settings; Operations owns physical state and recovery.
This guide explains declaration, loading, and orchestration owners, not another
public command manual.
Native Application Construction
NewApplication returns a native
*commandkit.App from application identity and injectable options. Construction
declares commands without configuration discovery, engine creation, provider
calls, or run-storage allocation. The executable supplies build identity;
RunWithOptions is a convenience execution entry point, not a manual dispatcher.
The constructor wires:
- native help/version and installed shell completion;
- application pipeline declarations and a native run alias;
- ckconfig whole-application and focused PromptKit scopes, sharing one loader;
- ckprompt resource/requirements inspection, concrete request validation, prepared preview, namespace selection, and explicit smoke testing.
ckconfig adapters use the original application result and focused native subtree view. ckprompt uses an engine loader through its standard builders rather than application-owned copies of inspection DTOs. Ordinary resource inspection does not become request preparation or an implicit probe. The native CLI reference owns parser/report mechanics.
Invocation-Local Loading
nativeLoaders belongs to one invocation.
It selects the main source and assembles one layered ConfigKit application
result. Engine construction calls promptkit.NewFromConfig on that result,
with runtime-only client options; it does not load YAML again.
The retained selection includes supplied-value state, overlay, and override values. Repeated identical selections share a result/engine, while distinct comparison selections cannot be memoized into one side. There is no process-global loader cache. The selected main's native context anchors companion imports; source edits do not mutate an existing captured engine.
Configuration Internals owns definition, normalization, origins, and conversion. Shared loaders allocate no output/cache/debug data.
Catalog And Preflight Boundaries
catalog.go composes generic, Seriatim, and D&D registrars into typed registries, codecs, evidence projectors, and validator defaults. Registration does not build an asset/schema registry or an LLM service. Injected registries/catalogs are alternative sources, not implicitly augmented with production entries.
pipeline_commands.go separates:
- listing: enumerate captured configured IDs without a catalog/engine;
- showing: domain resolution and composition description, without profile expansion;
- validating: domain resolution plus known-resource preflight, supplying the same captured engine only when model roles require it.
Preflight accepts collaborators/data; it does not load configuration, register/construct modules, read execution inputs, render CLI reports, or allocate state. Partial profiles pass native inspection, with concrete request readiness deferred until preparation.
Run Inputs And Native Overrides
run_input.go binds typed application inputs and repeated literal selections. execution_overrides.go uses reusable ckprompt resource/execution inputs, preserving omission versus explicit empty/false/zero. Only profile/session and execution controls needed by pipeline runs are selected; prompt inputs stay module-owned.
The resolved run-wide profile selection reaches every LLM-backed role. Native execution overrides travel through operation requests to producers, validators, and continuation, without mutating loaded settings. The public reference owns exact spellings/semantics.
Reference selectors are expanded at the CLI boundary using registered target specifications. Pipeline/lane actions become exact binding changes after specificity/conflict handling. Generic resolution receives exact reference bindings/unbinds, not CLI selector grammar. External/generated conflicts and required-slot/type checks remain with domain resolution; materialization follows.
session.go resolves the effective session from explicit supplied input or the input-module/raw-byte policy before runner work. Framework/model code transports it rather than deriving another session.
Run Orchestration
pipeline_run.go performs the ordered handoff:
- Load/validate the selected application result and derive runtime configuration.
- Generate a safe run identity and allocate requested capture.
- Capture selected configuration, compose registries, expand reference actions, and resolve the effective pipeline.
- Obtain the shared engine when needed and perform offline preflight.
- Materialize references, construct prepared typed modules, read input bytes, and resolve the effective session.
- Construct the accepted-result cache and optional recorder collaborator, create one native execution group, and invoke the runner with independent worker and execution selections.
- Report process diagnostics, publish returned logical files only after runner success, finalize requested capture, then submit the native completion report.
Modules receive the shared engine, operation data, and explicit collaborators, not physical roots or CommandKit reporters. Detailed worker, assessment, eligibility, and cache algorithms belong in Pipeline Internals; physical publication/capture collaborators belong in Run State Internals.
Requested capture allocates before engine/preflight and finalizes once. Primary operation causes and additional capture failures remain available. Later report delivery failure does not rerun model work, remove valid artifacts, or terminalize capture again.
Native Reporting And Outcomes
run_result.go submits one small application value with a native text template. Native serializers render that same value. Domain files, not a persisted report or ledger, are the deliverables. Fallback qualification is independent of optional diagnostic visibility.
Warnings/advisories keep their domain classification and use the reporter's diagnostic channel. Outcome helpers retain native configuration/preflight causes and distinguish identifiable invalid input from operational/mixed failures. CommandKit retains rendering/output/diagnostic delivery evidence separately from the operation cause; quiet mode does not mask such failures.
The completion report owns fields and stream/outcome contract owns process behavior. There is no universal Notarius envelope or parallel serializer.
Focused Verification
- Application tests cover lazy built-ins, shared scopes, selection evidence, and native diff outcomes.
- Loader tests and schema tests cover native composition, captured contexts, and operator contracts.
- Pipeline command tests cover listing/showing/preflight without execution inputs or state.
- Override tests and run tests cover supplied values, routing, references, sessions, and run ordering.
- Reference tests cover selector specificity, generated conflicts, and materialization boundaries.
- Native executable tests cover the real command routes and fake-provider presentations.
- Completion tests and recovery contracts cover retained publication, capture/delivery failures, reuse, fallback, and native facts.
Use focused CLI tests and pair with configuration/preflight tests when those boundaries change. Development owns wider checks.