base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Align reporting contracts and documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 05:06:47 +00:00
parent 1289868ed0
commit d14fa366f5
17 changed files with 160 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/consumers/guide.md
View File

@@ -18,17 +18,17 @@ installed at the application root, not as group children.
The published matched releases are core v0.3.0, ckconfig v0.2.0, and ckprompt v0.2.0.
The published ckconfig v0.3.0 uses ConfigKit v1.1.0 and does not compose
with ckprompt v0.2.0, which retains ckconfig v0.2.0 and ConfigKit v0.8.0.
Update application imports and dependency versions together; old and new core
paths have distinct Go type identities. Install core with
Install core with
`go get go.maximumdirect.net/commandkit@v0.3.0` and either integration with
`go get go.maximumdirect.net/ckconfig@v0.2.0` or
`go get go.maximumdirect.net/ckprompt@v0.2.0`.
The current ckprompt source targets ckconfig v0.3.0, ConfigKit v1.1.0, and
PromptKit v0.18.0 using their `go.maximumdirect.net` identities. Its v0.3.0
PromptKit v0.20.0 using their `go.maximumdirect.net` identities. Its v0.3.0
release is a candidate, not a published release. A Go 1.27.0 workspace may
compose all three local modules; independent tests with `GOWORK=off` exercise
the declared releases.
compose all three local modules. The current integration source uses APIs that
require the upcoming core and ckconfig releases; independent validation follows
their publication and dependency alignment.
The two integrations are independent optional imports. `ckprompt` uses the
public scope and error contracts from `ckconfig`; importing it does not add the
@@ -142,6 +142,13 @@ use `Output()` or `RenderOutput()` for deliberate raw output. Use `Warn`, `Info`
[CLI reference](../cli.md#reporting) owns flag grammar, visibility, prefixes,
and status behavior.
Reports use JSON serialization to establish the common value representation
for YAML and JSON. A text template receives the original value; without one,
text uses readable scalar or string-list output and YAML for structured values.
The CLI's shared format selection and the writer-level `RenderReport` use the
same rules. Use `DecodeYAMLReport` only for safe upstream inspection YAML that
must become a report value; ordinary strings are not parsed as YAML.
Return terminal text with `Failure(message, details...)`, `Usage(message,
details...)`, or `WithExplanation` on a domain outcome. Attach an optional Go
error separately with `WithCause`. A cause is preserved for inspection, but it
@@ -167,15 +174,6 @@ invocation are safe concurrently, but concurrent submission order is not
specified. The caller owns the writers passed to `Execute`; CommandKit does not
close them.
### Migrating from the previous reporting API
| Previous API | Current API |
| --- | --- |
| `invocation.Streams.Out` / `.Err` | `invocation.Reporter().Output()` and categorized reporter methods. `Streams` remains the argument to `App.Execute`. |
| `Failure(err)` / `Usage(err)` | `Failure("operator-facing explanation").WithCause(err)` / `Usage("usage explanation").WithCause(err)`. Choose the explanation deliberately; the cause alone is not printed. |
| `Outcome.Diagnostics` or terminal `SeverityError` | Submit independent messages through reporter methods. Put failure context in `Explanation`; provider `Acquired.Diagnostics` remains passive data for the owning integration to submit. |
| `ReportIncomplete`, `DiagnosticDelivery`, or `DeliveryError` | Inspect `Outcome.Presentation.Output` and `.Diagnostics`, including each `DeliveryResult.State`, `RenderError`, and `WriteError`. |
## Application-owned aliases
Pass commands and aliases together as declarations. Integration factories can
@@ -266,6 +264,8 @@ parses CLI records but cannot add them to an already-loaded result. The
engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
it under `config` with validate/show/sources/explain and native diff operations;
it does not install PromptKit catalog, definition, or requirements commands.
Its override feature is disabled because the released PromptKit configuration
loader does not accept ConfigKit override records.
`ckprompt.FromEngine(loadEngine)` supplies nine callbacks: prompt, profile,
backend, namespace, and collection catalogs; named prompt, profile, and backend
@@ -396,19 +396,7 @@ These are independent defaults for unqualified caller-supplied prompt, profile,
and backend names; qualified IDs pass through. Stored references and configuration
inspection are unchanged, while namespace and collection inventories remain global.
Catalog `--namespace` filters are separate from these defaults. See the released
[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go).
### PromptKit configuration migration
The current integration uses identified resource lists and keeps PromptKit's
native default OpenRouter bundle. Loaders can opt out with
`promptkit.WithBundledOpenRouter(false)`. Catalogs and configuration reports
expose the supplied engine's inventory and native source evidence. The
[upstream migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/configuration-migration.md)
covers list records, inheritance, source-root controls, and import requiredness.
Prompt catalog, prompt and requirements inspection, and smoke target reports no
longer carry descriptive prompt versions; collection release labels and source
version evidence retain their own meanings.
[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/namespaces.go).
## Outcomes and ownership
@@ -423,23 +411,7 @@ Go declarations and GoDoc own exact exported contracts. ConfigKit owns
configuration decoding, validation, and provenance. PromptKit owns prompt
formats, profile resolution, and inspection details. See the
[ConfigKit v1.1.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go),
[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go),
[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/configuration_inspection.go),
[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/smoke_diagnostics.go),
and [PromptKit v0.18.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md).
## ConfigKit v1.1 migration
Ckconfig v0.3.0 uses `go.maximumdirect.net/configkit v1.1.0`
and Go 1.27.0. Consumers must migrate ConfigKit imports and values passed to
ckconfig: the old and new package paths have distinct type identities. Source
reports rename `destination_unresolved` to `destination_is_fallback` and
`version_check` to `version_evidence`, and add `empty_import_selections`.
The upstream [v0.9 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md),
[v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md),
[v1.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md),
and [v1.1 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md)
cover source-root `configkit` controls becoming `config`, import requiredness
and defaults, collection registration and operations, removed APIs, and CLI
assignment order.
[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go),
[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/configuration_inspection.go),
[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go),
and [PromptKit v0.20.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md).