Compare commits

33 Commits

Author SHA1 Message Date
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
1ca660e35f Prepare ckprompt v0.6.0 with released dependencies 2026-11-08 15:23:50 +00:00
5ed947bd26 Prepare ckconfig v0.6.0 with released core 2026-11-08 15:22:33 +00:00
1613ff95ca Require downstream integration releases for dependency updates 2026-11-08 15:13:39 +00:00
68288ed684 Retire completed shared debug roadmap 2026-11-08 15:11:40 +00:00
56e3b013f9 Verify shared debug binding implementation 2026-11-08 15:11:15 +00:00
96c96bb793 Document shared debug input and reporting mode 2026-11-08 15:10:00 +00:00
d914295ced Align shared debug help and completion 2026-11-08 15:08:50 +00:00
a54ff03aef Cover shared debug binding composition 2026-11-08 15:03:24 +00:00
7aff296c86 Parse shared debug input once 2026-11-08 15:02:00 +00:00
3271c18b77 Accept shared debug bindings 2026-11-08 15:00:34 +00:00
7dd30f7df3 Expose invocation reporting mode 2026-11-08 14:59:37 +00:00
5e5f61a306 Plan shared debug bindings and reporting mode access 2026-11-08 14:51:21 +00:00
6727d22ce6 Adopt ordinary application settings for shared debug bindings 2026-11-08 13:59:34 +00:00
f23af30234 Select ordinary BoolFlag registration for shared debug input 2026-11-08 13:55:37 +00:00
ec0e58efff Plan shared debug binding and reporting mode access 2026-11-08 13:52:48 +00:00
69257066e2 Record completion of the integration releases 2026-11-08 00:34:41 +00:00
88ac6e76e4 Prepare ckprompt v0.5.0 with aligned release dependencies 2026-11-08 00:33:46 +00:00
67 changed files with 2275 additions and 529 deletions

View File

@@ -84,6 +84,12 @@ func RenameFlag[I any](flag Flag[I], name string) Flag[I] {
// BoolFlag declares a boolean flag. A bare flag is supplied by the parser as
// "true"; explicit values are converted with strconv.ParseBool. Set distinguishes
// an omitted flag from an explicit false value.
//
// A BoolFlag named debug receives the shared reporting flag's input. Its
// default and requiredness apply to application input, not reporting mode;
// explicit false satisfies requiredness. Its optional short spelling and
// completion metadata follow ordinary flag rules. The final input value can
// differ from [Invocation.ReportingMode] when other mode flags are supplied.
func BoolFlag[I any](meta FlagMeta, defaultValue bool, set func(*I, Supplied[bool])) Flag[I] {
binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(defaultValue), boolean: true}
if set == nil {

View File

@@ -95,7 +95,8 @@ type FlagMeta struct {
// Name is a nonempty long name without leading dashes. It consists of
// Unicode lowercase letters or digits in segments separated by single
// hyphens; digit-leading and numeric-only names are valid. The names help,
// quiet, verbose, debug, progress and format are reserved.
// quiet, verbose, debug, progress and format are reserved, except that a
// BoolFlag named debug attaches to the shared reporting flag.
Name string
// Short is an optional one-byte spelling other than '-' or the reserved 'h'.
Short string
@@ -498,7 +499,7 @@ func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
if binding.meta.Name == "help" {
return fmt.Errorf("flag name %q is reserved for help", binding.meta.Name)
}
if commandmeta.IsReportingFlag(binding.meta.Name) {
if commandmeta.IsReportingFlag(binding.meta.Name) && !(binding.meta.Name == "debug" && binding.boolean) {
return fmt.Errorf("flag name %q is reserved for reporting", binding.meta.Name)
}
if _, exists := flagNames[binding.meta.Name]; exists {

View File

@@ -35,8 +35,7 @@ type completionFlagState struct {
func completionFlags(context completionContext) []commandmeta.Flag {
flags := make([]commandmeta.Flag, 0, len(context.command.Flags)+len(context.command.CoreFlags)+1)
flags = append(flags, commandmeta.HelpFlag())
flags = append(flags, context.command.CoreFlags...)
flags = append(flags, context.command.Flags...)
flags = append(flags, commandmeta.EffectiveFlags(context.command.Flags, context.command.CoreFlags)...)
return flags
}

View File

@@ -70,6 +70,34 @@ func TestCompletionFlagAndValuePositions(t *testing.T) {
}
}
func TestSharedDebugCompletionHints(t *testing.T) {
for _, tc := range []struct {
name string
hint CompletionHint
want commandmeta.CompletionKind
}{
{"none", NoCompletion(), commandmeta.CompletionNone},
{"choices", CompleteChoices(CompletionChoice{Value: "true"}), commandmeta.CompletionChoices},
{"files", CompleteFiles(), commandmeta.CompletionFiles},
{"directories", CompleteDirectories(), commandmeta.CompletionDirectories},
} {
t.Run(tc.name, func(t *testing.T) {
command := NewCommand(CommandSpec[struct{}]{Name: "run", Flags: []Flag[struct{}]{BoolFlag(FlagMeta{Name: "debug", Short: "d", Completion: tc.hint}, false, func(*struct{}, Supplied[bool]) {})}, Run: func(Invocation, struct{}) Outcome { return Success() }})
app, err := New(Identity{Name: "example"}, command)
if err != nil {
t.Fatal(err)
}
snapshot := app.routeSnapshot()
for _, current := range []string{"--debug=", "-d="} {
target := completionTargetFor(snapshot, resolveCompletionContext(snapshot, []string{"run"}, current))
if target.kind != completionTargetValue || target.hint.Kind != tc.want {
t.Fatalf("%s: %#v", current, target)
}
}
})
}
}
func TestCompletionOperandAllocation(t *testing.T) {
arguments := []commandmeta.Argument{
{Name: "optional", Min: 0, Max: 1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionFiles}},

View File

@@ -120,3 +120,51 @@ func TestCompletionQueryDiscovery(t *testing.T) {
t.Fatalf("discovery outcome=%#v reply=%q", outcome, output.String())
}
}
func TestSharedDebugHelpAndCompletion(t *testing.T) {
var factories, setters, checks, handlers int
command := NewCommand(CommandSpec[struct{}]{
Name: "run",
NewInput: func() struct{} { factories++; return struct{}{} },
Flags: []Flag[struct{}]{BoolFlag(FlagMeta{Name: "debug", Short: "d", Usage: "application tracing", Required: true, Completion: CompleteChoices(CompletionChoice{Value: "true"}, CompletionChoice{Value: "trace"})}, true, func(*struct{}, Supplied[bool]) { setters++ })},
CheckInput: func(struct{}) error { checks++; return nil },
Run: func(Invocation, struct{}) Outcome { handlers++; return Success() },
})
app, err := New(Identity{Name: "example"}, command, Completion("example"), Alias("shortcut", "run"))
if err != nil {
t.Fatal(err)
}
for _, args := range [][]string{{"run", "--help"}, {"help", "run"}, {"shortcut", "--help"}, {"help", "shortcut"}, {"run", "--unknown"}, {"shortcut", "--unknown"}} {
var output, diagnostic bytes.Buffer
result := app.Execute(context.Background(), args, Streams{Out: &output, Err: &diagnostic})
text := output.String() + diagnostic.String()
if strings.Count(text, "--debug") != 1 || !strings.Contains(text, "-d") || !strings.Contains(text, "application tracing") || !strings.Contains(text, "application input defaults to true") || !strings.Contains(text, "required") || !strings.Contains(text, "default: false") {
t.Fatalf("%v: outcome=%#v text=%q", args, result, text)
}
}
for _, tc := range []struct {
args []string
want string
count int
}{
{[]string{"__complete", "run", "--deb"}, "--debug", 1},
{[]string{"__complete", "run", "-"}, "\n-d\t", 1},
{[]string{"__complete", "run", "--debug=tr"}, "trace", 1},
{[]string{"__complete", "run", "-d=tr"}, "trace", 1},
} {
var output bytes.Buffer
result := app.Execute(context.Background(), tc.args, Streams{Out: &output, Err: io.Discard})
if result.Kind != OutcomeSuccess || strings.Count(output.String(), tc.want) != tc.count {
t.Fatalf("%v: %#v %q", tc.args, result, output.String())
}
}
if factories != 0 || setters != 0 || checks != 0 || handlers != 0 {
t.Fatalf("callbacks: %d %d %d %d", factories, setters, checks, handlers)
}
if result := app.Execute(context.Background(), []string{"run", "--debug=invalid", "--help"}, Streams{Out: io.Discard, Err: io.Discard}); result.Kind != OutcomeUsage {
t.Fatalf("help skipped boolean validation: %#v", result)
}
if result := app.Execute(context.Background(), []string{"run", "--debug=trace"}, Streams{Out: io.Discard, Err: io.Discard}); result.Kind != OutcomeUsage {
t.Fatalf("suggestion bypassed boolean parsing: %#v", result)
}
}

View File

@@ -178,8 +178,11 @@ Reporting flags do not go before or between command-path components. Tokens
consumed as values and tokens after `--` retain their normal meaning.
The reserved long spellings are `--quiet`, `--verbose`, `--debug`,
`--progress`, and `--format`; application declarations cannot reuse them. There
are no built-in short spellings. Applications may define aliases such as `-q → --quiet`,
`--progress`, and `--format`. An application may attach its own boolean input
to the existing `--debug` option. Command help shows both purposes in one row,
including an application short spelling, requiredness, and any different
application default. Application input defaults do not select reporting mode.
There are no built-in short spellings. Applications may define aliases such as `-q → --quiet`,
`-v → --verbose`, and `-d → --debug`; canonical and aliased occurrences share
the same ordering. Thus `example export --verbose -q` selects quiet mode.
@@ -474,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.2.0 source
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/records.go)
for native evidence definitions.
### Explain a configuration path
@@ -619,8 +622,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
@@ -662,9 +666,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/171fb11f4e967a1da3af57843c6467954b14ba09/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
@@ -717,8 +722,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/171fb11f4e967a1da3af57843c6467954b14ba09/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
@@ -751,8 +758,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.21.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/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.
@@ -803,9 +810,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
@@ -862,9 +870,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/171fb11f4e967a1da3af57843c6467954b14ba09/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
@@ -926,9 +936,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.21.0 consumer
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md)
for resource and selection definitions. Catalog loading failures follow the
[configuration failure classification](#configuration-failure-classification).
## PromptKit smoke testing
@@ -962,10 +973,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
@@ -1094,19 +1108,32 @@ 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.21.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/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.
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,28 +14,42 @@ 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 distinguishes published combinations from the current checkout:
The v0.7.0 integrations select ConfigKit v1.2.0, and ckprompt selects PromptKit
v0.21.0.
| Selection | Core | ckconfig | ckprompt | Upstream libraries and status |
| --- | --- | --- | --- | --- |
| Published core | v0.5.0 | — | — | Usable independently. |
| Published ConfigKit integration | v0.4.0 | v0.4.0 | — | ConfigKit v1.1.0. |
| Published core | v0.6.0 | — | — | Usable independently. |
| ConfigKit integration | v0.6.0 | v0.7.0 | — | ConfigKit v1.2.0. |
| PromptKit integration | v0.6.0 | v0.7.0 | v0.7.0 | ConfigKit v1.2.0 and PromptKit v0.21.0. |
| 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. |
| Current source | Local | Local | Local | ConfigKit v1.1.0 and PromptKit v0.20.0; use an aligned workspace until release dependencies are updated. |
Install the published core with:
```sh
go get go.maximumdirect.net/commandkit@v0.5.0
go get go.maximumdirect.net/commandkit@v0.6.0
```
The integration releases being prepared are ckconfig v0.5.0 and ckprompt v0.5.0. Current
ckprompt source calls `ckconfig.AdaptDiagnostics`, which is absent from its
selected released ckconfig v0.4.0 dependency. It therefore needs local
ckconfig source in the workspace until [release
alignment](../roadmap/future.md#pending-release-and-integration-work) is
complete. 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.7.0`
or `go get go.maximumdirect.net/ckprompt@v0.7.0`. The published integrations
select core v0.6.0. ckprompt v0.7.0 selects ckconfig v0.7.0, which includes
`AdaptDiagnostics`.
Those published versions build independently against their released dependencies.
The current checkout of ckprompt uses an API added to local ckconfig after
v0.7.0, so it requires the aligned workspace until ckconfig v0.8.0 is published
and ckprompt updates its dependency. See the
[release handoff](../roadmap/future.md#configuration-outcome-release-handoff).
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).
PromptKit v0.21.0 exposes main-relative companion imports through its existing
configuration-source API. Applications select those inputs when constructing
the engine supplied to ckprompt's loader callback. [PromptKit companion import guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md#load-companion-prompts-relative-to-the-main-configuration).
Importing a module does not install its commands. Pass commands to
`commandkit.New` or `App.Register` explicitly. ckprompt depends on ckconfig's
@@ -155,6 +169,35 @@ Deferred submissions are accepted until finalization begins; later submissions
return `ErrReporterClosed`. The [CLI reference](../cli.md#reporting) owns flag
grammar, visibility, prefixes, and status behavior.
An application can attach a boolean input to the shared `--debug` option and
inspect the reporting selection separately. For example:
```go
type input struct { debug commandkit.Supplied[bool] }
command := commandkit.NewCommand(commandkit.CommandSpec[input]{
Name: "run",
Flags: []commandkit.Flag[input]{
commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Short: "d"}, false,
func(in *input, value commandkit.Supplied[bool]) { in.debug = value }),
},
Run: func(inv commandkit.Invocation, in input) commandkit.Outcome {
captureArtifacts := in.debug.Value
quiet := inv.ReportingMode() == commandkit.ReportingModeQuiet
_, _ = captureArtifacts, quiet // Apply application policy here.
return commandkit.Success()
},
})
_ = command
```
With `run --debug --quiet`, the input is true and explicitly supplied, while
the selected reporting mode is quiet. Application defaults and requiredness
affect input, not mode selection; explicit false counts as supplied. Captured
bindings retain the usual selection and application behavior. Applications own
any artifact creation and other effects. The mode reports selection rather than
successful delivery; see [Invocation.ReportingMode](../../identity.go).
Reports use JSON serialization to establish the common value representation
for YAML and JSON. A text template receives the original value; without one,
text uses readable scalar or string-list output and YAML for structured values.
@@ -282,6 +325,10 @@ 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
@@ -431,7 +478,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/171fb11f4e967a1da3af57843c6467954b14ba09/namespaces.go).
## Outcomes and ownership
@@ -445,8 +492,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.2.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/records.go),
[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/engine.go),
[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/configuration_inspection.go),
[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/smoke_diagnostics.go),
and [PromptKit v0.21.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md).

View File

@@ -62,7 +62,7 @@ capability proposals in [future work](roadmap/future.md).
| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0002](adr/0002-public-facade-and-cli-backend.md), [ADR 0004](adr/0004-optional-integration-modules.md), and the architecture policy |
| Module ownership and public contracts | [Consumer guide](consumers/guide.md), [internal overview](internal/overview.md), [core GoDoc](../doc.go), [ckconfig GoDoc](../integrations/ckconfig/doc.go), [ckprompt GoDoc](../integrations/ckprompt/doc.go), and applicable ADRs |
| Unfinished work and capability proposals | [Future work](roadmap/future.md) |
| Documentation refresh record | [Documentation roadmap](roadmap/documentation-refresh.md) |
| Completed documentation refresh | [Retired refresh record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/docs/roadmap/documentation-refresh.md) |
| Completed planning and implementation history | [Completed dependency upgrades, PromptKit validation, discovery, smoke testing, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/a6278a6d9f940948ec7745955d745523aaff0734/docs/roadmap), [earlier ConfigKit and PromptKit adoption and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap), [earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap), and [completed module implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap) in Git history |
| Release tooling | [Maintainer release procedure](release.md) |
| Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [possible further efficiency work](roadmap/future.md#possible-further-efficiency-work) |
@@ -73,7 +73,8 @@ Read all applicable rows for cross-cutting work. Go declarations and GoDoc own
current exported contracts; the CLI reference owns operator behavior. The
[maintainer release procedure](release.md) owns current release operations.
Completed roadmaps and implementation evidence remain available in Git history,
including [audit remediation and its declaration-path follow-up](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap),
including [shared debug binding and reporting-mode implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/56e3b013f9f83c9c9494f11602e802ce5ed8814e/docs/roadmap),
[audit remediation and its declaration-path follow-up](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap),
[shared reporting and PromptKit v0.20.0 implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/2f43f78f76439f5d11ef313cd379bec036543504/docs/roadmap),
[PromptKit v0.18.0 adoption and implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap),
[ConfigKit adoption, reporting, release-tooling, and remediation records](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap),
@@ -117,14 +118,16 @@ 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. The integrations select released core v0.4.0;
ckprompt also selects released ckconfig v0.4.0.
Current ckprompt source requires a ckconfig helper absent from that release, so
its independent suite remains pending release and dependency alignment; the
aligned workspace exercises the current source 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.6.0;
ckprompt also selects released ckconfig v0.7.0. The current ckprompt source uses
the new classifier in local ckconfig, so its independent build is pending
publication of ckconfig v0.8.0 and a ckprompt dependency update. The aligned
workspace exercises the local sources together; ckconfig remains independently
buildable against its published dependencies. See the
[release handoff](roadmap/future.md#configuration-outcome-release-handoff).
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately for core and
ckconfig, and for ckprompt after its published dependency is updated. From the
repository root, a workspace containing all three modules can also run:
```sh
GOTOOLCHAIN=local go test ./...

View File

@@ -38,6 +38,12 @@ collected parser events through that selection. The selected mode therefore
applies to command execution, help, and version; routing and parsing failures
remain visible in every mode.
An effective flag view combines a shared application debug binding with the
core declaration for parsing, help, and completion, while preserving the
application binding's position. The same occurrence stream selects reporting
mode independently of the prepared application value. The invocation's mode
accessor reads the reporter's selection under its existing state mutex.
The reporter owns invocation-scoped visibility, message formatting, managed
report rendering, delivery observations, and finalization. It presents queued
messages after the handler returns, then a failed outcome's explanation, and

View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.6
**Last Updated**: 2026-10-11
**Last Updated**: 2026-11-08
**Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md)
@@ -96,6 +96,22 @@ Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts.
### CommandKit downstream dependency alignment
Each new core or integration release requires dependency updates and new releases
of all downstream CommandKit-owned integration modules, following direct and
transitive dependencies. Each affected integration advances at least its minor
version to incorporate the dependency updates, even when the initiating release
is a patch. Use a major release where the compatibility rules above require it.
Versions remain independent and need not match across modules.
A module with no downstream CommandKit integrations may release independently;
its release does not require new versions of its dependencies. This policy does
not require releases of external consuming applications. The
[runbook](../release.md#scope-and-release-order) owns dependency-order sequencing.
Downstream releases are required follow-up work, not additional completion gates
for an already published source release.
## Consumer Minimum And Release Toolchain
Distinguish the minimum toolchain supported for consumers from the toolchain

View File

@@ -9,11 +9,28 @@ Gitea release page; there are no binaries,
checksums, or other delivery assets. CI, module proxy availability, and consumer
installation are not completion gates.
Publish in dependency order: core, then `ckconfig`, then `ckprompt`. The
integration modules require the preceding CommandKit releases, so prepare and
publish each module only after its CommandKit dependencies are available. A root
release runs only the root module's default suite; it need not run suites for
independently released integrations.
Plan the initiating release and all downstream integration releases required by
the [dependency-alignment policy](policy/release.md#commandkit-downstream-dependency-alignment).
That policy sets the minimum version bump for affected integrations; select
each module's version independently according to its compatibility impact.
| Initiating release | Required downstream releases, in order |
| --- | --- |
| Core | `ckconfig`, then `ckprompt` |
| `ckconfig` | `ckprompt` |
| `ckprompt` | None with the current dependency graph |
As integrations are added, follow their actual dependencies to include every
affected downstream integration. Publish dependencies before their consumers.
Prepare each integration after its updated CommandKit dependencies are published,
incorporating all of those versions in one candidate. For a core update, release
`ckprompt` once after both core and `ckconfig`; it does not need separate releases
for each dependency bump. Unaffected dependencies do not need new releases.
Track any remaining downstream releases as pending coordination work. Each
successful source-tag push still completes that module's release; a downstream
failure does not undo it or authorize replacing its tag. A root release runs
only the root module's default suite; each downstream release runs its own suite.
Use branch `main`, remote `origin`, and expected effective push endpoint
`ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git`. The selected
@@ -98,14 +115,17 @@ standard offline suite and ReleaseKit’s candidate/note and publication guards.
## Prepare and publish one candidate
Prepare dependencies in the selected module before the candidate is finalized.
Do this after the preceding CommandKit module has been published and before the
selected candidate suite is run. For `core`, run the command at the repository
root; for integrations, run it from that module directory.
Do this after any CommandKit dependency releases required by the coordinated
update have been published and before the selected candidate suite is run.
For `core`, run the command at the repository root; for integrations, run it
from that module directory.
Before downloading dependencies, update each integration to the newly published
CommandKit versions. `go mod download` downloads the versions already selected;
it does not upgrade requirements. Replace the version placeholders below with
the actual published versions, which may differ between modules:
the actual published versions, which may differ between modules. When a
dependency is not being released in this update, use its current selected
release; a `ckconfig`-initiated update does not require a new core release:
```sh
# After publishing core, prepare ckconfig from its module directory.
@@ -117,11 +137,11 @@ GOWORK=off GOTOOLCHAIN=local go get \
go.maximumdirect.net/ckconfig@vCKCONFIG_VERSION
```
Run only the command for the integration being prepared. In the current release
sequence, ckprompt needs a ckconfig release containing `AdaptDiagnostics`;
ckconfig v0.4.0 does not contain it. Validate the integration with the workspace
disabled against its updated requirements, using the selected module's release
validation below. An aligned workspace can hide an outdated dependency.
Run only the command for the integration being prepared. ckprompt needs a
ckconfig release containing `AdaptDiagnostics`; v0.5.0 contains it, while v0.4.0
does not. Validate the integration with the workspace disabled against its
updated requirements, using the selected module's release validation below.
An aligned workspace can hide an outdated dependency.
Review and commit the resulting `go.mod` and `go.sum` changes with the release
candidate, and make its release note agree with the selected versions. The sum

25
docs/releases/v0.6.0.md Normal file
View File

@@ -0,0 +1,25 @@
# CommandKit v0.6.0
CommandKit v0.6.0 lets applications bind the shared debug option to typed
input and inspect the selected reporting mode during and after an invocation.
## Changes
- A `BoolFlag` named `debug` attaches to the existing reporting option. Its
application default, requiredness, short spelling, and completion hints are
retained; help describes the combined option.
- `Invocation.ReportingMode` returns the resolved visibility selection, which
can differ from the bound debug value when other mode flags are supplied.
## Compatibility and upgrade
Other reporting flag names remain reserved. Applications choosing a required
debug binding require an explicit value; an explicit false satisfies it. A
true application default does not enable debug reporting. See the
[consumer guide](../consumers/guide.md#invocation-reporting) and
[CLI reference](../cli.md#reporting). The core consumer minimum remains Go
1.26.0 and the maintainer release toolchain remains Go 1.27.0.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.6.0/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.6.0/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.6.0/docs/oss/attribution.md)

View File

@@ -1,253 +0,0 @@
# Documentation refresh
Status: implemented and verified. Release/dependency alignment remains separate
work in [future.md](future.md#pending-release-and-integration-work).
## Purpose
Refresh CommandKit's documentation for the next minor release. Operators should
be able to find a command, understand what it does, and interpret its results
without learning the implementation. Application developers should have a short
path from choosing a module to using its public API. Maintainer documentation
and exact API contracts can retain technical detail where it is useful.
This roadmap captures the accepted documentation review recommendations. The
[documentation policy](../policy/documentation.md) remains authoritative for
audience, canonical ownership, examples, and document lifecycle. No new policy,
documentation framework, or ADR is needed.
## Scope and boundaries
The sprint covers current READMEs, the CLI reference, consumer guidance,
maintained example instructions, generated help descriptions, package
introductions, and release notes being prepared for publication.
Preserve API and CLI behavior: command and flag names, defaults, format
selection, report fields, status semantics, availability, and ownership rules.
Source edits for help text and GoDoc are in scope; runtime refactoring and new
features are not. If review exposes a behavioral defect or an unresolved
contract, record it separately rather than silently changing behavior through
an editorial revision.
Use existing documentation owners. Move useful detail to its appropriate owner
or link to the existing explanation; do not duplicate contracts. Keep exact
ownership, callback lifetime, error identity, and concurrency rules in GoDoc.
Internal documentation and maintainer procedures need only changes justified by
clarity or affected navigation, not a wholesale simplification.
Preserve accepted ADR decisions, historical published release records, license
texts, and attribution. Apply release-note editing to unpublished candidates
after checking their publication status under the
[release policy](../policy/release.md). Dependency alignment and publication
remain separate work under the [release procedure](../release.md).
## Audience and writing approach
| Audience | Starting points | Approach |
| --- | --- | --- |
| Prospective users | Root and integration READMEs | Explain purpose, useful capabilities, and where to start. |
| CLI operators | CLI reference and generated help | Lead with tasks, commands, results, and relevant limitations. |
| Go application developers | Consumer guide, examples, package introductions | Show a small useful integration first; explain choices and responsibilities next. |
| API users and maintainers | Symbol GoDoc, internal docs, development and release guides | Retain precise technical detail needed for correct use and maintenance. |
Use short, direct sentences and familiar terms. Define necessary domain terms
where first used; avoid a separate glossary unless one proves useful. For
example, explain a configuration scope as a named configuration such as `app`
or `promptkit`.
Where meaning permits, prefer “load configuration” to “acquire configuration,”
“command output” to “substantive results,” and “files and other sources used to
load configuration” to “source inventory captured during acquisition.” These
are editorial examples, not a mechanical replacement list. Keep technical names
when referring to an API symbol or a distinction that matters to the reader.
## Work areas
### 1. Product and module introductions
Update the [root README](../../README.md), [ckconfig README](../../integrations/ckconfig/README.md),
and [ckprompt README](../../integrations/ckprompt/README.md).
- Explain what the library helps applications and operators do before describing
declarations, adapters, or reporting internals.
- Keep the module overview, explicit installation distinction, and navigation.
Link to the consumer guide for compatibility and integration details.
- Provide the shortest useful starting example or a direct link to it, rather
than a catalog of callback counts or implementation responsibilities.
An illustrative root opening is: “CommandKit helps Go applications build
consistent command-line interfaces. It provides typed flags and arguments,
help, output formatting, and error reporting. Optional integrations add commands
for inspecting configuration and working with PromptKit.” Final wording can
evolve during implementation.
### 2. CLI tasks and reference detail
Refresh the [CLI reference](../cli.md), particularly reporting, configuration,
prepared-request preview, requirements, and smoke testing.
- Begin each operation with its purpose and a small command example. Explain
results and important limitations before detailed report fields.
- Replace installation and callback introductions with an operator explanation
of command availability; link to the consumer guide for application wiring.
- Move API-only material such as callback construction, writer ownership, and
`Outcome.Presentation` access to its existing developer-facing owner where
appropriate. Retain observable output, failure, and status behavior here.
- Organize detailed report shapes and edge cases into reference subsections so
they remain available without interrupting the ordinary task.
- Make application-defined flags and optional convenience aliases identifiable;
examples must not imply every application installs them.
Retain distinctions operators need: omission versus an explicit empty value,
concise versus detailed reports, independent comparison sides, redaction,
partial evidence on failure, and which operations can contact providers.
Explain that requirements discovery, request validation, prepared preview, and
smoke testing answer different questions. Successful preparation does not
guarantee later execution, and a smoke command's successful status does not
mean every reported observation is positive.
### 3. Guided examples
Refresh the [core example](../../examples/core/README.md),
[ConfigKit example](../../integrations/ckconfig/examples/simple/README.md), and
[composed example](../../integrations/ckprompt/examples/composed/README.md).
- State the working directory, required Go version, and applicable workspace or
independent-module setup before commands.
- Start with a few useful commands and explain expected results beside them.
Group additional examples by task rather than presenting one long command block.
- Label intentional failures beside the relevant command, including how to
interpret the result. Distinguish application status from `go run`'s own exit
behavior when explaining shell results.
- Explain early that the composed example uses local fixtures and requires no
model service or credentials; do not imply this about every consuming app.
- Put alias wiring, shared state, and cache explanations after the walkthrough,
linking to API contracts rather than repeating them.
### 4. Consumer guide and public API orientation
Update the [consumer guide](../consumers/guide.md) and the package introductions
in [core](../../doc.go), [ckconfig](../../integrations/ckconfig/doc.go), and
[ckprompt](../../integrations/ckprompt/doc.go).
- Demonstrate `Reporter.Report` with a small value so the recommended path to
shared `--format` support is visible. Explain raw output as a separate choice.
- Make the initial greeting example's name, description, and output agree; it
currently prints the count rather than a greeting.
- Present module compatibility in a compact table that distinguishes published
releases from current source requirements. Keep exact version guidance in
this owner and link from module introductions.
- Lead package introductions with purpose and primary entry points. Keep exact
symbol contracts in GoDoc, including factory timing, supplied values, error
handling, and object ownership.
Recheck compatibility statements when implementing the refresh. Current source
and released dependencies can differ; the
[pending alignment work](future.md#pending-release-and-integration-work) owns
the outstanding release work. Do not present workspace success as proof that
the selected published dependencies support an independent build.
### 5. Generated help
Review command summaries, descriptions, flag usage, and argument usage across
core and both integrations. These strings are operator documentation even when
stored in Go source.
Use action-oriented descriptions and explain choices where useful. In
particular, the [smoke command](../../integrations/ckprompt/smoke_command.go)
should explain that it can run one test or all tests and identify accepted kinds;
“Run one PromptKit smoke test” and “Native smoke-test kind” are insufficient.
The [request flag descriptions](../../integrations/ckprompt/request_flags.go)
can use direct wording such as “Use this model.” Preserve flag names, grammar,
defaults, and supported operations.
### 6. Release notes
Review the [core v0.5.0 note](../releases/v0.5.0.md) and applicable unpublished
integration candidates for the upcoming releases. Explain user benefits before
implementation mechanisms: accepted deferred messages are no longer lost,
YAML values retain their intended types, and installation and help avoid repeated
work. Remove unnecessary discussion of scratch paths, chain suffixes, and batch
detachment from the release summary.
Retain compatibility guidance, required consumer actions, meaningful API names,
and license/attribution links. Verify candidate dependencies against the versions
actually selected for publication. Do not invent release dates or performance
guarantees, or revise published historical notes as part of this refresh.
## Suggested sprint sequence
1. Refresh README introductions and the CLI reference together to establish
vocabulary and the operator/developer split.
2. Update example walkthroughs and generated help to match that language.
3. Polish consumer guidance, package introductions, and candidate release notes.
4. Review the changed documentation together for consistency and validate the
affected examples, help, and navigation.
No unresolved product decision blocks implementation planning. Exact wording,
section placement, and illustrative examples are ordinary editorial choices.
## Validation and completion checklist
Use the existing [documentation checks](../development.md#documentation-validation)
and [testing policy](../policy/testing.md). Review prose and local links; run
affected maintained examples and inspect representative help when those change.
For Go example or help-source edits, run the relevant existing package tests.
Do not add wording snapshots, readability gates, or a new checker framework.
Record workspace and independent-module results separately, including any
dependency limitation. This work adds no release gates.
- [x] README openings explain purpose and give a clear starting path.
- [x] CLI sections explain operator tasks before reference detail; necessary
behavior, report fields, status rules, and limitations remain discoverable.
- [x] Example setup is explicit, commands have nearby explanations, and intended
failures are labeled.
- [x] Consumer guidance demonstrates formatted reporting, has a coherent initial
example, and distinguishes published compatibility from current source needs.
- [x] Package introductions and generated help use clear, accurate language;
precise API contracts remain intact.
- [x] Unpublished release notes explain benefits and consumer impact while
historical records and required notices remain preserved.
- [x] Changed commands, snippets, and help have appropriate verification; local
links and Markdown whitespace checks pass.
- [x] Final review confirms consistent terminology, canonical ownership, and no
unintended behavior or contract changes.
## Implementation and verification
Completed the six work areas above. READMEs and package introductions now lead
with purpose and starting points; the CLI reference separates operator tasks
from report detail and developer wiring. Examples are grouped by task with
setup, expected results, and intentional failures explained nearby. The consumer
guide demonstrates shared report formatting and distinguishes published modules
from current source. Help strings and unpublished candidate notes use the same
plain language. Exact symbol contracts and runtime behavior were preserved.
Verification used Go 1.27.0 and existing cached dependencies:
- The aligned workspace suites passed for core, ckconfig, and ckprompt, including
their maintained examples.
- Independent core and ckconfig suites passed with `GOWORK=off`.
- Independent ckprompt compilation confirmed the existing dependency limitation:
released ckconfig v0.4.0 lacks `AdaptDiagnostics`. No module requirements,
checksums, or workspace files were changed to hide it. Its README, example,
consumer guidance, and candidate note identify the pending alignment.
- All 48 `go run` invocations in the three example READMEs were exercised with
binaries built from the aligned workspace, from the documented directories.
Results matched the walkthroughs, including two failed-load examples, missing
request input, and comparison status 3. Shared help and completion behavior
also passed the existing suites; representative rendered help was inspected.
- Both new consumer-guide report snippets compiled in a temporary consumer using
local core. Six checks confirmed greeting counts, empty-list output, and YAML
and JSON formatting.
- Local Markdown links, including incoming links to renamed sections, and
whitespace were checked. Go source changes are limited to help strings,
package comments, and formatting; no new tests or validation framework were
added.
- The authoritative remote had neither the core v0.5.0 nor ckprompt v0.3.0 tag
when their candidate notes were revised. Published notes, accepted ADRs,
policies, and license/attribution records were left intact.
The updated ckprompt candidate still requires dependency guidance to be finalized
when release alignment occurs. This is release preparation, not unfinished
editorial work or evidence of an independently buildable candidate.

View File

@@ -1,7 +1,6 @@
# Future work
Status: pending release/dependency alignment, optional shell validation, and
future capability proposals.
Status: release coordination, optional shell validation, and future capability proposals.
No delivery dates are selected here.
## Purpose and authority
@@ -9,6 +8,9 @@ No delivery dates are selected here.
Earlier completed roadmaps, implementation plans, and review findings have been retired.
This document preserves unfinished work and unselected ideas under the
[release policy](../policy/release.md#release-documentation-and-preparation).
The completed shared debug binding and reporting-mode implementation is recorded
in its [retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/56e3b013f9f83c9c9494f11602e802ce5ed8814e/docs/roadmap).
The completed [documentation refresh](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/docs/roadmap/documentation-refresh.md) remains available in Git history.
The completed audits, consolidated remediation, implementation plan, and
declaration-path follow-up remain available in the
[audit remediation retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap).
@@ -28,25 +30,25 @@ 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 release and integration work
## Configuration outcome release handoff
### Audit remediation release alignment
The current ckprompt source requires the classifier in local ckconfig, while
its published dependency remains ckconfig v0.7.0. The aligned workspace
validates the source combination; ckprompt independent validation remains
pending until the dependency is published and updated. Follow the
[dependency-first release procedure](../release.md#scope-and-release-order):
The audit remediation is complete in source. The released ckconfig v0.4.0 does
not include `AdaptDiagnostics`, which current ckprompt source uses. Select and
publish appropriate releases in dependency order, align module requirements and
checksums, and rerun independent module suites under the
[release procedure](../release.md). No publication is implied by source completion.
1. When publication is authorized, publish ckconfig v0.8.0 from its independently
validated candidate.
2. Prepare ckprompt against the actual published ckconfig v0.8.0 using `go get`
and `go mod download` with `GOWORK=off GOTOOLCHAIN=local`, retaining the real
checksums. Complete its v0.8.0 release note, compatibility guidance, and
candidate preparation under the existing rules for its other dependencies.
3. Independently validate and publish ckprompt v0.8.0 under the same
authorization and procedure. Track hosted release delivery separately under
the runbook.
### ckprompt release
The PromptKit v0.20.0 adoption is complete. The
[ckprompt v0.3.0 candidate](../../integrations/ckprompt/docs/releases/v0.3.0.md)
remains unpublished and needs revalidation against the current source and aligned
dependencies. Publication and hosted delivery remain separate operations
under the [release procedure](../release.md).
The published ckprompt v0.2.0 retains its earlier dependencies; see the
[consumer guide](../consumers/guide.md#module-selection) for module selection.
## Optional verification
### Optional shell completion validation

View File

@@ -0,0 +1,373 @@
# Invalid configuration outcome implementation
Status — complete. Release coordination remains in the
[future work handoff](future.md#configuration-outcome-release-handoff).
## Sprint scope and baseline
Implement the accepted [feature roadmap](invalid-configuration-outcomes.md).
Its target and accepted decisions govern the work. This plan supplies the
specific API, diagnostic mapping, integration edits, and validation.
The planning baseline is commit `a53bf9f916ffb44d816f3929fb5297a68ad118c0`.
Production sources still match the reviewed v0.7.0 integration baseline. Read
[development guidance](../development.md), the [agent policy](../policy/agents.md),
and the applicable architecture, testing, documentation, and release policies.
Execute Stage 1 through Stage 5 in order as one sprint. Intermediate stages may
leave dependent work or test expectation updates for a later stage. Mark each
stage complete with its actual verification evidence and commit completed units
under the repository's local commit policy. Continue through the remaining
stages using the decisions in this plan.
Use Go 1.27.0 and the ignored workspace containing core, ckconfig, and ckprompt.
The new shared API will first exist in local ckconfig. ckprompt currently selects
published ckconfig v0.7.0, which lacks it. The aligned workspace supplies local
ckconfig throughout this sprint. Published dependency alignment is release
coordination work described in Stage 5. Record that pending state explicitly
when reporting validation.
## Stage 1 — Implement the shared classifier
Status — complete. Added the shared classifier and focused tests for the
selected diagnostic codes, fallback evidence, wrappers, joins, cancellation,
and real ConfigKit loading errors. Verified with Go 1.27.0 using
`GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckconfig -run 'TestConfigurationDiagnosticClassification|TestClassifyConfigurationError' -count=1`
in the aligned workspace (with a temporary writable Go build cache).
Add `integrations/ckconfig/errors.go` with the following exported function and
GoDoc describing its CLI classification purpose, accepted evidence, fallback,
nil behavior, and precedence.
```go
func ClassifyConfigurationError(err error) commandkit.OutcomeKind
```
The function returns an outcome kind and reads error evidence. Handlers own
outcome construction, explanations, causes, and invocation context.
### Exact behavior
1. A nil error returns `commandkit.OutcomeSuccess`.
2. A nonnil error matching `context.Canceled` or `context.DeadlineExceeded`
through `errors.Is` returns `commandkit.OutcomeOperational`.
3. Recognize a nonnil `*configkit.LoadError`, including ordinary wrapping, and
inspect its complete `Diagnostics()` result. Ignore warning diagnostics.
Require at least one error-severity diagnostic and classify as usage only
when every error diagnostic has a usage code in the table below. An unknown
severity, an operational or unknown error code, or insufficient error
evidence selects operational.
4. Traverse ordinary `Unwrap() error` wrappers and `Unwrap() []error` branches.
A join selects usage only when every nonnil failing branch selects usage.
An operational branch wins in either ordering. A nonnil error exposing an
empty child list is an unclassified failure and selects operational.
5. Other nonnil errors select `commandkit.OutcomeOperational`. This includes an
empty or typed-nil `*configkit.LoadError`, opaque application errors, and
native PromptKit errors carrying their existing domain classifications.
Use the public ConfigKit constants in an explicit switch. The following table is
the complete usage-code list for the selected ConfigKit v1.2.0 baseline. All
error codes outside it select operational.
| Evidence | ConfigKit constants selecting usage |
| --- | --- |
| YAML content and fixed parser input bounds | `CodeYAMLInvalid`, `CodeYAMLEmpty`, `CodeYAMLMultipleDocuments`, `CodeYAMLRootType`, `CodeYAMLDuplicateKey`, `CodeYAMLTag`, `CodeYAMLAnchor`, `CodeYAMLAlias`, `CodeYAMLMergeKey`, `CodeYAMLScalar`, `CodeYAMLDepthLimit`, `CodeYAMLNodeLimit` |
| Typed decoding | `CodeDecodeType`, `CodeDecodeNull`, `CodeDecodeRange`, `CodeDecodeDuration`, `CodeDecodeText`, `CodeDecodeUnknownField`, `CodeDecodeArrayLength` |
| Excessive individual source input | `CodeSourceLimitExceeded` |
| Unsupported import directives and invalid graph relationships | `CodeImportDisabled`, `CodeImportCycle`, `CodeImportRepeated`, `CodeImportVersion` |
| Sequence declarations and peer composition | `CodeSequenceInvalid`, `CodeSequenceConflict`, `CodeComposeInvalid`, `CodeComposeConflict` |
| Protected version contributions | `CodeUnderlayVersion`, `CodeOverlayVersion` |
| Invalid overlay relationships and directives | `CodeOverlayRepeated`, `CodeOverlayDirective` |
| Version and explicit semantic rejection | `CodeVersionType`, `CodeVersionError`, `CodeResolveError`, `CodeValidateError` |
| Inheritance declarations and references | `CodeInheritanceInvalid`, `CodeInheritanceMissing`, `CodeInheritanceCycle`, `CodeInheritanceVersion` |
| Invalid override paths and conflicting assignments | `CodeOverrideInvalidPath`, `CodeOverrideDuplicate`, `CodeOverrideOverlap`, `CodeOverrideDirective`, `CodeOverrideVersion` |
| Excessive override input | `CodeOverrideLimitExceeded` |
| Invalid or absent typed secret references | `CodeSecretRequired`, `CodeSecretInvalidName` |
The mapping follows the public code meanings and ConfigKit v1.2.0's
`docs/config.md` sections on input limits, YAML documents, composition,
inheritance, overrides, secret references, and safe failures. Review the pinned
module source and documentation in the Go module cache when implementing it.
The fallback intentionally includes these reviewed cases.
- Acquisition failures, including missing or unreadable sources and imports,
permission failures, non-regular sources, and unavailable overlays.
- `CodeImportInvalid` and `CodeOverlayInvalid`, which cover both invalid content
and acquisition/context failures. Their codes alone provide ambiguous evidence.
- `CodeImportOutsideRoot` and `CodeOverlayOutsideRoot`, where containment can
reflect source resolution and filesystem conditions.
- `CodeImportLimitExceeded` and `CodeOverlayLimitExceeded`, whose acquisition
budgets can encompass source graph and filesystem traversal work.
- Schema and options errors, source-description and reused-reader errors,
`CodeHistoryLimitExceeded`, and callback failures or invalid callback actions.
- `CodeOverrideInvalidLabel` and `CodeOverrideInvalidValue`, whose meanings also
cover malformed application-created records and unsupported Go values.
- `CodeSecretUnset` and `CodeSecretEmpty`, which describe credential acquisition
from the runtime environment. Secrets-directory bootstrap failures also follow
the operational fallback.
The fixed source/parser bounds and override input budgets in the usage list
identify excessive supplied input. The acquisition and retained-evidence budgets
listed above retain operational classification under the accepted fallback.
These choices classify returned evidence and leave upstream limits and
validation rules with ConfigKit.
Implement straightforward error-tree traversal. Recognize the current typed
loading error before following its children. Inspect join branches separately
so an `errors.As` search over a whole join cannot hide later failures. Perform
the cancellation `errors.Is` checks once at the public entry point, then walk
the tree and inspect each encountered loading error's diagnostics once. A small
private diagnostics classifier and recursive walker are appropriate here.
Add focused tests in `integrations/ckconfig/errors_test.go`.
- Exercise the mapping through the private diagnostics classifier using ordinary
diagnostic values, including warnings, mixed evidence, unknown codes, and
missing error evidence. Include each selected usage constant and representative
operational families.
- Exercise the exported function with real public loading-error fixtures,
wrappers, all-input joins, mixed joins in both orders, nested joins,
cancellation, deadlines, nil, and empty loading errors. Assert classification
and preservation of the original error's supported identity.
Generate representative fixtures through public ConfigKit loading APIs. Assertions
own CommandKit's mapping and traversal. Upstream domain validation remains owned
by ConfigKit under the [testing policy](../policy/testing.md#upstream-integration-testing-ownership).
Run the focused classifier tests. Stage 5 owns the final independent module suite.
## Stage 2 — Apply classification and cancellation precedence in ckconfig
Status — complete. The configuration failure boundary now incorporates
invocation cancellation and selects the shared classification. Tests cover all
five operations, both comparison sides, filtered validation, report delivery,
operational failures, and cancellation with retained causes. Updated the native
override and simple-example expectations for their input diagnostic codes.
Verified with Go 1.27.0: `GOTOOLCHAIN=local GOPROXY=off go test
./integrations/ckconfig/...` in the aligned workspace, using a temporary Go
build cache; both the integration and simple example passed.
Update `configFailure` in `integrations/ckconfig/operations.go` to receive
`context.Context` as its first argument. Update its callers in `operations.go`,
`show.go`, `sources.go`, `explain.go`, `validate.go`, and `diff.go` to pass the
invocation context. Add context to `configAcquisitionFailure` and pass it through
from `runConfigShow`.
At this failure boundary, sample `ctx.Err()` when context is available. If it is
nonnull, use it as the cause when the operation cause is nil, or join it with the
operation cause when `errors.Is` does not already identify it. Preserve the
original cause directly when additional cancellation evidence is absent.
Call `ClassifyConfigurationError` with that combined cause. Construct
`commandkit.Usage` for usage classification and `commandkit.Failure` otherwise.
Keep the latter default for intentionally reported failures with a nil cause.
Retain the existing explanation selection, details, and cause attachment.
Apply the result to all acquisition errors reaching the five configuration
operations. Classification uses the returned error's complete evidence. Detailed
validation filters and projected `View.Findings` are report inputs. Successful
callbacks continue through their existing result flow.
Follow the existing operation-specific reporting lifecycle. Sources can emit
their inventory after failed loading, validation can emit its reached-scope
report, and comparisons retain side-specific diagnostics. The existing
`config diff --check` domain outcome and core presentation rules apply.
Extend the existing command and native-adapter tests to cover these outcomes.
1. A wrapped malformed-YAML loading error returned through `FromConfigKit`
produces usage status `2` for show, sources, validate, explain discovery, and
diff. Assert the actionable diagnostic, typed cause, and appropriate report
evidence for each operation.
2. Diff handles a failure on either loading side and preserves the acquired
diagnostic context. A detailed-validation filter hiding an error has the same
classification as the unfiltered failure.
3. Ordinary acquisition failures and a representative operational loading error
produce status `1`.
4. Already-canceled invocations produce status `1`, retain cancellation identity,
and leave stdout empty before acquisition. A callback that cancels context
and returns a loading error retains both causes and selects status `1`.
5. An output failure while delivering a source or validation report after an
input failure follows core's operational presentation-failure rule while
retaining the configuration cause.
Use existing coverage in `detailed_validation_test.go`, `diff_execution_test.go`,
the source/report tests, and `contracts_adapter_test.go` where suitable. Update
the invalid-fixture expectations in `examples/simple/main_test.go`, which
currently assert operational outcomes for native loading errors. Check related
expectations against their actual fixture codes before changing them.
Run the changed command tests and the affected simple-example tests. Stage 5
owns the final independent ckconfig suite.
## Stage 3 — Apply the shared function to PromptKit inspection and requests
Status — complete. PromptKit failure handling now samples invocation
cancellation and applies the shared classifier, including the smoke handler
call sites needed for compilation. Tests cover every catalog, named inspection,
requirements, validation, preparation, native loader and builder failures,
and cancellation with preserved causes. With Go 1.27.0, the aligned workspace
passed `GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckprompt -skip
'^TestPublicConfigDiffUsesPromptKitPairAndPreparedInputs$'`; that composition
test and the composed example retain expectations for Stage 4. A temporary Go
build cache was used.
Update `definitionFailure` in `integrations/ckprompt/command.go` to receive the
invocation context and combine observed cancellation with the operation cause
using the same handler-level approach as Stage 2. Call
`ckconfig.ClassifyConfigurationError` and choose Usage or Failure while retaining
the existing explanation and cause. A nil cause for a missing provider result
still yields an operational failure.
Update all callers, including the catalog fallback in `newCatalogListCommand`,
the handlers in `command.go`, `validation_command.go`, `preparation.go`, and the
smoke handlers that Stage 4 will verify.
Cover every installed catalog and named prompt/profile/backend inspection,
requirements discovery, concrete validation, and prepared-request preview.
Configuration loading errors may come from engine loaders or request builders.
The returned ConfigKit evidence selects the classification in each path.
Native lookup, preparation, validation, and provider errors with insufficient
configuration evidence take the operational fallback. Existing preflight and
application input-check contracts continue to govern their own failures.
Retain the original upstream error and diagnostic adaptation in `adapters.go`.
Use the newly context-aware failure boundary to observe cancellation when a
callback returns an error before the handler's later success checkpoint.
Extend tests around `command_test.go`, `requirements_command_test.go`,
`validation_command_test.go`, and `preparation_test.go`.
- Supply a shared real ConfigKit loading-error fixture through each relevant
suite callback and representative native loader/builder paths. Assert usage
status `2`, diagnostics, and `errors.As`/`errors.Is` preservation.
- Cover an ordinary PromptKit lookup error, an ordinary loader or builder
failure, and missing-result handling as operational outcomes.
- Cover pre-canceled input and cancellation occurring with a returned loading
error, checking status `1` and retained cancellation/loading identity.
Use table-driven cases for handlers with equivalent failure behavior. Reuse
existing tests for forwarding and lifecycle semantics. Verify the affected
packages using the aligned workspace.
## Stage 4 — Verify smoke aggregation and configuration composition
Status — complete. Verified individual and aggregate smoke outcomes, mixed
failures and cancellation with retained reports and causes, and all five
operations through the composed PromptKit configuration scope, including the
right comparison side and pre-canceled invocations. Updated the existing
comparison and composed-example expectations for input diagnostics. With Go
1.27.0, `GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckprompt/...`
passed in the aligned workspace using a temporary Go build cache.
In `integrations/ckprompt/smoke_command.go`, complete the context argument updates
and apply the shared classification to individual failures and the final joined
aggregate cause. Follow the existing sequential four-kind execution, cancellation
stop behavior, report delivery, explanation combination, and acquired diagnostic
flow. The classifier supplies the new aggregate outcome.
Extend `smoke_outcome_test.go`, `smoke_aggregate_test.go`, and related command
tests to verify a single input failure, an all-input aggregate, a mixed
input/operational aggregate, and cancellation joined with an input failure.
Assert the available reports and all supplied error identities. Existing
report-with-error behavior remains part of those assertions.
Exercise `ConfigScope` through the public ckconfig family in ckprompt tests.
Use a loader returning a wrapped malformed-YAML loading error and cover show,
sources, validate, explain discovery, and diff, including the right comparison
side. This establishes that composed PromptKit configuration commands use the
shared ckconfig policy. Check the accompanying source and validation report
evidence and the already-canceled behavior.
Update affected assertions in `examples/composed/main_test.go` against the
fixture's actual evidence. Add a focused fixture only where it establishes a
CommandKit-specific composition or outcome boundary. Reuse the existing example
and adapter tests for ordinary upstream capability forwarding.
Run the focused smoke/composition tests. Stage 5 owns the final aligned-workspace
ckprompt suite. Review native lookup and operational error tests for accidental
classification broadening.
## Stage 5 — Update documentation, validate, and record release coordination
Status — complete. Updated the CLI and consumer contracts, development
guidance, ckconfig v0.8.0 release note, and dependency-first release handoff.
With Go 1.27.0 and a temporary writable Go build cache, the independent ckconfig
suite passed with `GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test
-mod=readonly ./...`. In the aligned workspace, the three prescribed
`GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly` commands passed for
`./...`, `./integrations/ckconfig/...`, and `./integrations/ckprompt/...`.
Reviewed the diff, local Markdown links and fragments, and whitespace. The
independent ckprompt build remains pending publication and dependency alignment.
Update the implemented CLI contract in `docs/cli.md`, including the outcome
table and affected load-failure wording in configuration comparison, inspection,
requirements discovery, concrete validation, catalogs, preparation, and smoke
testing. Document input classification, operational fallback, mixed-error
precedence, and the existing output-failure rules. Add the new exported API's
GoDoc and concise consumer guidance linked to it.
Prepare `integrations/ckconfig/docs/releases/v0.8.0.md` explaining the status
contract change and shared classification API, using the module's existing
release-note conventions and immutable licensing footer. Record the planned
ckprompt v0.8.0 note and published-dependency update as release follow-up under
`docs/roadmap/future.md`. The ckprompt candidate is prepared after ckconfig
publication under the [release procedure](../release.md#scope-and-release-order).
### Final sprint verification
Format changed Go files. Run the commands below from the indicated module
directories, with Go 1.27.0 on PATH. The default suites are deterministic and
offline once selected dependencies are present in the module cache.
From `integrations/ckconfig`, verify its published dependencies independently.
```sh
GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./...
```
From the repository root, verify all three local modules together.
```sh
GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./...
GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./integrations/ckconfig/...
GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./integrations/ckprompt/...
```
The integration commands include their maintained example packages. Review
the final diff, Markdown links/fragments, and `git diff --check`. Confirm that
the shared code mapping, error trees, cancellation, reporting, both scope
adapters, and command families have the planned regression evidence. Report
actual checks and any remaining failures.
ckprompt's independent published-dependency build is pending the ckconfig release
because its current v0.7.0 selection lacks the new function. Keep that limitation
visible in the development/consumer guidance and release handoff. Retain the
existing published requirements through the implementation sprint. The ignored
aligned workspace is the local build setup for the new source combination.
### Release handoff
Record these follow-up actions together in `future.md` so they survive later
retirement of the implementation documents.
1. Publish ckconfig v0.8.0 from its independently validated candidate using the
documented release process when publication is authorized.
2. Prepare ckprompt with actual published ckconfig v0.8.0 using `go get` and
`go mod download` with `GOWORK=off GOTOOLCHAIN=local`. Retain real checksums,
then finish its v0.8.0 release note, consumer compatibility guidance, and
release preparation. The other dependency selections follow their existing
release preparation rules.
3. Validate ckprompt independently against its updated published dependencies
through its release candidate suite and publish ckprompt v0.8.0 under the
same authorization and procedure. Track hosted release delivery under the
runbook's separate delivery process.
These actions follow the existing dependency-first release procedure. The sprint
can complete with verified local behavior and explicit pending release alignment.
The release handoff identifies the remaining independent-build evidence.
Mark each completed stage with its implementation and verification evidence.
Commit the completed sprint work under the repository policy and report its
commits, checks, and pending release coordination.

View File

@@ -0,0 +1,142 @@
# Invalid configuration outcomes
Status — implemented, with review remediation complete. The
[implementation plan](implementation.md) and [remediation record](remediation.md)
record the completed work and verification. Publication and downstream dependency
alignment remain in the [release handoff](future.md#configuration-outcome-release-handoff).
The accepted behavior and design decisions are recorded below.
## Purpose
Make standard ckconfig and ckprompt commands return usage status `2` for
identifiable invalid configuration input, while returning operational status `1`
for cancellation and other operational failures. Preserve actionable upstream
diagnostics and supported typed error identity through the integration boundary.
CommandKit owns this CLI classification. ConfigKit and PromptKit own loading,
validation, diagnostic meaning, and their public error contracts. Application
commands own their domain outcomes. These responsibilities follow the
[architecture policy](../policy/architecture.md#ownership-boundaries).
## Historical baseline
The reviewed baseline is CommandKit commit
`1e92a87706e44684ee34395245e5b633474677e0`, following the publication of
ckconfig v0.7.0 and ckprompt v0.7.0. Both integration modules select core
v0.6.0 and ConfigKit v1.2.0. ckprompt selects ckconfig v0.7.0 and PromptKit
v0.21.0. Their manifests own the dependency selections.
The consumer report reproduced malformed operator YAML in Audita, including
its automatic `prompts.yml` companion and an explicitly selected application
configuration. Delegated inspection returned `yaml.invalid` with status `1`,
while Audita's processing command returned the same diagnostic with status `2`.
The report's reproduction is retained in Audita's
[upstream handoff](https://forge.maximumdirect.net/eric/audita/src/commit/a355f05a273d6ac9d577eab8d30caa60cb74eee8/docs/roadmap/implementation.md).
The initial review confirmed the baseline behavior through Audita's existing
regression tests and a temporary public-API reproduction against the aligned
CommandKit workspace.
The latter covered catalog listing and all five configuration operations in both
the application and PromptKit scopes, including wrapped ConfigKit loading errors
and already-canceled contexts.
- [FromConfigKit](../../integrations/ckconfig/configkit_adapter.go) and
[the PromptKit adapters](../../integrations/ckprompt/adapters.go) preserved the
ConfigKit loading error and adapted its diagnostic evidence.
- [configFailure](../../integrations/ckconfig/operations.go) and
[definitionFailure](../../integrations/ckprompt/command.go) constructed operational
outcomes for the affected failures. Configuration comparison and validation
also reached the former helper.
- ConfigKit's public `LoadError` represents several kinds of loading failure,
including malformed YAML, acquisition errors, and schema or callback problems.
Its public diagnostic codes provide the classification evidence. Its error
contract intentionally exposes safe diagnostics and preserves its own typed
identity across CommandKit adaptation.
- `config sources` can report discovered source evidence after failed loading,
and `config validate` can report failed validation. Cancellation observed
before acquisition leaves stdout empty in the reviewed command paths.
At that baseline, the published CLI contract assigned loading failures status
`1`. The implemented change classifies identifiable invalid configuration as
usage status `2`, with operational fallback, as described in the
[current CLI contract](../cli.md#configuration-failure-classification).
## Targeted end state
| Evidence available to the integration | Selected outcome |
| --- | --- |
| ConfigKit error diagnostics that identify invalid configuration input under the selected mapping | Usage, status `2` |
| Caller cancellation or deadline observed at an existing operation checkpoint, or present in the returned error chain | Operational, status `1` |
| I/O, schema or wiring defects, callback execution failures, and other recognized operational failures | Operational, status `1` |
| An unrecognized failure, including a loading error with insufficient classification evidence | Operational, status `1` |
| Successful acquisition with warnings | Follow the command's successful-result behavior |
Classification uses upstream structured evidence. Diagnostic text, filenames,
and source labels serve presentation and provenance. The input-error code
mapping follows the accepted decisions below.
The selected outcome retains the original returned cause, including ordinary
wrapping and joined errors, so supported `errors.Is` and `errors.As` queries
continue to work. Existing explanations, source context, diagnostic visibility,
and operation-specific reporting lifecycles apply to the newly classified
failures. Shared rendering and delivery failures follow the
[core output-failure rules](../cli.md#output-failures), including their effect on
usage outcomes.
Apply the classification to configuration acquisition failures throughout the
standard suites, including failures returned by application callbacks when they
carry the supported ConfigKit evidence. CLI syntax, resource lookup, request
execution, and application-specific error semantics retain their owning
contracts. The work concerns interpreting returned failure evidence at the CLI
boundary.
## Release targets
Target ckconfig v0.8.0 followed by ckprompt v0.8.0, with released ckprompt
selecting the published ckconfig version containing the shared API. This is a
published status-contract change under the
[compatibility policy](../policy/release.md#versioning-and-compatibility).
Implementation and source publication have their own completion evidence under
the [release procedure](../release.md). Pending downstream dependency alignment
belongs in the release handoff.
## Accepted decisions
### Exact diagnostic-code mapping
Use a built-in, explicit mapping based on ConfigKit v1.2.0's public
code semantics. Include YAML-content and decoding errors, explicit
`version.error`, `resolve.error`, and `validate.error` findings, and other codes
whose documented meaning clearly identifies invalid configuration content.
Classify schema/options defects, acquisition failures, hook execution failures,
invalid callback paths or records, and validation mutation as operational.
Use operational classification for ambiguous limit, secret, and source-selection
evidence. The implementation plan records the individual codes selected under
this rule, including limits that explicitly identify excessive input and secret
reference errors that explicitly identify invalid configuration.
This uses the evidence upstream already supplies and distinguishes reported
configuration rejection from callback machinery failing. Source evidence
alone may be insufficient to establish whether application-supplied data came
from an operator, so the rule follows the meaning recorded in upstream
diagnostics.
### Shared classification interface
Place one narrowly documented, exported classification function in ckconfig.
Both integrations use it, with ckprompt accessing it through its existing
dependency. The function inspects the returned error and its ConfigKit
diagnostics and returns the appropriate outcome classification. Its
responsibilities include the diagnostic mapping, operational fallback, and
joined-error precedence.
Keep command explanation construction, cause attachment, reporting, and
invocation-specific cancellation checks in their owning handlers. The
implementation plan specifies the shared function as
`ClassifyConfigurationError(error) commandkit.OutcomeKind`. It classifies nil as
success, identifiable input failures as usage, and other failures as operational.
A shared implementation reduces drift across the two standard families and
fits ckconfig's ownership of ConfigKit adaptation. The narrowly scoped public
function adds an API maintenance obligation while allowing the mapping and
error-chain rules to be maintained in one place.

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

@@ -0,0 +1,130 @@
# Configuration outcome review remediation
Status — R1 and R2 complete. Findings from the stage-by-stage review of
[the implementation plan](implementation.md) at commit
`8a22dd6`. Review findings concern the accepted
[feature target](invalid-configuration-outcomes.md).
## R1 — Present ConfigKit diagnostics returned by request builders
Priority — P2. Status — complete. Affects Stages 3 and 4.
Completed by sharing ConfigKit loading-error diagnostic adaptation between engine
loaders and all three request builders. Public-command regression coverage now
checks malformed configuration, warnings and semantic rejection, ordinary builder
failures, cancellation, preserved causes, and skipped engine loading across
validation, preparation, individual smoke, and aggregate smoke. The regression
fails against the original adapters using a temporary Go overlay and passes with
the fix. All three aligned-workspace module suites and maintained examples passed
with Go 1.27.0, offline dependencies, and read-only module metadata.
### Relevant implementation
- `WithRequestValidation` returns an empty acquisition when its builder fails in
[adapters.go](../../integrations/ckprompt/adapters.go) at line 196.
- `WithRequestPreparation` does the same in
[preparation.go](../../integrations/ckprompt/preparation.go) at line 43.
- `WithSmokeTesting` does the same in
[smoke.go](../../integrations/ckprompt/smoke.go) at line 51.
- The builder cases in
[configuration_outcomes_test.go](../../integrations/ckprompt/configuration_outcomes_test.go)
discard stderr and assert status and cause identity. The native engine-loader
cases also assert diagnostic presentation.
### Circumstances and observed behavior
An application request builder can load configuration while deriving a concrete
validation, preparation, or smoke request. If that load returns a wrapped
`*configkit.LoadError`, the native adapter returns the original cause with an
empty `Acquired` value. The handler correctly classifies the error, but receives
an empty diagnostic/explanation acquisition. Core renders the handler's generic
failure explanation and usage guidance.
A temporary public-API reproduction used a ConfigKit loading error for malformed
`profiles: [` YAML with source label `operator-prompts.yml`. The following
commands returned status `2` and retained the typed loading cause, while stderr
omitted both `yaml.invalid` and the source label.
- `promptkit requirements validate example`
- `promptkit show prepared example`
- `promptkit test reachability`
- `promptkit test all`
Returning the same error from the engine loader presented the diagnostic and
source context in each command. Builder-failure cases invoked the engine loader
zero times. The early builder returns predate this sprint, but they leave a gap
in its accepted target of preserving actionable configuration diagnostics across
the affected paths. Stage 3 explicitly includes diagnostics in the native
loader/builder verification.
### Expected behavior and remediation
Adapt available ConfigKit source evidence, warnings, and terminal diagnostics
from builder-returned loading errors through the same presentation logic used
for engine-loader failures. Keep the original returned error as the cause and
apply the shared classifier and handler cancellation precedence. A failing
builder completes through its existing failure path.
Reuse `promptKitDiagnostics` and the error adaptation already performed by
`loadPromptKitEngine`. A small private error-to-acquisition helper can make that
adaptation available to all three builder-failure branches. Ordinary application
errors follow their existing explanation and operational fallback behavior.
Extend the public-command builder cases to capture stderr and assert the
diagnostic code, source context, usage status, and typed/wrapped cause. Cover
validation, preparation, individual smoke, and aggregate smoke through their
native adapters. Retain cancellation coverage and verify that the engine loader
is skipped following a builder error. These assertions concern CommandKit's
adaptation of supplied error evidence.
## R2 — Reconcile feature-roadmap status and baseline wording
Priority — P3. Status — complete. Affects Stage 5 documentation consistency.
Completed by marking the feature as implemented with review remediation complete,
linking the release handoff, and labeling the old status behavior and failure
helpers as historical baseline evidence. Verified the document against the
implemented classifier, current CLI contract, and pending release coordination.
Local Markdown links/fragments and whitespace checks passed.
At review time, the [feature roadmap](invalid-configuration-outcomes.md) said
"pending implementation" at its opening. Its baseline section also described
the current CLI contract as assigning loading failures status `1` and presented
the status change as proposed. Meanwhile, the implementation plan recorded all
stages complete, and the
[CLI reference](../cli.md#configuration-failure-classification) documents the
implemented status `2` classification and operational fallback.
Update the feature status to reflect implemented work, outstanding remediation,
and the separately tracked release coordination. Describe the old status `1`
contract explicitly as behavior at the reviewed baseline. Keep the historical
baseline evidence and accepted decisions, with links to the current CLI contract
and [release handoff](future.md#configuration-outcome-release-handoff).
## Review verification
Reviewed the code mapping and error-tree traversal in Stage 1, configuration
failure handling in Stage 2, inspection and request paths in Stage 3, smoke
aggregation and composed scopes in Stage 4, and documentation and release
coordination in Stage 5. The classifier's usage switch matches all 48 constants
in the plan. The implementation maintains the accepted ownership boundaries and
operational fallback.
Using Go 1.27.0, offline dependencies, read-only module metadata, and a temporary
writable build cache, the following suites passed.
- Root module in the aligned workspace, including the core example and scripts.
- ckconfig independently against its declared published dependencies, including
the simple example.
- ckconfig in the aligned workspace, including the simple example.
- ckprompt in the aligned workspace, including the composed example.
Checked 133 local Markdown links/fragments across the six Markdown files changed
by the sprint and checked the sprint diff for whitespace errors. The temporary
builder reproduction described in R1 exercised the public command boundary
with deterministic, local failure fixtures.
ckprompt's independent published-dependency validation follows the recorded
release handoff because its manifest still selects ckconfig v0.7.0. This is the
planned release coordination state. The review identified no additional
strengthened contracts or restrictions requiring remediation.

View File

@@ -1,6 +1,7 @@
package commandkit
import (
"strconv"
"strings"
"testing"
@@ -313,3 +314,27 @@ func TestFlagAliasSharedSuffixAndUnavailableDestination(t *testing.T) {
}
}
}
func TestSharedDebugDeclarationValidation(t *testing.T) {
valid := BoolFlag(FlagMeta{Name: "debug", Short: "d"}, true, func(*struct{}, Supplied[bool]) {})
if _, err := New(Identity{Name: "Example"}, flagAliasCommand("run", valid)); err != nil {
t.Fatalf("valid debug: %v", err)
}
for _, flags := range [][]Flag[struct{}]{
{valid, valid},
{BoolFlag[struct{}](FlagMeta{Name: "debug"}, false, nil)},
{BoolFlag(FlagMeta{Name: "debug", Short: "h"}, false, func(*struct{}, Supplied[bool]) {})},
{ValueFlag(FlagMeta{Name: "debug"}, (*bool)(nil), strconv.ParseBool, func(*struct{}, Supplied[bool]) {})},
{OccurrenceFlag(FlagMeta{Name: "debug"}, strconv.ParseBool, func(*struct{}, Supplied[bool]) {})},
} {
if _, err := New(Identity{Name: "Example"}, flagAliasCommand("bad", flags...)); err == nil {
t.Fatalf("invalid binding accepted: %#v", flags)
}
}
for _, name := range []string{"quiet", "verbose", "progress", "format"} {
flag := BoolFlag(FlagMeta{Name: name}, false, func(*struct{}, Supplied[bool]) {})
if _, err := New(Identity{Name: "Example"}, flagAliasCommand("bad", flag)); err == nil {
t.Errorf("reserved boolean --%s was accepted", name)
}
}
}

View File

@@ -24,6 +24,8 @@ type FlagValues[I any] struct {
// each adapted flag stores its prepared value in target, associated with the
// original inner binding identity. Copies of an original handle remain
// selectable; an independently constructed lookalike does not.
// A captured debug BoolFlag shares reporting input as described by [BoolFlag];
// its requiredness is checked when selected for application.
func CaptureFlags[Outer, I any](flags []Flag[I], target func(*Outer) *FlagValues[I]) []Flag[Outer] {
captured := make([]Flag[Outer], len(flags))
for index, original := range flags {

View File

@@ -59,6 +59,21 @@ type Invocation struct {
// manually constructed Invocation has no reporter.
func (inv Invocation) Reporter() *Reporter { return inv.reporter }
// ReportingMode returns the selected reporting mode, independently of delivery
// success. The selection is stable during the handler and remains available
// after finalization. A zero Invocation returns ReportingModeOrdinary. Reads
// are safe alongside concurrent reporting; reporting callbacks must not reenter
// the same reporter.
func (inv Invocation) ReportingMode() ReportingMode {
if inv.reporter == nil || inv.reporter.state == nil {
return ReportingModeOrdinary
}
state := inv.reporter.state
state.mu.Lock()
defer state.mu.Unlock()
return state.mode
}
// Help renders the selected command's help through this invocation's output.
// It returns an operational failure when the invocation has no help renderer.
func (inv Invocation) Help() Outcome {

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

@@ -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

@@ -2,16 +2,16 @@
## ConfigKit
Selected module: `go.maximumdirect.net/configkit` at `v1.1.0`.
Selected module: `go.maximumdirect.net/configkit` at `v1.2.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/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e).
## go-yaml v4

View File

@@ -0,0 +1,16 @@
# CommandKit ckconfig v0.6.0
CommandKit ckconfig v0.6.0 selects CommandKit core v0.6.0, which supports
shared debug input bindings and access to the selected reporting mode.
ConfigKit remains at v1.1.0.
## Compatibility and upgrade
Select `go.maximumdirect.net/ckconfig v0.6.0` with CommandKit core v0.6.0.
The consumer minimum remains Go 1.27.0. See the
[consumer guide](../../../../docs/consumers/guide.md#invocation-reporting)
for the new core reporting and debug input APIs.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.6.0/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.6.0/integrations/ckconfig/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.6.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,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,14 +120,14 @@ 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
@@ -157,16 +157,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 +192,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,8 +3,8 @@ module go.maximumdirect.net/ckconfig
go 1.27.0
require (
go.maximumdirect.net/commandkit v0.5.0
go.maximumdirect.net/configkit v1.1.0
go.maximumdirect.net/commandkit v0.6.0
go.maximumdirect.net/configkit v1.2.0
go.yaml.in/yaml/v4 v4.0.0-rc.6
)

View File

@@ -10,8 +10,12 @@ go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7
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/configkit v1.2.0 h1:c4tDJ6Xeh/Jg90UZplLxsnf500lvrZBVj0E3i1ysir8=
go.maximumdirect.net/configkit v1.2.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=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

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

@@ -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

@@ -12,8 +12,7 @@ does not install commands.
The module path is `go.maximumdirect.net/ckprompt`. See the
[consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/branch/main/docs/consumers/guide.md#module-selection)
for compatible releases, Go requirements, and the current source's dependency
alignment requirement.
for compatible releases and Go requirements.
## Example

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
}
@@ -476,12 +477,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 +505,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

@@ -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

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

@@ -2,29 +2,29 @@
## PromptKit
Selected module: `go.maximumdirect.net/promptkit` at `v0.20.0`.
Selected module: `go.maximumdirect.net/promptkit` at `v0.21.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/171fb11f4e967a1da3af57843c6467954b14ba09/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09).
## ConfigKit
Selected module: `go.maximumdirect.net/configkit` at `v1.1.0` (direct dependency).
Selected module: `go.maximumdirect.net/configkit` at `v1.2.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/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e).
## ReleaseKit

View File

@@ -1,8 +1,8 @@
# CommandKit ckprompt v0.3.0
# CommandKit ckprompt v0.5.0
This unpublished candidate adds PromptKit v0.20.0 support, including request
preview, namespace selection, and shared text, YAML, and JSON output. It uses
ConfigKit v1.1.0 and requires Go 1.27.0.
CommandKit ckprompt v0.5.0 adds PromptKit v0.20.0 support, including request
preview, namespace selection, and shared text, YAML, and JSON output. It requires
CommandKit core v0.5.0, ckconfig v0.5.0, ConfigKit v1.1.0, and Go 1.27.0.
## Operator features
@@ -20,22 +20,33 @@ let application commands offer the same request flags. `ckprompt.Declarations`
adds the standard commands with their shorter flag aliases. Literal and file
inputs keep their command-line order.
## Compatibility and preparation
## Correctness improvements
This candidate changes resource report shapes, input flags, formatting, and
configuration comparison behavior. Review the current
Aggregate smoke testing retains cancellation when it stops remaining tests,
including previously returned errors and reports. A prepared-request preview
fails if the provider returns no prepared request without an error. Parsed
provider-parameter objects are copied between independent request destinations,
so mutations in one callback do not change later requests. Configuration
inspection shares ckconfig's native diagnostic adapter.
## Compatibility and upgrade
This pre-1.0 minor release changes resource report shapes, input flags,
formatting, and configuration comparison behavior. Review the current
[CLI reference](../../../../docs/cli.md#promptkit-definition-inspection) and
[consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
when updating declarations or code that reads reports. Applications continue to
own engine construction, credentials, and execution.
The current source requires `ckconfig.AdaptDiagnostics`, which is absent from
its selected ckconfig v0.4.0 dependency. Before publication, complete
[dependency alignment](../../../../docs/roadmap/future.md#pending-release-and-integration-work)
and update this candidate's dependency guidance to the selected releases.
Upgrade all three CommandKit modules to v0.5.0 together. This release follows
published ckprompt v0.2.0 and adopts the vanity imports
`go.maximumdirect.net/configkit` and `go.maximumdirect.net/promptkit`.
Replace earlier upstream import paths consistently; types from different
module identities cannot be mixed. Review callers of the former prompt
version-report API and use native prompt, profile, and backend inspections.
The [module selection table](../../../../docs/consumers/guide.md#module-selection)
distinguishes published combinations from the current workspace.
records the release dependencies.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.3.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.3.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.3.0/integrations/ckprompt/docs/oss/attribution.md)
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/docs/oss/attribution.md)

View File

@@ -0,0 +1,16 @@
# CommandKit ckprompt v0.6.0
CommandKit ckprompt v0.6.0 selects CommandKit core and ckconfig v0.6.0.
Core adds shared debug input bindings and access to the selected reporting mode.
ConfigKit remains at v1.1.0 and PromptKit at v0.20.0.
## Compatibility and upgrade
Select `go.maximumdirect.net/ckprompt v0.6.0` with CommandKit core and ckconfig
v0.6.0. The consumer minimum remains Go 1.27.0. See the
[consumer guide](../../../../docs/consumers/guide.md#invocation-reporting)
for the new core reporting and debug input APIs.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.6.0/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.6.0/integrations/ckprompt/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.6.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

@@ -4,11 +4,10 @@ This example combines application and PromptKit configuration, resource
inspection, request checks, and smoke tests. It uses local fixtures and an
in-memory model client. **No model service or credentials are required.**
Use Go 1.27.0 on `PATH` and an aligned workspace containing all three local
modules. Follow the [workspace setup](../../../../docs/development.md#documentation-validation)
from the repository root first. Current ckprompt source needs a helper in local
ckconfig source that its released dependency does not yet contain; independent
builds remain pending [release alignment](../../../../docs/roadmap/future.md#pending-release-and-integration-work).
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.
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
version and compatibility details.
@@ -168,5 +167,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. Once dependency alignment is complete, also use
for an aligned workspace check. Use
`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases.

View File

@@ -170,7 +170,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

View File

@@ -3,10 +3,10 @@ module go.maximumdirect.net/ckprompt
go 1.27.0
require (
go.maximumdirect.net/ckconfig v0.4.0
go.maximumdirect.net/commandkit v0.4.0
go.maximumdirect.net/configkit v1.1.0
go.maximumdirect.net/promptkit v0.20.0
go.maximumdirect.net/ckconfig v0.8.0
go.maximumdirect.net/commandkit v0.6.0
go.maximumdirect.net/configkit v1.2.0
go.maximumdirect.net/promptkit v0.21.0
go.yaml.in/yaml/v4 v4.0.0-rc.6
)

View File

@@ -12,12 +12,28 @@ github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
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/ckconfig v0.7.0 h1:jRmKqgReLYIRHJl7Pr4+TlucifFirGANcsoC+5WrW7A=
go.maximumdirect.net/ckconfig v0.7.0/go.mod h1:ZBKCi0Z72+C6kQV+1HJHXFGcZTc11FYyaH1pQDSZFl8=
go.maximumdirect.net/ckconfig v0.8.0 h1:ZhHlj2jGv2qXfbUJH/IwuSok/2hhopJEDqZ2fTJMbNU=
go.maximumdirect.net/ckconfig v0.8.0/go.mod h1:ZBKCi0Z72+C6kQV+1HJHXFGcZTc11FYyaH1pQDSZFl8=
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/configkit v1.2.0 h1:c4tDJ6Xeh/Jg90UZplLxsnf500lvrZBVj0E3i1ysir8=
go.maximumdirect.net/configkit v1.2.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.maximumdirect.net/promptkit v0.21.0 h1:Ws4y28lnW+lIXAq4tGhXVFnQV/6AqkDChhg8knIZFrU=
go.maximumdirect.net/promptkit v0.21.0/go.mod h1:pi9acdCi80HWyzY+XYwRvMEoCiTcDWKyeBh3mzHdIFo=
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=

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

@@ -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

@@ -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)
}
}

View File

@@ -77,9 +77,7 @@ func (session *Session) Parse(argv []string) commandmeta.Result {
}
remaining := append(commandpath.CloneTokens(unconsumed), tail...)
localFlags := make([]commandmeta.Flag, 0, len(selectedNode.Flags)+len(selectedNode.CoreFlags))
localFlags = append(localFlags, selectedNode.Flags...)
localFlags = append(localFlags, selectedNode.CoreFlags...)
localFlags := commandmeta.EffectiveFlags(selectedNode.Flags, selectedNode.CoreFlags)
aliases := session.flagAliases
if session.flagAliasesForPath != nil {
aliases = session.flagAliasesForPath(result.Path)
@@ -254,7 +252,7 @@ func displayCommandPath(rootName string, path []string) string {
return strings.Join(parts, " ")
}
// UsageLine returns Cobra's usage line for an exact path on this session.
// UsageLine returns usage for an exact path on this session.
func (session *Session) UsageLine(path []string) (string, *commandmeta.Failure) {
if session == nil || session.root == nil {
return "", &commandmeta.Failure{Message: "command tree is nil"}
@@ -269,6 +267,22 @@ func (session *Session) UsageLine(path []string) (string, *commandmeta.Failure)
if selected.HasSubCommands() {
line += " [command]"
}
for _, flag := range declaration.Flags {
if flag.Name != "debug" || !flag.Boolean {
continue
}
for _, effective := range commandmeta.EffectiveFlags(declaration.Flags, declaration.CoreFlags) {
if effective.Name == "debug" {
spelling := "--debug"
if effective.Short != "" {
spelling = "-" + effective.Short + ", " + spelling
}
line += "\n " + spelling + " " + flagUsage(effective)
break
}
}
break
}
return line, nil
}
@@ -316,7 +330,7 @@ func buildTree(root *commandmeta.Command) (*spfcobra.Command, map[*spfcobra.Comm
helpFlag := backend.Flags().Lookup("help")
helpFlag.NoOptDefVal = "true"
helpFlag.Usage = "help for this command (default: false)"
for _, declarationFlag := range append(append([]commandmeta.Flag(nil), declaration.Flags...), declaration.CoreFlags...) {
for _, declarationFlag := range commandmeta.EffectiveFlags(declaration.Flags, declaration.CoreFlags) {
value := &rawValue{boolean: declarationFlag.Boolean}
backend.Flags().VarP(value, declarationFlag.Name, declarationFlag.Short, flagUsage(declarationFlag))
backendFlag := backend.Flags().Lookup(declarationFlag.Name)

View File

@@ -281,3 +281,14 @@ func TestMissingSessionTreeReturnsNeutralFailures(t *testing.T) {
t.Fatalf("missing-tree usage failure = %#v", failure)
}
}
func TestSharedDebugExtractionPreservesConsumerIndexes(t *testing.T) {
tree := &Command{Name: "app", CoreFlags: commandmeta.ReportingFlags(), Children: []*Command{{Name: "run", Runnable: true, CoreFlags: commandmeta.ReportingFlags(), Flags: []Flag{{Name: "before"}, {Name: "debug", Short: "d", Boolean: true}, {Name: "after"}}}}}
result := Parse(tree, []string{"run", "--before=one", "-d", "--after=two", "-x=false"}, ParseOptions{FlagAliases: []commandmeta.FlagAlias{{Source: "-x", Target: "--debug"}}})
if result.Failure != nil {
t.Fatal(result.Failure)
}
if !reflect.DeepEqual(result.FlagValues, [][]string{{"one"}, {"true", "false"}, {"two"}}) || !reflect.DeepEqual(result.FlagSpellings[1], []string{"-d", "-x"}) || len(result.FlagOccurrences) != 4 {
t.Fatalf("parse = %#v", result)
}
}

View File

@@ -2,6 +2,8 @@
// its command-line backend.
package commandmeta
import "strings"
// Key identifies one command inside one routing snapshot.
type Key uint64
@@ -100,6 +102,35 @@ func ReportingFlags() []Flag {
return flags
}
// EffectiveFlags combines the shared debug option while preserving consumer order.
func EffectiveFlags(flags, core []Flag) []Flag {
result := append([]Flag(nil), flags...)
shared := -1
for i, flag := range result {
if flag.Name == "debug" && flag.Boolean {
shared = i
break
}
}
for _, flag := range core {
if flag.Name == "debug" && shared >= 0 {
app := result[shared]
usage := flag.Usage
if app.Usage != "" {
usage += "; " + app.Usage
}
if strings.EqualFold(app.Default, "true") {
usage += "; application input defaults to true (reporting defaults to ordinary)"
}
flag.Usage, flag.Short, flag.Required, flag.Completion = usage, app.Short, app.Required, app.Completion
result[shared] = flag
continue
}
result = append(result, flag)
}
return result
}
// IsReportingFlag reports whether name is reserved for a shared reporting flag.
func IsReportingFlag(name string) bool {
for _, flag := range reportingFlags {

View File

@@ -1,6 +1,9 @@
package commandmeta
import "testing"
import (
"strings"
"testing"
)
func TestReportingFlagsAreBooleanAndReturnedIndependently(t *testing.T) {
flags := ReportingFlags()
@@ -33,3 +36,15 @@ func TestReportingFlagsAreBooleanAndReturnedIndependently(t *testing.T) {
}
}
}
func TestEffectiveFlagsCombinesDebugMetadata(t *testing.T) {
flags := []Flag{{Name: "before"}, {Name: "debug", Short: "d", Boolean: true, Default: "true", Required: true, Usage: "application diagnostics", Completion: CompletionHint{Kind: CompletionFiles}}, {Name: "after"}}
core := ReportingFlags()
got := EffectiveFlags(flags, core)
if len(got) != len(flags)+len(core)-1 || got[1].Name != "debug" || got[1].Default != "false" || got[1].Short != "d" || !got[1].Required || got[1].Completion.Kind != CompletionFiles || !strings.Contains(got[1].Usage, "application diagnostics") || !strings.Contains(got[1].Usage, "application input defaults to true") {
t.Fatalf("effective debug = %#v", got)
}
if flags[1].Default != "true" || core[2].Short != "" {
t.Fatal("input metadata changed")
}
}

View File

@@ -10,13 +10,19 @@ import (
commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
)
type reportingMode uint8
// ReportingMode identifies the invocation's selected reporting visibility.
// Its zero value is ReportingModeOrdinary.
type ReportingMode uint8
const (
modeOrdinary reportingMode = iota
modeQuiet
modeVerbose
modeDebug
// ReportingModeOrdinary uses ordinary reporting visibility.
ReportingModeOrdinary ReportingMode = iota
// ReportingModeQuiet suppresses ordinary output and messages.
ReportingModeQuiet
// ReportingModeVerbose enables verbose reporting.
ReportingModeVerbose
// ReportingModeDebug enables debug reporting.
ReportingModeDebug
)
type reportingDestination uint8
@@ -41,7 +47,7 @@ type reportingState struct {
diagnostics destinationState
closed bool
deferredClosed bool
mode reportingMode
mode ReportingMode
format Format
progress bool
progressSet bool
@@ -109,7 +115,7 @@ func newReporter(streams Streams) *Reporter {
return &Reporter{state: &reportingState{
output: destinationState{writer: streams.Out},
diagnostics: destinationState{writer: streams.Err},
mode: modeOrdinary,
mode: ReportingModeOrdinary,
}}
}
@@ -125,13 +131,13 @@ func (r *Reporter) applySelection(selection commandmeta.ReportingSelection) {
}
switch selection.Mode {
case commandmeta.ReportingModeQuiet:
state.mode = modeQuiet
state.mode = ReportingModeQuiet
case commandmeta.ReportingModeVerbose:
state.mode = modeVerbose
state.mode = ReportingModeVerbose
case commandmeta.ReportingModeDebug:
state.mode = modeDebug
state.mode = ReportingModeDebug
default:
state.mode = modeOrdinary
state.mode = ReportingModeOrdinary
}
state.progress = selection.Progress
state.progressSet = selection.ProgressSet
@@ -189,7 +195,7 @@ func (r *Reporter) RenderOutput(write func(io.Writer) error) error {
destination.submitted = true
writer := &coordinatedWriter{state: state, destination: destinationOutput}
renderErr := write(writer)
if state.mode == modeQuiet {
if state.mode == ReportingModeQuiet {
destination.suppressed = true
} else if renderErr == nil && writer.writeError == nil {
destination.delivered = true
@@ -489,17 +495,17 @@ func renderDetailsLocked(state *reportingState, details []Detail, visible bool)
func (state *reportingState) visible(category messageCategory) bool {
switch category {
case categoryInfo, categoryWarning:
return state.mode == modeVerbose || state.mode == modeDebug
return state.mode == ReportingModeVerbose || state.mode == ReportingModeDebug
case categoryDebug:
return state.mode == modeDebug
return state.mode == ReportingModeDebug
case categoryProgress:
if state.mode == modeQuiet {
if state.mode == ReportingModeQuiet {
return false
}
if state.progressSet {
return state.progress
}
return state.mode == modeDebug
return state.mode == ReportingModeDebug
default:
return false
}
@@ -617,7 +623,7 @@ func (state *reportingState) destination(destination reportingDestination) *dest
func (state *reportingState) suppressed(destination reportingDestination) bool {
if destination == destinationOutput {
return state.mode == modeQuiet
return state.mode == ReportingModeQuiet
}
return false
}

View File

@@ -10,7 +10,7 @@ import (
)
func TestHiddenSimpleDeferredMessagesDoNotAccumulate(t *testing.T) {
for _, mode := range []reportingMode{modeOrdinary, modeQuiet} {
for _, mode := range []ReportingMode{ReportingModeOrdinary, ReportingModeQuiet} {
t.Run(fmt.Sprint(mode), func(t *testing.T) {
reporter := newReporter(Streams{})
setReporterVisibility(reporter, mode, false, false)
@@ -45,7 +45,7 @@ func TestHiddenSimpleDeferredMessagesDoNotAccumulate(t *testing.T) {
func TestHiddenDeferredDetailsRemainDeferredAndCaptured(t *testing.T) {
var diagnostics bytes.Buffer
reporter := newReporter(Streams{Err: &diagnostics})
setReporterVisibility(reporter, modeQuiet, false, false)
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
failure := errors.New("hidden rendering failed")
var order []string
details := []Detail{func(w io.Writer) error {
@@ -87,7 +87,7 @@ func TestReporterDeferredAcceptanceEndsBeforeDelivery(t *testing.T) {
writer := &gatedDiagnosticWriter{entered: make(chan struct{}), release: make(chan struct{})}
entered := writer.entered
reporter := newReporter(Streams{Err: writer})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
deferred := reporter.AtEnd()
if err := deferred.Warn("accepted"); err != nil {
t.Fatal(err)

View File

@@ -16,7 +16,7 @@ func TestReporterExplainsItsOwnFailuresWithoutExposingCauses(t *testing.T) {
var diagnostics bytes.Buffer
reporter := newReporter(Streams{Err: &diagnostics})
if quiet {
setReporterVisibility(reporter, modeQuiet, false, false)
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
}
failure := errors.New("private rendering detail")
render := func(io.Writer) error { return failure }
@@ -84,7 +84,7 @@ func TestReporterPreservesJoinedRendererEvidence(t *testing.T) {
writeErr := errors.Join(errors.New("sink failure"), errors.New("sink detail"))
destination := &reporterTestWriter{err: writeErr}
reporter := newReporter(Streams{Out: destination, Err: destination})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
render := func(w io.Writer) error {
_, err := io.WriteString(w, "report")
return test.combine(renderErr, err)

View File

@@ -12,7 +12,7 @@ import (
func TestReporterReportQuietAndClosed(t *testing.T) {
var out bytes.Buffer
reporter := newReporter(Streams{Out: &out})
reporter.state.mode = modeQuiet
reporter.state.mode = ReportingModeQuiet
err := reporter.Report(Report{Value: make(chan int)})
if err == nil {
t.Fatal("expected serialization error")

View File

@@ -80,7 +80,7 @@ func TestReporterLeavesCallerWriterOpen(t *testing.T) {
func TestReporterQuietOutputDiscardsSuccessfully(t *testing.T) {
var destination bytes.Buffer
reporter := newReporter(Streams{Out: &destination})
setReporterVisibility(reporter, modeQuiet, false, false)
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
writer := reporter.Output()
if n, err := writer.Write([]byte("hidden")); err != nil || n != len("hidden") {
@@ -177,7 +177,7 @@ func TestReporterClosedHandlesReturnClosedErrorIncludingQuiet(t *testing.T) {
var destination bytes.Buffer
reporter := newReporter(Streams{Out: &destination})
writer := reporter.Output()
setReporterVisibility(reporter, modeQuiet, false, false)
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
_ = reporter.finalize(Success(), nil)
if n, err := writer.Write([]byte("late")); n != 0 || !errors.Is(err, ErrReporterClosed) {
@@ -193,11 +193,11 @@ func TestNewReporterNormalizesNilDestinationsAndStartsOrdinary(t *testing.T) {
if reporter.state.output.writer != io.Discard || reporter.state.diagnostics.writer != io.Discard {
t.Fatalf("nil destinations were not normalized: %#v", reporter.state)
}
if reporter.state.mode != modeOrdinary || reporter.state.progress || reporter.state.progressSet {
if reporter.state.mode != ReportingModeOrdinary || reporter.state.progress || reporter.state.progressSet {
t.Fatalf("initial visibility = mode %v, progress %v (set %v)", reporter.state.mode, reporter.state.progress, reporter.state.progressSet)
}
setReporterVisibility(reporter, modeDebug, true, true)
if reporter.state.mode != modeDebug || !reporter.state.progress || !reporter.state.progressSet {
setReporterVisibility(reporter, ReportingModeDebug, true, true)
if reporter.state.mode != ReportingModeDebug || !reporter.state.progress || !reporter.state.progressSet {
t.Fatalf("visibility was not retained: mode %v, progress %v (set %v)", reporter.state.mode, reporter.state.progress, reporter.state.progressSet)
}
}
@@ -205,17 +205,17 @@ func TestNewReporterNormalizesNilDestinationsAndStartsOrdinary(t *testing.T) {
func TestReporterMessageVisibilityAndProgressPrecedence(t *testing.T) {
tests := []struct {
name string
mode reportingMode
mode ReportingMode
progress bool
progressSet bool
want string
}{
{name: "ordinary", mode: modeOrdinary},
{name: "verbose", mode: modeVerbose, want: "not used\nWARN: not used\n"},
{name: "debug", mode: modeDebug, want: "not used\nWARN: not used\nDEBUG: DEBUG\nPROGRESS\n"},
{name: "quiet overrides progress", mode: modeQuiet, progress: true, progressSet: true},
{name: "explicit ordinary progress", mode: modeOrdinary, progress: true, progressSet: true, want: "PROGRESS\n"},
{name: "explicit debug disable", mode: modeDebug, progressSet: true, want: "not used\nWARN: not used\nDEBUG: DEBUG\n"},
{name: "ordinary", mode: ReportingModeOrdinary},
{name: "verbose", mode: ReportingModeVerbose, want: "not used\nWARN: not used\n"},
{name: "debug", mode: ReportingModeDebug, want: "not used\nWARN: not used\nDEBUG: DEBUG\nPROGRESS\n"},
{name: "quiet overrides progress", mode: ReportingModeQuiet, progress: true, progressSet: true},
{name: "explicit ordinary progress", mode: ReportingModeOrdinary, progress: true, progressSet: true, want: "PROGRESS\n"},
{name: "explicit debug disable", mode: ReportingModeDebug, progressSet: true, want: "not used\nWARN: not used\nDEBUG: DEBUG\n"},
}
for _, test := range tests {
@@ -237,7 +237,7 @@ func TestReporterMessageVisibilityAndProgressPrecedence(t *testing.T) {
func TestReporterFormatsMessagesAndPreservesDetailOrder(t *testing.T) {
var diagnostics bytes.Buffer
reporter := newReporter(Streams{Err: &diagnostics})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
if err := reporter.Warn("Native warning\nwith second line\n", nil,
func(w io.Writer) error { _, err := io.WriteString(w, "detail one\n"); return err },
func(w io.Writer) error { _, err := io.WriteString(w, "detail two\n"); return err }); err != nil {
@@ -258,7 +258,7 @@ func TestReporterFormatsMessagesAndPreservesDetailOrder(t *testing.T) {
func TestReporterHiddenRenderersRunAgainstDiscardAndRetainErrors(t *testing.T) {
var diagnostics bytes.Buffer
reporter := newReporter(Streams{Err: &diagnostics})
setReporterVisibility(reporter, modeQuiet, false, false)
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
renderErr := errors.New("native renderer failed")
calls := 0
err := reporter.Warn("hidden warning", func(w io.Writer) error {
@@ -284,7 +284,7 @@ func TestReporterRecordsIgnoredRenderErrors(t *testing.T) {
renderErr := errors.New("output renderer failed")
diagnosticErr := errors.New("diagnostic renderer failed")
reporter := newReporter(Streams{Out: io.Discard, Err: io.Discard})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
_ = reporter.RenderOutput(func(io.Writer) error { return renderErr })
_ = reporter.Warn("warning", func(io.Writer) error { return diagnosticErr })
@@ -297,7 +297,7 @@ func TestReporterRecordsIgnoredRenderErrors(t *testing.T) {
func TestReporterRenderOutputRunsInQuietAndRetainsFailure(t *testing.T) {
destination := &reporterTestWriter{}
reporter := newReporter(Streams{Out: destination})
setReporterVisibility(reporter, modeQuiet, false, false)
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
renderErr := errors.New("quiet encoder failed")
calls := 0
_ = reporter.RenderOutput(func(w io.Writer) error {
@@ -321,7 +321,7 @@ func TestReporterCountsSuccessfulZeroByteRenderAsSubmitted(t *testing.T) {
if err := reporter.RenderOutput(func(io.Writer) error { return nil }); err != nil {
t.Fatal(err)
}
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
if err := reporter.Warn("", func(io.Writer) error { return nil }); err != nil {
t.Fatal(err)
}
@@ -409,7 +409,7 @@ func TestReporterConcurrentOperationsRemainWhole(t *testing.T) {
t.Run("render callback and message", func(t *testing.T) {
var output bytes.Buffer
reporter := newReporter(Streams{Out: &output, Err: &output})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
start := make(chan struct{})
ready := make(chan struct{}, 2)
done := make(chan struct{}, 2)
@@ -443,7 +443,7 @@ func TestReporterConcurrentOperationsRemainWhole(t *testing.T) {
t.Run("message details and render callback", func(t *testing.T) {
var output bytes.Buffer
reporter := newReporter(Streams{Out: &output, Err: &output})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
start := make(chan struct{})
ready := make(chan struct{}, 2)
done := make(chan struct{}, 2)
@@ -481,7 +481,7 @@ func TestReporterConcurrentOperationsRemainWhole(t *testing.T) {
func TestReporterEmptyHeadingDoesNotAddPrefixOrBlankLine(t *testing.T) {
var diagnostics bytes.Buffer
reporter := newReporter(Streams{Err: &diagnostics})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
if err := reporter.Warn("", func(w io.Writer) error {
_, err := io.WriteString(w, "native multiline\nsecond line\n")
return err
@@ -499,7 +499,7 @@ func TestReporterEmptyHeadingDoesNotAddPrefixOrBlankLine(t *testing.T) {
func TestReporterFinalizesDeferredMessagesBeforeCompletionAndExplanation(t *testing.T) {
var output, diagnostics bytes.Buffer
reporter := newReporter(Streams{Out: &output, Err: &diagnostics})
setReporterVisibility(reporter, modeDebug, false, false)
setReporterVisibility(reporter, ReportingModeDebug, false, false)
if err := reporter.Info("started"); err != nil {
t.Fatal(err)
}
@@ -525,7 +525,7 @@ func TestReporterFinalizesDeferredMessagesBeforeCompletionAndExplanation(t *test
func TestReporterDeferredSubmissionCopiesDetailsAndRetainsDeferredFailures(t *testing.T) {
var diagnostics bytes.Buffer
reporter := newReporter(Streams{Err: &diagnostics})
setReporterVisibility(reporter, modeVerbose, false, false)
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
writeFirst := Detail(func(w io.Writer) error { _, err := io.WriteString(w, "first detail\n"); return err })
writeSecond := Detail(func(w io.Writer) error { _, err := io.WriteString(w, "second detail\n"); return err })
details := []Detail{writeFirst}
@@ -545,7 +545,7 @@ func TestReporterDeferredSubmissionCopiesDetailsAndRetainsDeferredFailures(t *te
renderErr := errors.New("deferred renderer failed")
failedReporter := newReporter(Streams{Err: io.Discard})
setReporterVisibility(failedReporter, modeQuiet, false, false)
setReporterVisibility(failedReporter, ReportingModeQuiet, false, false)
if err := failedReporter.AtEnd().Warn("hidden", func(io.Writer) error { return renderErr }); err != nil {
t.Fatal(err)
}
@@ -699,14 +699,14 @@ func TestReporterFinalizationClosesOutputAndDeferredHandles(t *testing.T) {
}
}
func setReporterVisibility(reporter *Reporter, mode reportingMode, progress, progressSet bool) {
func setReporterVisibility(reporter *Reporter, mode ReportingMode, progress, progressSet bool) {
selection := commandmeta.ReportingSelection{Progress: progress, ProgressSet: progressSet}
switch mode {
case modeQuiet:
case ReportingModeQuiet:
selection.Mode = commandmeta.ReportingModeQuiet
case modeVerbose:
case ReportingModeVerbose:
selection.Mode = commandmeta.ReportingModeVerbose
case modeDebug:
case ReportingModeDebug:
selection.Mode = commandmeta.ReportingModeDebug
}
reporter.applySelection(selection)

View File

@@ -0,0 +1,205 @@
package commandkit_test
import (
"context"
"errors"
"io"
"sync"
"testing"
commandkit "go.maximumdirect.net/commandkit"
)
func TestInvocationReportingMode(t *testing.T) {
if got := (commandkit.Invocation{}).ReportingMode(); got != commandkit.ReportingModeOrdinary {
t.Fatalf("zero invocation mode = %v", got)
}
var retained commandkit.Invocation
var observed commandkit.ReportingMode
command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
retained = inv
observed = inv.ReportingMode()
return commandkit.Success()
}})
app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
flag string
want commandkit.ReportingMode
}{{"", commandkit.ReportingModeOrdinary}, {"--quiet", commandkit.ReportingModeQuiet}, {"--verbose", commandkit.ReportingModeVerbose}, {"--debug", commandkit.ReportingModeDebug}, {"", commandkit.ReportingModeOrdinary}} {
args := []string{"run"}
if tc.flag != "" {
args = append(args, tc.flag)
}
result := app.Execute(context.Background(), args, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if result.Kind != commandkit.OutcomeSuccess || observed != tc.want || retained.ReportingMode() != tc.want {
t.Fatalf("%q: outcome=%#v mode=%v", tc.flag, result, retained.ReportingMode())
}
}
}
func TestInvocationReportingModeConcurrentReads(t *testing.T) {
command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
start := make(chan struct{})
var wg sync.WaitGroup
for i := 0; i < 4; i++ {
wg.Add(1)
go func() {
defer wg.Done()
<-start
for j := 0; j < 100; j++ {
if inv.ReportingMode() != commandkit.ReportingModeDebug {
t.Error("mode changed")
}
_ = inv.Reporter().Debug("diagnostic")
}
}()
}
close(start)
wg.Wait()
return commandkit.Success()
}})
app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
if err != nil {
t.Fatal(err)
}
if outcome := app.Execute(context.Background(), []string{"run", "--debug"}, commandkit.Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != commandkit.OutcomeSuccess {
t.Fatal(outcome)
}
}
func TestSharedDebugBindingAndReportingMode(t *testing.T) {
type input struct {
debug commandkit.Supplied[bool]
before, after commandkit.Supplied[string]
operand commandkit.Supplied[string]
}
var received input
var mode commandkit.ReportingMode
factories, calls := 0, 0
parse := func(s string) (string, error) { return s, nil }
cmd := commandkit.NewCommand(commandkit.CommandSpec[input]{Name: "run", NewInput: func() input { factories++; return input{} }, Flags: []commandkit.Flag[input]{
commandkit.ValueFlag(commandkit.FlagMeta{Name: "before"}, (*string)(nil), parse, func(i *input, v commandkit.Supplied[string]) { i.before = v }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Short: "d"}, false, func(i *input, v commandkit.Supplied[bool]) { i.debug = v }),
commandkit.ValueFlag(commandkit.FlagMeta{Name: "after"}, (*string)(nil), parse, func(i *input, v commandkit.Supplied[string]) { i.after = v }),
}, Arguments: []commandkit.Argument[input]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "operand"}, false, parse, func(i *input, v commandkit.Supplied[string]) { i.operand = v })}, Run: func(inv commandkit.Invocation, i input) commandkit.Outcome {
calls++
received = i
mode = inv.ReportingMode()
return commandkit.Success()
}})
app, err := commandkit.New(commandkit.Identity{Name: "example"}, cmd, commandkit.FlagAlias("-x", "--debug"))
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
args []string
value, set bool
mode commandkit.ReportingMode
}{
{nil, false, false, commandkit.ReportingModeOrdinary}, {[]string{"--debug"}, true, true, commandkit.ReportingModeDebug}, {[]string{"--debug", "--quiet"}, true, true, commandkit.ReportingModeQuiet}, {[]string{"--quiet", "--debug"}, true, true, commandkit.ReportingModeDebug}, {[]string{"--debug", "--verbose"}, true, true, commandkit.ReportingModeVerbose}, {[]string{"--debug", "--debug=false"}, false, true, commandkit.ReportingModeOrdinary}, {[]string{"--verbose", "--debug", "--debug=false"}, false, true, commandkit.ReportingModeOrdinary}, {[]string{"--debug", "--quiet=false"}, true, true, commandkit.ReportingModeDebug}, {[]string{"--debug", "--progress=false"}, true, true, commandkit.ReportingModeDebug}, {[]string{"-x"}, true, true, commandkit.ReportingModeDebug}, {[]string{"-d=false"}, false, true, commandkit.ReportingModeOrdinary},
} {
args := append([]string{"run", "--before=one", "--after=two"}, tc.args...)
got := app.Execute(context.Background(), args, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if got.Kind != commandkit.OutcomeSuccess || received.debug.Value != tc.value || received.debug.Set != tc.set || mode != tc.mode || received.before.Value != "one" || received.after.Value != "two" {
t.Fatalf("%v: result=%#v input=%#v mode=%v", tc.args, got, received, mode)
}
}
for _, value := range []string{"--debug=", "--debug=invalid"} {
beforeFactories, beforeCalls := factories, calls
got := app.Execute(context.Background(), []string{"run", value}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if got.Kind != commandkit.OutcomeUsage || factories != beforeFactories || calls != beforeCalls {
t.Fatalf("%s result=%#v factories=%d calls=%d", value, got, factories, calls)
}
}
got := app.Execute(context.Background(), []string{"run", "--before", "--debug"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if got.Kind != commandkit.OutcomeSuccess || received.before.Value != "--debug" || received.debug.Set || mode != commandkit.ReportingModeOrdinary {
t.Fatalf("option-looking value: %#v %#v mode=%v", got, received, mode)
}
got = app.Execute(context.Background(), []string{"run", "--", "--debug"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
if got.Kind != commandkit.OutcomeSuccess || received.operand.Value != "--debug" || received.debug.Set || mode != commandkit.ReportingModeOrdinary {
t.Fatalf("operand after terminator: %#v %#v mode=%v", got, received, mode)
}
}
func TestSharedDebugCapturedDefaultsAndRequiredness(t *testing.T) {
type inner struct{ debug commandkit.Supplied[bool] }
type outer struct{ flags commandkit.FlagValues[inner] }
for _, required := range []bool{false, true} {
flag := commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Short: "d", Required: required}, true, func(i *inner, v commandkit.Supplied[bool]) { i.debug = v })
captured := commandkit.CaptureFlags([]commandkit.Flag[inner]{flag}, func(i *outer) *commandkit.FlagValues[inner] { return &i.flags })
var applied, supplied inner
var applyErr error
var mode commandkit.ReportingMode
cmd := commandkit.NewCommand(commandkit.CommandSpec[outer]{Name: "run", Flags: captured, Run: func(inv commandkit.Invocation, i outer) commandkit.Outcome {
mode = inv.ReportingMode()
applied = inner{}
supplied = inner{debug: commandkit.Supplied[bool]{Value: true, Set: true}}
applyErr = i.flags.ApplyTo(&applied, flag)
if err := i.flags.ApplySuppliedTo(&supplied, flag); err != nil && applyErr == nil {
applyErr = err
}
return commandkit.Success()
}})
app, err := commandkit.New(commandkit.Identity{Name: "example"}, cmd, commandkit.FlagAliasFor("run", "-x", "-d"))
if err != nil {
t.Fatal(err)
}
result := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{})
if result.Kind != commandkit.OutcomeSuccess || mode != commandkit.ReportingModeOrdinary {
t.Fatalf("omission=%#v mode=%v", result, mode)
}
if required {
if !errors.Is(applyErr, commandkit.ErrFlagInput) {
t.Fatalf("missing required: %v", applyErr)
}
} else if applyErr != nil || !applied.debug.Value || applied.debug.Set || !supplied.debug.Value || !supplied.debug.Set {
t.Fatalf("defaults=%#v %#v %v", applied, supplied, applyErr)
}
result = app.Execute(context.Background(), []string{"run", "-x=false"}, commandkit.Streams{})
if result.Kind != commandkit.OutcomeSuccess || applyErr != nil || applied.debug.Value || !applied.debug.Set || supplied.debug.Value || !supplied.debug.Set || mode != commandkit.ReportingModeOrdinary {
t.Fatalf("false=%#v %#v %#v mode=%v err=%v", result, applied, supplied, mode, applyErr)
}
}
}
func TestSharedDebugDirectRequiredAndRenamedBinding(t *testing.T) {
type input struct{ debug commandkit.Supplied[bool] }
var got input
var mode commandkit.ReportingMode
original := commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Required: true}, true, func(i *input, v commandkit.Supplied[bool]) { i.debug = v })
required := commandkit.NewCommand(commandkit.CommandSpec[input]{Name: "required", Flags: []commandkit.Flag[input]{original}, Run: func(inv commandkit.Invocation, i input) commandkit.Outcome {
got = i
mode = inv.ReportingMode()
return commandkit.Success()
}})
renamed := commandkit.NewCommand(commandkit.CommandSpec[input]{Name: "renamed", Flags: []commandkit.Flag[input]{commandkit.RenameFlag(original, "trace")}, Run: func(inv commandkit.Invocation, i input) commandkit.Outcome {
got = i
mode = inv.ReportingMode()
return commandkit.Success()
}})
ordinary := commandkit.BoolFlag(commandkit.FlagMeta{Name: "local"}, false, func(i *input, v commandkit.Supplied[bool]) { i.debug = v })
attached := commandkit.NewCommand(commandkit.CommandSpec[input]{Name: "attached", Flags: []commandkit.Flag[input]{commandkit.RenameFlag(ordinary, "debug")}, Run: func(inv commandkit.Invocation, i input) commandkit.Outcome {
got = i
mode = inv.ReportingMode()
return commandkit.Success()
}})
app, err := commandkit.New(commandkit.Identity{Name: "example"}, required, renamed, attached)
if err != nil {
t.Fatal(err)
}
if r := app.Execute(context.Background(), []string{"required"}, commandkit.Streams{}); r.Kind != commandkit.OutcomeUsage {
t.Fatalf("required omission=%#v", r)
}
if r := app.Execute(context.Background(), []string{"required", "--debug=false"}, commandkit.Streams{}); r.Kind != commandkit.OutcomeSuccess || got.debug.Value || !got.debug.Set || mode != commandkit.ReportingModeOrdinary {
t.Fatalf("explicit false=%#v %#v", r, got)
}
if r := app.Execute(context.Background(), []string{"renamed", "--trace=false", "--debug"}, commandkit.Streams{}); r.Kind != commandkit.OutcomeSuccess || got.debug.Value || !got.debug.Set || mode != commandkit.ReportingModeDebug {
t.Fatalf("renamed=%#v %#v mode=%v", r, got, mode)
}
if r := app.Execute(context.Background(), []string{"attached", "--debug"}, commandkit.Streams{}); r.Kind != commandkit.OutcomeSuccess || !got.debug.Value || !got.debug.Set || mode != commandkit.ReportingModeDebug {
t.Fatalf("renamed to debug=%#v %#v mode=%v", r, got, mode)
}
}