89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# Consumer guide
|
|
|
|
CommandKit's currently implemented Go API is the root `commandkit` package.
|
|
Start with an `App`, register CommandKit's standard inspection families, register application
|
|
commands, and call `App.Execute` with the caller's context and streams. The
|
|
caller retains process startup, signal handling, and exit mapping.
|
|
|
|
## Go compatibility
|
|
|
|
The consumer minimum is declared in [go.mod](../../go.mod): Go 1.26.0.
|
|
ReleaseKit v0.3.0 requires that version and is selected as a tool dependency in
|
|
the same module graph. The minimum therefore applies to library consumers even
|
|
though production packages do not import ReleaseKit. Consumers using Go 1.25
|
|
need a Go 1.26 or newer toolchain to adopt this revision.
|
|
|
|
The [release policy](../policy/release.md#consumer-minimum-and-release-toolchain)
|
|
defines support assumptions and versioning for changes to that minimum.
|
|
Maintainers select their validation toolchain separately in the
|
|
[release procedure](../release.md#release-toolchain). Updating that toolchain's
|
|
patch version alone leaves the consumer minimum unchanged.
|
|
|
|
## A configuration scope
|
|
|
|
Use [`NewConfigKitScope`](../../config.go) to adapt one ConfigKit loader. The
|
|
loader receives the invocation's explicit `Selection`; the application decides
|
|
how those supplied config and overlay values map to its inputs.
|
|
|
|
```go
|
|
scope, err := commandkit.NewConfigKitScope[appContext, appConfig](
|
|
"app",
|
|
"Application settings.",
|
|
func(ctx context.Context, selection commandkit.Selection, app appContext) (*configkit.Result[appConfig], error) {
|
|
return loadAppConfig(ctx, selection, app)
|
|
},
|
|
)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
err = commandkit.RegisterConfig(app, commandkit.ConfigSuite[appContext]{
|
|
Scopes: []commandkit.ConfigScope[appContext]{scope},
|
|
})
|
|
```
|
|
|
|
`config show`, `config sources`, and `config explain` use the configuration
|
|
captured by that load. A scope can support only the operations it provides.
|
|
When several scopes share invocation-local application state, create it in
|
|
`ConfigSuite.NewContext`; use typed `Selector` bindings to copy only the values
|
|
that apply to each scope. See the [composed example](../../examples/composed/README.md)
|
|
for a cache shared by the `app` and `promptkit` scopes.
|
|
|
|
## PromptKit configuration and definitions
|
|
|
|
Register `NewPromptKitScope` with the config suite when you want the effective
|
|
PromptKit configuration and its ConfigKit provenance available under `config`.
|
|
Register `NewPromptKitSuite` and `RegisterPromptKit` separately to enable
|
|
`promptkit show prompt` and/or `promptkit show profile`. Each adapter calls the
|
|
owning public inspection method and preserves acquisition diagnostics with a
|
|
failed named lookup. Definition inspection does not invoke execution APIs or
|
|
resolve provider credentials.
|
|
|
|
The [composed example](../../examples/composed/README.md) shares its ordinary app and
|
|
engine-loading functions across the configuration and definition suites. It
|
|
also keeps `session restore` as an application-owned typed command, including
|
|
its session data and domain outcome mapping.
|
|
|
|
## Typed application commands
|
|
|
|
Declare flags, operands, and a typed input struct with `NewCommand`. Bindings
|
|
preserve whether a value was explicitly supplied, so an explicit zero can differ
|
|
from an omitted default. `RepeatFlag` retains occurrence order. The
|
|
[simple example](../../examples/simple/README.md) combines both features with a typed
|
|
ConfigKit scope.
|
|
|
|
## Outcomes and process exit
|
|
|
|
Handlers return `Success`, `Failure`, or an application-owned `Outcome`. The
|
|
caller chooses how a nonzero status maps to process exit; `Execute` never exits
|
|
the process. It writes CommandKit diagnostics to the supplied error stream and
|
|
returns the resulting classification and delivery information. Applications
|
|
keep their domain meanings and output in their own handlers.
|
|
|
|
Exact CommandKit contracts are documented on the exported declarations and
|
|
their GoDoc comments. ConfigKit owns configuration decoding and provenance;
|
|
consult its [inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/inspection.go).
|
|
PromptKit owns prompt formats and profile resolution; consult its [public
|
|
engine methods](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/engine.go),
|
|
[configuration inspection](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/configuration_inspection.go),
|
|
and [inspection types](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/types.go).
|