Document native kit integration contracts and ownership
This commit is contained in:
111
docs/integrations/pkg-commandkit.md
Normal file
111
docs/integrations/pkg-commandkit.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user