Compare commits

...

49 Commits

Author SHA1 Message Date
eedbd83e7e Prepare ckconfig v0.10.0 for release 2026-11-21 21:18:11 +00:00
75949de63c Fix campaign prompt identity resolution 2026-11-21 20:53:36 +00:00
b874b1f076 Record the adoption review finding 2026-11-21 20:38:19 +00:00
e70a0ef301 Record adoption validation and release follow-up 2026-11-21 19:50:40 +00:00
2a086b6389 Document shared loading and integration upgrades 2026-11-21 19:48:59 +00:00
6a090ba571 Share application loading in composed example 2026-11-21 19:46:21 +00:00
ca6cf086f2 Migrate PromptKit integration to shared inspection 2026-11-21 19:43:11 +00:00
41bd3a69d4 Add native configuration subtree scopes 2026-11-21 19:38:35 +00:00
0c9e719312 Use native path readers for discovery 2026-11-21 19:35:13 +00:00
8e51ecf77e Select ConfigKit and PromptKit releases 2026-11-21 19:34:00 +00:00
946181a13e Plan the ConfigKit and PromptKit adoption 2026-11-21 19:25:05 +00:00
320526d3fc Resolve the native inspection adapter API direction 2026-11-21 19:08:44 +00:00
1546122b0b Include native inspection adapter in the adoption scope 2026-11-21 18:55:50 +00:00
71ba758a09 Document ConfigKit and PromptKit adoption roadmap 2026-11-21 18:46:48 +00:00
b1c7962f51 Make the Scriptorium format accessor proposal optional 2026-11-20 02:16:44 +00:00
d330d7637f Complete the coordinated dependency refresh releases 2026-11-17 18:20:43 +00:00
c9a56e1b15 Prepare ckprompt v0.10.0 with aligned released dependencies 2026-11-17 18:19:44 +00:00
9962368f0c Prepare ckconfig v0.9.0 with released CommandKit core 2026-11-17 18:17:47 +00:00
b57bfe176c Prepare CommandKit v0.7.0 and record release coordination 2026-11-17 18:15:55 +00:00
db8f6062af Upgrade dependencies and the release toolchain 2026-11-17 17:53:36 +00:00
29694ea874 Retire the completed PromptKit remediation 2026-11-17 01:18:00 +00:00
5905399ef3 Explain the PromptKit struct literal migration 2026-11-17 01:17:33 +00:00
6b9ccbf88b Record the PromptKit upgrade guidance gap 2026-11-17 01:03:55 +00:00
35e100fd94 Retire completed PromptKit adoption records 2026-11-17 00:54:11 +00:00
b1e7c1ee09 Record PromptKit adoption verification 2026-11-17 00:53:48 +00:00
3112068722 Prepare ckprompt v0.9.0 guidance 2026-11-17 00:53:04 +00:00
49fee9f8ee Verify constructor failure precedence 2026-11-17 00:51:51 +00:00
70b3818351 Cover PromptKit constructor configuration failures 2026-11-17 00:50:50 +00:00
46d63de913 Adopt PromptKit v0.23.1 2026-11-17 00:48:42 +00:00
d107b1235a Finalize the PromptKit adoption plan 2026-11-17 00:11:00 +00:00
8513949c20 Plan PromptKit v0.23.1 adoption 2026-11-16 21:12:17 +00:00
bf45a3fe2c Correct the published integration version table 2026-11-16 19:08:11 +00:00
263dc420b4 Record integration v0.8.0 releases and retire completed plans 2026-11-16 19:07:57 +00:00
6c7d7c90de Prepare ckprompt v0.8.0 with released ckconfig 2026-11-16 19:07:01 +00:00
735b35a0a1 Record completed configuration outcome remediation 2026-11-16 19:03:21 +00:00
21dac4f89e Preserve configuration diagnostics from request builders 2026-11-16 19:02:40 +00:00
9b673d0485 Record configuration outcome review findings 2026-11-16 18:45:50 +00:00
8a22dd6a4f Document configuration outcomes and release handoff 2026-11-16 18:08:33 +00:00
20d2924338 Verify smoke and composed configuration outcomes 2026-11-16 18:06:45 +00:00
2bd216f0d3 Classify PromptKit inspection failures 2026-11-16 18:05:24 +00:00
1c531e7109 Classify configuration command failures 2026-11-16 18:03:24 +00:00
b9cede22f9 Classify configuration loading errors 2026-11-16 18:01:26 +00:00
9d3ffff69f Plan configuration outcome implementation 2026-11-16 17:56:34 +00:00
a53bf9f916 Record configuration classification decisions 2026-11-16 17:46:31 +00:00
ed6060f344 Plan invalid configuration outcome handling 2026-11-16 17:36:31 +00:00
1e92a87706 Record completed integration releases 2026-11-10 15:34:42 +00:00
f369d6a782 Prepare ckprompt v0.7.0 with released ckconfig 2026-11-10 15:33:47 +00:00
64f6453b84 Adopt PromptKit v0.21.0 and prepare integration release notes 2026-11-10 15:30:59 +00:00
07a329033c Adopt ConfigKit v1.2.0 in both integrations 2026-11-10 15:13:00 +00:00
69 changed files with 3249 additions and 458 deletions

View File

@@ -477,8 +477,8 @@ records preserve their returned order. No records are
output begins with the scope heading and prints the same source fields,
quoting labels and paths. These fields come from ConfigKit's source records;
producing the report does not reload files or rerun version checks. See the
[ConfigKit v1.1.0 source
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go)
[ConfigKit v1.4.0 source
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/records.go)
for native evidence definitions.
### Explain a configuration path
@@ -502,7 +502,12 @@ occurred in history; `--under POINTER` selects a subtree, and `--explicit=true`
or `--explicit=false` filters current paths by native explicitness. Historical-only
paths do not match an explicitness filter. These options require `--list`.
The report contains the scope and each selected path's current presence and,
when present, its explicitness. Path discovery does not include values or history.
when present, its explicitness. Path discovery does not include values or
history. Focused scopes list their native candidates, such as paths beneath
`/promptkit`; explicit `--path`
queries use native whole-load paths, including outside the focus where supported.
A scope is not an access-control boundary. Sources and diagnostics retain the
whole load's evidence.
Pointer tokens use JSON Pointer escaping: `~1` represents `/` and `~0`
represents `~`. A malformed pointer is a usage error with status `2` and is
@@ -599,7 +604,10 @@ concise report contains `additions`, `changes`, and `deletions`. Additions and
changes keep the configuration's path structure and show right-side values
from the comparison. Deletions are JSON Pointer paths. Explicit null is a
value, not a deletion. Changed lists and regions replaced as a whole are shown
as whole values.
as whole values. Focused scopes render the selected subtree and compare native
views; differences at an atomic ancestor can remain in the result. An absent
focused effective value can fail output delivery, while an explicit null remains
null.
ConfigKit considers sensitivity on both sides. A secret value can change even
when both redacted snapshots look the same. For those ConfigKit-backed
@@ -622,8 +630,9 @@ fields remain distinct.
Without `--check`, successful comparisons return status `0`, including empty
results. Unsupported scopes and formats are usage errors. Application input
checks can report usage or operational failures. Load and comparison failures
use status `1`.
checks can report usage or operational failures. Configuration load failures
follow the [configuration failure classification](#configuration-failure-classification);
other comparison failures use status `1`.
The bundled adapters load the left side before the right. Diagnostics identify
the side and its sources; left-side diagnostics are retained if right loading
@@ -665,9 +674,10 @@ request overrides. Backend reports describe configured backend fields. An
`api_key_env` value names an environment variable; it is not a credential
value or a claim that one is available. Neither report resolves references or
performs a network probe. See the [PromptKit resource inspection
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/resource_inspection.go).
Omitting the ID is a usage error. Lookup failures and cancellation follow the
shared operational failure rules.
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/resource_inspection.go).
Omitting the ID is a usage error. Configuration loading follows the
[configuration failure classification](#configuration-failure-classification);
lookup failures and cancellation are operational.
### Resource namespace selection
@@ -720,8 +730,10 @@ text output use YAML. Preparation can read resources and include rendered
application content in the report. It does not guarantee that a later model
call will succeed. Application loaders and callbacks may have their own
effects. The [PromptKit Prepare
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go)
owns the prepared value and upstream preparation behavior.
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go)
owns the prepared value and upstream preparation behavior. Configuration failures
follow the [configuration failure classification](#configuration-failure-classification);
other preparation failures are operational.
## PromptKit requirements
@@ -754,8 +766,8 @@ identity rather than changing the discovered requirements. An enabled profile
namespace qualifies an explicitly supplied short profile ID; it does not
rewrite the prompt's stored default reference. Requirements inspection does
not require the selected profile to be execution-ready. See the [PromptKit
v0.20.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md)
v0.24.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md)
for configuration, selection, and requirements behavior. For built-in flags
other than `--llm-var`, repeating a flag uses its last value.
Application-defined flags follow their own repetition rules.
@@ -806,9 +818,10 @@ issues:
PromptKit determines these findings and explanations. A partial report can
still be a successful command result (status `0`); read `complete` and
`issues` to understand what remains unknown. A reported issue alone does not
fail this command. Load or selection failures, cancellation, and report
delivery failures use status `1`. Invalid syntax, arguments, variable
assignments, or formats use status `2`.
fail this command. Configuration loading follows the [configuration failure
classification](#configuration-failure-classification). Selection failures and
cancellation use status `1`; invalid syntax, arguments, variable assignments,
or formats use status `2`. Report delivery follows the [output failure rules](#output-failures).
### Concrete request validation
@@ -865,9 +878,11 @@ applicable. It does not make a model call or retain a prepared execution
snapshot. A successful report describes this preparation invocation; it does
not certify provider acceptance or guarantee later execution. See PromptKit's
[`Engine.ValidateRequest`
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go).
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go).
Request construction, engine loading, and validation failures use status `1`,
Configuration errors returned by request construction or engine loading follow
the [configuration failure classification](#configuration-failure-classification).
Other request construction, loading, and validation failures use status `1`,
retaining available diagnostics. Malformed syntax, missing arguments, and
unsupported formats use status `2`. Messages follow the common reporting
policy; report delivery failures follow the shared [output failure
@@ -929,9 +944,10 @@ The entries are:
A catalog result is an inventory, not a readiness check or execution result.
The owning provider controls membership and order. Namespace filters are
passed to PromptKit without local membership interpretation. See the
[PromptKit v0.20.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md)
for resource and selection definitions.
[PromptKit v0.24.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md)
for resource and selection definitions. Catalog loading failures follow the
[configuration failure classification](#configuration-failure-classification).
## PromptKit smoke testing
@@ -965,10 +981,13 @@ Status `0` means the requested operation and reporting completed without
error. It does not mean every check passed: inspect the reported facts,
`reason`, and whether the test was supported, applicable, and completed. For
`all`, all four operations must return without error for status `0`.
Individual errors use status `1`; the sequence continues after them but stops
on cancellation, preserving results already obtained. A report returned with
an error is still shown. Invalid syntax, arguments, formats, or conflicting
namespace flags use status `2`.
Configuration errors use the [configuration failure classification](#configuration-failure-classification);
other individual errors use status `1`. For `all`, every failing operation must
identify invalid configuration input to select status `2`; an operational
failure or cancellation takes precedence. The sequence continues after errors
but stops on cancellation, preserving results already obtained. A report
returned with an error is still shown. Invalid syntax, arguments, formats, or
conflicting namespace flags use status `2`.
### Smoke-test flags
@@ -1097,19 +1116,35 @@ separately from delivery failures through the [reporting
API](consumers/guide.md#invocation-reporting).
Native configuration, selection, and diagnostic meanings remain owned by
PromptKit. See the [v0.20.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go).
PromptKit. See the [v0.24.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go).
## Outcome status
| Status | Standard meaning |
| --- | --- |
| `0` | The operation succeeded. |
| `1` | Loading, execution, cancellation, or output failed. |
| `2` | The command syntax or supplied inputs were invalid. |
| `1` | An operational loading or execution failure, cancellation, or output failure occurred. |
| `2` | The command syntax, supplied inputs, or identifiable configuration input were invalid. |
| `3` | `config diff --check` found differences. |
### Configuration failure classification
Standard configuration and PromptKit commands classify ConfigKit loading errors
using their structured diagnostics. Identifiable invalid configuration input,
including malformed YAML, decoding errors, and explicit semantic rejection,
selects status `2`. Warnings do not fail a load. Missing or unreadable sources,
schema and application wiring errors, callback failures, unknown or ambiguous
diagnostics, and other failures select status `1`. An error with multiple
failing branches selects status `2` only when every branch identifies invalid
input; cancellation or a deadline always selects status `1`. Existing source
and validation reports can still be delivered after a failed load. Filters on
validation details do not change classification.
With the current ckprompt candidate, malformed PromptKit companion YAML from
engine construction follows this same classification, with available diagnostics
and typed causes retained.
Applications may define additional results and decide how CommandKit's status
maps to the process exit code. A command's successful status does not replace
reading its report: partial requirements discovery and unsupported smoke

View File

@@ -14,27 +14,48 @@ applications.
| `go.maximumdirect.net/ckconfig` | You want operators to view, validate, explain, and compare ConfigKit configuration. |
| `go.maximumdirect.net/ckprompt` | You want operators to inspect PromptKit resources, check and preview requests, or run smoke tests. |
The following lists the current release set and earlier module combinations:
ckconfig v0.9.0 and ckprompt v0.10.0 select ConfigKit v1.2.1.
ckprompt v0.10.0 selects PromptKit v0.23.2.
| Selection | Core | ckconfig | ckprompt | Upstream libraries and status |
| --- | --- | --- | --- | --- |
| Published core | v0.6.0 | — | — | Usable independently. |
| ConfigKit integration | v0.6.0 | v0.6.0 | — | ConfigKit v1.1.0. |
| PromptKit integration | v0.6.0 | v0.6.0 | v0.6.0 | ConfigKit v1.1.0 and PromptKit v0.20.0. |
| Published core | v0.7.0 | — | — | Usable independently. |
| ConfigKit integration | v0.7.0 | v0.9.0 | — | ConfigKit v1.2.1. |
| PromptKit integration | v0.7.0 | v0.9.0 | v0.10.0 | ConfigKit v1.2.1 and PromptKit v0.23.2. |
| Earlier matched integration set | v0.3.0 | v0.2.0 | v0.2.0 | ConfigKit v0.8.0 and PromptKit v0.16.0, using their earlier import paths. |
For applications moving from ckprompt v0.8.0, the
[v0.9.0 upgrade notes](../../integrations/ckprompt/docs/releases/v0.9.0.md#compatibility-and-upgrade)
cover migration of positional literals for affected native PromptKit structs.
Install the published core with:
```sh
go get go.maximumdirect.net/commandkit@v0.6.0
go get go.maximumdirect.net/commandkit@v0.7.0
```
Select either integration with `go get go.maximumdirect.net/ckconfig@v0.6.0`
or `go get go.maximumdirect.net/ckprompt@v0.6.0`. The integrations select core
v0.6.0, and ckprompt selects ckconfig v0.6.0, which includes `AdaptDiagnostics`.
They build independently against these released dependencies; a local workspace
is optional for development. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0
and does not compose with ckprompt v0.2.0's earlier ConfigKit dependency.
Select either integration with `go get go.maximumdirect.net/ckconfig@v0.9.0`
or `go get go.maximumdirect.net/ckprompt@v0.10.0`. Both integrations select
core v0.7.0. ckprompt v0.10.0 selects ckconfig v0.9.0, which includes
`AdaptDiagnostics` and `ClassifyConfigurationError`. Those published releases
build independently. The current checkout adopts
ConfigKit v1.4.0 and PromptKit v0.24.0; ckprompt uses the new local ckconfig API
while still requiring published ckconfig v0.9.0. Use an aligned workspace until
ckconfig is released and selected by ckprompt.
Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 and does not compose with
ckprompt v0.2.0's earlier ConfigKit dependency.
ConfigKit v1.2.0 adds fields to `Input` and `LayeredOptions`, so application
loaders should use keyed struct literals when constructing them. ConfigKit's
release notes describe
main-relative imports and overlay contexts. [ConfigKit v1.2.0 upgrade guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/releases/v1.2.0.md#upgrade-notes).
The current checkout selects PromptKit v0.24.0. Complete documents put
settings under `promptkit`; wrapperless fragments use `SettingsInput`, and
collection fragments use `CollectionInput`. Consult the [upstream migration
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md)
and [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md)
for the exact migration and schema rules.
Importing a module does not install its commands. Pass commands to
`commandkit.New` or `App.Register` explicitly. ckprompt depends on ckconfig's
@@ -43,13 +64,14 @@ the `config` family.
## Go compatibility
Core declares a consumer minimum of Go 1.26.0; both current integration
modules require Go 1.27.0. The root module also
selects ReleaseKit v0.9.0 (`go.maximumdirect.net/releasekit`) as a Go tool, which
All three modules in the current checkout declare a consumer minimum of
Go 1.27.0. Core v0.7.0 raises its minimum from v0.6.0's Go 1.26.0. The root module
selects ReleaseKit v0.10.0 (`go.maximumdirect.net/releasekit`) as a Go tool, which
makes that tool's module graph part of the root consumer module requirements
even though production packages do not import ReleaseKit. The
even though production packages do not import ReleaseKit. ReleaseKit v0.10.0
requires Go 1.27.0 and raises core's consumer minimum from Go 1.26.0. The
[release policy](../policy/release.md#consumer-minimum-and-release-toolchain)
defines the support assumption. Maintainers use Go 1.27.0 for validation and
defines the support assumption. Maintainers use Go 1.27.4 for validation and
publication; see the [release procedure](../release.md#release-toolchain).
## Core commands
@@ -291,6 +313,14 @@ separate initialization calls do not guarantee distinct objects. See
[ckconfig.Suite's GoDoc](../../integrations/ckconfig/contracts.go) for factory
timing, omitted-factory zero values (including nil pointers), and ownership.
The application owns the state type and what it caches.
`ckconfig.FromConfigKitSubtree(name, summary, path, load)` adapts the same typed
loader to a focused native inspection. The loader validates the whole result;
its sources and findings retain whole-load context. Listing uses the focused
native paths, while explicit paths and comparison retain native semantics. The
[composed example](../../integrations/ckprompt/examples/composed/main.go) uses
this adapter for `storage` and passes the same application result to
`promptkit.NewFromConfig`. The application composes `promptkit.Configure` and
selects `BundledOpenRouterUnderlay` before loading when it needs that catalog.
`ckconfig.FromConfigKit` adapts a typed ConfigKit loader without calling it
during construction. The bundled comparison adapters call the loader for the
left side before the right, retain left diagnostics if right loading fails,
@@ -302,14 +332,20 @@ The `config` family provides scope discovery, validation, safe effective configu
source inventory, path explanation, and ConfigKit-backed comparison for the
capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
owns operator syntax and report details. `Scope.Features` declares optional modes; acquired
`View.Metadata` and `View.Findings` carry native path metadata and diagnostic
records when available. `Findings.Messages` contains presentations associated
`View.Paths` supplies native discovery candidates; when nil, `View.Metadata`
supplies them for existing custom providers. Metadata remains required for
filtering and describing candidates. `View.Findings` carries diagnostic records
when available. `Findings.Messages` contains presentations associated
with those records, while `Acquired.Diagnostics` carries independent messages.
Custom explanation providers implement `Explain`; CommandKit renders the
acquired evidence. See `EffectiveWriter` and `ExplanationReader` in the
[ckconfig GoDoc](../../integrations/ckconfig/contracts.go) for the provider boundary.
`ckconfig.AdaptDiagnostics` captures native diagnostic presentation evidence
for applications providing their own ConfigKit-backed CLI integration.
[`ckconfig.ClassifyConfigurationError`](../../integrations/ckconfig/errors.go)
provides the standard CLI outcome classification for ConfigKit errors; callers
construct their own outcomes, explanations, and causes. The [CLI reference](../cli.md#configuration-failure-classification)
describes the standard commands' status behavior.
Set `Scope.Features.Overrides` only when the loader passes
`Selection.Overrides` to ConfigKit as part of its normal load. The integration
parses CLI records but cannot add them to an already-loaded result. The
@@ -321,8 +357,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.
Its override feature is disabled by default. Applications may enable it only
when their own loader applies the supplied overrides.
### Install resource commands and optional checks
@@ -366,7 +402,9 @@ If the loader is nil, the returned suite retains a wiring issue for installation
to report, even if capabilities are narrowed later. A builder runs before the
engine loader and receives the seed request, selection, typed input, shared
state, and invocation context. It returns the
concrete request; the adapter does not merge seed fields back afterward. The
concrete request; the adapter does not merge seed fields back afterward. For
validation replacements use `*promptkit.OutputContractInput`: a nil repair
budget remains omitted and a pointer to zero explicitly disables repair. The
loader receives the original selection. Builders should start from the seed,
preserve operator values and bindings, and apply defaults only when a map key is
absent, so explicitly supplied empty values stay meaningful. Applications that
@@ -399,6 +437,12 @@ and state. `FromEngine` uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`; validation must be opted into separately
and uses `Engine.ValidateRequest`.
Applications own engine construction and may build complete native requests in
callbacks. Preparation and validation use the supplied context; execution owns
prepared notifications and operation timeouts. See the [PromptKit consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md)
for conversation and execution capabilities.
`ckprompt.WithRequestPreparation` adds a separate callback backed by
`Engine.Prepare`. Its optional builder receives the seeded request and returns
the complete request to prepare. The resulting native report can contain
@@ -435,7 +479,7 @@ complete return value is authoritative. The [CLI reference](../cli.md#promptkit-
and reports.
The [composed example](../../integrations/ckprompt/examples/composed/README.md)
combines app and PromptKit config scopes, comparison and catalogs, named and
combines app, storage, and PromptKit config scopes, comparison and catalogs, named and
requirements inspection, request validation, smoke testing, and an
application-owned `session restore` command.
@@ -459,7 +503,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/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/namespaces.go).
[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/namespaces.go).
## Outcomes and ownership
@@ -473,8 +517,8 @@ signal handling, and exit mapping; `Execute` never exits the process.
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/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).
[ConfigKit v1.4.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/records.go),
[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go),
[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/configuration_inspection.go),
[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/smoke_diagnostics.go),
and [PromptKit v0.24.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md).

View File

@@ -108,7 +108,7 @@ Sibling-checkout references in retired planning records are historical review
evidence, not build dependencies. Implemented contracts belong in CommandKit
under their canonical owners.
The root module does not traverse nested modules. With Go 1.27.0 on `PATH`,
The root module does not traverse nested modules. With Go 1.27.4 on `PATH`,
create the local workspace from the repository root if `go.work` is absent:
```sh
@@ -118,13 +118,15 @@ go work init . ./integrations/ckconfig ./integrations/ckprompt
If a workspace already exists, ensure it includes these three modules. Preserve
the ignored `go.work` and `go.work.sum`; do not commit them. Use
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
and independent module suites. Both integrations select released core v0.6.0;
ckprompt also selects released ckconfig v0.6.0. Their declared dependencies
support independent builds. The aligned workspace exercises the local sources
together.
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module
directory. From the repository root, a workspace containing all three modules can
also run:
and independent module suites. Both integrations select released core v0.7.0;
ckprompt currently selects released ckconfig v0.9.0 but uses the new local
ckconfig API. Until the coordinated release, isolated validation uses a temporary
local replacement as described in the [implementation plan](roadmap/implementation.md#stage-7-validate-the-result-and-record-release-coordination);
the independent suite against published requirements remains pending.
The aligned workspace exercises local sources together. Run the independent
suites for core and ckconfig with `GOWORK=off GOTOOLCHAIN=local go test ./...`
from each module directory. From the repository root, a workspace containing
all three modules can also run:
```sh
GOTOOLCHAIN=local go test ./...

View File

@@ -91,7 +91,9 @@ Cobra and pflag imports remain inside this package.
`integrations/ckconfig` owns ConfigKit adaptation, scope capture, the standard
`config` command family, and native validate/show/sources/explain/diff behavior.
It depends on the public core facade and ConfigKit; it does not depend on
PromptKit. Each selected scope or comparison side receives an independently
PromptKit. Whole-result and subtree scopes share loader and diagnostic adaptation;
subtree scopes delegate focused path enumeration and comparison to native
ConfigKit inspection. Each selected scope or comparison side receives an independently
initialized input, while one suite-owned state value is shared by an invocation's
acquisitions or comparison callback.

View File

@@ -2,18 +2,18 @@
## Cobra
Selected module: `github.com/spf13/cobra` at `v1.10.1`.
Selected module: `github.com/spf13/cobra` at `v1.10.2`.
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE.txt](https://github.com/spf13/cobra/blob/7da941c3547e93b8c9f70bbd3befca79c6335388/LICENSE.txt).
[LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/spf13/cobra/tree/7da941c3547e93b8c9f70bbd3befca79c6335388).
[Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## pflag
Selected module: `github.com/spf13/pflag` at `v1.0.9`.
Selected module: `github.com/spf13/pflag` at `v1.1.0`.
Copyright (c) 2012 Alex Ogier. All rights reserved.
@@ -22,13 +22,13 @@ Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/spf13/pflag/blob/10438578954bba2527fe5cae3684d4532b064bbe/LICENSE).
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://github.com/spf13/pflag/tree/10438578954bba2527fe5cae3684d4532b064bbe).
[Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).
## go-yaml v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov
@@ -38,14 +38,14 @@ Copyright 2025 The go-yaml Project Contributors
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
## go-yaml v3
Selected module: `gopkg.in/yaml.v3` at `v3.0.1` (transitive dependency).
Selected module: `go.yaml.in/yaml/v3` at `v3.0.4` (transitive dependency).
Copyright (c) 2006-2010 Kirill Simonov
@@ -55,10 +55,10 @@ Copyright 2011-2016 Canonical Ltd.
License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/c3552c15f996075a7634df5159d9161c67bf3d76/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/c3552c15f996075a7634df5159d9161c67bf3d76/NOTICE).
[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
[Source](https://github.com/yaml/go-yaml/tree/c3552c15f996075a7634df5159d9161c67bf3d76).
## go-md2man
@@ -144,52 +144,54 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
## ReleaseKit
Selected module: `go.maximumdirect.net/releasekit` at `v0.9.0` (selected Go tool; not a runtime import).
Selected module: `go.maximumdirect.net/releasekit` at `v0.10.0` (selected Go tool; not a runtime import).
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3.0](../../LICENSE) |
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/LICENSE).
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243).
## Goldmark
Selected module: `github.com/yuin/goldmark/v2` at `v2.1.6` (ReleaseKit tool dependency).
Selected module: `github.com/yuin/goldmark/v2` at `v2.1.16` (ReleaseKit tool dependency).
Copyright (c) 2019 Yusuke Inuzuka
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[LICENSE](https://github.com/yuin/goldmark/blob/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c/LICENSE).
[LICENSE](https://github.com/yuin/goldmark/blob/c3f939122ba4dd6f80e05043ad195b82e77fcb41/LICENSE).
[Source](https://github.com/yuin/goldmark/tree/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c).
[Source](https://github.com/yuin/goldmark/tree/c3f939122ba4dd6f80e05043ad195b82e77fcb41).
## Go modules
Selected module: `golang.org/x/mod` at `v0.40.0` (ReleaseKit tool dependency).
Selected module: `golang.org/x/mod` at `v0.43.0` (ReleaseKit tool dependency).
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f/LICENSE).
[LICENSE](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde/LICENSE) |
[PATENTS](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde/PATENTS).
[Source](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f).
[Source](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde).
## Go tools
Selected module: `golang.org/x/tools` at `v0.49.0` (ReleaseKit tool graph dependency).
Selected module: `golang.org/x/tools` at `v0.52.0` (ReleaseKit tool graph dependency).
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/tools/+/18332fec72972efbb8ab9881984fec2d8cfc2b58/LICENSE).
[LICENSE](https://go.googlesource.com/tools/+/16517d951552611e7bd358c48ee1051fd0e57b0c/LICENSE) |
[PATENTS](https://go.googlesource.com/tools/+/16517d951552611e7bd358c48ee1051fd0e57b0c/PATENTS).
[Source](https://go.googlesource.com/tools/+/18332fec72972efbb8ab9881984fec2d8cfc2b58).
[Source](https://go.googlesource.com/tools/+/16517d951552611e7bd358c48ee1051fd0e57b0c).

View File

@@ -25,7 +25,7 @@ additional release requirements.
CommandKit independently versions three source-only Go modules: the root core,
`integrations/ckconfig`, and `integrations/ckprompt`. Standard CLI behavior is
exposed by consuming applications; CommandKit does not declare binary
deliverables or a cross-platform build matrix. ReleaseKit v0.9.0 is selected as
deliverables or a cross-platform build matrix. ReleaseKit v0.10.0 is selected as
the maintainer publication tool. Maintainers may separately deliver page-only
Gitea releases from tagged source; delivery has its own outcome and URL. The
[release procedure](../release.md) owns the selected-module workflow, release

View File

@@ -39,34 +39,34 @@ module profile enforces the endpoint. The maintainer needs the selected
This procedure follows the [release policy](policy/release.md); release-note
footers follow the [OSS discoverability policy](policy/oss.md#discoverability).
ReleaseKit v0.9.0 (`go.maximumdirect.net/releasekit`) owns candidate validation,
ReleaseKit v0.10.0 (`go.maximumdirect.net/releasekit`) owns candidate validation,
publication guards, tag creation, tag publication, and outcome reporting.
Its pinned public contracts are the
[CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/cli.md),
[profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/config.md),
the [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/publish.md),
and the [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/delivery.md).
[CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/cli.md),
[profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/config.md),
the [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/consumers/publish.md),
and the [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/consumers/delivery.md).
The repository selects one default module suite per invocation. The launcher
uses the root module’s registered tool with native host settings and read-only
module metadata.
## Release toolchain
The selected release toolchain is **Go 1.27.0**. Core declares a
consumer minimum of **Go 1.26.0**; both integrations require **Go 1.27.0**. Maintainers
use Go 1.27.0 for dependency preparation, candidate validation, and ReleaseKit
The selected release toolchain is **Go 1.27.4**. All three modules declare a
consumer minimum of **Go 1.27.0**. Maintainers use Go 1.27.4 for dependency
preparation, candidate validation, and ReleaseKit
execution. The
[consumer guide](consumers/guide.md#go-compatibility) and
[release policy](policy/release.md#consumer-minimum-and-release-toolchain)
describe these selections.
Select Go 1.27.0 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed,
Select Go 1.27.4 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed,
install it with the standard Go tools:
```sh
GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.27.0@latest
go1.27.0 download
export PATH="$(go1.27.0 env GOROOT)/bin:$PATH"
GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.27.4@latest
go1.27.4 download
export PATH="$(go1.27.4 env GOROOT)/bin:$PATH"
hash -r
GOWORK=off GOTOOLCHAIN=local go version
```
@@ -96,7 +96,7 @@ integration directory. Future tag URLs need not resolve before publication.
All three release profiles explicitly select the repository-root `COPYRIGHT`,
`LICENSE`, and `docs/oss/attribution.md` through `validation.shared_files`.
ReleaseKit requires these committed files to exist in the candidate. The list
does not expand Go validation scope; see the pinned [profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/config.md).
does not expand Go validation scope; see the pinned [profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/config.md).
Each integration also distributes its own `COPYRIGHT`, `LICENSE`, and
`docs/oss/attribution.md`. These module-local materials are separate from the
@@ -200,9 +200,9 @@ Reconciliation observes the recorded endpoint, full tag, and tag object without
rerunning candidate validation or changing tags. It distinguishes confirmed
publication, current absence, conflict, and an unresolved observation. Current
absence does not prove that a version was never published. The pinned
[CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/cli.md#recover-a-saved-publication-attempt-or-discover-local-attempts)
[CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/cli.md#recover-a-saved-publication-attempt-or-discover-local-attempts)
owns recovery statuses and structured output; the
[publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/publish.md#retain-and-reconcile-publication-evidence)
[publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/consumers/publish.md#retain-and-reconcile-publication-evidence)
describes record storage and recovery entry points.
If no usable record was saved, use the exact endpoint, full tag, and annotated
@@ -232,7 +232,7 @@ worktree and index, then deliver the selected module's page:
The profile derives the full module-specific tag from the version. Delivery
uses the checked-in release note as a page-only body and reports its own outcome
and URL separately from source publication. Retry later from the same original
tagged source. The pinned [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/delivery.md)
tagged source. The pinned [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/docs/consumers/delivery.md)
owns delivery and retry behavior.
A nonblank `RELEASEKIT_GITEA_TOKEN` takes precedence over the repository-relative

29
docs/releases/v0.7.0.md Normal file
View File

@@ -0,0 +1,29 @@
# CommandKit v0.7.0
CommandKit v0.7.0 refreshes the CLI, YAML, and maintainer-tool dependencies.
## Dependency updates
- Cobra v1.10.1 → v1.10.2 and pflag v1.0.9 → v1.1.0 update CLI parsing,
help, and diagnostics. Cobra also selects the maintained YAML v3 module path.
- go-yaml v4.0.0 replaces v4.0.0-rc.6 for report decoding and encoding.
- ReleaseKit v0.10.0 updates maintainer tooling and selects Goldmark v2.1.16
and Go Modules v0.43.0.
## Compatibility and upgrade
The core consumer minimum increases from Go 1.26.0 to Go 1.27.0 because the
registered ReleaseKit tool now requires Go 1.27.0. Upgrade the Go toolchain
before selecting this release. Maintainer validation uses Go 1.27.4.
Applications continue to use the existing CommandKit APIs and standard command
grammar. Review scripts that depend on exact backend diagnostic or help text
when adopting the parser updates. The current CLI and reporting contracts are
documented in the [CLI reference](../cli.md), and the
[consumer guide](../consumers/guide.md#module-selection) records module pairing.
Coordinated ckconfig and ckprompt releases follow this core release under the
[dependency-alignment policy](../policy/release.md#commandkit-downstream-dependency-alignment).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/oss/attribution.md)

View File

@@ -0,0 +1,280 @@
# ConfigKit v1.4.0 and PromptKit v0.24.0 adoption
Status: implementation complete; coordinated releases pending. Prepared 2026-11-21.
This document defines the desired target and accepted scope, not implemented
behavior or authorization to publish releases. The
[implementation plan](implementation.md) owns execution stages and completion
evidence.
## Purpose and ownership
Adopt the released upstream capabilities through the existing operator command
suite. `ckprompt` should neutrally expose PromptKit's public APIs, using the
implementation with the lowest conceptual complexity and the least
CommandKit-owned domain machinery. ConfigKit and PromptKit continue to own
loading, resolution, validation, preparation, inspection, and comparison.
Applications own construction, startup, credentials, and execution workflows.
Core owns shared CLI parsing, reporting, and delivery.
For this adoption, minimize complexity borne by applications first, then
complexity maintained by ckconfig. These priorities take precedence over a more
tailored operator experience. Prefer native paths, whole-load evidence, and
existing outcome handling to extra machinery for more polished subtree reports.
The [architecture policy](../policy/architecture.md) and
[integration ADR](../adr/0004-optional-integration-modules.md) govern these
boundaries. Native delegation preserves upstream meaning; it does not require
removing useful existing CLI projections, filters, or outcome handling.
This adoption introduces no additional ordering, copying, concurrency,
serialization-stability, or isolation guarantees.
## Baseline and upstream targets
Reviewed repository revision: `b1c7962f51eb9e81104a291bc1966a90b4e772a3`.
| Component | Baseline | Adoption target |
| --- | --- | --- |
| CommandKit core | v0.7.0 | No core change required by this scope |
| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0, native scoped path enumeration, and a public native-inspection adapter |
| ckprompt | v0.10.0; PromptKit v0.23.2, ConfigKit v1.2.1, ckconfig v0.9.0 | PromptKit v0.24.0, ConfigKit v1.4.0, and the resulting released ckconfig |
| Go | Consumer minimum 1.27.0; release toolchain 1.27.4 | No change required by these upstream releases |
Adoption covers the intervening ConfigKit v1.3.0 and PromptKit v0.23.3 changes.
Use the released versions, not unreleased upstream work. The reviewed release
commits are ConfigKit `4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3` and PromptKit
`5ea60e9b96651fd7dfcbc7d05b6f43d131df358f`.
Upstream sources:
- [ConfigKit v1.3.0: configured secrets bootstrap](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.3.0/docs/releases/v1.3.0.md).
- [ConfigKit v1.4.0: typed value access and focused inspection](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md).
- [PromptKit v0.23.3: timeout and cancellation identities](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/releases/v0.23.3.md).
- [PromptKit v0.24.0: shared loading, schemas, and preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/releases/v0.24.0.md).
- [PromptKit configuration migration](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md)
and [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md).
The pre-adoption review used a temporary copy with only dependency declarations
and checksums updated. The ckconfig package and simple-example suites passed.
The ckprompt production packages built, but its test package failed to compile
because `constructor_outcomes_test.go` uses removed `WithSchemaFile`; seven
top-level composed-example tests failed with the old configuration layout.
An offline shared-load probe confirmed both automatic reporting of the new
prepared hash and repair budget, and the path-listing mismatch described below.
These observations establish migration work; they are not final acceptance
evidence for the implementation.
## Targeted end state
### One application-owned load, existing integration callbacks
The maintained composed example demonstrates an application configuration with
`promptkit.Settings` under `promptkit`, rules composed with `promptkit.Configure`,
and a completed ConfigKit result passed directly to `promptkit.NewFromConfig`.
The application result serves configuration inspection and the engine serves
PromptKit commands through the existing loader callbacks and shared invocation
state. This removes the example's separate reconstruction and loading of
PromptKit configuration where the shared result supplies that information.
The example should make source selection, campaign-derived settings, and
comparison sides understandable. Any reused result must correspond to the
requested selection and relevant application inputs; left and right comparisons
still receive their independently selected configurations. Reuse remains an
application choice, not a CommandKit cache or a new promise about load counts.
Preserve the meaningful selector and lifecycle demonstrations when restructuring
the example.
Select `BundledOpenRouterUnderlay` before the application-owned load when the
example intends to include that catalog. `NewFromConfig` does not add it or
rerun configuration callbacks. `NewEngine` remains a supported standalone
construction path. No CommandKit constructor wrapper is needed for either path.
`Result.Value` supplies trusted current Go values, potentially including resolved
secrets and shared references. It is not a replacement for safe inspection in
CLI reports. Continue to use upstream frozen, redacted evidence for configuration
output; the application's handoff follows upstream ownership semantics.
### Native scoped inspection
PromptKit's configuration inspection now focuses on `/promptkit`. Its
`HistoricalPaths()` enumerates that focus, while `Metadata()`, source evidence,
and explicit path queries retain whole-load context. For example, a load with
`app_name` and `promptkit` should not acquire `/app_name` in the PromptKit path
list merely because that path exists in the original load's metadata.
Currently, [ckconfig's explanation handler](../../integrations/ckconfig/explain.go)
enumerates `View.Metadata.HistoricalPaths()`. The
[PromptKit adapter](../../integrations/ckprompt/adapters.go) supplies full metadata,
so this bypasses upstream's new focused enumeration.
Provide the narrow capability needed for the shared handler to enumerate native
inspection paths. `ckprompt` supplies PromptKit's `HistoricalPaths()` directly;
ckconfig uses metadata to describe the returned paths' presence and explicitness.
Ordinary whole-result scopes continue to enumerate their native metadata paths.
The [implementation plan](implementation.md#stage-2-separate-native-path-enumeration-from-metadata-lookup)
selects the narrow provider extension and preserves existing custom-provider
behavior. This capability is not a parallel inspection model.
Retain the existing CLI filters (`--under`, `--historical`, and `--explicit`) on
the supplied enumeration. Preserve native application paths, such as
`/promptkit/profiles/0/model`, without rebasing or adding compatibility aliases
for the former document layout. Explicit `--path` queries use upstream semantics,
including queries outside the focus where upstream supports them. Selecting a
scope is not an access-control boundary.
Continue native comparison and source reporting. Do not filter away upstream
ancestor differences or trim the source catalog to manufacture isolation.
Focused rendering reports the selected subtree; explicit root queries retain
their native whole-document meaning. An absent effective subtree and explicit
null retain their upstream distinction and errors through the existing report
delivery mechanism. Do not invent an empty configuration to hide absence.
### Public native-inspection adapter
Include a reusable ckconfig adapter in this adoption and the next ckconfig
release. It registers a named configuration scope backed by ConfigKit's native
subtree inspection, reducing application wiring for effective settings, path
discovery, explanations, source evidence, and comparison. Applications retain
configuration acquisition and selection; the adapter supplies standard CLI
integration and delegates domain operations to ConfigKit.
The adapter shares the native path-enumeration capability. The maintained
composed example demonstrates one application section, such as storage settings.
The section name is illustrative, not a new reserved scope.
Preserve load diagnostics and error evidence through existing reporting and
outcome conventions. A focused inspection does not independently validate a
subtree or make whole-load evidence local to it.
Use a small sibling of `FromConfigKit`, with `FromConfigKitSubtree` as the planned
helper name. The application supplies a scope name and summary, an explicit
`configkit.Path`, and its existing typed loader returning
`(*configkit.Result[T], error)` with the same context, selection, input, and state
parameters as `FromConfigKit`. The helper returns the existing `Scope[I, S]`.
Applications need not assemble diagnostic bundles, translate errors, or create
an intermediate inspection representation.
The adapter obtains source and diagnostic evidence from the result and selects
the native view with `InspectSubtree(path)`. For comparison, it acquires each
side's result, selects the same subtree, and calls native `Inspection.Diff`.
Share existing acquisition and diagnostic/error handling where useful without
introducing a general framework solely to remove repeated lines.
Retain whole-load diagnostics and validation outcomes. Successful loads with
warnings remain usable; detailed validation retains native findings and sources
through the existing presentation conventions. On failed loading, preserve
available ConfigKit load-error evidence and supported error identity. Other
application errors remain errors without invented ConfigKit findings. Reuse
existing classification and duplicate-presentation handling; do not silently
filter evidence to the selected subtree, ignore failures elsewhere in the load,
or create an independent subtree-validation result.
This release targets exposing a section from an ordinary typed application
result. An additional entry point for already selected inspection views and
accommodation of different root Go types across comparison sides are outside
this adoption. An options framework is unnecessary for the single path argument.
PromptKit uses the shared inspection capability directly. It need not pass
through this new helper if that would require converting its public inspection
type merely to fit the helper. The accepted API and evidence direction is recorded
in OD-2 below; the [implementation plan](implementation.md) owns the exact
declaration and internal factoring within that direction.
### Existing commands expose the new upstream evidence
| Operator task | Existing command | Adoption behavior |
| --- | --- | --- |
| Inspect a prompt's output contract | `promptkit show prompt ID` | Report native inline schema or schema references and resolved repair budget, including zero |
| Preview the completed request | `promptkit show prepared ID` | Report native `message_content_hash`, resolved contract, and prepared schema evidence without model execution |
| Discover inputs or validate a request | `promptkit requirements show ID`, `promptkit requirements validate ID` | Preserve upstream effective requirements, including application defaults, and current preparation/error semantics |
| Inspect configuration and provenance | `config show`, `sources`, `explain`, `diff`, `validate` with `--scope promptkit` | Use native focused inspection and retain supporting whole-load evidence |
| Exercise native smoke checks | `promptkit test ...` | Continue forwarding selected requests and presenting native evidence and errors |
Prompt and prepared reports already hand native values to the core reporter.
Keep that path so new fields appear without a second renderer or a local hash
implementation. Existing projections, such as requirements reports, should retain
the meaning of the updated native results. Hash semantics, schema resolution,
repair behavior, and error identities remain upstream-owned.
## Compatibility and delivery
The adopted configuration uses native `/promptkit` locations for complete
settings documents and inspection paths; resource IDs retain their names.
Wrapperless fragments and collection fragments use the corresponding upstream
input helpers. Removed schema options are replaced by supported inline,
source-relative, or explicit-root selection. The upstream migration and format
references above own their exact rules. Successful construction alone is not
migration evidence: old root-level resources can become application data while
disappearing from PromptKit catalogs.
Request builders use the upstream input contract for validation replacements,
including optional repair budgets. Native resolved repair budgets, including
zero, and schema/hash evidence reach reports without a local substitute.
The upstream enabled repair default may add a generation call, latency, and
usage to application execution. Applications retain resource-version policy and
sensitivity decisions for their extension fields. The adoption also retains the
intervening PromptKit timeout and cancellation identity corrections.
Canonical GoDoc, CLI, consumer, developer, internal, and candidate release
guidance should agree with the completed integration. The maintained composed
example demonstrates shared loading and the native subtree adapter. Validation
protects CommandKit's acquisition, selection, adaptation, reporting, and outcomes;
upstream libraries own validation of their domain algorithms. Tests remain
offline and credential-independent.
The independently versioned integration releases explain the changed provider
API and breaking PromptKit migration under the [release policy](../policy/release.md).
The coordinated target is released ckconfig followed by ckprompt selecting that
release, with the downstream integration advancing at least its minor version.
The [release runbook](../release.md) owns preparation and publication operations.
Local workspace validation and isolated checks with a local dependency are
identified separately from independent validation against released requirements.
Any remaining release coordination stays recorded until completed.
No core release is needed solely for this adoption. Unrelated core work,
including the optional Scriptorium proposal, is not a prerequisite. The
[implementation plan](implementation.md) owns dependency migration, focused
coverage, candidate preparation, validation commands, and completion records.
## Scope retained outside this adoption
The existing [future work record](future.md) retains output-contract override
flags, appended-message flags, secrets-bootstrap commands, and other deferred
capabilities. ConfigKit v1.3.0's configured bootstrap and overwrite options remain
available to application startup code without a new CommandKit command.
This roadmap selects no new commands, engine-construction convenience API,
automatic configuration migration, core cache, or application execution workflow.
These are scope decisions for this adoption, not additional permanent prohibitions.
## Resolved decisions
### OD-1: Include the native-inspection adapter in this adoption — closed
Include the helper in the next ckconfig release, as part of this roadmap.
Its implementation overlaps the required native enumeration work; designing both
together provides a concrete second use of the shared boundary and avoids
revisiting that boundary immediately after release. Keep the adapter focused on
standard CLI scopes and direct upstream inspection. Preserve native comparison
semantics for the views accepted by the selected API.
The previous deferral recommendation is superseded.
### OD-2: Typed result loader, subtree path, and existing evidence handling — closed
Adopt the result-loader-plus-path approach described under
[public native-inspection adapter](#public-native-inspection-adapter).
Prioritize application simplicity, then ckconfig implementation simplicity, over
tailoring the inspection command's presentation. The complete result already
supplies source and diagnostic evidence; accepting the application's ordinary
loader avoids a new handoff envelope or application-owned adaptation layer.
Use native paths and comparison, retain whole-load diagnostics and failures,
and reuse existing reporting and outcome conventions. Keep the helper focused
on the selected task; do not add an options framework or another entry point for
arbitrary inspection views in this adoption. Supporting preselected views and
different root types would require a broader acquisition handoff and is not
needed for the selected application workflow.
## Execution status
The [staged implementation plan](implementation.md) records the completed local
work and validation evidence. The coordinated integration releases remain pending
as recorded in [future work](future.md#pending-integration-release-coordination).

View File

@@ -1,6 +1,7 @@
# Future work
Status: optional shell validation and future capability proposals.
Status — integration release coordination, optional shell validation, and future
capability proposals.
No delivery dates are selected here.
## Purpose and authority
@@ -25,11 +26,35 @@ and remediation records remain available at the
[Earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap)
also remain in Git history. Completed records are not assignments to restart work.
The completed configuration-outcome implementation and remediation are preserved
in the [v0.8.0 retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/6c7d7c90de4deea8be38b2a447b5c957d748d1b0/docs/roadmap).
The completed PromptKit v0.23.1 adoption, companion-YAML report, and
verification evidence are preserved in the [adoption snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b1e7c1ee09bf4fb7845b3b5222ccb448ac7fb468/docs/roadmap).
The completed adoption review and upgrade-guidance remediation are preserved
in the [remediation snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5905399ef3b23ee405bb31a50e534b139cef2e05/docs/roadmap/remediation.md).
Accepted [ADRs](../adr/) and the [architecture policy](../policy/architecture.md)
govern any future implementation. The [CLI reference](../cli.md), public GoDoc,
and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining
an idea here does not select its syntax, API, priority, or delivery date.
## Pending integration release coordination
The ConfigKit v1.4.0 and PromptKit v0.24.0 adoption is implemented locally;
publication remains separate. Follow the [release procedure](../release.md)
and obtain the required publication authorization. Prepare and release ckconfig
v0.10.0 first. Then select that actual release in ckprompt, tidy with real
checksums, update matching-version attribution, and run ckprompt's independent
default suite before preparing its v0.11.0 release. Core remains v0.7.0 for this
adoption. Candidate notes and planned versions must be checked again at release
time. Hosted delivery is separately authorized.
The current ckprompt checkout still requires published ckconfig v0.9.0, which
lacks the new path-reader API. Its aligned workspace and isolated local-replace
tests passed; those checks do not establish an independent build against the
published requirement. See the [implementation record](implementation.md) for
the validation evidence and upstream missing-file error-identity limitation.
## Optional verification
### Optional shell completion validation

View File

@@ -0,0 +1,444 @@
# ConfigKit and PromptKit adoption implementation plan
Status: implementation complete; coordinated releases pending. Prepared 2026-11-21.
Implementation baseline: `320526d3fc92fac7795b4b5e65c623181680452d`.
## Authority and execution
Implement the accepted [feature roadmap](configkit-v1.4.0-promptkit-v0.24.0.md)
in the numbered order below. That document owns intent, scope, upstream targets,
and resolved decisions. This plan selects the API shape, implementation steps,
and completion evidence for a Luna coding agent.
Read [development guidance](../development.md), the applicable policies in its
reading guide, and ADRs [0003](../adr/0003-configuration-scopes.md) and
[0004](../adr/0004-optional-integration-modules.md). Prefer the codebase knowledge
graph for code discovery. Inspect the actual worktree before editing and preserve
unrelated work, ignored workspace files, and local credentials.
This is one end-to-end implementation sprint. Continue through all stages without
intermediate approval or compilation gates. Earlier stages may temporarily fail
to build while later migrations are pending. Resolve failures before declaring
the implementation complete. After a focused unit is complete, record its actual
evidence here and commit it under the [agent policy](../policy/agents.md).
Do not create empty commits or claim checks that have not run.
Implementation approval authorizes the implementation and local commits. Source
publication and hosted delivery follow the [release procedure](../release.md)
when separately authorized. Publication is follow-up coordination, not an internal
gate in this sprint. Stage 7 defines honest pre-publication validation when
ckprompt needs the new, still-unpublished ckconfig API.
Use the existing command families, reporters, classification, and provider
lifetimes. Keep domain resolution, schemas, validation, preparation, redaction,
and comparison upstream. Do not add a core cache, new commands, constructor
wrapper, arbitrary-view adapter, cross-root-type loader API, or options framework
for this adoption. The roadmap's scope choices do not establish permanent bans.
## Stage 1: Select the released upstream dependencies
Status: complete.
Evidence: With Go 1.27.4 and the workspace disabled, selected the specified
versions using `go get`, ran `go mod tidy` and `go mod download` in both
integrations, and reviewed the module graphs, checksums, and selected upstream
copyright and license material. The upstream license texts match the previously
selected versions; the remaining selected transitive versions are unchanged.
Updated both integration attribution entries. The existing workspace includes
all three modules. The independent ckconfig suite passed. The ckprompt suite
currently fails on removed `WithSchemaFile` and unmigrated composed-example
resources; those migrations are assigned to Stages 4 and 5.
1. With Go 1.27.4 on `PATH`, update ConfigKit to v1.4.0 in both integration
modules and PromptKit to v0.24.0 in ckprompt. Keep core v0.7.0, the root
module's requirements, and the consumer minimum of Go 1.27.0 unless an actual
dependency requirement demonstrates a necessary change.
2. Prepare dependencies from each integration directory using `GOWORK=off
GOTOOLCHAIN=local go get` for these exact versions, then download/tidy actual
dependencies and review the resulting requirements and checksums. Leave
ckprompt's ckconfig requirement at published v0.9.0 until the new ckconfig
is published. Do not record a fictitious future checksum or commit a local
replacement to make the new API appear published. Repeat tidy after source
migration if temporary compilation errors prevent it now.
3. Use the existing ignored workspace containing the root and both integrations
for development. Preserve it, or create it following the developer guide if
absent. Do not depend on sibling upstream checkouts.
4. Review the selected upstream license and notice material and update affected
module-local and root attribution entries under the [OSS policy](../policy/oss.md).
ConfigKit's selected source is `4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3`;
PromptKit's is `5ea60e9b96651fd7dfcbc7d05b6f43d131df358f`. Update changed
transitive entries only where the selected graphs warrant it. Finalize graph
and notice review after the migrations; no unrelated dependency sweep.
Completion evidence: reviewed integration module diffs and genuine sums selecting
the two target releases. Record any temporary test/build failures as migration
work for subsequent stages, not reasons to stop.
## Stage 2: Separate native path enumeration from metadata lookup
Status: complete.
Evidence: Added the optional native path reader and metadata fallback, populated
whole-result views, and exercised selected candidates, empty readers, the legacy
fallback, and discovery filters alongside existing missing-metadata coverage.
`GOWORK=off GOTOOLCHAIN=local go test ./...` passed in ckconfig with Go 1.27.4.
Primary files: [contracts.go](../../integrations/ckconfig/contracts.go),
[explain.go](../../integrations/ckconfig/explain.go), and
[configkit_adapter.go](../../integrations/ckconfig/configkit_adapter.go).
1. Add this narrow public capability alongside the existing reader interfaces:
```go
type PathReader interface {
HistoricalPaths() []configkit.Path
}
```
Add `Paths PathReader` to `View`. It supplies the native discovery candidates.
`Metadata` continues to supply presence, explicitness, and history. Update
GoDoc for `View`, `PathReader`, and `ScopeFeatures.PathDiscovery` together.
2. In `runConfigExplanation` listing mode, retain the metadata requirement.
Enumerate `View.Paths.HistoricalPaths()` when `Paths` is nonnil; otherwise
enumerate `View.Metadata.HistoricalPaths()` for existing custom providers.
A nonnil reader returning nil or an empty slice means an empty native list,
and must not trigger the fallback. Apply the existing `--under`,
`--historical`, and `--explicit` filters to those candidates using metadata.
Keep explicit-path handling on `ExplanationReader`.
3. Populate whole-result `FromConfigKit` views with their metadata as the path
reader. Keep native paths and existing report projection. This change does
not require new sorting, deduplication, path rebasing, or metadata copying.
4. Extend existing discovery tests with a reader whose candidates exclude a
real metadata sibling, a valid empty reader, and the legacy nil-reader
fallback. Exercise the existing filter meanings on supplied candidates.
Retain missing-metadata failure coverage instead of creating a second path
metadata model.
Completion evidence: focused ckconfig discovery coverage proves that enumeration
comes from the supplied capability while metadata still describes each path.
Existing whole-result discovery remains supported.
## Stage 3: Add the typed-result subtree scope adapter
Status: complete.
Evidence: Added the typed loader and native subtree adapter, sharing acquisition
and comparison coordination with the whole-result adapter. Offline scope and CLI
tests cover focused output and paths, explicit outside-focus explanations,
whole-load warnings and failures, error identity, absence and null, unavailable
inspection, and native comparison including an atomic ancestor. The independent
ckconfig suite passed with Go 1.27.4 and `GOWORK=off GOTOOLCHAIN=local`.
Add the following public sibling of `FromConfigKit` in the ckconfig package:
```go
func FromConfigKitSubtree[I, S, T any](
name, summary string,
path configkit.Path,
load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
) Scope[I, S]
```
1. Declare the same operations and path features as `FromConfigKit`. Retain its
application-owned loader, input/state, selection, and operation-list
customization conventions. Attach a nil-loader construction error with
`WithScopeError`; declaration/help/discovery must not invoke loading.
2. Share ordinary result acquisition and diagnostic adaptation with
`FromConfigKit` through a small private helper. Preserve the existing
handling of `LoadError`, nonnil results accompanying other errors, nil-result
failures, findings, sources, and terminal explanations. A successful result
remains the source of whole-load diagnostics. Do not expose a new envelope
or callback framework to applications.
3. After successful loading, call `result.InspectSubtree(path)`. Use the returned
inspection for `Effective`, `Explanation`, and `Paths`, and its whole-load
metadata and sources for the corresponding fields. Keep `Findings` from the
result. If selection returns `false`, return a contextual operational error
with the already acquired source/diagnostic evidence. This covers invalid
paths and results without captured inspection. Do not classify an unavailable
view as invalid user configuration without supporting native evidence.
4. A valid absent scope is a successful acquisition, not an unavailable view.
Let its native writer report an unavailable effective value through existing
show/render delivery handling. Preserve explicit null. Explicit queries,
including root and paths outside the focus, continue to use native semantics.
5. Reuse `loadComparisonSide` and the existing pair-loading cancellation and
diagnostic accumulation conventions. Extract the common pair-acquisition
portion privately if needed to avoid duplicating that coordination. Select
the same path from both successful results and call `leftView.Diff(rightView)`.
Preserve existing left/right selection inputs, shared state, warnings,
explanations, cause wrapping, and checks before the next acquisition or diff.
Do not filter native ancestor differences or compare rendered YAML.
Keep ordinary `FromConfigKit` on its existing same-type `configkit.Diff`.
6. Add focused public-scope/CLI coverage, using real offline ConfigKit results:
focused show/list/explain with a sibling outside the focus; native diff with
distinct selections; whole-load warnings and failed-load findings outside
the focus; and error identity/outcomes for loader failure. Reuse existing
evidence and delivery tests where they already protect the shared path.
Cover valid absence versus null and unavailable inspection without building
an upstream inspection conformance suite. Compare representative diff values
to native results, including a retained atomic ancestor where applicable.
Completion evidence: standard scope commands expose a native subtree using only
the ordinary typed loader and path. Whole-load failures remain failures and
available evidence survives adaptation. Exported GoDoc describes this handoff.
## Stage 4: Migrate ckprompt adapters, fixtures, and boundary coverage
Status: complete.
Evidence: Migrated discovered settings fragments to `/promptkit`, exposed native
inspection paths, and added shared-load, requirements, schema, prepared-hash,
and request-replacement coverage. `GOTOOLCHAIN=local go test
./integrations/ckprompt` passed in the aligned workspace with Go 1.27.4. The
missing-main-file constructor retains PromptKit's invalid-config identity and
produces an operational outcome with native load diagnostics. ConfigKit's
`LoadError` explicitly does not unwrap underlying filesystem errors, so this
native error cannot also match `os.ErrNotExist` as originally anticipated;
the separate joined-error case verifies forwarding of that identity when supplied.
The composed example migration remains in Stage 5.
Primary files: [adapters.go](../../integrations/ckprompt/adapters.go), the
integration's existing configuration/comparison/preparation/requirements tests,
and [constructor outcomes](../../integrations/ckprompt/constructor_outcomes_test.go).
1. Set successful `ConfigScope` views' `Paths` directly to PromptKit's native
`ConfigurationInspection`. Retain its native effective writer, explanation,
full metadata, sources, diagnostics, and native comparison. Do not convert
it into a ConfigKit result to route it through the new adapter.
2. Migrate complete-document test/configuration mappings beneath `promptkit`.
Mount wrapperless fragments through `SettingsInput`, and collection fragments
through `CollectionInput`. Discovery-produced fragments require an explicit
destination when they are not whole documents. Update override paths,
explanation assertions, and comparison paths to native locations such as
`/promptkit/profiles/0/model`; resource IDs and references retain their names.
Review inline maps, byte strings, embedded files, and filesystem fixtures,
not just YAML files. In particular review composition and comparison fixtures.
3. Replace any `Config.SchemaDir`, `WithSchemaFS`, or `WithSchemaFile` uses with
the selected release's supported schema configuration/resource contexts.
In `TestPromptConstructorFailurePrecedence`, replace the missing-schema
constructor with a missing main configuration file passed to `NewEngine`.
Retain the intended operational outcome and `os.ErrNotExist`/PromptKit cause
identity checks, plus joined-error and cancellation precedence. Retain the
real malformed companion-YAML regression and its structured load evidence.
Schema-file failures now belong to preparation, so exercise their forwarding
there only where needed to protect a distinct adapter path.
4. Migrate request-builder replacements to `*promptkit.OutputContractInput`
wherever used. Forward the whole replacement with pointer-valued repair
budgets; omitted stays omitted and explicit zero stays zero. Do not insert
the former repair default. Keep ordinary `OutputContract` uses for resolved
prepared results where that is the upstream type.
5. Keep prompt and prepared values on the existing native reporting path.
Extend focused report tests to compare native returned inline/reference
schema fields, repair-budget zero, and `message_content_hash` with CLI report
values. Preserve text/JSON/YAML behavior through shared serialization tests
and a small representative format selection, not an exhaustive cross-product
of fields and formats. Do not calculate expected hashes locally.
6. Verify requirements projections preserve the native result, including input
metadata supplied by application defaults. Keep preparation, validation,
namespace, smoke, cancellation, diagnostic, and outcome adaptation semantics.
Use existing boundary tests for supported error identities; PromptKit owns
tests of its v0.23.3 HTTP timeout/cancellation algorithms.
7. Add a shared-load fixture with a genuine application sibling outside
`/promptkit`. Through `ConfigScope`, prove list candidates follow native
`HistoricalPaths`, filters still apply, explicit outside-focus paths retain
native behavior, and full source/diagnostic evidence remains available.
Expected values come from native inspection rather than a local scope filter.
Completion evidence: migrated ckprompt package coverage passes in the aligned
workspace and resource-selection assertions detect silently unmigrated catalogs.
The composed example is completed in Stage 5.
## Stage 5: Demonstrate shared loading and the subtree adapter
Status: complete.
Evidence: The composed example loads application defaults, bundled and local
resources, campaign-derived settings, and storage in one ConfigKit result;
the engine consumes that result and the storage scope uses the subtree adapter.
Updated fixtures and tests exercise native paths, shared inspection and reuse,
storage show/explain/diff and overrides, whole-load failure evidence, and the
existing campaign, comparison, catalog, and lifecycle cases. With Go 1.27.4,
`GOTOOLCHAIN=local go test ./integrations/ckprompt/examples/composed` passed in
the aligned workspace.
Update the maintained [composed example](../../integrations/ckprompt/examples/composed/main.go),
its fixtures, and its existing tests. A separate consumer example is unnecessary.
1. Add `PromptKit promptkit.Settings` with `yaml:"promptkit"` to
`appConfiguration`, plus an illustrative typed `storage` section. Keep the
existing campaign data, selector presence, request-builder, session outcome,
alias, completion, and injected-client demonstrations.
2. Move the example's generated resources into the application load. Compose
its definition using `promptkit.Configure` with the settings selector.
Supply the existing local collection and common prompt resources as an
application-owned mapping underlay beneath `promptkit`, so selecting a main
fixture retains the example resources. Keep application defaults in the
application definition. Retain the example's bundled OpenRouter catalog
by selecting `BundledOpenRouterUnderlay()` before this load, once in its input
composition. Engine construction must not perform a second configuration load.
3. Derive campaign-specific profiles and prompt defaults during the application
definition's resolve callback, before PromptKit's composed resolve callback.
Use ConfigKit's resolution recording helpers for changes, with native
`/promptkit/...` paths and relevant campaign dependencies. This keeps frozen
inspection and engine settings consistent. Do not mutate the completed
result's settings to inject a campaign before handing it to the engine.
Preserve existing campaign selection and override precedence, including
explicit empty selections and native conflicting-override errors.
4. Keep `loadApplicationConfig` as the ordinary result loader, retaining its
application-owned successful-result reuse keyed by the full selection and
campaign presence/value. Keep failed loads out of that reuse. In
`loadPromptEngine`, pass that result directly to `promptkit.NewFromConfig`
with `RuntimeConfig` and the existing injected LLM client. Remove the separate
PromptKit source reconstruction and `NewEngine` call from this shared path.
Keep standalone `NewEngine` fixtures elsewhere as supported usage.
5. Register a `storage` scope with `FromConfigKitSubtree`, the existing result
loader, and `configkit.Keys("storage")`. Enable overrides for this scope
because that loader supports them. Apply the existing campaign selector and
its comparison counterpart to this scope as well; retain the app-only limit
selector and input checks. Keep PromptKit scope capability declarations at
their existing supported settings; shared loading itself does not require
expanding its advertised override modes.
6. Give before/after fixtures distinct storage values while retaining campaign
differences. Extend existing tests to demonstrate subtree show/explanation
and comparison through the standard commands and available failed-load
diagnostics. Use package-level adapter tests for the fuller evidence matrix.
Update `--scope all` expectations to include the new application scope and
the fact that the `app` whole-result view now includes PromptKit settings.
7. Retain tests distinguishing left/right configuration, campaigns, overrides,
and repeated invocation state. Confirm help/completion do not acquire an
engine, catalogs still contain selected IDs, and preparation does not call
the LLM client. Smoke examples use the existing local injected client.
Test successful reuse as example behavior, without creating a library-wide
exact-load-count contract or redesigning its small cache.
Completion evidence: existing composed-example coverage plus focused subtree
cases passes offline. Both scope adapters consume the same application-owned
result for corresponding selections, and comparison sides remain independent.
## Stage 6: Update canonical guidance and candidate release notes
Status: complete.
Evidence: Updated GoDoc, CLI, consumer, development, internal, and composed
example guidance, plus candidate notes for ckconfig v0.10.0 and ckprompt
v0.11.0. Neither candidate tag exists locally or on `origin`. Reviewed selected
module graphs and upstream license material; affected attribution was updated
in Stage 1 and no transitive version changed. Local Markdown links and fragments
passed a repository link check, `git diff --check` passed, and the ckprompt
workspace suite including the example passed with Go 1.27.4. Publication and
the ckprompt released-dependency update remain pending.
1. Finish exported GoDoc and package guidance in both integrations. Document
`View.Paths` precedence and metadata fallback, the subtree helper signature,
typed loader ownership, whole-load validation/evidence, and native path/diff
behavior. Keep exact upstream format rules linked to the selected releases.
2. Update [CLI guidance](../cli.md) for native scoped listings and explicit paths,
focused rendering, source evidence, and comparison. Update the
[consumer guide](../consumers/guide.md) with the maintained shared-load and
storage-scope example, upstream migration links, and request-builder changes.
Update [development guidance](../development.md) and internal documentation
where the changed mechanics affect them. Describe the local development
dependency state accurately until release coordination is finished.
3. Write candidate notes for ckconfig v0.10.0 and ckprompt v0.11.0. These are the
next minor targets from the reviewed v0.9.0/v0.10.0 baselines. Check existing
notes/tags before creating them; if another release has consumed either
target, use the next appropriate fresh minor and adjust candidate references.
The release command performs authoritative publication guards later.
4. The ckconfig note covers the new adapter and optional reader. Adding a public
`View` field can require migration of positional struct literals; recommend
keyed fields and explain the metadata fallback for existing custom scopes.
The ckprompt note covers the upstream breaking configuration/API migration,
native path changes, removed schema options and explicit schema roots,
`OutputContractInput`, resolved repair-budget zero/defaults, new prepared
evidence, and whole-load context. Mention possible extra generation latency
and usage from upstream's enabled repair default. Include positional
`PreparedRun` literal migration and older JSON's missing-hash behavior where
relevant, linking upstream for its exact contract.
5. Preserve upstream ownership of resource-version policy and extension-field
sensitivity. Keep unrelated deferred CLI capabilities in `future.md`.
Add the required module-specific immutable release footer to each candidate
note. Do not rewrite previously published notes or tags.
6. Finalize affected attribution against the selected module graphs. Review prose
diffs, local links/fragments, copied notices, commands, examples, and future
tag URL paths under the documentation/OSS policies. Published compatibility
tables must distinguish available releases from these candidates.
Completion evidence: canonical guidance and candidate notes agree with the
implemented APIs and examples, have valid local navigation, and describe the
remaining dependency release coordination without claiming publication.
## Stage 7: Validate the result and record release coordination
Status: complete.
Evidence: With Go 1.27.4, `GOWORK=off GOTOOLCHAIN=local go test ./...`
passed separately in core and ckconfig; ckconfig `go mod tidy` and `go mod
download` completed without further changes. From the root, the aligned
workspace commands `GOTOOLCHAIN=local go test ./...`, `go test
./integrations/ckconfig/...`, and `go test ./integrations/ckprompt/...` all
passed. For isolated ckprompt validation, copied its module files to a temporary
directory, replaced ckconfig with the local module only in that temporary
modfile, ran tidy and `GOWORK=off GOTOOLCHAIN=local go test -modfile=... ./...`,
and removed the temporary files; both package and example passed. This is not
independent validation against the published ckconfig v0.9.0 requirement.
Reviewed the module and attribution diffs, focused evidence, prose whitespace,
and local links and fragments. No core optional dependencies were introduced.
The remaining release order and dependency validation are recorded in
[future work](future.md#pending-integration-release-coordination). The Stage 4
record explains the upstream missing-file error-identity limitation.
1. Format changed Go files, finish tidy/download with the workspace disabled
where the module can resolve its selected APIs, and inspect all module and
attribution diffs. Keep downloaded checksum evidence real. Root should not
acquire optional integration dependencies.
2. With Go 1.27.4 selected, run the complete affected independent/default suites
and the aligned workspace suites. From the root, use these commands:
```sh
(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test ./...)
GOTOOLCHAIN=local go test ./...
GOTOOLCHAIN=local go test ./integrations/ckconfig/...
GOTOOLCHAIN=local go test ./integrations/ckprompt/...
```
Run ckprompt's ordinary independent suite once its required ckconfig release
is selected. Before publication, that suite cannot resolve the new API from
its v0.9.0 requirement. For isolated development validation, copy
ckprompt's `go.mod` and matching `go.sum` to a temporary directory, add a
temporary `replace go.maximumdirect.net/ckconfig => ABSOLUTE_LOCAL_CKCONFIG`
with `go mod edit -modfile=...`, and run tidy and `GOWORK=off GOTOOLCHAIN=local
go test -modfile=... ./...` from the ckprompt directory. Remove the temporary
files afterward. Label this result as isolated validation against local
ckconfig, not independent validation against its published requirements.
Do not block subsequent sprint work on the publication dependency.
3. Review focused evidence from Stages 2–5 against the roadmap's targeted end
state. Reuse successful checks for unchanged content. No performance
benchmarks, live provider calls, new CI gates, or mandatory expanded matrices
are needed for this adoption. Investigate concrete failures and rerun the
affected checks after fixes.
4. Run prose whitespace checks and validate affected local links/fragments,
including new notes. Review intended new files as well as tracked diffs.
Record actual commands, outcomes, and any remaining independent-dependency
limitation here; do not mark unrun checks passed.
5. Record pending release coordination in `future.md` before retiring any
completed planning records. Keep this plan's implementation completion
separate from publication status. The follow-up order is ckconfig first,
then ckprompt with that actual released ckconfig selected, real sums/tidy,
updated matching-version attribution, and its independent default suite.
Core remains v0.7.0 for this scope. Follow the runbook for candidate commits,
authorized pushes/tags, and separately authorized hosted delivery. The release
command runs candidate validation itself; no duplicate mandatory preflight.
6. Review and commit the completed implementation units and records under the
agent policy. Report changed APIs and migration requirements, tests and their
limits, commit identifiers, and the pending coordinated integration releases.
Do not pause midway for an approval already covered by implementation scope.
Completion evidence: all implementation-stage work is finished, focused and
workspace checks pass, ckconfig passes independently, documentation is validated,
and any ckprompt published-dependency validation still awaiting release is
explicitly recorded. Eventual adoption completion includes both coordinated
releases; this sprint does not claim that follow-up has occurred.
## Open Questions
None. The feature roadmap resolves product scope and adapter direction; this
plan selects the remaining API, migration, example, and validation approach.

100
docs/roadmap/remediation.md Normal file
View File

@@ -0,0 +1,100 @@
# ConfigKit and PromptKit adoption review
Reviewed revision: `e70a0ef301a3d34f64a6cba86dd68b728436534d`.
Status: all findings addressed. Reviewed and remediated 2026-11-21.
## Scope and results
Reviewed all seven stages of the [implementation plan](implementation.md)
against the accepted [feature roadmap](configkit-v1.4.0-promptkit-v0.24.0.md),
the implementation, changed tests, and documentation.
| Stage | Review result |
| --- | --- |
| 1 — Dependencies | Both integrations select ConfigKit v1.4.0; ckprompt selects PromptKit v0.24.0. Core and the Go minimum remain at the planned versions. Changed attribution identifies the selected upstream commits. |
| 2 — Native path enumeration | Optional `View.Paths` and the metadata fallback preserve the distinction between an unavailable reader and an empty native list. Existing metadata-backed filters remain in use. |
| 3 — Subtree adapter | The typed loader/path API shares acquisition and diagnostics, delegates focused inspection and comparison, and retains whole-load evidence and native ancestor differences. |
| 4 — PromptKit migration | Native inspection supplies the new path capability; fixtures use the new destinations. Native schema, repair-budget, hash, requirements, and supported error evidence pass through the existing adapters. |
| 5 — Shared-load example | Shared loading and storage scope wiring are present. The campaign prompt-ID defect identified in R1 has been corrected. |
| 6 — Documentation | Current guidance and candidate notes describe the new APIs and migration, distinguishing candidates from published dependencies. |
| 7 — Validation and coordination | Workspace and isolated-local-dependency checks pass. The ckprompt released-dependency limitation and coordinated releases are explicitly pending as planned. |
No additional strengthened contract, prohibition, or guarantee requiring
remediation was identified. The recorded ConfigKit filesystem-error identity
limitation follows the upstream error contract and is not an integration defect.
## R1 — Campaign prompt-ID changes fail configuration resolution
Priority: P2. Status: completed 2026-11-21.
Completion: the resolver now records prompt-ID normalization at the collection
path, retaining the existing reason and campaign dependencies. Added
`TestComposedCampaignPromptID` for a main configuration selecting `custom`;
it verifies successful loading, matching application/engine inspection values,
and the selected ID in the CLI catalog. The test failed before the fix and
passed afterward. The original override reproduction also now succeeds.
Relevant code: the application resolve callback in
[`loadApplicationConfig`](../../integrations/ckprompt/examples/composed/main.go),
particularly the prompt-ID assignment and resolution record at lines 136–138.
This is maintained example code; the generic scope adapters are not the cause.
When the selected campaign's `prompt_id` differs from `briefing`, the callback
renames the example's default prompt. It records normalization only at
`/promptkit/prompts/<index>/id`. `promptkit.Configure` registers this list as an
identified sequence. Changing an identity changes collection membership, which
requires a record covering the list or an ancestor under ConfigKit's
[resolution contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/docs/config.md).
The leaf record does not cover that change.
Reproduced from `integrations/ckprompt/examples/composed` with Go 1.27.4 and the
aligned workspace:
```sh
GOTOOLCHAIN=local go run . config validate --scope app \
--set '/campaigns/spring/prompt_id="custom"' --format json
```
Actual behavior: loading fails with `resolve.unrecorded_change` at
`/promptkit/prompts`, the report marks the app scope failed, and the application
exits with status 1. The same failure occurs when a main configuration selects
that campaign prompt ID. Because resolution is shared, it also prevents engine
construction and inspection through other scopes for that configuration.
Expected behavior: the application result and engine expose the selected valid
campaign prompt ID, with a correctly recorded derivation. The earlier example
constructed the prompt with `chosen.PromptID`; Stage 5 requires preservation of
campaign selection while moving its derivation into the shared load. Neither
the campaign configuration nor the roadmap restricts the ID to `briefing`.
Remediation: record the membership change at `promptPath`
(`/promptkit/prompts`) when renaming the prompt, retaining the campaign
dependencies and reason. Alternatively, restructure campaign prompt derivation
to create/select the intended entry and record any collection membership change
at that same native collection boundary. Keep ConfigKit's audit enabled and
preserve application selection; restricting IDs to the hard-coded default would
hide the regression.
Extend the existing composed-example coverage with a non-default campaign
prompt ID. Verify successful loading, the selected resource in the catalog, and
agreement between shared inspection and engine inspection. Existing fixtures
all select `briefing`, so their passing results do not exercise this branch.
## Verification
With Go 1.27.4, the core and ckconfig independent default suites passed. All
three aligned workspace suites passed, including maintained examples. ckprompt's
isolated default suite also passed with an external temporary modfile replacing
only ckconfig with the local module; the repository module files were unchanged.
That result does not establish an independent build against the still-selected
published ckconfig v0.9.0, as already recorded in
[release coordination](future.md#pending-integration-release-coordination).
At review time the R1 reproduction failed despite those passing suites; the
review itself changed no production code or tests.
After remediation, `GOTOOLCHAIN=local go test ./integrations/ckprompt/...
-count=1` passed with Go 1.27.4, including the composed example and regression.
The isolated ckprompt suite with a temporary local ckconfig replacement also
passed. The original override command now reports a valid app scope and exits
successfully. The published-dependency release coordination remains unchanged.

View File

@@ -0,0 +1,60 @@
# Selected Report Format Access: Optional Proposal
## Status
Consumer proposal from Scriptorium, prepared and revised 2026-11-19.
**This is no longer a prerequisite for Scriptorium's CommandKit migration.**
It remains an optional API proposal for independent upstream consideration,
not an accepted CommandKit contract or required release.
The reviewed baseline is CommandKit v0.7.0, with public guidance at revision
`d330d7637f2e7507eca931a899397222c82bc892`.
## Revised Consumer Direction
Scriptorium will submit PromptKit's native `RunResult` through the invocation
reporter. Its text template emits the artifact; JSON and YAML use native
structured rendering. The main result goes to stdout, and callers save it
through shell redirection or their subprocess API. Scriptorium will not add
`--output`; callers wanting the main result omit `--quiet`, including when
stdout is redirected. Diagnostics remain on stderr.
The optional `--report PATH` flag additionally writes the native result as fixed
JSON using the existing `RenderReport(writer, report, FormatJSON)` API. That
application-owned effect still occurs in quiet mode when a result exists.
This design needs no access to the selected main format outside the invocation
reporter. It can use the existing public APIs without a second parser, custom
serializer, or change to quiet semantics. Scriptorium owns only the separate
report file; callers own main-output redirection and its file lifecycle.
## Optional Public Capability
The original request proposed a read-only selected-format accessor usable by an
application handler with `RenderReport(writer, report, format)`. It addressed
application-owned main files whose format followed `--format` and whose writes
continued in quiet mode. Scriptorium has removed that requirement.
If other consumer needs justify this capability, the proposal is to expose the
selection already interpreted by CommandKit:
- Preserve automatic selection when `--format` is omitted, allowing the report's
text template or native fallback to determine presentation at rendering time.
- Preserve explicit text, JSON, and YAML selections and native repeated-flag,
alias, and argument-placement behavior.
- Leave reporting mode, destinations, diagnostics, and presentation state
unchanged when reading the selection.
The exported name and design remain upstream choices. Such an accessor would
add no standard output-file flag, file lifecycle management, or automatic
tracking of application writer failures. The
[reporting contract](../cli.md#reporting) and
[consumer guide](../consumers/guide.md#invocation-reporting) retain ownership of
native rendering and outcomes.
## Adoption Impact
Scriptorium no longer has accessor-specific acceptance scenarios or a release
dependency on this proposal. The earlier `--output` scenarios are superseded by
stdout reporting and caller-controlled redirection. Neither ckconfig nor
ckprompt needs a change for this revised delivery model.

14
go.mod
View File

@@ -1,18 +1,18 @@
module go.maximumdirect.net/commandkit
go 1.26.0
go 1.27.0
require (
github.com/spf13/cobra v1.10.1
github.com/spf13/pflag v1.0.9
go.yaml.in/yaml/v4 v4.0.0-rc.6
github.com/spf13/cobra v1.10.2
github.com/spf13/pflag v1.1.0
go.yaml.in/yaml/v4 v4.0.0
)
require (
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/yuin/goldmark/v2 v2.1.6 // indirect
go.maximumdirect.net/releasekit v0.9.0 // indirect
golang.org/x/mod v0.40.0 // indirect
github.com/yuin/goldmark/v2 v2.1.16 // indirect
go.maximumdirect.net/releasekit v0.10.0 // indirect
golang.org/x/mod v0.43.0 // indirect
)
tool go.maximumdirect.net/releasekit/cmd/releasekit

25
go.sum
View File

@@ -2,17 +2,18 @@ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6N
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/yuin/goldmark/v2 v2.1.6 h1:igy0q9JcqovoFXFx/XjtU8sHVhcUHavPj2sA3EoKJUE=
github.com/yuin/goldmark/v2 v2.1.6/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
go.maximumdirect.net/releasekit v0.9.0 h1:sK+Aoj6gS6ATU/1reocjwBekp4YETYENwkcX5ti6mrE=
go.maximumdirect.net/releasekit v0.9.0/go.mod h1:QE4BLrAhVJTzi+/YTcVl21K/qZp9ojRLg5kuoy3Zb44=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/yuin/goldmark/v2 v2.1.16 h1:MXvCVo+Cb2SVJ5cwJUzXetDjI7HECRJCkcqylEQtcJo=
github.com/yuin/goldmark/v2 v2.1.16/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
go.maximumdirect.net/releasekit v0.10.0 h1:3GOgaIigXTkvYaRkntWZASE//2NTR1+IhkoKmt64aJo=
go.maximumdirect.net/releasekit v0.10.0/go.mod h1:cT5NZNEcf7SKDx4MPG40YNK9V4bNyIxcLLFuNlbGQ90=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/mod v0.43.0 h1:MFuq5J6s35W9D3IjkwyWc9vHh0nENOrt5K8Iof4ofmg=
golang.org/x/mod v0.43.0/go.mod h1:4ec1JnuyBz5+FIVhg86UsA39YG8BpnrZdJYSNHmGzHY=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

View File

@@ -0,0 +1,119 @@
package ckconfig
import (
"bytes"
"context"
"errors"
"fmt"
"io"
"strings"
"testing"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
func TestNativeConfigurationInputOutcomes(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("malformed-input", []byte("broken: [")))
var native *configkit.LoadError
if !errors.As(loadErr, &native) || len(native.Diagnostics()) == 0 {
t.Fatalf("fixture: %v", loadErr)
}
wrapped := fmt.Errorf("application loader: %w", loadErr)
app := newConfigTestApp(t, AppCommand(func(context.Context, Selection) (*configkit.Result[map[string]any], error) { return nil, wrapped }))
cases := []struct {
name string
args []string
report string
}{
{"show", []string{"config", "show"}, ""},
{"sources", []string{"config", "sources", "--format=json"}, `"sources"`},
{"validation", []string{"config", "validate", "--details", "--format=json"}, `"code": "yaml.invalid"`},
{"filtered validation", []string{"config", "validate", "--details", "--code=not-selected", "--format=json"}, `"state": "filtered"`},
{"discovery", []string{"config", "explain", "--list"}, ""},
{"diff", []string{"config", "diff"}, ""},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var out, diag bytes.Buffer
result := app.Execute(context.Background(), tc.args, commandkit.Streams{Out: &out, Err: &diag})
var got *configkit.LoadError
if result.Kind != commandkit.OutcomeUsage || result.Status != 2 || !errors.Is(result.Cause, loadErr) || !errors.As(result.Cause, &got) || got != native {
t.Fatalf("outcome: %#v", result)
}
if !strings.Contains(diag.String(), native.Diagnostics()[0].Message) || !strings.Contains(diag.String(), "malformed-input") {
t.Fatalf("diagnostics: %q", diag.String())
}
if tc.report != "" && !strings.Contains(out.String(), tc.report) {
t.Fatalf("report: %q", out.String())
}
})
}
}
func TestNativeConfigurationComparisonFailureSides(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("bad-side", []byte("broken: [")))
for _, bad := range []string{"left", "right"} {
t.Run(bad, func(t *testing.T) {
app := newConfigTestApp(t, AppCommand(func(_ context.Context, selection Selection) (*configkit.Result[map[string]any], error) {
if selection.Config.Value == bad {
return nil, fmt.Errorf("wrapped: %w", loadErr)
}
return configkit.Load[map[string]any](configkit.Bytes("good-side", []byte("ok: true")))
}))
var diag bytes.Buffer
result := app.Execute(context.Background(), []string{"config", "diff", "--config=left", "--against-config=right"}, commandkit.Streams{Out: io.Discard, Err: &diag})
if result.Kind != commandkit.OutcomeUsage || result.Status != 2 || !errors.Is(result.Cause, loadErr) || !strings.Contains(diag.String(), "bad-side") || !strings.Contains(diag.String(), bad) {
t.Fatalf("outcome=%#v diagnostics=%q", result, diag.String())
}
})
}
}
func TestConfigurationFailureCancellationAndDelivery(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("bad-input", []byte("broken: [")))
for _, args := range [][]string{{"config", "show"}, {"config", "sources"}, {"config", "validate"}, {"config", "explain", "--list"}, {"config", "diff"}} {
t.Run(strings.Join(args, "_"), func(t *testing.T) {
calls := 0
app := newConfigTestApp(t, AppCommand(func(context.Context, Selection) (*configkit.Result[map[string]any], error) {
calls++
return nil, loadErr
}))
ctx, cancel := context.WithCancel(context.Background())
cancel()
var out bytes.Buffer
result := app.Execute(ctx, args, commandkit.Streams{Out: &out, Err: io.Discard})
if result.Status != 1 || !errors.Is(result.Cause, context.Canceled) || calls != 0 || out.Len() != 0 {
t.Fatalf("outcome=%#v calls=%d output=%q", result, calls, out.String())
}
ctx, cancel = context.WithCancel(context.Background())
defer cancel()
app = newConfigTestApp(t, AppCommand(func(context.Context, Selection) (*configkit.Result[map[string]any], error) {
cancel()
return nil, loadErr
}))
result = app.Execute(ctx, args, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if result.Status != 1 || !errors.Is(result.Cause, context.Canceled) || !errors.Is(result.Cause, loadErr) {
t.Fatalf("joined outcome=%#v", result)
}
})
}
app := newConfigTestApp(t, AppCommand(func(context.Context, Selection) (*configkit.Result[map[string]any], error) { return nil, loadErr }))
for _, args := range [][]string{{"config", "sources"}, {"config", "validate"}} {
result := app.Execute(context.Background(), args, commandkit.Streams{Out: shortWriter{}, Err: io.Discard})
if result.Kind != commandkit.OutcomeOperational || result.Status != 1 || !errors.Is(result.Cause, loadErr) || result.Presentation.Output.State != commandkit.DeliveryIncomplete {
t.Fatalf("delivery %v: %#v", args, result)
}
}
}
func TestConfigurationOperationalFailures(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.File("/nonexistent-commandkit-outcome-test"))
for _, failure := range []error{errors.New("unavailable"), loadErr} {
app := newConfigTestApp(t, AppCommand(func(context.Context, Selection) (*configkit.Result[map[string]any], error) { return nil, failure }))
result := app.Execute(context.Background(), []string{"config", "show"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if result.Status != 1 || !errors.Is(result.Cause, failure) {
t.Fatalf("outcome=%#v", result)
}
}
}

View File

@@ -33,64 +33,19 @@ func FromConfigKit[I, S, T any](
}
scope.Acquire = func(ctx context.Context, request Request, input I, state S) (commandkit.Acquired[View], error) {
result, err := load(ctx, request.Selection, input, state)
acquired := commandkit.Acquired[View]{}
if err != nil {
var loadError *configkit.LoadError
if errors.As(err, &loadError) && loadError != nil {
records := loadError.Diagnostics()
messages, explanation := configKitDiagnostics(name, loadError.Sources(), records)
acquired.Value.Sources = loadError
acquired.Value.Findings = &Findings{Records: records, Messages: messages}
acquired.Explanation = explanation
return acquired, err
}
}
if result == nil {
if err != nil {
return acquired, err
}
return commandkit.Acquired[View]{}, fmt.Errorf("ConfigKit scope %q returned a nil result", name)
}
records := result.Diagnostics()
messages, explanation := configKitDiagnostics(name, result.Sources(), records)
acquired.Value = View{Sources: result, Findings: &Findings{Records: records, Messages: messages}}
acquired.Explanation = explanation
result, acquired, err := acquireConfigKit(ctx, name, load, request.Selection, input, state)
if err != nil {
return acquired, err
}
metadata := result.Metadata()
acquired.Value.Effective, acquired.Value.Explanation, acquired.Value.Metadata = result, result, &metadata
acquired.Value.Effective, acquired.Value.Explanation, acquired.Value.Metadata, acquired.Value.Paths = result, result, &metadata, &metadata
return acquired, nil
}
scope.Compare = func(ctx context.Context, request ComparisonRequest[I], state S) (commandkit.Acquired[[]configkit.Difference], error) {
if err := ctx.Err(); err != nil {
return commandkit.Acquired[[]configkit.Difference]{}, fmt.Errorf("ConfigKit scope %q comparison before left load: %w", name, err)
}
acquired := commandkit.Acquired[[]configkit.Difference]{}
left, leftDiagnostics, leftExplanation, err := loadComparisonSide(ctx, name, "left", load, request.Left, state)
acquired.Diagnostics = append(acquired.Diagnostics, leftDiagnostics...)
acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, leftExplanation)
left, right, acquired, err := loadComparisonPair(ctx, name, load, request, state)
if err != nil {
return acquired, err
}
if err := ctx.Err(); err != nil {
return acquired, fmt.Errorf("ConfigKit scope %q comparison after left load: %w", name, err)
}
right, rightDiagnostics, rightExplanation, err := loadComparisonSide(ctx, name, "right", load, request.Right, state)
acquired.Diagnostics = append(acquired.Diagnostics, rightDiagnostics...)
acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, rightExplanation)
if err != nil {
return acquired, err
}
if err := ctx.Err(); err != nil {
return acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err)
}
acquired.Value, err = configkit.Diff(left, right)
if err != nil {
return acquired, fmt.Errorf("ConfigKit scope %q native diff: %w", name, err)
@@ -100,6 +55,130 @@ func FromConfigKit[I, S, T any](
return scope
}
// FromConfigKitSubtree adapts an application-owned typed loader to the same
// operations as FromConfigKit, using native inspection at path. Loading and
// validation cover the whole result; sources and findings retain that context.
// Discovery and rendering use the focused inspection, while explicit paths and
// comparison retain ConfigKit's native semantics. Construction and help do not
// load configuration, and a nil loader is recorded as a construction issue.
// The loader receives each operation's selection, input, and shared state.
// A valid absent subtree can be acquired, but rendering its effective value
// reports the native unavailable-value error. An unavailable inspection returns
// an operational error with any whole-load evidence already acquired.
func FromConfigKitSubtree[I, S, T any](
name, summary string,
path configkit.Path,
load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
) Scope[I, S] {
scope := Scope[I, S]{
Name: name, Summary: summary,
Operations: []Operation{Validate, Show, Sources, Explain, Diff},
Features: ScopeFeatures{PathDiscovery: true, PathShow: true},
}
if load == nil {
return WithScopeError(scope, fmt.Errorf("ConfigKit scope %q loader must not be nil", name))
}
scope.Acquire = func(ctx context.Context, request Request, input I, state S) (commandkit.Acquired[View], error) {
result, acquired, err := acquireConfigKit(ctx, name, load, request.Selection, input, state)
if err != nil {
return acquired, err
}
inspection, ok := result.InspectSubtree(path)
if !ok {
return acquired, fmt.Errorf("ConfigKit scope %q inspection at %q is unavailable", name, path.String())
}
metadata := inspection.Metadata()
acquired.Value.Effective = inspection
acquired.Value.Explanation = inspection
acquired.Value.Paths = inspection
acquired.Value.Metadata = &metadata
acquired.Value.Sources = inspection
return acquired, nil
}
scope.Compare = func(ctx context.Context, request ComparisonRequest[I], state S) (commandkit.Acquired[[]configkit.Difference], error) {
left, right, acquired, err := loadComparisonPair(ctx, name, load, request, state)
if err != nil {
return acquired, err
}
leftView, ok := left.InspectSubtree(path)
if !ok {
return acquired, fmt.Errorf("ConfigKit scope %q left inspection at %q is unavailable", name, path.String())
}
rightView, ok := right.InspectSubtree(path)
if !ok {
return acquired, fmt.Errorf("ConfigKit scope %q right inspection at %q is unavailable", name, path.String())
}
if err := ctx.Err(); err != nil {
return acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err)
}
acquired.Value, err = leftView.Diff(rightView)
if err != nil {
return acquired, fmt.Errorf("ConfigKit scope %q native diff: %w", name, err)
}
return acquired, nil
}
return scope
}
func acquireConfigKit[I, S, T any](ctx context.Context, name string,
load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
selection Selection, input I, state S,
) (*configkit.Result[T], commandkit.Acquired[View], error) {
result, err := load(ctx, selection, input, state)
acquired := commandkit.Acquired[View]{}
if err != nil {
var loadError *configkit.LoadError
if errors.As(err, &loadError) && loadError != nil {
records := loadError.Diagnostics()
messages, explanation := configKitDiagnostics(name, loadError.Sources(), records)
acquired.Value.Sources = loadError
acquired.Value.Findings = &Findings{Records: records, Messages: messages}
acquired.Explanation = explanation
return result, acquired, err
}
}
if result == nil {
if err != nil {
return nil, acquired, err
}
return nil, acquired, fmt.Errorf("ConfigKit scope %q returned a nil result", name)
}
records := result.Diagnostics()
messages, explanation := configKitDiagnostics(name, result.Sources(), records)
acquired.Value = View{Sources: result, Findings: &Findings{Records: records, Messages: messages}}
acquired.Explanation = explanation
return result, acquired, err
}
func loadComparisonPair[I, S, T any](ctx context.Context, name string,
load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
request ComparisonRequest[I], state S,
) (*configkit.Result[T], *configkit.Result[T], commandkit.Acquired[[]configkit.Difference], error) {
acquired := commandkit.Acquired[[]configkit.Difference]{}
if err := ctx.Err(); err != nil {
return nil, nil, acquired, fmt.Errorf("ConfigKit scope %q comparison before left load: %w", name, err)
}
left, diagnostics, explanation, err := loadComparisonSide(ctx, name, "left", load, request.Left, state)
acquired.Diagnostics = append(acquired.Diagnostics, diagnostics...)
acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, explanation)
if err != nil {
return nil, nil, acquired, err
}
if err := ctx.Err(); err != nil {
return nil, nil, acquired, fmt.Errorf("ConfigKit scope %q comparison after left load: %w", name, err)
}
right, diagnostics, explanation, err := loadComparisonSide(ctx, name, "right", load, request.Right, state)
acquired.Diagnostics = append(acquired.Diagnostics, diagnostics...)
acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, explanation)
if err != nil {
return nil, nil, acquired, err
}
if err := ctx.Err(); err != nil {
return nil, nil, acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err)
}
return left, right, acquired, nil
}
func loadComparisonSide[I, S, T any](
ctx context.Context,
scope, side string,

View File

@@ -80,11 +80,19 @@ type ExplanationReader interface {
Explain(configkit.Path) (configkit.Explanation, bool)
}
// PathReader supplies native candidates for configuration path discovery.
type PathReader interface {
HistoricalPaths() []configkit.Path
}
// View exposes native configuration evidence used to build reports.
type View struct {
Effective EffectiveWriter
Sources SourceReader
Explanation ExplanationReader
// Paths supplies discovery candidates. When nil, discovery uses Metadata.
// A nonnil reader may return an empty list without triggering that fallback.
Paths PathReader
// Metadata supplies native configuration path metadata when available.
Metadata *configkit.Metadata
// Findings supplies native diagnostics and their ordinary presentations.
@@ -102,7 +110,8 @@ type Findings struct {
// ScopeFeatures describes optional modes within configuration operations.
type ScopeFeatures struct {
// PathDiscovery indicates support for metadata-backed path discovery.
// PathDiscovery indicates support for path discovery using Paths or, when
// absent, Metadata. Metadata is required to describe and filter candidates.
PathDiscovery bool
// PathShow indicates support for displaying a selected effective path.
PathShow bool

View File

@@ -10,25 +10,25 @@ import (
func runConfigDiff[I, S any](invocation commandkit.Invocation, plan *configOperationPlan[I, S], state S) commandkit.Outcome {
if plan.comparison == nil || plan.comparison.scope == nil {
cause := errors.New("configuration comparison was not prepared")
return configFailure("Configuration comparison was not prepared.", commandkit.Explanation{}, cause)
return configFailure(invocation.Context, "Configuration comparison was not prepared.", commandkit.Explanation{}, cause)
}
selected := plan.comparison
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration comparison was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration comparison was canceled.", commandkit.Explanation{}, err)
}
compare := selected.scope.scope.Compare
if compare == nil {
cause := fmt.Errorf("configuration scope %q has no comparison callback", selected.scope.scope.Name)
return configFailure("Configuration scope does not support comparison.", commandkit.Explanation{}, cause)
return configFailure(invocation.Context, "Configuration scope does not support comparison.", commandkit.Explanation{}, cause)
}
acquired, err := compare(invocation.Context, selected.request, state)
reporter := invocation.Reporter()
queueConfigDiagnostics(reporter, acquired.Diagnostics)
if err != nil {
return configFailure(fmt.Sprintf("Unable to compare configuration scope %q.", selected.scope.scope.Name), acquired.Explanation, err)
return configFailure(invocation.Context, fmt.Sprintf("Unable to compare configuration scope %q.", selected.scope.scope.Name), acquired.Explanation, err)
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration comparison was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration comparison was canceled.", acquired.Explanation, err)
}
outcome := renderPreparedConfigReport(invocation, acquired.Explanation, func() (any, error) {
if plan.details {

View File

@@ -154,3 +154,68 @@ func TestExplainBareHelpRecordsDeliveryFailure(t *testing.T) {
t.Fatalf("help delivery = %#v, input/state/acquire=%d/%d/%d", result, inputs, states, calls)
}
}
type discoveryPaths []configkit.Path
func (paths discoveryPaths) HistoricalPaths() []configkit.Path { return paths }
func TestExplainDiscoveryUsesSuppliedPaths(t *testing.T) {
scope := FromConfigKit("app", "", func(_ context.Context, selection Selection, _, _ struct{}) (*configkit.Result[map[string]any], error) {
return configkit.Load(configkit.Mapping("fixture", map[string]any{
"focus": map[string]any{"keep": 1, "gone": map[string]any{"child": 2}},
"sibling": 3,
}), configkit.Options[map[string]any]{Overrides: selection.Overrides})
})
scope.Features.Overrides = true
acquire := scope.Acquire
var reader PathReader
scope.Acquire = func(ctx context.Context, request Request, input, state struct{}) (commandkit.Acquired[View], error) {
acquired, err := acquire(ctx, request, input, state)
acquired.Value.Paths = reader
return acquired, err
}
app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}}))
run := func(args ...string) pathDiscoveryReport {
t.Helper()
var out bytes.Buffer
arguments := append([]string{"config", "explain", "--list", "--format=json", "--set=/focus/gone=null"}, args...)
outcome := app.Execute(context.Background(), arguments, commandkit.Streams{Out: &out, Err: io.Discard})
var report pathDiscoveryReport
if outcome.Kind != commandkit.OutcomeSuccess {
t.Fatalf("discovery %v: %#v", args, outcome)
}
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
return report
}
reader = discoveryPaths{configkit.Keys("focus", "keep"), configkit.Keys("focus", "gone"), configkit.Keys("focus", "gone", "child")}
check := func(report pathDiscoveryReport, want ...string) {
t.Helper()
var got []string
for _, entry := range report.Paths {
got = append(got, entry.Path)
}
if !reflect.DeepEqual(got, want) {
t.Fatalf("paths = %v, want %v", got, want)
}
}
check(run(), "/focus/keep", "/focus/gone")
check(run("--historical"), "/focus/keep", "/focus/gone", "/focus/gone/child")
check(run("--under=/focus/gone", "--historical"), "/focus/gone", "/focus/gone/child")
check(run("--historical", "--explicit=true"), "/focus/keep", "/focus/gone")
check(run("--historical", "--explicit=false"))
reader = discoveryPaths(nil)
check(run("--historical"))
reader = discoveryPaths{}
check(run("--historical"))
reader = nil
fallback := run()
foundSibling := false
for _, entry := range fallback.Paths {
foundSibling = foundSibling || entry.Path == "/sibling"
}
if !foundSibling {
t.Fatalf("metadata fallback omitted sibling: %#v", fallback.Paths)
}
}

View File

@@ -4,6 +4,12 @@
// Use AppCommand for one application configuration loader, or Command with a
// Suite for multiple named configurations and application-specific flags.
// Install the returned command with commandkit.New or App.Register.
//
// FromConfigKitSubtree adapts an ordinary typed loader and native path to a
// focused scope, retaining whole-load sources, findings, and validation.
// View.Paths selects native listing candidates; nil falls back to Metadata.
// Explicit paths and comparison retain upstream semantics.
//
// Importing this package alone installs no commands.
//
// ConfigKit owns configuration loading and interpretation. CommandKit formats

View File

@@ -2,20 +2,20 @@
## ConfigKit
Selected module: `go.maximumdirect.net/configkit` at `v1.1.0`.
Selected module: `go.maximumdirect.net/configkit` at `v1.4.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3.0](../../LICENSE) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/LICENSE).
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3).
## go-yaml v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov
@@ -25,25 +25,25 @@ Copyright 2025 The go-yaml Project Contributors
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
## Cobra
Selected module: `github.com/spf13/cobra` at `v1.10.1`.
Selected module: `github.com/spf13/cobra` at `v1.10.2`.
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE.txt](https://github.com/spf13/cobra/blob/7da941c3547e93b8c9f70bbd3befca79c6335388/LICENSE.txt).
[LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/spf13/cobra/tree/7da941c3547e93b8c9f70bbd3befca79c6335388).
[Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## pflag
Selected module: `github.com/spf13/pflag` at `v1.0.9`.
Selected module: `github.com/spf13/pflag` at `v1.1.0`.
Copyright (c) 2012 Alex Ogier. All rights reserved.
@@ -52,9 +52,9 @@ Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/spf13/pflag/blob/10438578954bba2527fe5cae3684d4532b064bbe/LICENSE).
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://github.com/spf13/pflag/tree/10438578954bba2527fe5cae3684d4532b064bbe).
[Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).
## go-md2man
@@ -141,7 +141,7 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
## go-yaml v3
Selected module: `gopkg.in/yaml.v3` at `v3.0.1` (transitive dependency).
Selected module: `go.yaml.in/yaml/v3` at `v3.0.4` (transitive dependency).
Copyright (c) 2006-2010 Kirill Simonov
@@ -151,46 +151,47 @@ Copyright 2011-2016 Canonical Ltd.
License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/c3552c15f996075a7634df5159d9161c67bf3d76/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/c3552c15f996075a7634df5159d9161c67bf3d76/NOTICE).
[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
[Source](https://github.com/yaml/go-yaml/tree/c3552c15f996075a7634df5159d9161c67bf3d76).
## ReleaseKit
Selected module: `go.maximumdirect.net/releasekit` at `v0.9.0` (transitive Go tool requirement; not a runtime import).
Selected module: `go.maximumdirect.net/releasekit` at `v0.10.0` (transitive Go tool requirement; not a runtime import).
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3.0](../../LICENSE) |
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/LICENSE).
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243).
## Goldmark
Selected module: `github.com/yuin/goldmark/v2` at `v2.1.6` (ReleaseKit tool dependency).
Selected module: `github.com/yuin/goldmark/v2` at `v2.1.16` (ReleaseKit tool dependency).
Copyright (c) 2019 Yusuke Inuzuka
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[LICENSE](https://github.com/yuin/goldmark/blob/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c/LICENSE).
[LICENSE](https://github.com/yuin/goldmark/blob/c3f939122ba4dd6f80e05043ad195b82e77fcb41/LICENSE).
[Source](https://github.com/yuin/goldmark/tree/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c).
[Source](https://github.com/yuin/goldmark/tree/c3f939122ba4dd6f80e05043ad195b82e77fcb41).
## Go modules
Selected module: `golang.org/x/mod` at `v0.40.0` (ReleaseKit tool dependency).
Selected module: `golang.org/x/mod` at `v0.43.0` (ReleaseKit tool dependency).
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f/LICENSE).
[LICENSE](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde/LICENSE) |
[PATENTS](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde/PATENTS).
[Source](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f).
[Source](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde).

View File

@@ -0,0 +1,23 @@
# CommandKit ckconfig v0.10.0
CommandKit ckconfig v0.10.0 adopts ConfigKit v1.4.0 and adds native focused
configuration scopes. It continues to select CommandKit core v0.7.0 and Go
1.27.0 as the consumer minimum.
## Compatibility and upgrade
`FromConfigKitSubtree` adapts an application-owned typed result loader and a
ConfigKit path to the standard scope operations. Loading and validation cover
the whole result; focused output and comparison use native inspection while
sources and diagnostics retain whole-load context. See the
[consumer guide](../../../../docs/consumers/guide.md#configkit-scopes) and
[ConfigKit v1.4.0 notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md).
`View.Paths` optionally supplies native path-discovery candidates. When it is
nil, existing custom scopes continue to enumerate `View.Metadata`; metadata
still describes and filters candidates. The added exported field can break
positional `View` literals. Convert them to keyed literals before upgrading.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/docs/oss/attribution.md)

View File

@@ -0,0 +1,20 @@
# CommandKit ckconfig v0.7.0
CommandKit ckconfig v0.7.0 adopts ConfigKit v1.2.0. Application-owned loaders
can select main-relative companion imports and overlay contexts through
ConfigKit's public APIs, then expose the resulting configuration through
ckconfig's existing scope adapter. [ConfigKit v1.2.0 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/releases/v1.2.0.md)
## Compatibility and upgrade
Select `go.maximumdirect.net/ckconfig v0.7.0` with CommandKit core v0.6.0.
The consumer minimum is Go 1.27.0.
Application loaders constructing ConfigKit `Input` or `LayeredOptions` must use
field-named struct literals to accommodate the fields added upstream. See the
[consumer guide](../../../../docs/consumers/guide.md#module-selection) for module
selection and loader guidance.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.7.0/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.7.0/integrations/ckconfig/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.7.0/integrations/ckconfig/docs/oss/attribution.md)

View File

@@ -0,0 +1,19 @@
# CommandKit ckconfig v0.8.0
CommandKit ckconfig v0.8.0 classifies identifiable invalid ConfigKit input as a
usage failure. The new `ClassifyConfigurationError` function exposes the same
CLI classification for callers building their own outcomes.
## Compatibility and upgrade
Select `go.maximumdirect.net/ckconfig v0.8.0` with CommandKit core v0.6.0. The
consumer minimum remains Go 1.27.0. Standard configuration commands now return
status `2` for diagnostic evidence identifying invalid configuration input;
previously these loading failures returned status `1`. Update scripts that
interpret those statuses. Cancellation, operational failures, and ambiguous or
unknown evidence remain status `1`. See the [CLI contract](../../../../docs/cli.md#configuration-failure-classification)
and the [classifier GoDoc](../../errors.go) for details.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.8.0/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.8.0/integrations/ckconfig/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.8.0/integrations/ckconfig/docs/oss/attribution.md)

View File

@@ -0,0 +1,23 @@
# CommandKit ckconfig v0.9.0
CommandKit ckconfig v0.9.0 aligns with CommandKit core v0.7.0 and adopts
ConfigKit v1.2.1 and stable go-yaml v4.0.0.
## Compatibility and upgrade
Select `go.maximumdirect.net/ckconfig v0.9.0` with CommandKit core v0.7.0.
The consumer minimum remains Go 1.27.0. ConfigKit v1.2.1 includes the loader
adaptation for stable go-yaml. Applications continue to use the existing
configuration scope, loader, and classification APIs. See the
[consumer guide](../../../../docs/consumers/guide.md#configkit-scopes) and
[ConfigKit release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/releases/v1.2.1.md).
The selected core updates Cobra to v1.10.2 and pflag to v1.1.0. Review scripts
that depend on exact backend diagnostic or help text. Identifiable invalid
configuration input continues to select status `2`, while operational failures
and cancellation select status `1` under the
[configuration-failure contract](../../../../docs/cli.md#configuration-failure-classification).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.9.0/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.9.0/integrations/ckconfig/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.9.0/integrations/ckconfig/docs/oss/attribution.md)

View File

@@ -0,0 +1,102 @@
package ckconfig
import (
"context"
"errors"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
// ClassifyConfigurationError selects a CLI outcome from ConfigKit loading
// diagnostics. A nil error is success. A loading error is usage only when it
// contains at least one error diagnostic and all error diagnostics identify
// invalid configuration input; warnings are ignored. Unknown evidence and
// other errors are operational. Wrappers and joined errors are inspected, and
// any operational branch, cancellation, or deadline takes precedence.
// The caller remains responsible for constructing an outcome and its cause.
func ClassifyConfigurationError(err error) commandkit.OutcomeKind {
if err == nil {
return commandkit.OutcomeSuccess
}
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
return commandkit.OutcomeOperational
}
return classifyConfigurationTree(err)
}
func classifyConfigurationTree(err error) commandkit.OutcomeKind {
if load, ok := err.(*configkit.LoadError); ok {
if load == nil {
return commandkit.OutcomeOperational
}
return classifyConfigurationDiagnostics(load.Diagnostics())
}
switch wrapped := err.(type) {
case interface{ Unwrap() []error }:
found := false
for _, child := range wrapped.Unwrap() {
if child == nil {
continue
}
found = true
if classifyConfigurationTree(child) != commandkit.OutcomeUsage {
return commandkit.OutcomeOperational
}
}
if found {
return commandkit.OutcomeUsage
}
case interface{ Unwrap() error }:
if child := wrapped.Unwrap(); child != nil {
return classifyConfigurationTree(child)
}
}
return commandkit.OutcomeOperational
}
func classifyConfigurationDiagnostics(diagnostics []configkit.Diagnostic) commandkit.OutcomeKind {
found := false
for _, diagnostic := range diagnostics {
switch diagnostic.Severity {
case configkit.SeverityWarning:
continue
case configkit.SeverityError:
found = true
if !configurationInputCode(diagnostic.Code) {
return commandkit.OutcomeOperational
}
default:
return commandkit.OutcomeOperational
}
}
if found {
return commandkit.OutcomeUsage
}
return commandkit.OutcomeOperational
}
func configurationInputCode(code configkit.Code) bool {
switch code {
case configkit.CodeYAMLInvalid, configkit.CodeYAMLEmpty, configkit.CodeYAMLMultipleDocuments,
configkit.CodeYAMLRootType, configkit.CodeYAMLDuplicateKey, configkit.CodeYAMLTag,
configkit.CodeYAMLAnchor, configkit.CodeYAMLAlias, configkit.CodeYAMLMergeKey,
configkit.CodeYAMLScalar, configkit.CodeYAMLDepthLimit, configkit.CodeYAMLNodeLimit,
configkit.CodeDecodeType, configkit.CodeDecodeNull, configkit.CodeDecodeRange,
configkit.CodeDecodeDuration, configkit.CodeDecodeText, configkit.CodeDecodeUnknownField,
configkit.CodeDecodeArrayLength, configkit.CodeSourceLimitExceeded,
configkit.CodeImportDisabled, configkit.CodeImportCycle, configkit.CodeImportRepeated,
configkit.CodeImportVersion, configkit.CodeSequenceInvalid, configkit.CodeSequenceConflict,
configkit.CodeComposeInvalid, configkit.CodeComposeConflict, configkit.CodeUnderlayVersion,
configkit.CodeOverlayVersion, configkit.CodeOverlayRepeated, configkit.CodeOverlayDirective,
configkit.CodeVersionType, configkit.CodeVersionError, configkit.CodeResolveError,
configkit.CodeValidateError, configkit.CodeInheritanceInvalid, configkit.CodeInheritanceMissing,
configkit.CodeInheritanceCycle, configkit.CodeInheritanceVersion, configkit.CodeOverrideInvalidPath,
configkit.CodeOverrideDuplicate, configkit.CodeOverrideOverlap, configkit.CodeOverrideDirective,
configkit.CodeOverrideVersion, configkit.CodeOverrideLimitExceeded, configkit.CodeSecretRequired,
configkit.CodeSecretInvalidName:
return true
default:
return false
}
}

View File

@@ -0,0 +1,93 @@
package ckconfig
import (
"context"
"errors"
"fmt"
"testing"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
func TestConfigurationDiagnosticClassification(t *testing.T) {
usageCodes := []configkit.Code{
configkit.CodeYAMLInvalid, configkit.CodeYAMLEmpty, configkit.CodeYAMLMultipleDocuments, configkit.CodeYAMLRootType, configkit.CodeYAMLDuplicateKey, configkit.CodeYAMLTag, configkit.CodeYAMLAnchor, configkit.CodeYAMLAlias, configkit.CodeYAMLMergeKey, configkit.CodeYAMLScalar, configkit.CodeYAMLDepthLimit, configkit.CodeYAMLNodeLimit,
configkit.CodeDecodeType, configkit.CodeDecodeNull, configkit.CodeDecodeRange, configkit.CodeDecodeDuration, configkit.CodeDecodeText, configkit.CodeDecodeUnknownField, configkit.CodeDecodeArrayLength, configkit.CodeSourceLimitExceeded,
configkit.CodeImportDisabled, configkit.CodeImportCycle, configkit.CodeImportRepeated, configkit.CodeImportVersion, configkit.CodeSequenceInvalid, configkit.CodeSequenceConflict, configkit.CodeComposeInvalid, configkit.CodeComposeConflict, configkit.CodeUnderlayVersion, configkit.CodeOverlayVersion, configkit.CodeOverlayRepeated, configkit.CodeOverlayDirective,
configkit.CodeVersionType, configkit.CodeVersionError, configkit.CodeResolveError, configkit.CodeValidateError, configkit.CodeInheritanceInvalid, configkit.CodeInheritanceMissing, configkit.CodeInheritanceCycle, configkit.CodeInheritanceVersion, configkit.CodeOverrideInvalidPath, configkit.CodeOverrideDuplicate, configkit.CodeOverrideOverlap, configkit.CodeOverrideDirective, configkit.CodeOverrideVersion, configkit.CodeOverrideLimitExceeded, configkit.CodeSecretRequired, configkit.CodeSecretInvalidName,
}
for _, code := range usageCodes {
t.Run(string(code), func(t *testing.T) {
ds := []configkit.Diagnostic{{Severity: configkit.SeverityWarning, Code: configkit.CodeSourceRead}, {Severity: configkit.SeverityError, Code: code}}
if got := classifyConfigurationDiagnostics(ds); got != commandkit.OutcomeUsage {
t.Fatalf("got %s", got)
}
})
}
for _, code := range []configkit.Code{configkit.CodeSourceMissing, configkit.CodeSourcePermission, configkit.CodeImportInvalid, configkit.CodeImportOutsideRoot, configkit.CodeImportLimitExceeded, configkit.CodeOverlayInvalid, configkit.CodeOverlayOutsideRoot, configkit.CodeOverlayLimitExceeded, configkit.CodeSchemaRoot, configkit.CodeOptionsInvalid, configkit.CodeHistoryLimitExceeded, configkit.CodeResolveHookFailed, configkit.CodeValidateMutation, configkit.CodeOverrideInvalidLabel, configkit.CodeOverrideInvalidValue, configkit.CodeSecretUnset, configkit.CodeSecretEmpty, configkit.CodeSecretsMissing, "future.code"} {
t.Run(string(code), func(t *testing.T) {
ds := []configkit.Diagnostic{{Severity: configkit.SeverityError, Code: configkit.CodeYAMLInvalid}, {Severity: configkit.SeverityError, Code: code}}
if got := classifyConfigurationDiagnostics(ds); got != commandkit.OutcomeOperational {
t.Fatalf("got %s", got)
}
})
}
for _, ds := range [][]configkit.Diagnostic{nil, {{Severity: configkit.SeverityWarning, Code: configkit.CodeYAMLInvalid}}, {{Severity: "future", Code: configkit.CodeYAMLInvalid}}, {{Severity: configkit.SeverityError, Code: configkit.CodeYAMLInvalid}, {Severity: "future"}}} {
if got := classifyConfigurationDiagnostics(ds); got != commandkit.OutcomeOperational {
t.Fatalf("%v: got %s", ds, got)
}
}
}
type emptyChildren struct{}
func (emptyChildren) Error() string { return "empty" }
func (emptyChildren) Unwrap() []error { return nil }
func TestClassifyConfigurationError(t *testing.T) {
_, invalid := configkit.Load[map[string]any](configkit.Bytes("invalid", []byte("broken: [")))
_, missing := configkit.Load[map[string]any](configkit.File("/nonexistent-commandkit-classifier-test"))
var load *configkit.LoadError
if !errors.As(invalid, &load) || load == nil {
t.Fatalf("invalid fixture: %v", invalid)
}
if missing == nil {
t.Fatal("missing fixture unexpectedly succeeded")
}
var typedNil *configkit.LoadError
opaque := errors.New("opaque")
cases := []struct {
name string
err error
want commandkit.OutcomeKind
}{
{"nil", nil, commandkit.OutcomeSuccess},
{"invalid", invalid, commandkit.OutcomeUsage},
{"wrapped", fmt.Errorf("wrapped: %w", invalid), commandkit.OutcomeUsage},
{"all input", errors.Join(invalid, fmt.Errorf("wrapped: %w", invalid)), commandkit.OutcomeUsage},
{"mixed first", errors.Join(missing, invalid), commandkit.OutcomeOperational},
{"mixed last", errors.Join(invalid, missing), commandkit.OutcomeOperational},
{"nested", errors.Join(invalid, errors.Join(invalid, opaque)), commandkit.OutcomeOperational},
{"canceled", errors.Join(invalid, context.Canceled), commandkit.OutcomeOperational},
{"deadline", fmt.Errorf("deadline: %w", context.DeadlineExceeded), commandkit.OutcomeOperational},
{"missing", missing, commandkit.OutcomeOperational},
{"opaque", opaque, commandkit.OutcomeOperational},
{"empty load", &configkit.LoadError{}, commandkit.OutcomeOperational},
{"typed nil", typedNil, commandkit.OutcomeOperational},
{"empty children", emptyChildren{}, commandkit.OutcomeOperational},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := ClassifyConfigurationError(tc.err); got != tc.want {
t.Fatalf("got %s, want %s", got, tc.want)
}
if errors.Is(tc.err, invalid) {
var got *configkit.LoadError
if !errors.As(tc.err, &got) || got == nil {
t.Fatal("load identity lost")
}
}
})
}
}

View File

@@ -176,11 +176,11 @@ func TestSimpleFailedLoadReportsEvidence(t *testing.T) {
t.Fatalf("fixture failure = %v", failure)
}
outcome, output, _ := executeSimple(t, "config", "validate", "--config=fixtures/invalid.yml", "--details", "--severity=error", "--format=json")
if outcome.Kind != commandkit.OutcomeOperational || !strings.Contains(output, `"state": "present"`) || !strings.Contains(output, `"severity": "error"`) {
if outcome.Kind != commandkit.OutcomeUsage || !strings.Contains(output, `"state": "present"`) || !strings.Contains(output, `"severity": "error"`) {
t.Fatalf("detailed failure = %#v %q", outcome, output)
}
outcome, output, _ = executeSimple(t, "config", "sources", "--config=fixtures/invalid.yml", "--source-id="+native.Sources()[0].ID, "--format=json")
if outcome.Kind != commandkit.OutcomeOperational || !strings.Contains(output, `"id":`) || !strings.Contains(output, "invalid.yml") {
if outcome.Kind != commandkit.OutcomeUsage || !strings.Contains(output, `"id":`) || !strings.Contains(output, "invalid.yml") {
t.Fatalf("source failure = %#v %q", outcome, output)
}
}

View File

@@ -108,11 +108,11 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
name := selected.scope.scope.Name
reporter := invocation.Reporter()
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration explanation was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration explanation was canceled.", commandkit.Explanation{}, err)
}
if selected.scope.scope.Acquire == nil {
cause := fmt.Errorf("configuration scope %q has no acquisition callback", name)
return configFailure(fmt.Sprintf("Unable to explain configuration scope %q.", name), commandkit.Explanation{}, cause)
return configFailure(invocation.Context, fmt.Sprintf("Unable to explain configuration scope %q.", name), commandkit.Explanation{}, cause)
}
acquired, acquireErr := selected.scope.scope.Acquire(invocation.Context, Request{
Operation: Explain,
@@ -120,21 +120,25 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
}, selected.input, state)
queueConfigAcquisition(reporter, acquired)
if acquireErr != nil {
return configFailure(fmt.Sprintf("Unable to explain configuration scope %q.", name), acquired.Explanation, acquireErr)
return configFailure(invocation.Context, fmt.Sprintf("Unable to explain configuration scope %q.", name), acquired.Explanation, acquireErr)
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration explanation was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration explanation was canceled.", acquired.Explanation, err)
}
if plan.list {
if acquired.Value.Metadata == nil {
return configFailure("Configuration scope did not provide path metadata.", acquired.Explanation, fmt.Errorf("configuration scope %q declared path discovery without metadata", name))
return configFailure(invocation.Context, "Configuration scope did not provide path metadata.", acquired.Explanation, fmt.Errorf("configuration scope %q declared path discovery without metadata", name))
}
report := pathDiscoveryReport{Scope: name, Paths: []pathDiscoveryEntry{}}
var prefix []string
if plan.under != nil {
prefix = pointerTokens(plan.under.String())
}
for _, path := range acquired.Value.Metadata.HistoricalPaths() {
paths := acquired.Value.Paths
if paths == nil {
paths = acquired.Value.Metadata
}
for _, path := range paths.HistoricalPaths() {
pointer := path.String()
if plan.under != nil && !pathWithin(pointer, prefix) {
continue
@@ -157,16 +161,16 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
}
if acquired.Value.Explanation == nil {
cause := fmt.Errorf("configuration scope %q did not provide an explanation reader", name)
return configFailure("Configuration scope did not provide explanation data.", acquired.Explanation, cause)
return configFailure(invocation.Context, "Configuration scope did not provide explanation data.", acquired.Explanation, cause)
}
explanation, found := acquired.Value.Explanation.Explain(plan.path)
if !found {
cause := fmt.Errorf("configuration path %q is not known in scope %q", plan.path.String(), name)
return configFailure("The requested configuration path is not available.", acquired.Explanation, cause)
return configFailure(invocation.Context, "The requested configuration path is not available.", acquired.Explanation, cause)
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration explanation was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration explanation was canceled.", acquired.Explanation, err)
}
report := makeExplanationReport(name, explanation)
if acquired.Value.Metadata != nil {
@@ -192,7 +196,7 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
}
renderErr := reporter.Report(commandkit.Report{Value: report, TextTemplate: explanationTemplate})
if renderErr != nil && invocation.Context.Err() != nil {
return configFailure("Configuration explanation was canceled.", acquired.Explanation, invocation.Context.Err())
return configFailure(invocation.Context, "Configuration explanation was canceled.", acquired.Explanation, invocation.Context.Err())
}
return commandkit.Success()
}

View File

@@ -3,13 +3,13 @@ module go.maximumdirect.net/ckconfig
go 1.27.0
require (
go.maximumdirect.net/commandkit v0.6.0
go.maximumdirect.net/configkit v1.1.0
go.yaml.in/yaml/v4 v4.0.0-rc.6
go.maximumdirect.net/commandkit v0.7.0
go.maximumdirect.net/configkit v1.4.0
go.yaml.in/yaml/v4 v4.0.0
)
require (
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/spf13/cobra v1.10.1 // indirect
github.com/spf13/pflag v1.0.9 // indirect
github.com/spf13/cobra v1.10.2 // indirect
github.com/spf13/pflag v1.1.0 // indirect
)

View File

@@ -2,19 +2,16 @@ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6N
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
go.maximumdirect.net/commandkit v0.5.0 h1:Ln+bCp+FwCg4tZD3NaMKQXUDB3mPusgwsnRZmb0+3cM=
go.maximumdirect.net/commandkit v0.5.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
go.maximumdirect.net/commandkit v0.6.0 h1:4PHhMIlZuuvreIxZhUazeweg6zoYixEvhM9LJnkbGNA=
go.maximumdirect.net/commandkit v0.6.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
go.maximumdirect.net/configkit v1.1.0 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
go.maximumdirect.net/configkit v1.4.0 h1:TfOupZbQ23/ZMs+xt5lmyukCF11ekqKep8KbmFQD63o=
go.maximumdirect.net/configkit v1.4.0/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

View File

@@ -1,6 +1,8 @@
package ckconfig
import (
"context"
"errors"
"fmt"
"io"
@@ -15,7 +17,7 @@ func runConfigOperation[I, S any](invocation commandkit.Invocation, operation Op
return invocation.Help()
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration operation was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration operation was canceled.", commandkit.Explanation{}, err)
}
plan := input.plan
var state S
@@ -64,11 +66,23 @@ func queueConfigAcquisition(reporter *commandkit.Reporter, acquired commandkit.A
}
}
func configFailure(message string, explanation commandkit.Explanation, cause error) commandkit.Outcome {
func configFailure(ctx context.Context, message string, explanation commandkit.Explanation, cause error) commandkit.Outcome {
if explanation.Message != "" || len(explanation.Details) > 0 {
message = explanation.Message
}
if ctx != nil {
if canceled := ctx.Err(); canceled != nil {
if cause == nil {
cause = canceled
} else if !errors.Is(cause, canceled) {
cause = errors.Join(cause, canceled)
}
}
}
outcome := commandkit.Failure(message, explanation.Details...)
if cause != nil && ClassifyConfigurationError(cause) == commandkit.OutcomeUsage {
outcome = commandkit.Usage(message, explanation.Details...)
}
if cause != nil {
outcome = outcome.WithCause(cause)
}
@@ -76,6 +90,7 @@ func configFailure(message string, explanation commandkit.Explanation, cause err
}
func configAcquisitionFailure(
ctx context.Context,
reporter *commandkit.Reporter,
operation, scope string,
acquired commandkit.Acquired[View],
@@ -83,7 +98,7 @@ func configAcquisitionFailure(
) commandkit.Outcome {
queueConfigAcquisition(reporter, acquired)
message := fmt.Sprintf("Unable to %s configuration scope %q.", operation, scope)
return configFailure(message, acquired.Explanation, cause)
return configFailure(ctx, message, acquired.Explanation, cause)
}
// Preserve the preparation/delivery cancellation checkpoint for buffered reports.
@@ -105,7 +120,7 @@ func renderPreparedConfigReport(invocation commandkit.Invocation, explanation co
canceled = invocation.Context.Err()
}
if canceled != nil {
return configFailure("Configuration report preparation was canceled.", explanation, canceled)
return configFailure(invocation.Context, "Configuration report preparation was canceled.", explanation, canceled)
}
if renderErr == nil {
_ = invocation.Reporter().Report(commandkit.Report{Value: value})

View File

@@ -88,7 +88,7 @@ func TestOverrideNativeLoadErrorAndProvenance(t *testing.T) {
}
result = app.Execute(context.Background(), []string{"config", "validate", "--set==1"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
var loadErr *configkit.LoadError
if result.Kind != commandkit.OutcomeOperational || !errors.As(result.Cause, &loadErr) {
if result.Kind != commandkit.OutcomeUsage || !errors.As(result.Cause, &loadErr) {
t.Fatalf("native invalid root override: %#v", result)
}
}

View File

@@ -19,29 +19,29 @@ func runConfigShow[I, S any](invocation commandkit.Invocation, plan *configOpera
reporter := invocation.Reporter()
for _, selected := range plan.scopes {
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration show was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration show was canceled.", commandkit.Explanation{}, err)
}
if selected.scope.scope.Acquire == nil {
return commandkit.Failure(fmt.Sprintf("Configuration scope %q has no acquisition callback.", selected.scope.scope.Name))
}
acquired, acquireErr := selected.scope.scope.Acquire(invocation.Context, Request{Operation: Show, Selection: selected.selection}, selected.input, state)
if acquireErr != nil {
return configAcquisitionFailure(reporter, "show", selected.scope.scope.Name, acquired, acquireErr)
return configAcquisitionFailure(invocation.Context, reporter, "show", selected.scope.scope.Name, acquired, acquireErr)
}
queueConfigAcquisition(reporter, acquired)
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration show was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration show was canceled.", acquired.Explanation, err)
}
if plan.pathSet {
if acquired.Value.Explanation == nil {
return configFailure("Configuration scope did not provide explanation data.", acquired.Explanation, fmt.Errorf("configuration scope %q declared path show without an explanation reader", selected.scope.scope.Name))
return configFailure(invocation.Context, "Configuration scope did not provide explanation data.", acquired.Explanation, fmt.Errorf("configuration scope %q declared path show without an explanation reader", selected.scope.scope.Name))
}
explanation, found := acquired.Value.Explanation.Explain(plan.path)
if !found || !explanation.Effective.Present {
return configFailure("The requested effective configuration path is not available.", acquired.Explanation, fmt.Errorf("configuration path %q is not effective in scope %q", plan.path.String(), selected.scope.scope.Name))
return configFailure(invocation.Context, "The requested effective configuration path is not available.", acquired.Explanation, fmt.Errorf("configuration path %q is not effective in scope %q", plan.path.String(), selected.scope.scope.Name))
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration show was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration show was canceled.", acquired.Explanation, err)
}
var value any
err := reporter.RenderOutput(func(io.Writer) error {
@@ -51,7 +51,7 @@ func runConfigShow[I, S any](invocation commandkit.Invocation, plan *configOpera
})
if err == nil {
if canceled := invocation.Context.Err(); canceled != nil {
return configFailure("Configuration show was canceled.", acquired.Explanation, canceled)
return configFailure(invocation.Context, "Configuration show was canceled.", acquired.Explanation, canceled)
}
_ = reporter.Report(commandkit.Report{Value: value})
}
@@ -63,7 +63,7 @@ func runConfigShow[I, S any](invocation commandkit.Invocation, plan *configOpera
documents = append(documents, effectiveDocument{name: selected.scope.scope.Name, view: acquired.Value})
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration show was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration show was canceled.", commandkit.Explanation{}, err)
}
var value any
var canceled error
@@ -92,16 +92,16 @@ func runConfigShow[I, S any](invocation commandkit.Invocation, plan *configOpera
return nil
})
if canceled != nil {
return configFailure("Configuration show was canceled.", commandkit.Explanation{}, canceled)
return configFailure(invocation.Context, "Configuration show was canceled.", commandkit.Explanation{}, canceled)
}
if err != nil {
if canceled := invocation.Context.Err(); canceled != nil {
return configFailure("Configuration show was canceled.", commandkit.Explanation{}, canceled)
return configFailure(invocation.Context, "Configuration show was canceled.", commandkit.Explanation{}, canceled)
}
return commandkit.Success()
}
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration show was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration show was canceled.", commandkit.Explanation{}, err)
}
_ = reporter.Report(commandkit.Report{Value: value})
return commandkit.Success()

View File

@@ -59,11 +59,11 @@ func runConfigSources[I, S any](invocation commandkit.Invocation, plan *configOp
name := selected.scope.scope.Name
reporter := invocation.Reporter()
if err := invocation.Context.Err(); err != nil {
return configFailure("Configuration source listing was canceled.", commandkit.Explanation{}, err)
return configFailure(invocation.Context, "Configuration source listing was canceled.", commandkit.Explanation{}, err)
}
if selected.scope.scope.Acquire == nil {
cause := fmt.Errorf("configuration scope %q has no acquisition callback", name)
return configFailure(fmt.Sprintf("Unable to list sources for configuration scope %q.", name), commandkit.Explanation{}, cause)
return configFailure(invocation.Context, fmt.Sprintf("Unable to list sources for configuration scope %q.", name), commandkit.Explanation{}, cause)
}
acquired, acquireErr := selected.scope.scope.Acquire(invocation.Context, Request{
Operation: Sources,
@@ -72,15 +72,15 @@ func runConfigSources[I, S any](invocation commandkit.Invocation, plan *configOp
queueConfigAcquisition(reporter, acquired)
if acquireErr == nil && invocation.Context.Err() != nil {
err := invocation.Context.Err()
return configFailure("Configuration source listing was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration source listing was canceled.", acquired.Explanation, err)
}
if acquired.Value.Sources == nil {
if acquireErr != nil {
explanation := sourceSelectionExplanation(acquired.Explanation, "Source inventory is unavailable.")
return configFailure(fmt.Sprintf("Unable to list sources for configuration scope %q.", name), explanation, acquireErr)
return configFailure(invocation.Context, fmt.Sprintf("Unable to list sources for configuration scope %q.", name), explanation, acquireErr)
}
cause := fmt.Errorf("configuration scope %q did not provide a source reader", name)
return configFailure("Configuration scope did not provide source information.", acquired.Explanation, cause)
return configFailure(invocation.Context, "Configuration scope did not provide source information.", acquired.Explanation, cause)
}
sources := acquired.Value.Sources.Sources()
@@ -134,17 +134,17 @@ func runConfigSources[I, S any](invocation commandkit.Invocation, plan *configOp
if plan.sourceID.Set && len(document.Sources) == 0 {
message := fmt.Sprintf("Source ID %q was not found in configuration scope %q.", plan.sourceID.Value, name)
if acquireErr != nil {
return configFailure(fmt.Sprintf("Unable to list sources for configuration scope %q.", name), sourceSelectionExplanation(acquired.Explanation, message), acquireErr)
return configFailure(invocation.Context, fmt.Sprintf("Unable to list sources for configuration scope %q.", name), sourceSelectionExplanation(acquired.Explanation, message), acquireErr)
}
return configFailure(message, acquired.Explanation, fmt.Errorf("source ID %q was not found", plan.sourceID.Value))
return configFailure(invocation.Context, message, acquired.Explanation, fmt.Errorf("source ID %q was not found", plan.sourceID.Value))
}
if acquireErr == nil && invocation.Context.Err() != nil {
err := invocation.Context.Err()
return configFailure("Configuration source listing was canceled.", acquired.Explanation, err)
return configFailure(invocation.Context, "Configuration source listing was canceled.", acquired.Explanation, err)
}
_ = reporter.Report(commandkit.Report{Value: document, TextTemplate: sourceTextTemplate})
if acquireErr != nil {
return configFailure(fmt.Sprintf("Unable to list sources for configuration scope %q.", name), acquired.Explanation, acquireErr)
return configFailure(invocation.Context, fmt.Sprintf("Unable to list sources for configuration scope %q.", name), acquired.Explanation, acquireErr)
}
return commandkit.Success()
}

View File

@@ -0,0 +1,182 @@
package ckconfig
import (
"bytes"
"context"
"errors"
"io"
"reflect"
"strings"
"testing"
commandkit "go.maximumdirect.net/commandkit"
configkit "go.maximumdirect.net/configkit"
)
func TestSubtreeScopeUsesNativeInspection(t *testing.T) {
definition := configkit.Definition[map[string]any]{Validate: func(_ *map[string]any, validation *configkit.Validation) {
validation.Warning(configkit.Keys("sibling"), "sibling warning")
}}
makeResult := func(value any) *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.Load(configkit.Mapping("application", map[string]any{"storage": value, "sibling": "outside"}), configkit.Options[map[string]any]{Definition: definition})
if err != nil {
t.Fatal(err)
}
return result
}
left, right := makeResult(map[string]any{"name": "before"}), makeResult(map[string]any{"name": "after"})
calls := 0
scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(_ context.Context, selection Selection, _, _ struct{}) (*configkit.Result[map[string]any], error) {
calls++
if selection.Config.Value == "after" {
return right, nil
}
return left, nil
})
app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}}))
if calls != 0 {
t.Fatal("construction acquired configuration")
}
run := func(args ...string) (commandkit.Outcome, string, string) {
t.Helper()
var out, diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), append(append([]string{"config"}, args...), "--scope=storage"), commandkit.Streams{Out: &out, Err: &diagnostics})
return outcome, out.String(), diagnostics.String()
}
for _, tc := range []struct {
args []string
contains, excludes string
}{
{[]string{"show"}, "before", "outside"},
{[]string{"explain", "--list"}, "/storage/name", "/sibling"},
{[]string{"explain", "--path=/sibling"}, "/sibling", ""},
{[]string{"sources"}, "application", ""},
{[]string{"diff", "--config=before", "--against-config=after"}, "after", ""},
} {
outcome, output, diagnostics := run(tc.args...)
if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output, tc.contains) || (tc.excludes != "" && strings.Contains(output, tc.excludes)) {
t.Errorf("%v: outcome=%#v output=%q diagnostics=%q", tc.args, outcome, output, diagnostics)
}
}
lv, _ := left.InspectSubtree(configkit.Keys("storage"))
rv, _ := right.InspectSubtree(configkit.Keys("storage"))
want, err := lv.Diff(rv)
if err != nil {
t.Fatal(err)
}
got, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{Left: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "before", Set: true}}}, Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "after", Set: true}}}}, struct{}{})
if err != nil || !reflect.DeepEqual(got.Value, want) || len(got.Diagnostics) != 2 {
t.Fatalf("comparison = %#v, %v; want %#v", got, err, want)
}
}
func TestSubtreeScopeAbsenceAndErrors(t *testing.T) {
load := func(value map[string]any) *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.Load[map[string]any](configkit.Mapping("application", value))
if err != nil {
t.Fatal(err)
}
return result
}
for _, tc := range []struct {
name string
result *configkit.Result[map[string]any]
wantWriteError bool
}{
{"absent", load(map[string]any{"sibling": 1}), true}, {"null", load(map[string]any{"storage": nil}), false},
} {
t.Run(tc.name, func(t *testing.T) {
scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[map[string]any], error) {
return tc.result, nil
})
acquired, err := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{})
if err != nil {
t.Fatal(err)
}
var output bytes.Buffer
err = acquired.Value.Effective.WriteEffective(&output)
if (err != nil) != tc.wantWriteError || (!tc.wantWriteError && !strings.Contains(output.String(), "null")) {
t.Fatalf("write = %q, %v", output.String(), err)
}
})
}
cause := errors.New("application load failed")
result := load(map[string]any{"sibling": 1})
scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[map[string]any], error) {
return result, cause
})
acquired, err := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{})
if !errors.Is(err, cause) || acquired.Value.Sources == nil || acquired.Value.Findings == nil {
t.Fatalf("load failure = %#v, %v", acquired, err)
}
app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}}))
outcome := app.Execute(context.Background(), []string{"config", "show", "--scope=storage"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, cause) {
t.Fatalf("outcome = %#v", outcome)
}
unavailable := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[map[string]any], error) {
return &configkit.Result[map[string]any]{}, nil
})
acquired, err = unavailable.Acquire(context.Background(), Request{}, struct{}{}, struct{}{})
if err == nil || acquired.Value.Findings == nil || acquired.Value.Sources == nil {
t.Fatalf("unavailable = %#v, %v", acquired, err)
}
nilScope := FromConfigKitSubtree[struct{}, struct{}, map[string]any]("storage", "", configkit.Keys("storage"), nil)
if len(nilScope.issues) == 0 {
t.Fatal("nil loader not retained")
}
}
func TestSubtreeScopeRetainsWholeLoadFailure(t *testing.T) {
path := configkit.Keys("sibling")
_, loadErr := configkit.Load(configkit.Bytes("bad application", []byte("{}\n")), configkit.Options[struct{}]{Definition: configkit.Definition[struct{}]{Version: &configkit.VersionRule{
Path: path, Check: func(_ configkit.Version, validation *configkit.Validation) error {
validation.Warning(path, "outside warning")
return errors.New("invalid outside")
},
}}})
if loadErr == nil {
t.Fatal("fixture did not fail")
}
scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[struct{}], error) {
return nil, loadErr
})
acquired, err := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{})
var native *configkit.LoadError
if !errors.As(err, &native) || !errors.Is(err, loadErr) || acquired.Value.Sources == nil || acquired.Value.Findings == nil || !reflect.DeepEqual(acquired.Value.Findings.Records, native.Diagnostics()) || len(acquired.Explanation.Details) == 0 {
t.Fatalf("failure evidence = %#v, %v", acquired, err)
}
app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}}))
outcome := app.Execute(context.Background(), []string{"config", "validate", "--scope=storage"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if !errors.Is(outcome.Cause, loadErr) {
t.Fatalf("validation outcome = %#v", outcome)
}
}
func TestSubtreeComparisonRetainsNativeAncestor(t *testing.T) {
makeResult := func(item string) *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.Load[map[string]any](configkit.Mapping(item, map[string]any{"items": []any{item}}))
if err != nil {
t.Fatal(err)
}
return result
}
left, right := makeResult("before"), makeResult("after")
path := configkit.Keys("items", "0")
scope := FromConfigKitSubtree("item", "", path, func(_ context.Context, selection Selection, _, _ struct{}) (*configkit.Result[map[string]any], error) {
if selection.Config.Value == "right" {
return right, nil
}
return left, nil
})
got, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}}}, struct{}{})
lv, _ := left.InspectSubtree(path)
rv, _ := right.InspectSubtree(path)
want, nativeErr := lv.Diff(rv)
if err != nil || nativeErr != nil || !reflect.DeepEqual(got.Value, want) || len(want) != 1 || want[0].Path.String() != "/items" {
t.Fatalf("comparison = %#v, %v; native = %#v, %v", got.Value, err, want, nativeErr)
}
}

View File

@@ -71,7 +71,7 @@ func runConfigValidation[I, S any](invocation commandkit.Invocation, plan *confi
}
for _, selected := range plan.scopes {
if err := invocation.Context.Err(); err != nil {
outcome = configFailure("Configuration validation was canceled.", commandkit.Explanation{}, err)
outcome = configFailure(invocation.Context, "Configuration validation was canceled.", commandkit.Explanation{}, err)
break
}
name := selected.scope.scope.Name
@@ -109,7 +109,7 @@ func runConfigValidation[I, S any](invocation commandkit.Invocation, plan *confi
if entry.Outcome == "canceled" {
message = "Configuration validation was canceled."
}
outcome = configFailure(message, acquired.Explanation, err)
outcome = configFailure(invocation.Context, message, acquired.Explanation, err)
break
}
}

View File

@@ -196,7 +196,8 @@ func WithRequestValidation[I, S any](
if build != nil {
built, err := build(ctx, request, input, state)
if err != nil {
return commandkit.Acquired[struct{}]{}, err
messages := promptKitLoadErrorDiagnostics(err, "")
return commandkit.Acquired[struct{}]{Diagnostics: messages.diagnostics, Explanation: messages.explanation}, err
}
concreteRequest = built
}
@@ -294,6 +295,7 @@ func ConfigScope[I, S any](load func(context.Context, ckconfig.Selection, I, S)
Effective: *inspection,
Sources: *inspection,
Explanation: *inspection,
Paths: *inspection,
Metadata: &metadata,
Findings: &ckconfig.Findings{Records: inspection.Diagnostics(), Messages: messages.diagnostics},
},
@@ -476,12 +478,7 @@ func loadPromptKitEngine[I, S any](
) (*promptkit.Engine, *promptkit.ConfigurationInspection, promptKitAcquisition, error) {
engine, err := load(ctx, selection, input, state)
if err != nil {
var loadErr *configkit.LoadError
if errors.As(err, &loadErr) {
messages := promptKitDiagnostics("promptkit", side, loadErr.Sources(), loadErr.Diagnostics())
return nil, nil, messages, err
}
return nil, nil, promptKitAcquisition{}, err
return nil, nil, promptKitLoadErrorDiagnostics(err, side), err
}
if engine == nil {
return nil, nil, promptKitAcquisition{}, errors.New("PromptKit configuration loader returned a nil engine")
@@ -509,6 +506,14 @@ func appendPromptKitAcquisition(left, right promptKitAcquisition) promptKitAcqui
return left
}
func promptKitLoadErrorDiagnostics(err error, side string) promptKitAcquisition {
var loadErr *configkit.LoadError
if errors.As(err, &loadErr) && loadErr != nil {
return promptKitDiagnostics("promptkit", side, loadErr.Sources(), loadErr.Diagnostics())
}
return promptKitAcquisition{}
}
func promptKitDiagnostics(scope, side string, sources []configkit.SourceInfo, records []configkit.Diagnostic) promptKitAcquisition {
heading := "Configuration scope " + strconv.Quote(scope)
if side != "" {

View File

@@ -98,6 +98,9 @@ func adapterEngineFrom(t *testing.T, label, configuration string, options ...pro
if err != nil {
t.Fatal(err)
}
for index := range inputs {
inputs[index].Destination = configkit.Keys("promptkit")
}
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{
Underlays: []configkit.Underlay{{Inputs: inputs}},
}}, append([]promptkit.Option{promptkit.WithBundledOpenRouter(false)}, options...)...)

View File

@@ -202,7 +202,7 @@ func newCatalogListCommand[I, S any](suite Suite[I, S], name string) commandkit.
}
return runCatalogList(invocation, suite, input, name, list, collectionCatalogReport)
default:
return definitionFailure("Unable to list the selected PromptKit catalog.", commandkit.Explanation{}, fmt.Errorf("unknown PromptKit catalog %q", name))
return definitionFailure(invocation.Context, "Unable to list the selected PromptKit catalog.", commandkit.Explanation{}, fmt.Errorf("unknown PromptKit catalog %q", name))
}
},
})
@@ -368,7 +368,7 @@ func runCatalogList[T any, I, S any](
) commandkit.Outcome {
if invocation.Context != nil {
if err := invocation.Context.Err(); err != nil {
return definitionFailure("PromptKit catalog listing was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit catalog listing was canceled.", commandkit.Explanation{}, err)
}
}
var state S
@@ -377,18 +377,18 @@ func runCatalogList[T any, I, S any](
}
if invocation.Context != nil {
if err := invocation.Context.Err(); err != nil {
return definitionFailure("PromptKit catalog listing was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit catalog listing was canceled.", commandkit.Explanation{}, err)
}
}
acquired, err := list(invocation.Context, CatalogRequest{Selection: input.selection, Filter: input.filter}, input.selected, state)
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
if err != nil {
return definitionFailure(fmt.Sprintf("Unable to list PromptKit %s.", catalog), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Unable to list PromptKit %s.", catalog), acquired.Explanation, err)
}
if invocation.Context != nil {
if err := invocation.Context.Err(); err != nil {
return definitionFailure("PromptKit catalog listing was canceled.", acquired.Explanation, err)
return definitionFailure(invocation.Context, "PromptKit catalog listing was canceled.", acquired.Explanation, err)
}
}
_ = invocation.Reporter().Report(commandkit.Report{Value: project(acquired.Value)})
@@ -397,14 +397,14 @@ func runCatalogList[T any, I, S any](
func runDefinitionInspection[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *definitionInput[I], kind string) commandkit.Outcome {
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit inspection was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit inspection was canceled.", commandkit.Explanation{}, err)
}
var state S
if suite.NewState != nil {
state = suite.NewState()
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit inspection was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit inspection was canceled.", commandkit.Explanation{}, err)
}
var value any
var diagnostics []commandkit.Diagnostic
@@ -435,13 +435,13 @@ func runDefinitionInspection[I, S any](invocation commandkit.Invocation, suite S
}
queuePromptDiagnostics(invocation.Reporter(), diagnostics)
if err != nil {
return definitionFailure(fmt.Sprintf("Unable to inspect PromptKit %s %q.", kind, input.id), explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Unable to inspect PromptKit %s %q.", kind, input.id), explanation, err)
}
if value == nil {
return definitionFailure(fmt.Sprintf("PromptKit %s inspection returned no result.", kind), explanation, nil)
return definitionFailure(invocation.Context, fmt.Sprintf("PromptKit %s inspection returned no result.", kind), explanation, nil)
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure(fmt.Sprintf("Inspection of PromptKit %s %q was canceled.", kind, input.id), explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Inspection of PromptKit %s %q was canceled.", kind, input.id), explanation, err)
}
_ = invocation.Reporter().Report(commandkit.Report{Value: value})
return commandkit.Success()
@@ -520,7 +520,7 @@ func requirementsReportFromInspection(inspection *promptkit.RequirementInspectio
func runRequirementsInspection[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *requirementsInput[I]) commandkit.Outcome {
if invocation.Context != nil {
if err := invocation.Context.Err(); err != nil {
return definitionFailure("PromptKit requirements inspection was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit requirements inspection was canceled.", commandkit.Explanation{}, err)
}
}
var state S
@@ -529,7 +529,7 @@ func runRequirementsInspection[I, S any](invocation commandkit.Invocation, suite
}
if invocation.Context != nil {
if err := invocation.Context.Err(); err != nil {
return definitionFailure("PromptKit requirements inspection was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit requirements inspection was canceled.", commandkit.Explanation{}, err)
}
}
@@ -537,14 +537,14 @@ func runRequirementsInspection[I, S any](invocation commandkit.Invocation, suite
acquired, err := suite.InspectRequirements(invocation.Context, request, input.selected, state)
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
if err != nil {
return definitionFailure(fmt.Sprintf("Unable to inspect requirements for PromptKit prompt %q.", input.inspection.PromptID), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Unable to inspect requirements for PromptKit prompt %q.", input.inspection.PromptID), acquired.Explanation, err)
}
if acquired.Value == nil {
return definitionFailure("PromptKit requirements inspection returned no result.", acquired.Explanation, nil)
return definitionFailure(invocation.Context, "PromptKit requirements inspection returned no result.", acquired.Explanation, nil)
}
if invocation.Context != nil {
if err := invocation.Context.Err(); err != nil {
return definitionFailure(fmt.Sprintf("Requirements inspection for PromptKit prompt %q was canceled.", input.inspection.PromptID), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Requirements inspection for PromptKit prompt %q was canceled.", input.inspection.PromptID), acquired.Explanation, err)
}
}
_ = invocation.Reporter().Report(commandkit.Report{Value: requirementsReportFromInspection(acquired.Value)})
@@ -602,8 +602,20 @@ func queuePromptDiagnostics(reporter *commandkit.Reporter, diagnostics []command
}
}
func definitionFailure(message string, explanation commandkit.Explanation, cause error) commandkit.Outcome {
func definitionFailure(ctx context.Context, message string, explanation commandkit.Explanation, cause error) commandkit.Outcome {
if ctx != nil {
if canceled := ctx.Err(); canceled != nil {
if cause == nil {
cause = canceled
} else if !errors.Is(cause, canceled) {
cause = errors.Join(cause, canceled)
}
}
}
outcome := commandkit.Failure(message)
if cause != nil && ckconfig.ClassifyConfigurationError(cause) == commandkit.OutcomeUsage {
outcome = commandkit.Usage(message)
}
if explanation.Message != "" || len(explanation.Details) > 0 {
outcome = outcome.WithExplanation(explanation.Message, explanation.Details...)
}

View File

@@ -154,7 +154,7 @@ func TestPublicConfigDiffUsesPromptKitPairAndPreparedInputs(t *testing.T) {
var diagnostics bytes.Buffer
failure := app.Execute(context.Background(), []string{"config", "diff", "--scope", "promptkit", "--config", "bad-left.yml", "--against-config", "right.yml", "--campaign", "spring", "--against-campaign", "spring"}, commandkit.Streams{Out: io.Discard, Err: &diagnostics})
if failure.Kind != commandkit.OutcomeOperational || !strings.Contains(diagnostics.String(), `Configuration scope "promptkit" (left):`) {
if failure.Kind != commandkit.OutcomeUsage || !strings.Contains(diagnostics.String(), `Configuration scope "promptkit" (left):`) {
t.Fatalf("installed load failure = %#v, diagnostics %q", failure, diagnostics.String())
}
var loadFailure *configkit.LoadError
@@ -247,6 +247,9 @@ profiles:
if err != nil {
t.Fatal(err)
}
for index := range inputs {
inputs[index].Destination = configkit.Keys("promptkit")
}
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Underlays: []configkit.Underlay{{Inputs: inputs}}}}, promptkit.WithBundledOpenRouter(false))
if err != nil {
t.Fatalf("construct comparison engine: %v", err)

View File

@@ -163,6 +163,9 @@ profiles:
if err != nil {
t.Fatal(err)
}
for index := range inputs {
inputs[index].Destination = configkit.Keys("promptkit")
}
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Underlays: []configkit.Underlay{{Inputs: inputs}}}}, promptkit.WithBundledOpenRouter(false))
if err != nil {
t.Fatalf("construct engine: %v", err)

View File

@@ -0,0 +1,100 @@
package ckprompt
import (
"bytes"
"context"
"errors"
"fmt"
"io"
"strings"
"testing"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
func TestComposedConfigurationInputOutcomes(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("prompt-invalid", []byte("broken: [")))
engine := adapterEngine(t)
calls := 0
scope := ConfigScope(func(_ context.Context, selection ckconfig.Selection, _, _ struct{}) (*promptkit.Engine, error) {
calls++
if selection.Config.Value == "good" {
return engine, nil
}
return nil, fmt.Errorf("wrapped: %w", loadErr)
})
app := newPromptTestApp(t, ckconfig.Command(ckconfig.Suite[struct{}, struct{}]{Scopes: []ckconfig.Scope[struct{}, struct{}]{scope}}))
cases := []struct {
args []string
report string
side string
}{
{[]string{"config", "show"}, "", ""},
{[]string{"config", "sources", "--format=json"}, `"sources"`, ""},
{[]string{"config", "validate", "--details", "--format=json"}, `"code": "yaml.invalid"`, ""},
{[]string{"config", "explain", "--list"}, "", ""},
{[]string{"config", "diff"}, "", "left"},
{[]string{"config", "diff", "--config=good", "--against-config=bad"}, "", "right"},
}
for _, tc := range cases {
t.Run(strings.Join(tc.args, "_"), func(t *testing.T) {
var out, diag bytes.Buffer
args := append(append([]string{}, tc.args...), "--scope=promptkit")
result := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diag})
var native *configkit.LoadError
if result.Status != 2 || !errors.Is(result.Cause, loadErr) || !errors.As(result.Cause, &native) || !strings.Contains(diag.String(), "prompt-invalid") || (tc.report != "" && !strings.Contains(out.String(), tc.report)) || (tc.side != "" && !strings.Contains(diag.String(), "("+tc.side+")")) {
t.Fatalf("result=%#v output=%q diagnostics=%q", result, out.String(), diag.String())
}
})
}
for _, tc := range cases {
ctx, cancel := context.WithCancel(context.Background())
cancel()
before := calls
var out bytes.Buffer
args := append(append([]string{}, tc.args...), "--scope=promptkit")
result := app.Execute(ctx, args, commandkit.Streams{Out: &out, Err: io.Discard})
if result.Status != 1 || !errors.Is(result.Cause, context.Canceled) || calls != before || out.Len() != 0 {
t.Fatalf("canceled %v: %#v output=%q", tc.args, result, out.String())
}
}
}
func TestSmokeConfigurationFailureOutcomes(t *testing.T) {
_, first := configkit.Load[map[string]any](configkit.Bytes("first", []byte("broken: [")))
_, second := configkit.Load[map[string]any](configkit.Bytes("second", []byte("other: [")))
operational := errors.New("provider failure")
for _, tc := range []struct {
name, command string
failures []error
cancel bool
want int
}{
{"single", "reachability", []error{first}, false, 2},
{"all input", "all", []error{first, second, first, second}, false, 2},
{"mixed", "all", []error{first, operational, second, first}, false, 1},
{"cancellation", "all", []error{first}, true, 1},
} {
t.Run(tc.name, func(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
calls := 0
app := newPromptTestApp(t, Command(Suite[struct{}, struct{}]{SmokeTest: func(_ context.Context, req SmokeRequest, _, _ struct{}) (commandkit.Acquired[*promptkit.SmokeTestReport], error) {
err := tc.failures[calls]
calls++
if tc.cancel {
cancel()
}
return commandkit.Acquired[*promptkit.SmokeTestReport]{Value: &promptkit.SmokeTestReport{Kind: req.Request.Kind}, Explanation: commandkit.Explanation{Message: fmt.Sprintf("context-%d", calls)}}, err
}}))
var out, diag bytes.Buffer
result := app.Execute(ctx, []string{"promptkit", "test", tc.command, "--format=json"}, commandkit.Streams{Out: &out, Err: &diag})
if result.Status != tc.want || calls != len(tc.failures) || !errors.Is(result.Cause, first) || (tc.name == "all input" && !errors.Is(result.Cause, second)) || (tc.name == "mixed" && (!errors.Is(result.Cause, second) || !errors.Is(result.Cause, operational))) || (tc.cancel && !errors.Is(result.Cause, context.Canceled)) || out.Len() == 0 || !strings.Contains(diag.String(), "context-1") {
t.Fatalf("outcome=%#v calls=%d report=%q diagnostics=%q", result, calls, out.String(), diag.String())
}
})
}
}

View File

@@ -0,0 +1,209 @@
package ckprompt
import (
"bytes"
"context"
"errors"
"fmt"
"io"
"strings"
"testing"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
func TestPromptConfigurationFailureCallbacks(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("prompt-config", []byte("broken: [")))
var native *configkit.LoadError
if !errors.As(loadErr, &native) {
t.Fatalf("fixture: %v", loadErr)
}
wrapped := fmt.Errorf("load: %w", loadErr)
diag := commandkit.Explanation{Message: "configuration diagnostic"}
suite := Suite[struct{}, struct{}]{
ListPrompts: func(context.Context, CatalogRequest, struct{}, struct{}) (commandkit.Acquired[[]promptkit.PromptIdentity], error) {
return commandkit.Acquired[[]promptkit.PromptIdentity]{Explanation: diag}, wrapped
},
ListProfiles: func(context.Context, CatalogRequest, struct{}, struct{}) (commandkit.Acquired[[]string], error) {
return commandkit.Acquired[[]string]{Explanation: diag}, wrapped
},
ListBackends: func(context.Context, CatalogRequest, struct{}, struct{}) (commandkit.Acquired[[]string], error) {
return commandkit.Acquired[[]string]{Explanation: diag}, wrapped
},
ListNamespaces: func(context.Context, NamespaceRequest, struct{}, struct{}) (commandkit.Acquired[[]string], error) {
return commandkit.Acquired[[]string]{Explanation: diag}, wrapped
},
ListCollections: func(context.Context, ckconfig.Selection, struct{}, struct{}) (commandkit.Acquired[[]promptkit.CollectionInfo], error) {
return commandkit.Acquired[[]promptkit.CollectionInfo]{Explanation: diag}, wrapped
},
InspectPrompt: func(context.Context, PromptRequest, struct{}, struct{}) (commandkit.Acquired[*promptkit.PromptInspection], error) {
return commandkit.Acquired[*promptkit.PromptInspection]{Explanation: diag}, wrapped
},
InspectProfile: func(context.Context, ProfileRequest, struct{}, struct{}) (commandkit.Acquired[*promptkit.ProfileInspection], error) {
return commandkit.Acquired[*promptkit.ProfileInspection]{Explanation: diag}, wrapped
},
InspectBackend: func(context.Context, BackendRequest, struct{}, struct{}) (commandkit.Acquired[*promptkit.BackendInspection], error) {
return commandkit.Acquired[*promptkit.BackendInspection]{Explanation: diag}, wrapped
},
InspectRequirements: func(context.Context, RequirementsRequest, struct{}, struct{}) (commandkit.Acquired[*promptkit.RequirementInspection], error) {
return commandkit.Acquired[*promptkit.RequirementInspection]{Explanation: diag}, wrapped
},
ValidateRequest: func(context.Context, ValidationRequest, struct{}, struct{}) (commandkit.Acquired[struct{}], error) {
return commandkit.Acquired[struct{}]{Explanation: diag}, wrapped
},
PrepareRequest: func(context.Context, PreparationRequest, struct{}, struct{}) (commandkit.Acquired[*promptkit.PreparedRun], error) {
return commandkit.Acquired[*promptkit.PreparedRun]{Explanation: diag}, wrapped
},
}
app := newPromptTestApp(t, Command(suite))
for _, args := range [][]string{{"promptkit", "list", "prompts"}, {"promptkit", "list", "profiles"}, {"promptkit", "list", "backends"}, {"promptkit", "list", "namespaces"}, {"promptkit", "list", "collections"}, {"promptkit", "show", "prompt", "example"}, {"promptkit", "show", "profile", "example"}, {"promptkit", "show", "backend", "example"}, {"promptkit", "requirements", "show", "example"}, {"promptkit", "requirements", "validate", "example"}, {"promptkit", "show", "prepared", "example"}} {
t.Run(strings.Join(args, "_"), func(t *testing.T) {
var out, diagnostic bytes.Buffer
result := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic})
var got *configkit.LoadError
if result.Kind != commandkit.OutcomeUsage || result.Status != 2 || !errors.Is(result.Cause, loadErr) || !errors.As(result.Cause, &got) || got != native || !strings.Contains(diagnostic.String(), "configuration diagnostic") {
t.Fatalf("outcome=%#v diagnostics=%q", result, diagnostic.String())
}
})
}
}
func TestPromptNativeConfigurationFailures(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("native-config", []byte("broken: [")))
load := func(context.Context, ckconfig.Selection, struct{}, struct{}) (*promptkit.Engine, error) {
return nil, fmt.Errorf("wrapped: %w", loadErr)
}
suite := FromEngine[struct{}, struct{}](load)
suite = WithRequestValidation(suite, load, nil)
suite = WithRequestPreparation(suite, load, nil)
app := newPromptTestApp(t, Command(suite))
for _, args := range [][]string{{"promptkit", "list", "prompts"}, {"promptkit", "show", "prompt", "example"}, {"promptkit", "requirements", "show", "example"}, {"promptkit", "requirements", "validate", "example"}, {"promptkit", "show", "prepared", "example"}} {
t.Run(strings.Join(args, "_"), func(t *testing.T) {
var diag bytes.Buffer
result := app.Execute(context.Background(), args, commandkit.Streams{Out: io.Discard, Err: &diag})
var native *configkit.LoadError
if result.Status != 2 || !errors.Is(result.Cause, loadErr) || !errors.As(result.Cause, &native) || !strings.Contains(diag.String(), "native-config") {
t.Fatalf("outcome=%#v diagnostics=%q", result, diag.String())
}
})
}
}
func TestBuilderConfigurationFailureDiagnostics(t *testing.T) {
_, malformed := configkit.Load[map[string]any](configkit.Bytes("builder-config", []byte("broken: [")))
path := configkit.Keys("version")
_, rejected := configkit.Load(configkit.Bytes("builder-config", []byte("version: 1\n")), configkit.Options[map[string]any]{
Definition: configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
Path: path,
Check: func(_ configkit.Version, validation *configkit.Validation) error {
validation.Warning(path, "builder warning")
validation.Error(path, "builder rejection")
return nil
},
}},
})
for _, fixture := range []struct {
name string
cause error
code string
warning string
status int
}{
{"malformed", malformed, "yaml.invalid", "", 2},
{"rejected", rejected, "version.error", "builder warning", 2},
{"application failure", errors.New("builder unavailable"), "", "", 1},
} {
if fixture.cause == nil {
t.Fatalf("%s fixture succeeded", fixture.name)
}
for _, args := range [][]string{
{"promptkit", "requirements", "validate", "example"},
{"promptkit", "show", "prepared", "example"},
{"promptkit", "test", "reachability"},
{"promptkit", "test", "all"},
} {
for _, canceled := range []bool{false, true} {
name := fmt.Sprintf("%s/%s/canceled=%t", fixture.name, strings.Join(args, "_"), canceled)
t.Run(name, func(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
loaderCalls, builderCalls := 0, 0
load := func(context.Context, ckconfig.Selection, struct{}, struct{}) (*promptkit.Engine, error) {
loaderCalls++
return nil, errors.New("unexpected engine load")
}
wrapped := fmt.Errorf("builder load: %w", fixture.cause)
buildError := func() error {
builderCalls++
if canceled {
cancel()
}
return wrapped
}
suite := WithRequestValidation(Suite[struct{}, struct{}]{}, load, func(context.Context, ValidationRequest, struct{}, struct{}) (promptkit.RunRequest, error) {
return promptkit.RunRequest{}, buildError()
})
suite = WithRequestPreparation(suite, load, func(context.Context, PreparationRequest, struct{}, struct{}) (promptkit.RunRequest, error) {
return promptkit.RunRequest{}, buildError()
})
suite = WithSmokeTesting(suite, load, func(context.Context, SmokeRequest, struct{}, struct{}) (promptkit.SmokeTestRequest, error) {
return promptkit.SmokeTestRequest{}, buildError()
})
app := newPromptTestApp(t, Command(suite))
var out, diagnostic bytes.Buffer
result := app.Execute(ctx, append(append([]string{}, args...), "--verbose"), commandkit.Streams{Out: &out, Err: &diagnostic})
wantStatus, wantCalls := fixture.status, 1
if args[len(args)-1] == "all" && !canceled {
wantCalls = 4
}
if canceled {
wantStatus = 1
if !errors.Is(result.Cause, context.Canceled) {
t.Fatalf("lost cancellation: %#v", result)
}
}
if result.Status != wantStatus || !errors.Is(result.Cause, wrapped) || loaderCalls != 0 || builderCalls != wantCalls {
t.Fatalf("result=%#v loader calls=%d builder calls=%d", result, loaderCalls, builderCalls)
}
if fixture.code != "" {
var expected, retained *configkit.LoadError
if !errors.As(fixture.cause, &expected) || !errors.As(result.Cause, &retained) || retained != expected {
t.Fatalf("lost loading error: %#v", result)
}
if !strings.Contains(diagnostic.String(), fixture.code) || !strings.Contains(diagnostic.String(), "builder-config") || !strings.Contains(diagnostic.String(), fixture.warning) {
t.Fatalf("diagnostics: %q", diagnostic.String())
}
}
})
}
}
}
}
func TestPromptConfigurationFailureCancellation(t *testing.T) {
_, loadErr := configkit.Load[map[string]any](configkit.Bytes("invalid", []byte("broken: [")))
ctx, cancel := context.WithCancel(context.Background())
calls := 0
suite := Suite[struct{}, struct{}]{InspectPrompt: func(context.Context, PromptRequest, struct{}, struct{}) (commandkit.Acquired[*promptkit.PromptInspection], error) {
calls++
cancel()
return commandkit.Acquired[*promptkit.PromptInspection]{}, loadErr
}}
app := newPromptTestApp(t, Command(suite))
var out bytes.Buffer
result := app.Execute(ctx, []string{"promptkit", "show", "prompt", "example"}, commandkit.Streams{Out: &out, Err: io.Discard})
if result.Status != 1 || !errors.Is(result.Cause, context.Canceled) || !errors.Is(result.Cause, loadErr) || out.Len() != 0 || calls != 1 {
t.Fatalf("outcome=%#v calls=%d output=%q", result, calls, out.String())
}
ctx, cancel = context.WithCancel(context.Background())
cancel()
calls = 0
result = app.Execute(ctx, []string{"promptkit", "show", "prompt", "example"}, commandkit.Streams{Out: &out, Err: io.Discard})
if result.Status != 1 || !errors.Is(result.Cause, context.Canceled) || calls != 0 || out.Len() != 0 {
t.Fatalf("pre-canceled=%#v calls=%d", result, calls)
}
}

View File

@@ -0,0 +1,133 @@
package ckprompt
import (
"bytes"
"context"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
func TestPromptConstructorConfigurationOutcomes(t *testing.T) {
dir := t.TempDir()
mainPath := filepath.Join(dir, "config.yml")
companionPath := filepath.Join(dir, "prompts.yml")
for path, data := range map[string]string{mainPath: "companion: prompts.yml\n", companionPath: "profiles: [\n"} {
if err := os.WriteFile(path, []byte(data), 0600); err != nil {
t.Fatal(err)
}
}
good := adapterEngine(t)
var constructorErr error
load := func(_ context.Context, selection ckconfig.Selection, _, _ struct{}) (*promptkit.Engine, error) {
if selection.Config.Value == "good" {
return good, nil
}
appConfig, err := configkit.Load[struct {
Companion string `yaml:"companion"`
}](configkit.File(selection.Config.Value))
if err != nil {
return nil, err
}
companion := filepath.Join(filepath.Dir(selection.Config.Value), appConfig.Config.Companion)
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: configkit.File(companion)}}}, promptkit.WithBundledOpenRouter(false))
constructorErr = err
return engine, err
}
app := newPromptTestApp(t, Command(FromEngine[struct{}, struct{}](load)), ckconfig.Command(ckconfig.Suite[struct{}, struct{}]{Scopes: []ckconfig.Scope[struct{}, struct{}]{ConfigScope(load)}}))
cases := []struct {
name string
args []string
report, side string
}{
{"catalog", []string{"promptkit", "list", "prompts", "--config", mainPath}, "", ""},
{"show", []string{"config", "show", "--scope=promptkit", "--config", mainPath}, "", ""},
{"sources", []string{"config", "sources", "--format=json", "--scope=promptkit", "--config", mainPath}, `"sources"`, ""},
{"validate", []string{"config", "validate", "--details", "--format=json", "--scope=promptkit", "--config", mainPath}, `"code": "yaml.invalid"`, ""},
{"explain", []string{"config", "explain", "--list", "--scope=promptkit", "--config", mainPath}, "", ""},
{"diff left", []string{"config", "diff", "--scope=promptkit", "--config", mainPath, "--against-config=good"}, "", "left"},
{"diff right", []string{"config", "diff", "--scope=promptkit", "--config=good", "--against-config", mainPath}, "", "right"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
constructorErr = nil
var out, diag bytes.Buffer
result := app.Execute(context.Background(), tc.args, commandkit.Streams{Out: &out, Err: &diag})
var actual, expected *configkit.LoadError
if constructorErr == nil || !errors.As(constructorErr, &expected) || !errors.As(result.Cause, &actual) || actual != expected || !errors.Is(result.Cause, constructorErr) || !errors.Is(result.Cause, promptkit.ErrInvalidConfig) || result.Kind != commandkit.OutcomeUsage || result.Status != 2 {
t.Fatalf("outcome=%#v constructor=%v diagnostic=%q", result, constructorErr, diag.String())
}
if !strings.Contains(diag.String(), "yaml.invalid") || !strings.Contains(diag.String(), "prompts.yml") || (tc.report != "" && !strings.Contains(out.String(), tc.report)) || (tc.side != "" && !strings.Contains(diag.String(), "("+tc.side+")")) {
t.Fatalf("output=%q diagnostics=%q", out.String(), diag.String())
}
if tc.name == "sources" && !strings.Contains(out.String(), "prompts.yml") {
t.Fatalf("source evidence missing companion: %q", out.String())
}
})
}
}
func TestPromptConstructorFailurePrecedence(t *testing.T) {
dir := t.TempDir()
malformed := filepath.Join(dir, "prompts.yml")
if err := os.WriteFile(malformed, []byte("profiles: [\n"), 0600); err != nil {
t.Fatal(err)
}
_, invalid := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: configkit.File(malformed)}}}, promptkit.WithBundledOpenRouter(false))
_, missing := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: configkit.File(filepath.Join(dir, "missing.yml"))}}}, promptkit.WithBundledOpenRouter(false))
if invalid == nil || missing == nil || !errors.Is(invalid, promptkit.ErrInvalidConfig) || !errors.Is(missing, promptkit.ErrInvalidConfig) {
t.Fatalf("constructor fixtures invalid=%v missing=%v", invalid, missing)
}
operational := errors.New("independent failure")
for _, tc := range []struct {
name string
cause error
extra error
canceled bool
kind commandkit.OutcomeKind
}{
{"missing configuration", missing, promptkit.ErrInvalidConfig, false, commandkit.OutcomeOperational},
{"joined missing error", errors.Join(missing, os.ErrNotExist), os.ErrNotExist, false, commandkit.OutcomeOperational},
{"joined operational", errors.Join(invalid, operational), operational, false, commandkit.OutcomeOperational},
{"joined cancellation", errors.Join(invalid, context.Canceled), context.Canceled, false, commandkit.OutcomeOperational},
{"already canceled", nil, context.Canceled, true, commandkit.OutcomeOperational},
} {
for _, args := range [][]string{{"promptkit", "list", "prompts"}, {"config", "show", "--scope=promptkit"}} {
t.Run(tc.name+"/"+strings.Join(args, "_"), func(t *testing.T) {
calls := 0
load := func(context.Context, ckconfig.Selection, struct{}, struct{}) (*promptkit.Engine, error) {
calls++
if tc.cause != nil {
return nil, tc.cause
}
return adapterEngine(t), nil
}
app := newPromptTestApp(t, Command(FromEngine[struct{}, struct{}](load)), ckconfig.Command(ckconfig.Suite[struct{}, struct{}]{Scopes: []ckconfig.Scope[struct{}, struct{}]{ConfigScope(load)}}))
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
if tc.canceled {
cancel()
}
var out bytes.Buffer
result := app.Execute(ctx, args, commandkit.Streams{Out: &out})
if result.Kind != tc.kind || !errors.Is(result.Cause, tc.extra) {
t.Fatalf("outcome=%#v output=%q", result, out.String())
}
if tc.canceled {
if calls != 0 || out.Len() != 0 {
t.Fatalf("calls=%d output=%q", calls, out.String())
}
} else if calls != 1 || !errors.Is(result.Cause, tc.cause) || !errors.Is(result.Cause, promptkit.ErrInvalidConfig) {
t.Fatalf("outcome=%#v calls=%d", result, calls)
}
})
}
}
}

View File

@@ -8,6 +8,10 @@
// these with commandkit.New or App.Register.
//
// ConfigScope separately exposes engine configuration through ckconfig.
// ConfigScope preserves PromptKit focused discovery and whole-load evidence.
// Applications can compose PromptKit settings into an application-owned load
// and pass the completed result to promptkit.NewFromConfig.
//
// Importing this package installs neither command family. Applications own
// engine construction, credentials, and client configuration.
package ckprompt

View File

@@ -2,53 +2,53 @@
## PromptKit
Selected module: `go.maximumdirect.net/promptkit` at `v0.20.0`.
Selected module: `go.maximumdirect.net/promptkit` at `v0.24.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3.0](../../LICENSE) |
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/LICENSE).
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f).
## ConfigKit
Selected module: `go.maximumdirect.net/configkit` at `v1.1.0` (direct dependency).
Selected module: `go.maximumdirect.net/configkit` at `v1.4.0` (direct dependency).
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3.0](../../LICENSE) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/LICENSE).
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3).
## ReleaseKit
Selected module: `go.maximumdirect.net/releasekit` at `v0.9.0` (transitive Go tool requirement; not a runtime import).
Selected module: `go.maximumdirect.net/releasekit` at `v0.10.0` (transitive Go tool requirement; not a runtime import).
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3.0](../../LICENSE) |
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/LICENSE).
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243).
## JSON Schema
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2` (transitive dependency).
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3` (transitive dependency).
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE).
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
## Regular expression engine
@@ -65,17 +65,17 @@ License and notices: [MIT](licenses/MIT.txt) |
## Go text
Selected module: `golang.org/x/text` at `v0.14.0` (transitive dependency).
Selected module: `golang.org/x/text` at `v0.44.0` (transitive dependency).
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE) |
[PATENTS](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/PATENTS).
[LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
[PATENTS](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
[Source](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353).
[Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
## Standard Repository Policies
@@ -110,7 +110,7 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
## go-yaml v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov
@@ -120,14 +120,14 @@ Copyright 2025 The go-yaml Project Contributors
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
## go-yaml v3
Selected module: `gopkg.in/yaml.v3` at `v3.0.1` (transitive dependency).
Selected module: `go.yaml.in/yaml/v3` at `v3.0.4` (transitive dependency).
Copyright (c) 2006-2010 Kirill Simonov
@@ -137,77 +137,80 @@ Copyright 2011-2016 Canonical Ltd.
License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/c3552c15f996075a7634df5159d9161c67bf3d76/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/c3552c15f996075a7634df5159d9161c67bf3d76/NOTICE).
[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
[Source](https://github.com/yaml/go-yaml/tree/c3552c15f996075a7634df5159d9161c67bf3d76).
## Go modules
Selected module: `golang.org/x/mod` at `v0.40.0` (ReleaseKit tool dependency).
Selected module: `golang.org/x/mod` at `v0.43.0` (ReleaseKit tool dependency).
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f/LICENSE).
[LICENSE](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde/LICENSE) |
[PATENTS](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde/PATENTS).
[Source](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f).
[Source](https://go.googlesource.com/mod/+/d4f320b9266480df5ed3d791e0c68e64c58c5dde).
## Go tools
Selected module: `golang.org/x/tools` at `v0.6.0` (transitive dependency).
Selected module: `golang.org/x/tools` at `v0.52.0` (transitive dependency).
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/tools/+/d0863f03daeff79ab917de5768285bb077f77b20/LICENSE).
[LICENSE](https://go.googlesource.com/tools/+/16517d951552611e7bd358c48ee1051fd0e57b0c/LICENSE) |
[PATENTS](https://go.googlesource.com/tools/+/16517d951552611e7bd358c48ee1051fd0e57b0c/PATENTS).
[Source](https://go.googlesource.com/tools/+/d0863f03daeff79ab917de5768285bb077f77b20).
[Source](https://go.googlesource.com/tools/+/16517d951552611e7bd358c48ee1051fd0e57b0c).
## Go system
## Go synchronization
Selected module: `golang.org/x/sys` at `v0.5.0` (transitive dependency).
Selected module: `golang.org/x/sync` at `v0.25.0` (transitive dependency).
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/sys/+/90c8f94a055257f9ab343137cbada4e658750fbb/LICENSE).
[LICENSE](https://go.googlesource.com/sync/+/1f920df1e8fcf601d1aaf0f2ea500e1d2ccce105/LICENSE) |
[PATENTS](https://go.googlesource.com/sync/+/1f920df1e8fcf601d1aaf0f2ea500e1d2ccce105/PATENTS).
[Source](https://go.googlesource.com/sys/+/90c8f94a055257f9ab343137cbada4e658750fbb).
[Source](https://go.googlesource.com/sync/+/1f920df1e8fcf601d1aaf0f2ea500e1d2ccce105).
## Goldmark
Selected module: `github.com/yuin/goldmark/v2` at `v2.1.6` (ReleaseKit tool dependency).
Selected module: `github.com/yuin/goldmark/v2` at `v2.1.16` (ReleaseKit tool dependency).
Copyright (c) 2019 Yusuke Inuzuka
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[LICENSE](https://github.com/yuin/goldmark/blob/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c/LICENSE).
[LICENSE](https://github.com/yuin/goldmark/blob/c3f939122ba4dd6f80e05043ad195b82e77fcb41/LICENSE).
[Source](https://github.com/yuin/goldmark/tree/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c).
[Source](https://github.com/yuin/goldmark/tree/c3f939122ba4dd6f80e05043ad195b82e77fcb41).
## Cobra
Selected module: `github.com/spf13/cobra` at `v1.10.1` (core dependency).
Selected module: `github.com/spf13/cobra` at `v1.10.2` (core dependency).
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE.txt](https://github.com/spf13/cobra/blob/7da941c3547e93b8c9f70bbd3befca79c6335388/LICENSE.txt).
[LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/spf13/cobra/tree/7da941c3547e93b8c9f70bbd3befca79c6335388).
[Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## pflag
Selected module: `github.com/spf13/pflag` at `v1.0.9` (core dependency).
Selected module: `github.com/spf13/pflag` at `v1.1.0` (core dependency).
Copyright (c) 2012 Alex Ogier. All rights reserved.
@@ -216,9 +219,9 @@ Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/spf13/pflag/blob/10438578954bba2527fe5cae3684d4532b064bbe/LICENSE).
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://github.com/spf13/pflag/tree/10438578954bba2527fe5cae3684d4532b064bbe).
[Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).
## go-md2man

View File

@@ -0,0 +1,33 @@
# CommandKit ckprompt v0.10.0
CommandKit ckprompt v0.10.0 aligns with CommandKit core v0.7.0 and ckconfig
v0.9.0 and adopts PromptKit v0.23.2.
## Dependency updates
- ConfigKit v1.2.1 and stable go-yaml v4.0.0 update configuration loading.
- jsonschema v6.0.3 fixes validation-location reporting and numeric and email
validation edge cases. Go Text advances to v0.44.0.
- The selected core updates Cobra to v1.10.2 and pflag to v1.1.0. The
maintainer workflow uses ReleaseKit v0.10.0 and Go 1.27.4.
## Compatibility and upgrade
Pair `go.maximumdirect.net/ckprompt v0.10.0` with ckconfig v0.9.0 and core
v0.7.0. The consumer minimum remains Go 1.27.0. Applications continue to
construct engines and native requests through the existing callbacks.
Upstream validator fixes can change edge-case validation results and diagnostic
locations. Review scripts that depend on exact backend diagnostic or help text.
See the [consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
and [PromptKit upgrade guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/releases/v0.23.2.md#compatibility-and-upgrade).
Configuration failures retain the classification introduced in ckprompt v0.9.0.
Identifiable invalid input selects status `2`; operational failures and
cancellation select status `1` under the
[configuration-failure contract](../../../../docs/cli.md#configuration-failure-classification).
When upgrading from v0.8.0 or earlier, also review the
[v0.9.0 upgrade guidance](v0.9.0.md#compatibility-and-upgrade).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.10.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.10.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.10.0/integrations/ckprompt/docs/oss/attribution.md)

View File

@@ -0,0 +1,40 @@
# CommandKit ckprompt v0.11.0
Candidate note; publication is pending.
CommandKit ckprompt v0.11.0 adopts PromptKit v0.24.0 and ConfigKit v1.4.0.
It supports application-owned shared configuration loading and exposes native
focused PromptKit inspection. Core remains v0.7.0 and the consumer minimum
remains Go 1.27.0.
## Compatibility and upgrade
Pair this release with the coordinated ckconfig release. Complete PromptKit
configuration documents now place settings under `promptkit`; mount wrapperless
settings with `SettingsInput` and collection fragments with `CollectionInput`.
Discovery inputs for fragments need an explicit destination. Resource IDs do
not gain a prefix, but configuration paths now use native locations such as
`/promptkit/profiles/0/model`. Focused listings use native paths; explicit
queries, sources, diagnostics, and comparison retain whole-load context.
PromptKit removed `Config.SchemaDir`, `WithSchemaFS`, and `WithSchemaFile`.
Use supported inline, source-relative, or explicit-root schema selection.
Request builders replace validation with `*promptkit.OutputContractInput`;
its pointer repair budget distinguishes omission from explicit zero. Resolved
reports include the budget, including zero, and prompt reports include native
schema selections. The default enables one repair for eligible modes, which
can add a generation call, latency, and usage. Applications own resource-version
policy and sensitivity of their extension fields.
Prepared reports now include `message_content_hash` and native schema evidence.
Migrate positional `PreparedRun` literals to keyed fields; older JSON without
the hash decodes with an empty hash. See the [PromptKit migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md),
[format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md),
and [release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/releases/v0.24.0.md)
for the upstream contract. PromptKit v0.23.3's timeout and cancellation identity
corrections are included. The [consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
links the maintained shared-load example.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/docs/oss/attribution.md)

View File

@@ -0,0 +1,21 @@
# CommandKit ckprompt v0.7.0
CommandKit ckprompt v0.7.0 adopts PromptKit v0.21.0 and ConfigKit v1.2.0.
Application-owned engine loaders can select main-relative companion imports
through PromptKit's existing configuration-source API. ckprompt exposes the
resulting engine through its inspection, request, and smoke-testing adapters.
[PromptKit v0.21.0 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.21.0/docs/releases/v0.21.0.md)
## Compatibility and upgrade
Pair `go.maximumdirect.net/ckprompt v0.7.0` with ckconfig v0.7.0 and CommandKit
core v0.6.0. The consumer minimum is Go 1.27.0.
Application loaders constructing ConfigKit `Input` or `LayeredOptions` must use
field-named struct literals to accommodate the fields added upstream. See the
[consumer guide](../../../../docs/consumers/guide.md#module-selection) for module
selection and loader guidance.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.7.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.7.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.7.0/integrations/ckprompt/docs/oss/attribution.md)

View File

@@ -0,0 +1,25 @@
# CommandKit ckprompt v0.8.0
CommandKit ckprompt v0.8.0 adopts ckconfig v0.8.0's shared configuration-error
classification across inspection, catalogs, requirements, request preparation,
and smoke testing. ConfigKit loading errors returned by application request
builders now provide their source context, warnings, and terminal diagnostics
through the same adaptation used for engine-loader failures.
## Compatibility and upgrade
Pair `go.maximumdirect.net/ckprompt v0.8.0` with ckconfig v0.8.0 and CommandKit
core v0.6.0. The selected upstream versions are ConfigKit v1.2.0 and PromptKit
v0.21.0. The consumer minimum is Go 1.27.0.
Identifiable invalid configuration input now selects status `2`, including
configuration errors returned by request builders. These failures previously
selected status `1`. Update scripts that interpret those statuses. Operational
failures, cancellation, and ambiguous or unknown failure evidence select status
`1`. In aggregate smoke testing, operational failures take precedence over input
failures. Typed causes and available reports are preserved through the shared
reporting lifecycle. See the [CLI contract](../../../../docs/cli.md#configuration-failure-classification).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.8.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.8.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.8.0/integrations/ckprompt/docs/oss/attribution.md)

View File

@@ -0,0 +1,32 @@
# CommandKit ckprompt v0.9.0
This candidate upgrades PromptKit from v0.21.0 to v0.23.1. PromptKit's
constructor now preserves configuration causes without treating its category
sentinel as a separate failure.
## Compatibility and upgrade
Malformed PromptKit companion YAML returned by engine construction now selects
status `2` instead of `1`. Update scripts that interpret this status. Available
source and validation reports, diagnostics, typed ConfigKit causes, and
`promptkit.ErrInvalidConfig` recognition are retained. Operational failures and
cancellation continue to select status `1`. See the [configuration failure
contract](../../../../docs/cli.md#configuration-failure-classification).
Pair ckprompt v0.9.0 with ckconfig v0.8.0 and CommandKit core v0.6.0. The
selected upstream versions are ConfigKit v1.2.0 and PromptKit v0.23.1; the Go
consumer minimum remains 1.27.0. Native request builders continue to pass the
whole PromptKit request, including additive fields, and prepared reports carry
upstream fields such as parent run identifiers. Applications own construction
of engines and requests. See the [consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
and [upstream upgrade guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/releases/v0.23.1.md#compatibility-and-upgrade).
PromptKit v0.22.0 and v0.23.0 added fields to exported request, prepared,
result, and observation structs. If your application constructs affected types
with positional literals, migrate those literals to keyed fields when upgrading
from v0.21.0. See [PromptKit v0.22.0 compatibility](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/releases/v0.22.0.md#efficiency-and-compatibility)
and [PromptKit v0.23.0 upgrade guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/releases/v0.23.0.md#compatibility-and-upgrade).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.9.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.9.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.9.0/integrations/ckprompt/docs/oss/attribution.md)

View File

@@ -6,8 +6,8 @@ in-memory model client. **No model service or credentials are required.**
Use Go 1.27.0 on `PATH`. An aligned workspace containing all three local modules
exercises their current sources; follow the [workspace setup](../../../../docs/development.md#documentation-validation)
from the repository root. The example also builds independently with
`GOWORK=off` against its module's released dependencies.
from the repository root. The current checkout requires the local ckconfig API;
its published v0.9.0 dependency does not yet provide that API.
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
version and compatibility details.
@@ -21,7 +21,7 @@ go run . promptkit list prompts --campaign spring
go run . promptkit show prompt briefing --campaign spring --format yaml
```
The first command lists `app` and `promptkit` configurations and their available
The first command lists `app`, `storage`, and `promptkit` configurations and their available
operations. The next commands find and inspect the `briefing` prompt.
`--campaign` is a selector supplied by this example, not a standard PromptKit flag.
@@ -30,6 +30,8 @@ operations. The next commands find and inspect the `briefing` prompt.
```sh
go run . config validate --scope all --campaign spring --limit=0
go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml
go run . config show --scope storage --config fixtures/before.yml
go run . config diff --scope storage --config fixtures/before.yml --against-config fixtures/after.yml
go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring --against-campaign spring
```
@@ -44,8 +46,8 @@ The two sides have independent selectors and overrides:
go run . config diff --scope app --campaign spring --limit=0 --against-campaign autumn --against-limit=0 --set '/campaigns/spring/model="left"' --against-set '/campaigns/spring/model="right"' --details
```
Only the application scope supports `--set` here. The released PromptKit loader
has no override handoff, so its configuration scope does not enable the feature.
The application and storage scopes support `--set` here. The PromptKit scope
does not advertise override support in this example.
An aggregate operation that includes that scope rejects overrides.
## List resources and select namespaces
@@ -155,7 +157,9 @@ selects the command context without loading an engine.
The example installs `ckconfig.Command(suite)` and
`ckprompt.Declarations(definitions)` with application-owned aliases in a
`[]commandkit.Declaration`. `NewInput` initializes scope inputs; `NewState`
creates a cache shared within an invocation. The loaders cache successful
creates a cache shared within an invocation. The application composes PromptKit
settings and resources into its ConfigKit load; the engine consumes the same
result, and `FromConfigKitSubtree` exposes `storage`. The loaders cache successful
configuration results by the complete configuration/overlay selection,
overrides, and supplied campaign, including whether each value was supplied.
These are example choices, not a CommandKit cache policy.
@@ -167,5 +171,5 @@ for suite composition, builders, and ownership, and the [source](main.go) for
the complete application.
Run `GOWORK=auto GOTOOLCHAIN=local go test ./...` from this example directory
for an aligned workspace check. Use
`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases.
for an aligned workspace check. Independent ckprompt validation against its
declared requirements follows the coordinated ckconfig release.

View File

@@ -8,3 +8,6 @@ campaigns:
prompt_id: briefing
profile_id: autumn
model: autumn-model
storage:
driver: local
location: ./after

View File

@@ -8,3 +8,6 @@ campaigns:
prompt_id: briefing
profile_id: autumn
model: autumn-model
storage:
driver: local
location: ./before

View File

@@ -22,9 +22,16 @@ type campaign struct {
Model string `yaml:"model"`
}
type storageConfiguration struct {
Driver string `yaml:"driver"`
Location string `yaml:"location"`
}
type appConfiguration struct {
DefaultCampaign string `yaml:"default_campaign"`
Campaigns map[string]campaign `yaml:"campaigns"`
PromptKit promptkit.Settings `yaml:"promptkit"`
Storage storageConfiguration `yaml:"storage"`
DefaultCampaign string `yaml:"default_campaign"`
Campaigns map[string]campaign `yaml:"campaigns"`
}
type inspectionInput struct {
@@ -95,26 +102,75 @@ func loadApplicationConfig(ctx context.Context, selection ckconfig.Selection, in
}
}
}
source := configkit.Mapping("composed application settings", map[string]any{
"default_campaign": "spring",
"campaigns": map[string]any{
"spring": map[string]any{"prompt_id": "briefing", "profile_id": "spring", "model": "spring-model"},
"autumn": map[string]any{"prompt_id": "briefing", "profile_id": "autumn", "model": "autumn-model"},
definition := configkit.Definition[appConfiguration]{
Defaults: func() appConfiguration {
return appConfiguration{DefaultCampaign: "spring", Storage: storageConfiguration{Driver: "local", Location: "./data"}, Campaigns: map[string]campaign{
"spring": {PromptID: "briefing", ProfileID: "spring", Model: "spring-model"},
"autumn": {PromptID: "briefing", ProfileID: "autumn", Model: "autumn-model"},
}}
},
})
Resolve: func(value *appConfiguration, resolution *configkit.Resolution) error {
name, chosen, err := selectedCampaign(*value, commandkit.Supplied[string]{})
if err != nil {
return nil
}
deps := []configkit.Path{configkit.Keys("default_campaign"), configkit.Keys("campaigns", name)}
profilePath := configkit.Keys("promptkit", "profiles")
profileFound := false
for _, profile := range value.PromptKit.Profiles {
if profile.ID == chosen.ProfileID {
profileFound = true
break
}
}
if !profileFound {
value.PromptKit.Profiles = append(value.PromptKit.Profiles, promptkit.ProfileSettings{ID: chosen.ProfileID, Backend: new("local"), Endpoint: new("https://example.invalid/v1"), Model: new(chosen.Model), ExtraParams: map[string]any{"campaign": name}})
resolution.RecordNormalization(profilePath, "Selected campaign profile", deps...)
}
promptPath := configkit.Keys("promptkit", "prompts")
for index := range value.PromptKit.Prompts {
prompt := &value.PromptKit.Prompts[index]
if prompt.ID != "briefing" {
continue
}
if chosen.PromptID != prompt.ID {
prompt.ID = chosen.PromptID
resolution.RecordNormalization(promptPath, "Selected campaign prompt", deps...)
}
if prompt.DefaultProfile == nil {
prompt.DefaultProfile = new(chosen.ProfileID)
resolution.RecordDerivedDefault(promptPath.Index(index).Key("default_profile"), "Selected campaign profile", deps...)
}
break
}
return nil
},
}
definition = promptkit.Configure(definition, func(value *appConfiguration) *promptkit.Settings { return &value.PromptKit })
resources := promptkit.SettingsInput(configkit.Mapping("example resources", map[string]any{
"collections": map[string]any{"field-notes": map[string]any{
"release_version": "1",
"backends": []any{map[string]any{"id": "demo", "endpoint": "https://example.invalid/v1"}},
"profiles": []any{map[string]any{"id": "assistant", "backend": "field-notes/demo", "model": "example-model"}},
"prompts": []any{map[string]any{"id": "briefing", "default_profile": "field-notes/assistant", "inputs": []any{map[string]any{"name": "topic", "required": true, "content_type": "text/plain", "description": "Topic to brief"}}, "messages": []any{map[string]any{"role": "user", "content": "Write a concise briefing about {{.topic}}."}}, "output": map[string]any{"format": "text", "validation_mode": "none"}}},
}},
"prompts": []any{map[string]any{"id": "briefing", "inputs": []any{map[string]any{"name": "topic", "required": true, "content_type": "text/plain", "description": "Topic to brief"}}, "messages": []any{map[string]any{"role": "user", "content": "Write a concise briefing about {{.topic}}. {{if .mode}}{{input \"notes\"}}{{end}}"}}, "output": map[string]any{"format": "text", "validation_mode": "none"}}},
"backends": []any{map[string]any{"id": "local", "endpoint": "https://example.invalid/v1"}},
}))
source := configkit.NoSource()
if selection.Config.Set {
source = configkit.File(selection.Config.Value)
}
options := configkit.Options[appConfiguration]{}
options := configkit.LayeredOptions[appConfiguration]{Definition: definition, Underlays: []configkit.Underlay{promptkit.BundledOpenRouterUnderlay(), {Inputs: []configkit.Input{resources}}}}
if selection.Overlay.Set {
options.Overlay = selection.Overlay.Value
options.Filesystem = &configkit.FilesystemContext{Root: ".", BaseDir: "."}
options.OverlayFilesystem = &configkit.FilesystemContext{Root: ".", BaseDir: "."}
}
if campaignInput.Set {
options.Overrides = []configkit.Override{{Path: configkit.Keys("default_campaign"), Value: campaignInput.Value, Flag: "--campaign"}}
}
options.Overrides = append(options.Overrides, selection.Overrides...)
result, err := configkit.Load(source, options)
result, err := configkit.LoadLayered(configkit.Input{Source: source}, options)
if err == nil && result != nil && cache != nil {
cache.applications = append(cache.applications, applicationCacheEntry{selection: selection, campaign: campaignInput, result: result})
}
@@ -126,48 +182,14 @@ func loadPromptEngine(ctx context.Context, selection ckconfig.Selection, input *
if err != nil {
return nil, err
}
name, chosen, err := selectedCampaign(application.Config, input.Campaign)
if err != nil {
if _, _, err := selectedCampaign(application.Config, commandkit.Supplied[string]{}); err != nil {
return nil, err
}
engineConfig := configkit.Mapping("campaign "+name, map[string]any{
"collections": map[string]any{
"field-notes": map[string]any{
"release_version": "1",
"backends": []any{map[string]any{"id": "demo", "endpoint": "https://example.invalid/v1"}},
"profiles": []any{map[string]any{"id": "assistant", "backend": "field-notes/demo", "model": "example-model"}},
"prompts": []any{map[string]any{
"id": "briefing",
"default_profile": "field-notes/assistant",
"inputs": []any{map[string]any{"name": "topic", "required": true, "content_type": "text/plain", "description": "Topic to brief"}},
"messages": []any{map[string]any{"role": "user", "content": "Write a concise briefing about {{.topic}}."}},
"output": map[string]any{"format": "text", "validation_mode": "none"},
}},
},
},
"backends": []any{map[string]any{"id": "local", "endpoint": "https://example.invalid/v1"}},
"profiles": []any{map[string]any{
"id": chosen.ProfileID,
"backend": "local",
"endpoint": "https://example.invalid/v1",
"model": chosen.Model,
"extra_params": map[string]any{
"campaign": name,
},
}},
"prompts": []any{map[string]any{
"id": chosen.PromptID,
"default_profile": chosen.ProfileID,
"inputs": []any{map[string]any{"name": "topic", "required": true, "content_type": "text/plain", "description": "Topic to brief"}},
"messages": []any{map[string]any{"role": "user", "content": "Write a concise briefing about {{.topic}}. {{if .mode}}{{input \"notes\"}}{{end}}"}},
"output": map[string]any{"format": "text", "validation_mode": "none"},
}},
})
var client promptkit.LLMClient = &exampleLLMClient{}
if cache != nil && cache.llmClient != nil {
client = cache.llmClient
}
return promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: engineConfig}}}, promptkit.WithLLMClient(client))
return promptkit.NewFromConfig(application, promptkit.RuntimeConfig{}, promptkit.WithLLMClient(client))
}
func selectedCampaign(configuration appConfiguration, supplied commandkit.Supplied[string]) (string, campaign, error) {
@@ -231,6 +253,8 @@ func newAppWithEngineLoader(
appScope := ckconfig.FromConfigKit("app", "Application settings.", loadApplicationConfig)
appScope.Features.Overrides = true
storageScope := ckconfig.FromConfigKitSubtree("storage", "Storage settings.", configkit.Keys("storage"), loadApplicationConfig)
storageScope.Features.Overrides = true
engineScope := ckprompt.ConfigScope(engineLoader)
configCommand := ckconfig.Command(ckconfig.Suite[*inspectionInput, *runCache]{
NewInput: inputFactory,
@@ -242,10 +266,10 @@ func newAppWithEngineLoader(
return nil
},
Selectors: []ckconfig.Selector[*inspectionInput]{
{Binding: campaignSelector(), AgainstName: "against-campaign", Scopes: []string{"app", "promptkit"}},
{Binding: campaignSelector(), AgainstName: "against-campaign", Scopes: []string{"app", "storage", "promptkit"}},
{Binding: limitFlag, AgainstName: "against-limit", Scopes: []string{"app"}},
},
Scopes: []ckconfig.Scope[*inspectionInput, *runCache]{appScope, engineScope},
Scopes: []ckconfig.Scope[*inspectionInput, *runCache]{appScope, storageScope, engineScope},
})
definitions := ckprompt.FromEngine(engineLoader)

View File

@@ -7,6 +7,8 @@ import (
"errors"
"fmt"
"io"
"os"
"path/filepath"
"reflect"
"strings"
"testing"
@@ -170,7 +172,7 @@ func TestComposedIndependentOverridesAndFailureEvidence(t *testing.T) {
}
outcome = app.Execute(context.Background(), []string{"config", "validate", "--scope", "app", "--campaign", "spring", "--limit=0", "--set", `/default_campaign="autumn"`}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if outcome.Kind != commandkit.OutcomeOperational || outcome.Cause == nil {
if outcome.Kind != commandkit.OutcomeUsage || outcome.Cause == nil {
t.Fatalf("overlapping native overrides: %#v", outcome)
}
loads := 0
@@ -294,7 +296,7 @@ func TestComposedPromptKitAndDomainCommandsRemainAvailable(t *testing.T) {
{"config", "validate", "--scope", "all", "--campaign", "spring", "--limit=0"},
{"config", "show", "--scope", "promptkit", "--campaign", "spring"},
{"config", "sources", "--scope", "promptkit", "--campaign", "spring"},
{"config", "explain", "--scope", "promptkit", "--path", fmt.Sprintf("/profiles/%d/model", index), "--campaign", "spring"},
{"config", "explain", "--scope", "promptkit", "--path", fmt.Sprintf("/promptkit/profiles/%d/model", index), "--campaign", "spring"},
{"promptkit", "show", "prompt", "briefing", "--campaign", "spring", "--format", "yaml"},
{"promptkit", "show", "profile", "spring", "--campaign", "spring"},
{"session", "restore", "session-42", "--campaign", "spring"},
@@ -461,17 +463,19 @@ func TestPromptKitScopeDiffAndCatalogsUseSelectedCampaign(t *testing.T) {
}
var diff struct {
Changes struct {
Profiles []struct {
ID string `yaml:"id"`
Model string `yaml:"model"`
} `yaml:"profiles"`
PromptKit struct {
Profiles []struct {
ID string `yaml:"id"`
Model string `yaml:"model"`
} `yaml:"profiles"`
} `yaml:"promptkit"`
} `yaml:"changes"`
}
if err := yaml.Unmarshal(output.Bytes(), &diff); err != nil {
t.Fatal(err)
}
foundChange := false
for _, profile := range diff.Changes.Profiles {
for _, profile := range diff.Changes.PromptKit.Profiles {
if profile.ID == "spring" && profile.Model == "spring-model-after" {
foundChange = true
}
@@ -740,3 +744,124 @@ func composedField(mapping *yaml.Node, name string) *yaml.Node {
func ckconfigSelection(path string) ckconfig.Selection {
return ckconfig.Selection{Config: commandkit.Supplied[string]{Value: path, Set: true}}
}
func TestComposedStorageScopeAndSharedResult(t *testing.T) {
cache := &runCache{}
selection := ckconfigSelection("fixtures/before.yml")
input := &inspectionInput{Campaign: commandkit.Supplied[string]{Value: "spring", Set: true}}
result, err := loadApplicationConfig(context.Background(), selection, input, cache)
if err != nil {
t.Fatal(err)
}
engine, err := loadPromptEngine(context.Background(), selection, input, cache)
if err != nil {
t.Fatal(err)
}
if len(cache.applications) != 1 || cache.applications[0].result != result {
t.Fatal("engine did not use the selected application result")
}
inspection, err := engine.InspectConfiguration()
if err != nil {
t.Fatal(err)
}
appView, ok := result.InspectSubtree(configkit.Keys("promptkit"))
if !ok {
t.Fatal("missing application inspection")
}
var appYAML, promptYAML bytes.Buffer
if err := appView.WriteEffective(&appYAML); err != nil {
t.Fatal(err)
}
if err := inspection.WriteEffective(&promptYAML); err != nil {
t.Fatal(err)
}
if appYAML.String() != promptYAML.String() {
t.Fatal("engine inspection differs from shared application result")
}
app, err := newApp()
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
args []string
want string
}{
{[]string{"config", "show", "--scope=storage", "--config=fixtures/before.yml"}, "./before"},
{[]string{"config", "explain", "--scope=storage", "--config=fixtures/before.yml", "--path=/storage/location"}, "/storage/location"},
{[]string{"config", "diff", "--scope=storage", "--config=fixtures/before.yml", "--against-config=fixtures/after.yml"}, "./after"},
{[]string{"config", "show", "--scope=storage", `--set=/storage/location="custom"`, "--campaign=spring"}, "custom"},
{[]string{"config", "show", "--scope=app"}, "promptkit:"},
{[]string{"config", "validate", "--scope=all"}, "storage"},
} {
var output, diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), tc.args, commandkit.Streams{Out: &output, Err: &diagnostics})
if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output.String(), tc.want) {
t.Errorf("%v: %#v output=%q diagnostics=%q", tc.args, outcome, output.String(), diagnostics.String())
}
}
var diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), []string{"config", "show", "--scope=storage", "--config=fixtures/missing.yml"}, commandkit.Streams{Out: io.Discard, Err: &diagnostics})
if outcome.Kind != commandkit.OutcomeOperational || !strings.Contains(diagnostics.String(), "missing.yml") {
t.Fatalf("failed load: %#v %q", outcome, diagnostics.String())
}
}
func TestComposedCampaignPromptID(t *testing.T) {
path := filepath.Join(t.TempDir(), "campaign.yml")
if err := os.WriteFile(path, []byte("campaigns:\n spring:\n prompt_id: custom\n profile_id: spring\n model: spring-model\n"), 0600); err != nil {
t.Fatal(err)
}
selection := ckconfigSelection(path)
cache := &runCache{}
input := &inspectionInput{}
result, err := loadApplicationConfig(t.Context(), selection, input, cache)
if err != nil {
t.Fatal(err)
}
engine, err := loadPromptEngine(t.Context(), selection, input, cache)
if err != nil {
t.Fatal(err)
}
view, ok := result.InspectSubtree(configkit.Keys("promptkit"))
if !ok {
t.Fatal("missing application inspection")
}
inspection, err := engine.InspectConfiguration()
if err != nil {
t.Fatal(err)
}
var applicationOutput, engineOutput bytes.Buffer
if err := view.WriteEffective(&applicationOutput); err != nil {
t.Fatal(err)
}
if err := inspection.WriteEffective(&engineOutput); err != nil {
t.Fatal(err)
}
applicationValue, err := commandkit.DecodeYAMLReport(&applicationOutput)
if err != nil {
t.Fatal(err)
}
engineValue, err := commandkit.DecodeYAMLReport(&engineOutput)
if err != nil || !reflect.DeepEqual(applicationValue, engineValue) {
t.Fatalf("shared inspection mismatch: application=%#v engine=%#v error=%v", applicationValue, engineValue, err)
}
app, err := newApp()
if err != nil {
t.Fatal(err)
}
var output, diagnostics bytes.Buffer
outcome := app.Execute(t.Context(), []string{"promptkit", "list", "prompts", "--config=" + path, "--format=json"}, commandkit.Streams{Out: &output, Err: &diagnostics})
if outcome.Kind != commandkit.OutcomeSuccess {
t.Fatalf("catalog failed: %#v, %s", outcome, diagnostics.String())
}
var prompts []struct{ ID string }
if err := json.Unmarshal(output.Bytes(), &prompts); err != nil {
t.Fatal(err)
}
for _, prompt := range prompts {
if prompt.ID == "custom" {
return
}
}
t.Fatalf("catalog lacks selected campaign prompt: %s", output.String())
}

View File

@@ -3,17 +3,17 @@ module go.maximumdirect.net/ckprompt
go 1.27.0
require (
go.maximumdirect.net/ckconfig v0.6.0
go.maximumdirect.net/commandkit v0.6.0
go.maximumdirect.net/configkit v1.1.0
go.maximumdirect.net/promptkit v0.20.0
go.yaml.in/yaml/v4 v4.0.0-rc.6
go.maximumdirect.net/ckconfig v0.9.0
go.maximumdirect.net/commandkit v0.7.0
go.maximumdirect.net/configkit v1.4.0
go.maximumdirect.net/promptkit v0.24.0
go.yaml.in/yaml/v4 v4.0.0
)
require (
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
github.com/spf13/cobra v1.10.1 // indirect
github.com/spf13/pflag v1.0.9 // indirect
golang.org/x/text v0.14.0 // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
github.com/spf13/cobra v1.10.2 // indirect
github.com/spf13/pflag v1.1.0 // indirect
golang.org/x/text v0.44.0 // indirect
)

View File

@@ -4,31 +4,24 @@ github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cn
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
go.maximumdirect.net/ckconfig v0.4.0 h1:7MpI/jIy+3BZrVME5rhKQibh5U9IA3s97BUJ2EOG41s=
go.maximumdirect.net/ckconfig v0.4.0/go.mod h1:Mk6QOfHrFy00uE0/gw9h6/Y9LcdTShVEzM/oI/HGDns=
go.maximumdirect.net/ckconfig v0.5.0 h1:5YCPFySTFIFR+gzd0FjqkTPEVB7zkGa8kOEYh4aBvWc=
go.maximumdirect.net/ckconfig v0.5.0/go.mod h1:BONXRSQlHdJvYVw9mN6lMV4G4ldlV/5fRO9EEApA99s=
go.maximumdirect.net/ckconfig v0.6.0 h1:N7MJKJiXhv+tT4HA7dnINUxC0Uq8hzYmBTFjrpvkbvQ=
go.maximumdirect.net/ckconfig v0.6.0/go.mod h1:69HOkR2Jbq7rJz3jlFAL6Oo5qorEiVrxQVLXoqav98s=
go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
go.maximumdirect.net/commandkit v0.5.0 h1:Ln+bCp+FwCg4tZD3NaMKQXUDB3mPusgwsnRZmb0+3cM=
go.maximumdirect.net/commandkit v0.5.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
go.maximumdirect.net/commandkit v0.6.0 h1:4PHhMIlZuuvreIxZhUazeweg6zoYixEvhM9LJnkbGNA=
go.maximumdirect.net/commandkit v0.6.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
go.maximumdirect.net/configkit v1.1.0 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
go.maximumdirect.net/promptkit v0.20.0 h1:ZpwbjiCZWXdnnZ26RuWKoOco0jFnaAX8m2tQAX7ZlnM=
go.maximumdirect.net/promptkit v0.20.0/go.mod h1:kCoyvI0xSax9K9aRPCEkpkyAP5YLs157oBLFLdzgRbM=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
go.maximumdirect.net/ckconfig v0.9.0 h1:s9Ikga4wt4K1NpLCX9bLhm5vbcm1Fgqy9yk2lmO4Sss=
go.maximumdirect.net/ckconfig v0.9.0/go.mod h1:yGjFVr2UzjJjiwDdMwsKehuQfvvtv7rTEOIk5NQOY00=
go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
go.maximumdirect.net/configkit v1.4.0 h1:TfOupZbQ23/ZMs+xt5lmyukCF11ekqKep8KbmFQD63o=
go.maximumdirect.net/configkit v1.4.0/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
go.maximumdirect.net/promptkit v0.24.0 h1:C6UFY8WgW10PIEuXQN2Z0qi0at5mD3/GQoPul6alYHo=
go.maximumdirect.net/promptkit v0.24.0/go.mod h1:o2axdkV11KTPDgk81i2vrJ66dtcedXRhau/Ko3YSZ4A=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/text v0.44.0 h1:YItdp/mQNGnsmrgpcdA5yQ3bnRxCfo/Tj/iByGW9GGo=
golang.org/x/text v0.44.0/go.mod h1:S4FR1waQ9LbjQTls97SyRjDaUUVkaM+cXwwuG/G+MwY=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

View File

@@ -43,7 +43,8 @@ func WithRequestPreparation[I, S any](
if build != nil {
built, err := build(ctx, request, input, state)
if err != nil {
return commandkit.Acquired[*promptkit.PreparedRun]{}, err
messages := promptKitLoadErrorDiagnostics(err, "")
return commandkit.Acquired[*promptkit.PreparedRun]{Diagnostics: messages.diagnostics, Explanation: messages.explanation}, err
}
concrete = built
}
@@ -82,26 +83,26 @@ func newPreparationCommand[I, S any](suite Suite[I, S], aliases *[]commandkit.De
func runRequestPreparation[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *concreteRequestInput[I]) commandkit.Outcome {
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit request preparation was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit request preparation was canceled.", commandkit.Explanation{}, err)
}
var state S
if suite.NewState != nil {
state = suite.NewState()
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit request preparation was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit request preparation was canceled.", commandkit.Explanation{}, err)
}
request := PreparationRequest{Selection: input.request.Selection, Request: input.request.Request, Namespaces: input.request.Namespaces}
acquired, err := suite.PrepareRequest(invocation.Context, request, input.selected, state)
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
if err != nil {
return definitionFailure(fmt.Sprintf("Unable to prepare the PromptKit request for prompt %q.", input.promptID), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Unable to prepare the PromptKit request for prompt %q.", input.promptID), acquired.Explanation, err)
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure(fmt.Sprintf("Preparation of the PromptKit request for prompt %q was canceled.", input.promptID), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Preparation of the PromptKit request for prompt %q was canceled.", input.promptID), acquired.Explanation, err)
}
if acquired.Value == nil {
return definitionFailure("PromptKit request preparation returned no result.", acquired.Explanation, nil)
return definitionFailure(invocation.Context, "PromptKit request preparation returned no result.", acquired.Explanation, nil)
}
_ = invocation.Reporter().Report(commandkit.Report{Value: acquired.Value})
return commandkit.Success()

View File

@@ -19,7 +19,7 @@ func TestPreparationCommandForwardsOrderedInputsAndNativeReport(t *testing.T) {
ctx := context.WithValue(context.Background(), key{}, "context")
var received PreparationRequest
calls := 0
native := &promptkit.PreparedRun{PromptID: "native", Messages: []promptkit.RenderedMessage{{Content: "rendered"}}}
native := &promptkit.PreparedRun{PromptID: "native", ParentRunID: "parent-run", Messages: []promptkit.RenderedMessage{{Content: "rendered"}}}
app := newPromptTestApp(t, Command(Suite[struct{}, struct{}]{PrepareRequest: func(got context.Context, req PreparationRequest, _, _ struct{}) (commandkit.Acquired[*promptkit.PreparedRun], error) {
if got.Value(key{}) != "context" {
t.Fatal("invocation context lost")

View File

@@ -0,0 +1,109 @@
package ckprompt
import (
"bytes"
"context"
"encoding/json"
"io"
"reflect"
"testing"
"go.maximumdirect.net/ckconfig"
commandkit "go.maximumdirect.net/commandkit"
promptkit "go.maximumdirect.net/promptkit"
)
func TestNativeSchemaAndPreparedEvidenceReports(t *testing.T) {
const fixture = `profiles:
- id: default
endpoint: https://example.invalid/v1
model: example
prompts:
- id: inline
default_profile: default
messages: [{role: user, content: hello}]
output:
format: json
validation_mode: json_schema
schema: {type: object}
repair_attempts: 0
- id: referenced
default_profile: default
messages: [{role: user, content: hello}]
output:
format: json
validation_mode: json_schema
schema_file: schema.json
repair_attempts: 0
`
engine := adapterEngineFrom(t, "schemas", fixture)
loader := func(context.Context, ckconfig.Selection, struct{}, struct{}) (*promptkit.Engine, error) {
return engine, nil
}
suite := WithRequestPreparation(FromEngine(loader), loader, nil)
app := newPromptTestApp(t, Command(suite))
for _, id := range []string{"inline", "referenced"} {
native, err := engine.InspectPrompt(t.Context(), id)
if err != nil {
t.Fatal(err)
}
if native.OutputContract.RepairAttempts != 0 || (id == "inline" && native.OutputContract.Schema == nil) || (id == "referenced" && native.OutputContract.SchemaFile == nil) {
t.Fatalf("native output = %#v", native.OutputContract)
}
var output bytes.Buffer
result := app.Execute(t.Context(), []string{"promptkit", "show", "prompt", id, "--format=json"}, commandkit.Streams{Out: &output, Err: io.Discard})
var actual any
decoder := json.NewDecoder(&output)
decoder.UseNumber()
err = decoder.Decode(&actual)
if result.Kind != commandkit.OutcomeSuccess || err != nil || !reflect.DeepEqual(actual, jsonValue(t, native)) {
t.Fatalf("report = %#v, %v, %#v", result, err, actual)
}
}
native, err := engine.Prepare(t.Context(), promptkit.RunRequest{PromptID: "inline"})
if err != nil {
t.Fatal(err)
}
if native.MessageContentHash == "" || native.OutputContract.RepairAttempts != 0 || native.OutputContract.Schema == nil {
t.Fatalf("native prepared = %#v", native)
}
var output bytes.Buffer
outcome := app.Execute(t.Context(), []string{"promptkit", "show", "prepared", "inline", "--format=json"}, commandkit.Streams{Out: &output, Err: io.Discard})
var actual any
decoder := json.NewDecoder(&output)
decoder.UseNumber()
err = decoder.Decode(&actual)
if outcome.Kind != commandkit.OutcomeSuccess || err != nil {
t.Fatalf("prepared report = %#v, %v", outcome, err)
}
gotReport := actual.(map[string]any)
expected := jsonValue(t, native).(map[string]any)
for _, key := range []string{"message_content_hash", "output_contract", "structured_output"} {
if !reflect.DeepEqual(gotReport[key], expected[key]) {
t.Errorf("%s = %#v, want %#v", key, gotReport[key], expected[key])
}
}
}
func TestPreparationBuilderForwardsReplacementRepairBudget(t *testing.T) {
engine := adapterEngine(t)
loader := func(context.Context, ckconfig.Selection, struct{}, struct{}) (*promptkit.Engine, error) {
return engine, nil
}
zero := 0
for _, budget := range []*int{nil, &zero} {
replacement := &promptkit.OutputContractInput{Format: promptkit.FormatJSON, ValidationMode: promptkit.ValidationJSON, RepairAttempts: budget}
request := promptkit.RunRequest{PromptID: "empty", Validation: replacement}
want, err := engine.Prepare(t.Context(), request)
if err != nil {
t.Fatal(err)
}
suite := WithRequestPreparation(Suite[struct{}, struct{}]{}, loader, func(context.Context, PreparationRequest, struct{}, struct{}) (promptkit.RunRequest, error) {
return request, nil
})
got, err := suite.PrepareRequest(t.Context(), PreparationRequest{}, struct{}{}, struct{}{})
if err != nil || !reflect.DeepEqual(got.Value.OutputContract, want.OutputContract) || got.Value.MessageContentHash != want.MessageContentHash || (budget == nil && got.Value.OutputContract.RepairAttempts != 1) || (budget != nil && got.Value.OutputContract.RepairAttempts != 0) {
t.Fatalf("replacement = %#v, %v; native = %#v", got.Value, err, want)
}
}
}

View File

@@ -0,0 +1,118 @@
package ckprompt
import (
"bytes"
"context"
"encoding/json"
"reflect"
"strings"
"testing"
"go.maximumdirect.net/ckconfig"
commandkit "go.maximumdirect.net/commandkit"
configkit "go.maximumdirect.net/configkit"
promptkit "go.maximumdirect.net/promptkit"
)
func TestConfigScopeUsesNativeSharedLoadPaths(t *testing.T) {
type application struct {
Name string `yaml:"app_name"`
PromptKit promptkit.Settings `yaml:"promptkit"`
}
definition := promptkit.Configure(configkit.Definition[application]{Validate: func(_ *application, v *configkit.Validation) {
v.Warning(configkit.Keys("app_name"), "application warning")
}}, func(a *application) *promptkit.Settings { return &a.PromptKit })
source := "app_name: example\npromptkit:\n " + strings.ReplaceAll(strings.TrimSpace(adapterPrompt), "\n", "\n ") + "\n"
result, err := configkit.Load(configkit.Bytes("shared application", []byte(source)), configkit.Options[application]{Definition: definition})
if err != nil {
t.Fatal(err)
}
engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{})
if err != nil {
t.Fatal(err)
}
native, err := engine.InspectConfiguration()
if err != nil {
t.Fatal(err)
}
scope := ConfigScope(func(context.Context, ckconfig.Selection, struct{}, struct{}) (*promptkit.Engine, error) {
return engine, nil
})
app := newPromptTestApp(t, ckconfig.Command(ckconfig.Suite[struct{}, struct{}]{Scopes: []ckconfig.Scope[struct{}, struct{}]{scope}}))
run := func(args ...string) ([]string, string, string) {
t.Helper()
var out, diag bytes.Buffer
argv := append([]string{"config", "explain", "--scope=promptkit", "--format=json", "--verbose"}, args...)
outcome := app.Execute(context.Background(), argv, commandkit.Streams{Out: &out, Err: &diag})
if outcome.Kind != commandkit.OutcomeSuccess {
t.Fatalf("%v: %#v %s", args, outcome, diag.String())
}
var report struct {
Paths []struct {
Path string `json:"path"`
} `json:"paths"`
}
if args[0] == "--list" {
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
}
var paths []string
for _, entry := range report.Paths {
paths = append(paths, entry.Path)
}
return paths, out.String(), diag.String()
}
metadata := native.Metadata()
expected := func(prefix string, explicit *bool) []string {
var paths []string
for _, path := range native.HistoricalPaths() {
info, present := metadata.Lookup(path)
if !present || (prefix != "" && !strings.HasPrefix(path.String(), prefix)) || (explicit != nil && info.Explicit != *explicit) {
continue
}
paths = append(paths, path.String())
}
return paths
}
yes := true
for _, tc := range []struct {
args []string
prefix string
explicit *bool
}{
{[]string{"--list"}, "", nil}, {[]string{"--list", "--historical"}, "", nil}, {[]string{"--list", "--under=/promptkit/prompts"}, "/promptkit/prompts", nil}, {[]string{"--list", "--explicit=true"}, "", &yes},
} {
paths, _, diag := run(tc.args...)
if !reflect.DeepEqual(paths, expected(tc.prefix, tc.explicit)) || !strings.Contains(diag, "application warning") {
t.Fatalf("paths=%v want=%v diagnostics=%q", paths, expected(tc.prefix, tc.explicit), diag)
}
}
_, output, diag := run("--path=/app_name")
if !strings.Contains(output, "app_name") || !strings.Contains(output, "shared application") || !strings.Contains(diag, "application warning") {
t.Fatalf("output=%q diagnostics=%q", output, diag)
}
}
func TestRequirementsReportsApplicationInputDefaults(t *testing.T) {
type application struct {
PromptKit promptkit.Settings `yaml:"promptkit"`
}
settings := promptkit.Settings{
Profiles: []promptkit.ProfileSettings{{ID: "default", Endpoint: new("https://example.invalid/v1"), Model: new("example")}},
Prompts: []promptkit.PromptSettings{{ID: "briefing", DefaultProfile: new("default"), Inputs: []promptkit.PromptInputSettings{{Name: "doc", Required: true, ContentType: new("text/plain"), Description: new("application default")}}, Messages: []promptkit.PromptMessageSettings{{Role: new("user"), Content: new("hello")}}, Output: &promptkit.PromptOutputSettings{Format: new("text"), ValidationMode: new("none")}}},
}
definition := promptkit.Configure(configkit.Definition[application]{Defaults: func() application { return application{PromptKit: settings} }}, func(value *application) *promptkit.Settings { return &value.PromptKit })
result, err := configkit.Load(configkit.NoSource(), configkit.Options[application]{Definition: definition})
if err != nil {
t.Fatal(err)
}
engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{})
if err != nil {
t.Fatal(err)
}
native, _, report, _ := executeRequirementsAgainstNative(t, engine, promptkit.RequirementInspectionRequest{PromptID: "briefing"}, []string{"promptkit", "requirements", "show", "briefing"})
if len(native.Inputs) != 1 || native.Inputs[0].ContentType == nil || *native.Inputs[0].ContentType != "text/plain" || native.Inputs[0].Description == nil || *native.Inputs[0].Description != "application default" || len(report) == 0 {
t.Fatalf("native requirements = %#v, report = %#v", native, report)
}
}

View File

@@ -51,7 +51,8 @@ func WithSmokeTesting[I, S any](
if build != nil {
built, err := build(ctx, request, input, state)
if err != nil {
return commandkit.Acquired[*promptkit.SmokeTestReport]{}, err
messages := promptKitLoadErrorDiagnostics(err, "")
return commandkit.Acquired[*promptkit.SmokeTestReport]{Diagnostics: messages.diagnostics, Explanation: messages.explanation}, err
}
concreteRequest = built
}

View File

@@ -91,14 +91,14 @@ func newSmokeTestCommand[I, S any](suite Suite[I, S], aliases *[]commandkit.Decl
func runSmokeTest[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *smokeCommandInput[I]) commandkit.Outcome {
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit smoke testing was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit smoke testing was canceled.", commandkit.Explanation{}, err)
}
var state S
if suite.NewState != nil {
state = suite.NewState()
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit smoke testing was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit smoke testing was canceled.", commandkit.Explanation{}, err)
}
if input.kind == "all" {
return runSmokeAggregate(invocation, suite, input, state)
@@ -118,12 +118,12 @@ func runSmokeTest[I, S any](invocation commandkit.Invocation, suite Suite[I, S],
}
}
if acquired.Value == nil {
return definitionFailure(smokeFailureMessage(input.kind), acquired.Explanation, operationErr)
return definitionFailure(invocation.Context, smokeFailureMessage(input.kind), acquired.Explanation, operationErr)
}
_ = invocation.Reporter().Report(commandkit.Report{Value: smokeReportFromNative(acquired.Value)})
if operationErr != nil {
return definitionFailure(smokeFailureMessage(input.kind), acquired.Explanation, operationErr)
return definitionFailure(invocation.Context, smokeFailureMessage(input.kind), acquired.Explanation, operationErr)
}
return commandkit.Success()
}
@@ -146,7 +146,7 @@ func runSmokeAggregate[I, S any](invocation commandkit.Invocation, suite Suite[I
for _, kind := range kinds {
if err := promptKitContextError(invocation.Context); err != nil {
if len(results) == 0 {
return definitionFailure("PromptKit aggregate smoke testing was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit aggregate smoke testing was canceled.", commandkit.Explanation{}, err)
}
operationErrors = append(operationErrors, err)
break
@@ -182,11 +182,11 @@ func runSmokeAggregate[I, S any](invocation commandkit.Invocation, suite Suite[I
}
if len(results) == 0 {
return definitionFailure("PromptKit aggregate smoke testing did not produce any results.", combineSmokeExplanations(explanations), errors.Join(operationErrors...))
return definitionFailure(invocation.Context, "PromptKit aggregate smoke testing did not produce any results.", combineSmokeExplanations(explanations), errors.Join(operationErrors...))
}
_ = invocation.Reporter().Report(commandkit.Report{Value: smokeResultsReport(results)})
if len(operationErrors) > 0 {
return definitionFailure("One or more PromptKit smoke tests failed.", combineSmokeExplanations(explanations), errors.Join(operationErrors...))
return definitionFailure(invocation.Context, "One or more PromptKit smoke tests failed.", combineSmokeExplanations(explanations), errors.Join(operationErrors...))
}
return commandkit.Success()
}

View File

@@ -37,6 +37,9 @@ func validationTestEngine(t *testing.T, configuration string, options ...promptk
if err != nil {
t.Fatal(err)
}
for index := range inputs {
inputs[index].Destination = configkit.Keys("promptkit")
}
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{
Underlays: []configkit.Underlay{{Inputs: inputs}},
}}, append([]promptkit.Option{promptkit.WithBundledOpenRouter(false)}, options...)...)

View File

@@ -102,23 +102,23 @@ func newValidationCommand[I, S any](suite Suite[I, S], aliases *[]commandkit.Dec
func runRequestValidation[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *concreteRequestInput[I]) commandkit.Outcome {
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit request validation was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit request validation was canceled.", commandkit.Explanation{}, err)
}
var state S
if suite.NewState != nil {
state = suite.NewState()
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure("PromptKit request validation was canceled.", commandkit.Explanation{}, err)
return definitionFailure(invocation.Context, "PromptKit request validation was canceled.", commandkit.Explanation{}, err)
}
acquired, err := suite.ValidateRequest(invocation.Context, input.request, input.selected, state)
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
if err != nil {
return definitionFailure(fmt.Sprintf("Unable to validate the PromptKit request for prompt %q.", input.promptID), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Unable to validate the PromptKit request for prompt %q.", input.promptID), acquired.Explanation, err)
}
if err := promptKitContextError(invocation.Context); err != nil {
return definitionFailure(fmt.Sprintf("Validation of the PromptKit request for prompt %q was canceled.", input.promptID), acquired.Explanation, err)
return definitionFailure(invocation.Context, fmt.Sprintf("Validation of the PromptKit request for prompt %q was canceled.", input.promptID), acquired.Explanation, err)
}
_ = invocation.Reporter().Report(commandkit.Report{Value: requestValidationReport{PromptID: input.promptID, Valid: true}})
return commandkit.Success()

View File

@@ -409,7 +409,7 @@ func TestValidationCommandRetainsProviderDiagnosticsAndClassifiesFailures(t *tes
}, nil)))
outcome = loadApp.Execute(context.Background(), []string{"promptkit", "requirements", "validate", "briefing"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
var retained *configkit.LoadError
if outcome.Kind != commandkit.OutcomeOperational || outcome.Status != 1 || !errors.Is(outcome.Cause, loadErr) || !errors.As(outcome.Cause, &retained) || retained != loadErr || outcome.Explanation.Message == "" && len(outcome.Explanation.Details) == 0 {
if outcome.Kind != commandkit.OutcomeUsage || outcome.Status != 2 || !errors.Is(outcome.Cause, loadErr) || !errors.As(outcome.Cause, &retained) || retained != loadErr || outcome.Explanation.Message == "" && len(outcome.Explanation.Details) == 0 {
t.Fatalf("loader failure = %#v, want retained ConfigKit error and diagnostics", outcome)
}
}