2026-07-26 13:20:18 +00:00
|
|
|
# CLI Internals
|
|
|
|
|
|
2026-11-22 06:41:22 +00:00
|
|
|
`internal/cli` is the production composition root. [CLI Reference](../cli.md)
|
|
|
|
|
owns syntax, reports, and outcome codes; [Configuration](../config.md) owns
|
|
|
|
|
settings; [Operations](../operations.md) owns physical state and recovery.
|
|
|
|
|
This guide explains declaration, loading, and orchestration owners, not another
|
|
|
|
|
public command manual.
|
|
|
|
|
|
|
|
|
|
## Native Application Construction
|
|
|
|
|
|
|
|
|
|
[NewApplication](../../internal/cli/application.go) 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][native-cli] owns parser/report mechanics.
|
|
|
|
|
|
|
|
|
|
## Invocation-Local Loading
|
|
|
|
|
|
|
|
|
|
[nativeLoaders](../../internal/cli/configkit_load.go) 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](configuration.md) owns definition, normalization,
|
|
|
|
|
origins, and conversion. Shared loaders allocate no output/cache/debug data.
|
|
|
|
|
|
|
|
|
|
## Catalog And Preflight Boundaries
|
|
|
|
|
|
|
|
|
|
[catalog.go](../../internal/cli/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](../../internal/cli/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](../../internal/preflight/preflight.go) 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](../../internal/cli/run_input.go) binds typed application inputs
|
|
|
|
|
and repeated literal selections. [execution_overrides.go](../../internal/cli/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](../cli.md#run-wide-llm-overrides) 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](../../internal/cli/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.
|
2026-07-30 02:03:04 +00:00
|
|
|
|
2026-07-26 13:20:18 +00:00
|
|
|
## Run Orchestration
|
|
|
|
|
|
2026-11-22 06:41:22 +00:00
|
|
|
[pipeline_run.go](../../internal/cli/pipeline_run.go) performs the ordered handoff:
|
|
|
|
|
|
|
|
|
|
1. Load/validate the selected application result and derive runtime configuration.
|
|
|
|
|
2. Generate a safe run identity and allocate requested capture.
|
|
|
|
|
3. Capture selected configuration, compose registries, expand reference actions,
|
|
|
|
|
and resolve the effective pipeline.
|
|
|
|
|
4. Obtain the shared engine when needed and perform offline preflight.
|
|
|
|
|
5. Materialize references, construct prepared typed modules, read input bytes,
|
|
|
|
|
and resolve the effective session.
|
|
|
|
|
6. Construct the accepted-result cache and optional recorder collaborator,
|
|
|
|
|
create one native execution group, and invoke the runner with independent
|
|
|
|
|
worker and execution selections.
|
|
|
|
|
7. 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](pipeline.md);
|
|
|
|
|
physical publication/capture collaborators belong in [Run State Internals](state.md).
|
|
|
|
|
|
|
|
|
|
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](../../internal/cli/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](../cli.md#completion-report) owns fields and
|
|
|
|
|
[stream/outcome contract](../cli.md#output-streams-and-exit-statuses) owns process
|
|
|
|
|
behavior. There is no universal Notarius envelope or parallel serializer.
|
|
|
|
|
|
|
|
|
|
## Focused Verification
|
|
|
|
|
|
|
|
|
|
- [Application tests](../../internal/cli/application_test.go) cover lazy built-ins,
|
|
|
|
|
shared scopes, selection evidence, and native diff outcomes.
|
|
|
|
|
- [Loader tests](../../internal/cli/native_load_test.go) and
|
|
|
|
|
[schema tests](../../internal/cli/native_schema_load_test.go) cover native
|
|
|
|
|
composition, captured contexts, and operator contracts.
|
|
|
|
|
- [Pipeline command tests](../../internal/cli/pipeline_commands_test.go) cover
|
|
|
|
|
listing/showing/preflight without execution inputs or state.
|
|
|
|
|
- [Override tests](../../internal/cli/execution_overrides_test.go) and
|
|
|
|
|
[run tests](../../internal/cli/pipeline_run_test.go) cover supplied values,
|
|
|
|
|
routing, references, sessions, and run ordering.
|
|
|
|
|
- [Reference tests](../../internal/cli/reference_contract_test.go) cover selector
|
|
|
|
|
specificity, generated conflicts, and materialization boundaries.
|
|
|
|
|
- [Native executable tests](../../internal/cli/native_process_test.go) cover the
|
|
|
|
|
real command routes and fake-provider presentations.
|
|
|
|
|
- [Completion tests](../../internal/cli/run_result_command_test.go) and
|
|
|
|
|
[recovery contracts](../../internal/cli/recovery_contract_test.go) 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](../development.md#validation) owns wider checks.
|
|
|
|
|
|
|
|
|
|
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md
|