Files
notarius/docs/internal/cli.md

158 lines
8.5 KiB
Markdown
Raw Normal View History

# CLI Internals
`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.
## Run Orchestration
[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