Files
notarius/docs/integrations/pkg-commandkit.md

112 lines
6.9 KiB
Markdown

# CommandKit Integration
Notarius declares its CLI through the selected native modules:
| Module | Selected release | Attribution |
| --- | --- | --- |
| `go.maximumdirect.net/commandkit` | [v0.7.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0) | [CommandKit](../oss/attribution.md#commandkit) |
| `go.maximumdirect.net/ckconfig` | [v0.10.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/README.md) | [ckconfig](../oss/attribution.md#commandkit-ckconfig) |
| `go.maximumdirect.net/ckprompt` | [v0.11.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/README.md) | [ckprompt](../oss/attribution.md#commandkit-ckprompt) |
[go.mod](../../go.mod) owns declared versions. The integrations are independently
versioned modules in the CommandKit repository; their selected tags/source
revisions are not the root module's tag. The [tagged consumer guide][consumer]
and [CLI contract][cli] own native declaration, parser, reporter, and outcome
mechanics. [Notarius CLI Reference](../cli.md) owns the installed product surface.
## Application Construction And Inputs
Notarius supplies identity, declarations, loaders, and domain handlers to
`commandkit.New`. Native help/version and installed shell completion need no
configuration, engine, provider, or run storage. Application pipeline commands
coexist with the full selected configuration/PromptKit suites; adoption is
implemented, not deferred behind a manual dispatcher.
The run convenience route is `commandkit.Alias`, not a forwarding handler.
Typed flags/arguments carry native `Supplied` values, preserving omission and
explicit empty/false/zero. Native parsing, repeated-value handling, mode ordering,
formats, and progress remain CommandKit-owned. The application chooses the
applicable inputs and their domain validation; it does not reconstruct parsing
or recursively execute another command.
## Configuration Scopes
Notarius installs a `ckconfig.Suite` with invocation state and two adapters:
`FromConfigKit` for the application and `FromConfigKitSubtree` for the native
PromptKit subtree. Both use the original successful application result, not
an engine-owned second configuration load. Overrides are enabled because the
loader actually passes native override records into its selected load.
The selected [adapter API](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/configkit_adapter.go)
owns acquisition/focused-view semantics. Focused display/discovery retains native
root-relative explicit paths, whole-load validation, and source/findings evidence.
The application owns complete-selection result/engine reuse; comparisons retain
distinct sides including overlay/override presence. Native reports/differences
replace copied effective-configuration DTOs.
[ConfigKit integration](pkg-configkit.md) owns the load boundary and
[Configuration Internals](../internal/configuration.md) locates its implementation.
## PromptKit Suite And Run Overrides
Notarius installs `FromEngine` with request validation, request preparation,
smoke testing, namespace selection, and scoped convenience aliases through
`Declarations`. Standard upstream request builders are used without copied
inspection/probe implementations. The engine loader uses the same original
result and invocation state as configuration inspection/runtime.
Inspection/requirements do not call a provider. Concrete validation/preview
perform native request preparation; explicit smoke tests can perform network or
model work and retain native supported/applicable/result distinctions.
Pipeline validation is separately application-owned offline preflight, not a
mode added to native configuration validation.
Application run inputs reuse `NewResourceFlags` and `NewExecutionFlags`, selecting
profile/session and execution controls while leaving prompt/source inputs
module-owned. Native execution overrides reach initial, continuation, and nested
validator requests without mutating loaded settings. The selected
[request-flag API](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/request_flags.go)
owns those reusable values; [PromptKit integration](pkg-promptkit.md) owns engine
execution. Exact installed syntax belongs in [CLI Reference](../cli.md).
## Reports, Diagnostics, And Outcomes
Handlers submit ordinary values through `Invocation.Reporter().Report`, with a
native text template where appropriate. JSON/YAML render the same report value;
there is no Notarius-wide envelope or separate success serializer.
The [completion contract](../cli.md#completion-report) is intentionally small;
domain artifacts, not a saved report, are the durable deliverables.
Native reporting handles result/diagnostic destinations, visibility, progress,
and delivery evidence. Application findings retain process-warning versus
advisory classification. Fallback qualification remains in the report even when
optional warnings are hidden. Requested capture is application work independent
of native verbosity; on success it finishes after publication and before reporting.
Application outcomes retain operation causes separately from native rendering,
output-write, and diagnostic-delivery failures. Post-publication failure retains
valid artifacts/available locations without rerun or repeated terminalization;
failed stdout can be partial. Standard commands keep their native classifications,
including diff differences; [CLI Reference](../cli.md#output-streams-and-exit-statuses)
owns exact statuses/caller behavior. See the upstream
[reporting guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md#invocation-reporting).
## Verification And Ownership
[Application tests](../../internal/cli/application_test.go),
[pipeline/preflight tests](../../internal/cli/pipeline_commands_test.go),
[native override tests](../../internal/cli/execution_overrides_test.go),
[real executable checks](../../internal/cli/native_process_test.go), and
[result-boundary tests](../../internal/cli/run_result_command_test.go) exercise
the actual kits with fake providers and temporary files. [Assembled recovery](../../internal/cli/recovery_contract_test.go)
verifies the same shared load/engine through domain work and publication/capture.
[CLI Internals](../internal/cli.md) locates declarations and orchestration;
[Operations](../operations.md) owns state handling and
[subprocess guidance](../consumers/subprocess.md) owns consumer workflow.
On dependency upgrades, review the core and separately versioned integrations,
installed capabilities, supplied-value/selection behavior, native outcomes,
and notices together rather than assuming root-version parity.
[consumer]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md
[cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md