Compare commits
33 Commits
integratio
...
integratio
| Author | SHA1 | Date | |
|---|---|---|---|
| 6c7d7c90de | |||
| 735b35a0a1 | |||
| 21dac4f89e | |||
| 9b673d0485 | |||
| 8a22dd6a4f | |||
| 20d2924338 | |||
| 2bd216f0d3 | |||
| 1c531e7109 | |||
| b9cede22f9 | |||
| 9d3ffff69f | |||
| a53bf9f916 | |||
| ed6060f344 | |||
| 1e92a87706 | |||
| f369d6a782 | |||
| 64f6453b84 | |||
| 07a329033c | |||
| 1ca660e35f | |||
| 5ed947bd26 | |||
| 1613ff95ca | |||
| 68288ed684 | |||
| 56e3b013f9 | |||
| 96c96bb793 | |||
| d914295ced | |||
| a54ff03aef | |||
| 7aff296c86 | |||
| 3271c18b77 | |||
| 7dd30f7df3 | |||
| 5e5f61a306 | |||
| 6727d22ce6 | |||
| f23af30234 | |||
| ec0e58efff | |||
| 69257066e2 | |||
| 88ac6e76e4 |
@@ -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
|
// BoolFlag declares a boolean flag. A bare flag is supplied by the parser as
|
||||||
// "true"; explicit values are converted with strconv.ParseBool. Set distinguishes
|
// "true"; explicit values are converted with strconv.ParseBool. Set distinguishes
|
||||||
// an omitted flag from an explicit false value.
|
// 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] {
|
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}
|
binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(defaultValue), boolean: true}
|
||||||
if set == nil {
|
if set == nil {
|
||||||
|
|||||||
@@ -95,7 +95,8 @@ type FlagMeta struct {
|
|||||||
// Name is a nonempty long name without leading dashes. It consists of
|
// Name is a nonempty long name without leading dashes. It consists of
|
||||||
// Unicode lowercase letters or digits in segments separated by single
|
// Unicode lowercase letters or digits in segments separated by single
|
||||||
// hyphens; digit-leading and numeric-only names are valid. The names help,
|
// 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
|
Name string
|
||||||
// Short is an optional one-byte spelling other than '-' or the reserved 'h'.
|
// Short is an optional one-byte spelling other than '-' or the reserved 'h'.
|
||||||
Short string
|
Short string
|
||||||
@@ -498,7 +499,7 @@ func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
|
|||||||
if binding.meta.Name == "help" {
|
if binding.meta.Name == "help" {
|
||||||
return fmt.Errorf("flag name %q is reserved for help", binding.meta.Name)
|
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)
|
return fmt.Errorf("flag name %q is reserved for reporting", binding.meta.Name)
|
||||||
}
|
}
|
||||||
if _, exists := flagNames[binding.meta.Name]; exists {
|
if _, exists := flagNames[binding.meta.Name]; exists {
|
||||||
|
|||||||
@@ -35,8 +35,7 @@ type completionFlagState struct {
|
|||||||
func completionFlags(context completionContext) []commandmeta.Flag {
|
func completionFlags(context completionContext) []commandmeta.Flag {
|
||||||
flags := make([]commandmeta.Flag, 0, len(context.command.Flags)+len(context.command.CoreFlags)+1)
|
flags := make([]commandmeta.Flag, 0, len(context.command.Flags)+len(context.command.CoreFlags)+1)
|
||||||
flags = append(flags, commandmeta.HelpFlag())
|
flags = append(flags, commandmeta.HelpFlag())
|
||||||
flags = append(flags, context.command.CoreFlags...)
|
flags = append(flags, commandmeta.EffectiveFlags(context.command.Flags, context.command.CoreFlags)...)
|
||||||
flags = append(flags, context.command.Flags...)
|
|
||||||
return flags
|
return flags
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -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) {
|
func TestCompletionOperandAllocation(t *testing.T) {
|
||||||
arguments := []commandmeta.Argument{
|
arguments := []commandmeta.Argument{
|
||||||
{Name: "optional", Min: 0, Max: 1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionFiles}},
|
{Name: "optional", Min: 0, Max: 1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionFiles}},
|
||||||
|
|||||||
@@ -120,3 +120,51 @@ func TestCompletionQueryDiscovery(t *testing.T) {
|
|||||||
t.Fatalf("discovery outcome=%#v reply=%q", outcome, output.String())
|
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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
87
docs/cli.md
87
docs/cli.md
@@ -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.
|
consumed as values and tokens after `--` retain their normal meaning.
|
||||||
|
|
||||||
The reserved long spellings are `--quiet`, `--verbose`, `--debug`,
|
The reserved long spellings are `--quiet`, `--verbose`, `--debug`,
|
||||||
`--progress`, and `--format`; application declarations cannot reuse them. There
|
`--progress`, and `--format`. An application may attach its own boolean input
|
||||||
are no built-in short spellings. Applications may define aliases such as `-q → --quiet`,
|
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
|
`-v → --verbose`, and `-d → --debug`; canonical and aliased occurrences share
|
||||||
the same ordering. Thus `example export --verbose -q` selects quiet mode.
|
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,
|
output begins with the scope heading and prints the same source fields,
|
||||||
quoting labels and paths. These fields come from ConfigKit's source records;
|
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
|
producing the report does not reload files or rerun version checks. See the
|
||||||
[ConfigKit v1.1.0 source
|
[ConfigKit v1.2.0 source
|
||||||
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go)
|
records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/records.go)
|
||||||
for native evidence definitions.
|
for native evidence definitions.
|
||||||
|
|
||||||
### Explain a configuration path
|
### Explain a configuration path
|
||||||
@@ -619,8 +622,9 @@ fields remain distinct.
|
|||||||
|
|
||||||
Without `--check`, successful comparisons return status `0`, including empty
|
Without `--check`, successful comparisons return status `0`, including empty
|
||||||
results. Unsupported scopes and formats are usage errors. Application input
|
results. Unsupported scopes and formats are usage errors. Application input
|
||||||
checks can report usage or operational failures. Load and comparison failures
|
checks can report usage or operational failures. Configuration load failures
|
||||||
use status `1`.
|
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 bundled adapters load the left side before the right. Diagnostics identify
|
||||||
the side and its sources; left-side diagnostics are retained if right loading
|
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
|
`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
|
value or a claim that one is available. Neither report resolves references or
|
||||||
performs a network probe. See the [PromptKit resource inspection
|
performs a network probe. See the [PromptKit resource inspection
|
||||||
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/resource_inspection.go).
|
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/resource_inspection.go).
|
||||||
Omitting the ID is a usage error. Lookup failures and cancellation follow the
|
Omitting the ID is a usage error. Configuration loading follows the
|
||||||
shared operational failure rules.
|
[configuration failure classification](#configuration-failure-classification);
|
||||||
|
lookup failures and cancellation are operational.
|
||||||
|
|
||||||
### Resource namespace selection
|
### 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
|
application content in the report. It does not guarantee that a later model
|
||||||
call will succeed. Application loaders and callbacks may have their own
|
call will succeed. Application loaders and callbacks may have their own
|
||||||
effects. The [PromptKit Prepare
|
effects. The [PromptKit Prepare
|
||||||
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)
|
||||||
owns the prepared value and upstream preparation behavior.
|
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
|
## 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
|
namespace qualifies an explicitly supplied short profile ID; it does not
|
||||||
rewrite the prompt's stored default reference. Requirements inspection does
|
rewrite the prompt's stored default reference. Requirements inspection does
|
||||||
not require the selected profile to be execution-ready. See the [PromptKit
|
not require the selected profile to be execution-ready. See the [PromptKit
|
||||||
v0.20.0 consumer
|
v0.21.0 consumer
|
||||||
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md)
|
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
|
for configuration, selection, and requirements behavior. For built-in flags
|
||||||
other than `--llm-var`, repeating a flag uses its last value.
|
other than `--llm-var`, repeating a flag uses its last value.
|
||||||
Application-defined flags follow their own repetition rules.
|
Application-defined flags follow their own repetition rules.
|
||||||
@@ -803,9 +810,10 @@ issues:
|
|||||||
PromptKit determines these findings and explanations. A partial report can
|
PromptKit determines these findings and explanations. A partial report can
|
||||||
still be a successful command result (status `0`); read `complete` and
|
still be a successful command result (status `0`); read `complete` and
|
||||||
`issues` to understand what remains unknown. A reported issue alone does not
|
`issues` to understand what remains unknown. A reported issue alone does not
|
||||||
fail this command. Load or selection failures, cancellation, and report
|
fail this command. Configuration loading follows the [configuration failure
|
||||||
delivery failures use status `1`. Invalid syntax, arguments, variable
|
classification](#configuration-failure-classification). Selection failures and
|
||||||
assignments, or formats use status `2`.
|
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
|
### 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
|
snapshot. A successful report describes this preparation invocation; it does
|
||||||
not certify provider acceptance or guarantee later execution. See PromptKit's
|
not certify provider acceptance or guarantee later execution. See PromptKit's
|
||||||
[`Engine.ValidateRequest`
|
[`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
|
retaining available diagnostics. Malformed syntax, missing arguments, and
|
||||||
unsupported formats use status `2`. Messages follow the common reporting
|
unsupported formats use status `2`. Messages follow the common reporting
|
||||||
policy; report delivery failures follow the shared [output failure
|
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.
|
A catalog result is an inventory, not a readiness check or execution result.
|
||||||
The owning provider controls membership and order. Namespace filters are
|
The owning provider controls membership and order. Namespace filters are
|
||||||
passed to PromptKit without local membership interpretation. See the
|
passed to PromptKit without local membership interpretation. See the
|
||||||
[PromptKit v0.20.0 consumer
|
[PromptKit v0.21.0 consumer
|
||||||
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md)
|
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md)
|
||||||
for resource and selection definitions.
|
for resource and selection definitions. Catalog loading failures follow the
|
||||||
|
[configuration failure classification](#configuration-failure-classification).
|
||||||
|
|
||||||
## PromptKit smoke testing
|
## 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,
|
error. It does not mean every check passed: inspect the reported facts,
|
||||||
`reason`, and whether the test was supported, applicable, and completed. For
|
`reason`, and whether the test was supported, applicable, and completed. For
|
||||||
`all`, all four operations must return without error for status `0`.
|
`all`, all four operations must return without error for status `0`.
|
||||||
Individual errors use status `1`; the sequence continues after them but stops
|
Configuration errors use the [configuration failure classification](#configuration-failure-classification);
|
||||||
on cancellation, preserving results already obtained. A report returned with
|
other individual errors use status `1`. For `all`, every failing operation must
|
||||||
an error is still shown. Invalid syntax, arguments, formats, or conflicting
|
identify invalid configuration input to select status `2`; an operational
|
||||||
namespace flags use status `2`.
|
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
|
### Smoke-test flags
|
||||||
|
|
||||||
@@ -1094,19 +1108,32 @@ separately from delivery failures through the [reporting
|
|||||||
API](consumers/guide.md#invocation-reporting).
|
API](consumers/guide.md#invocation-reporting).
|
||||||
|
|
||||||
Native configuration, selection, and diagnostic meanings remain owned by
|
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),
|
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/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go),
|
[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/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go).
|
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/engine.go).
|
||||||
|
|
||||||
## Outcome status
|
## Outcome status
|
||||||
|
|
||||||
| Status | Standard meaning |
|
| Status | Standard meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `0` | The operation succeeded. |
|
| `0` | The operation succeeded. |
|
||||||
| `1` | Loading, execution, cancellation, or output failed. |
|
| `1` | An operational loading or execution failure, cancellation, or output failure occurred. |
|
||||||
| `2` | The command syntax or supplied inputs were invalid. |
|
| `2` | The command syntax, supplied inputs, or identifiable configuration input were invalid. |
|
||||||
| `3` | `config diff --check` found differences. |
|
| `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
|
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
|
maps to the process exit code. A command's successful status does not replace
|
||||||
reading its report: partial requirements discovery and unsupported smoke
|
reading its report: partial requirements discovery and unsupported smoke
|
||||||
|
|||||||
@@ -14,28 +14,42 @@ applications.
|
|||||||
| `go.maximumdirect.net/ckconfig` | You want operators to view, validate, explain, and compare ConfigKit configuration. |
|
| `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. |
|
| `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 |
|
| Selection | Core | ckconfig | ckprompt | Upstream libraries and status |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
| Published core | v0.5.0 | — | — | Usable independently. |
|
| Published core | v0.6.0 | — | — | Usable independently. |
|
||||||
| Published ConfigKit integration | v0.4.0 | v0.4.0 | — | ConfigKit v1.1.0. |
|
| 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. |
|
| 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:
|
Install the published core with:
|
||||||
|
|
||||||
```sh
|
```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
|
Select either integration with `go get go.maximumdirect.net/ckconfig@v0.7.0`
|
||||||
ckprompt source calls `ckconfig.AdaptDiagnostics`, which is absent from its
|
or `go get go.maximumdirect.net/ckprompt@v0.7.0`. The published integrations
|
||||||
selected released ckconfig v0.4.0 dependency. It therefore needs local
|
select core v0.6.0. ckprompt v0.7.0 selects ckconfig v0.7.0, which includes
|
||||||
ckconfig source in the workspace until [release
|
`AdaptDiagnostics`.
|
||||||
alignment](../roadmap/future.md#pending-release-and-integration-work) is
|
Those published versions build independently against their released dependencies.
|
||||||
complete. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 and does not
|
The current checkout of ckprompt uses an API added to local ckconfig after
|
||||||
compose with ckprompt v0.2.0's earlier ConfigKit dependency.
|
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
|
Importing a module does not install its commands. Pass commands to
|
||||||
`commandkit.New` or `App.Register` explicitly. ckprompt depends on ckconfig's
|
`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
|
return `ErrReporterClosed`. The [CLI reference](../cli.md#reporting) owns flag
|
||||||
grammar, visibility, prefixes, and status behavior.
|
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
|
Reports use JSON serialization to establish the common value representation
|
||||||
for YAML and JSON. A text template receives the original value; without one,
|
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.
|
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 GoDoc](../../integrations/ckconfig/contracts.go) for the provider boundary.
|
||||||
`ckconfig.AdaptDiagnostics` captures native diagnostic presentation evidence
|
`ckconfig.AdaptDiagnostics` captures native diagnostic presentation evidence
|
||||||
for applications providing their own ConfigKit-backed CLI integration.
|
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
|
Set `Scope.Features.Overrides` only when the loader passes
|
||||||
`Selection.Overrides` to ConfigKit as part of its normal load. The integration
|
`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
|
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
|
and backend names; qualified IDs pass through. Stored references and configuration
|
||||||
inspection are unchanged, while namespace and collection inventories remain global.
|
inspection are unchanged, while namespace and collection inventories remain global.
|
||||||
Catalog `--namespace` filters are separate from these defaults. See the released
|
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
|
## 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
|
Go declarations and GoDoc own exact exported contracts. ConfigKit owns
|
||||||
configuration decoding, validation, and provenance. PromptKit owns prompt
|
configuration decoding, validation, and provenance. PromptKit owns prompt
|
||||||
formats, profile resolution, and inspection details. See the
|
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),
|
[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/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.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/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/configuration_inspection.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/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go),
|
[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/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).
|
and [PromptKit v0.21.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md).
|
||||||
|
|||||||
@@ -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 |
|
| 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 |
|
| 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) |
|
| 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 |
|
| 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) |
|
| 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) |
|
| 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
|
current exported contracts; the CLI reference owns operator behavior. The
|
||||||
[maintainer release procedure](release.md) owns current release operations.
|
[maintainer release procedure](release.md) owns current release operations.
|
||||||
Completed roadmaps and implementation evidence remain available in Git history,
|
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),
|
[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),
|
[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),
|
[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
|
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
|
the ignored `go.work` and `go.work.sum`; do not commit them. Use
|
||||||
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
||||||
and independent module suites. The integrations select released core v0.4.0;
|
and independent module suites. Both integrations select released core v0.6.0;
|
||||||
ckprompt also selects released ckconfig v0.4.0.
|
ckprompt also selects released ckconfig v0.7.0. The current ckprompt source uses
|
||||||
Current ckprompt source requires a ckconfig helper absent from that release, so
|
the new classifier in local ckconfig, so its independent build is pending
|
||||||
its independent suite remains pending release and dependency alignment; the
|
publication of ckconfig v0.8.0 and a ckprompt dependency update. The aligned
|
||||||
aligned workspace exercises the current source together.
|
workspace exercises the local sources together; ckconfig remains independently
|
||||||
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module
|
buildable against its published dependencies. See the
|
||||||
directory. From the repository root, a workspace containing all three modules can
|
[release handoff](roadmap/future.md#configuration-outcome-release-handoff).
|
||||||
also run:
|
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
|
```sh
|
||||||
GOTOOLCHAIN=local go test ./...
|
GOTOOLCHAIN=local go test ./...
|
||||||
|
|||||||
@@ -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
|
applies to command execution, help, and version; routing and parsing failures
|
||||||
remain visible in every mode.
|
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
|
The reporter owns invocation-scoped visibility, message formatting, managed
|
||||||
report rendering, delivery observations, and finalization. It presents queued
|
report rendering, delivery observations, and finalization. It presents queued
|
||||||
messages after the handler returns, then a failed outcome's explanation, and
|
messages after the handler returns, then a failed outcome's explanation, and
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
**Base Policy Version:** 1.6
|
**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)
|
**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
|
adopted policy or canonical contract documentation. Release notes explain
|
||||||
changes; they do not redefine current compatibility contracts.
|
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
|
## Consumer Minimum And Release Toolchain
|
||||||
|
|
||||||
Distinguish the minimum toolchain supported for consumers from the toolchain
|
Distinguish the minimum toolchain supported for consumers from the toolchain
|
||||||
|
|||||||
@@ -9,11 +9,28 @@ Gitea release page; there are no binaries,
|
|||||||
checksums, or other delivery assets. CI, module proxy availability, and consumer
|
checksums, or other delivery assets. CI, module proxy availability, and consumer
|
||||||
installation are not completion gates.
|
installation are not completion gates.
|
||||||
|
|
||||||
Publish in dependency order: core, then `ckconfig`, then `ckprompt`. The
|
Plan the initiating release and all downstream integration releases required by
|
||||||
integration modules require the preceding CommandKit releases, so prepare and
|
the [dependency-alignment policy](policy/release.md#commandkit-downstream-dependency-alignment).
|
||||||
publish each module only after its CommandKit dependencies are available. A root
|
That policy sets the minimum version bump for affected integrations; select
|
||||||
release runs only the root module's default suite; it need not run suites for
|
each module's version independently according to its compatibility impact.
|
||||||
independently released integrations.
|
|
||||||
|
| 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
|
Use branch `main`, remote `origin`, and expected effective push endpoint
|
||||||
`ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git`. The selected
|
`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 and publish one candidate
|
||||||
|
|
||||||
Prepare dependencies in the selected module before the candidate is finalized.
|
Prepare dependencies in the selected module before the candidate is finalized.
|
||||||
Do this after the preceding CommandKit module has been published and before the
|
Do this after any CommandKit dependency releases required by the coordinated
|
||||||
selected candidate suite is run. For `core`, run the command at the repository
|
update have been published and before the selected candidate suite is run.
|
||||||
root; for integrations, run it from that module directory.
|
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
|
Before downloading dependencies, update each integration to the newly published
|
||||||
CommandKit versions. `go mod download` downloads the versions already selected;
|
CommandKit versions. `go mod download` downloads the versions already selected;
|
||||||
it does not upgrade requirements. Replace the version placeholders below with
|
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
|
```sh
|
||||||
# After publishing core, prepare ckconfig from its module directory.
|
# 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
|
go.maximumdirect.net/ckconfig@vCKCONFIG_VERSION
|
||||||
```
|
```
|
||||||
|
|
||||||
Run only the command for the integration being prepared. In the current release
|
Run only the command for the integration being prepared. ckprompt needs a
|
||||||
sequence, ckprompt needs a ckconfig release containing `AdaptDiagnostics`;
|
ckconfig release containing `AdaptDiagnostics`; v0.5.0 contains it, while v0.4.0
|
||||||
ckconfig v0.4.0 does not contain it. Validate the integration with the workspace
|
does not. Validate the integration with the workspace disabled against its
|
||||||
disabled against its updated requirements, using the selected module's release
|
updated requirements, using the selected module's release validation below.
|
||||||
validation below. An aligned workspace can hide an outdated dependency.
|
An aligned workspace can hide an outdated dependency.
|
||||||
|
|
||||||
Review and commit the resulting `go.mod` and `go.sum` changes with the release
|
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
|
candidate, and make its release note agree with the selected versions. The sum
|
||||||
|
|||||||
25
docs/releases/v0.6.0.md
Normal file
25
docs/releases/v0.6.0.md
Normal 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)
|
||||||
@@ -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.
|
|
||||||
@@ -1,7 +1,6 @@
|
|||||||
# Future work
|
# Future work
|
||||||
|
|
||||||
Status: pending release/dependency alignment, optional shell validation, and
|
Status: release coordination, optional shell validation, and future capability proposals.
|
||||||
future capability proposals.
|
|
||||||
No delivery dates are selected here.
|
No delivery dates are selected here.
|
||||||
|
|
||||||
## Purpose and authority
|
## Purpose and authority
|
||||||
@@ -9,6 +8,9 @@ No delivery dates are selected here.
|
|||||||
Earlier completed roadmaps, implementation plans, and review findings have been retired.
|
Earlier completed roadmaps, implementation plans, and review findings have been retired.
|
||||||
This document preserves unfinished work and unselected ideas under the
|
This document preserves unfinished work and unselected ideas under the
|
||||||
[release policy](../policy/release.md#release-documentation-and-preparation).
|
[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
|
The completed audits, consolidated remediation, implementation plan, and
|
||||||
declaration-path follow-up remain available in the
|
declaration-path follow-up remain available in the
|
||||||
[audit remediation retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap).
|
[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
|
and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining
|
||||||
an idea here does not select its syntax, API, priority, or delivery date.
|
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
|
1. When publication is authorized, publish ckconfig v0.8.0 from its independently
|
||||||
not include `AdaptDiagnostics`, which current ckprompt source uses. Select and
|
validated candidate.
|
||||||
publish appropriate releases in dependency order, align module requirements and
|
2. Prepare ckprompt against the actual published ckconfig v0.8.0 using `go get`
|
||||||
checksums, and rerun independent module suites under the
|
and `go mod download` with `GOWORK=off GOTOOLCHAIN=local`, retaining the real
|
||||||
[release procedure](../release.md). No publication is implied by source completion.
|
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
|
## Optional verification
|
||||||
|
|
||||||
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 shell completion validation
|
### Optional shell completion validation
|
||||||
|
|
||||||
|
|||||||
373
docs/roadmap/implementation.md
Normal file
373
docs/roadmap/implementation.md
Normal 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.
|
||||||
142
docs/roadmap/invalid-configuration-outcomes.md
Normal file
142
docs/roadmap/invalid-configuration-outcomes.md
Normal 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
130
docs/roadmap/remediation.md
Normal 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.
|
||||||
@@ -1,6 +1,7 @@
|
|||||||
package commandkit
|
package commandkit
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
"strconv"
|
||||||
"strings"
|
"strings"
|
||||||
"testing"
|
"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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -24,6 +24,8 @@ type FlagValues[I any] struct {
|
|||||||
// each adapted flag stores its prepared value in target, associated with the
|
// each adapted flag stores its prepared value in target, associated with the
|
||||||
// original inner binding identity. Copies of an original handle remain
|
// original inner binding identity. Copies of an original handle remain
|
||||||
// selectable; an independently constructed lookalike does not.
|
// 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] {
|
func CaptureFlags[Outer, I any](flags []Flag[I], target func(*Outer) *FlagValues[I]) []Flag[Outer] {
|
||||||
captured := make([]Flag[Outer], len(flags))
|
captured := make([]Flag[Outer], len(flags))
|
||||||
for index, original := range flags {
|
for index, original := range flags {
|
||||||
|
|||||||
15
identity.go
15
identity.go
@@ -59,6 +59,21 @@ type Invocation struct {
|
|||||||
// manually constructed Invocation has no reporter.
|
// manually constructed Invocation has no reporter.
|
||||||
func (inv Invocation) Reporter() *Reporter { return inv.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.
|
// Help renders the selected command's help through this invocation's output.
|
||||||
// It returns an operational failure when the invocation has no help renderer.
|
// It returns an operational failure when the invocation has no help renderer.
|
||||||
func (inv Invocation) Help() Outcome {
|
func (inv Invocation) Help() Outcome {
|
||||||
|
|||||||
119
integrations/ckconfig/config_outcomes_test.go
Normal file
119
integrations/ckconfig/config_outcomes_test.go
Normal 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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -10,25 +10,25 @@ import (
|
|||||||
func runConfigDiff[I, S any](invocation commandkit.Invocation, plan *configOperationPlan[I, S], state S) commandkit.Outcome {
|
func runConfigDiff[I, S any](invocation commandkit.Invocation, plan *configOperationPlan[I, S], state S) commandkit.Outcome {
|
||||||
if plan.comparison == nil || plan.comparison.scope == nil {
|
if plan.comparison == nil || plan.comparison.scope == nil {
|
||||||
cause := errors.New("configuration comparison was not prepared")
|
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
|
selected := plan.comparison
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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
|
compare := selected.scope.scope.Compare
|
||||||
if compare == nil {
|
if compare == nil {
|
||||||
cause := fmt.Errorf("configuration scope %q has no comparison callback", selected.scope.scope.Name)
|
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)
|
acquired, err := compare(invocation.Context, selected.request, state)
|
||||||
reporter := invocation.Reporter()
|
reporter := invocation.Reporter()
|
||||||
queueConfigDiagnostics(reporter, acquired.Diagnostics)
|
queueConfigDiagnostics(reporter, acquired.Diagnostics)
|
||||||
if err != nil {
|
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 {
|
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) {
|
outcome := renderPreparedConfigReport(invocation, acquired.Explanation, func() (any, error) {
|
||||||
if plan.details {
|
if plan.details {
|
||||||
|
|||||||
@@ -2,16 +2,16 @@
|
|||||||
|
|
||||||
## ConfigKit
|
## 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
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-or-later
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
License and notices: [LGPL v3.0](../../LICENSE) |
|
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
|
## go-yaml v4
|
||||||
|
|
||||||
|
|||||||
16
integrations/ckconfig/docs/releases/v0.6.0.md
Normal file
16
integrations/ckconfig/docs/releases/v0.6.0.md
Normal 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)
|
||||||
20
integrations/ckconfig/docs/releases/v0.7.0.md
Normal file
20
integrations/ckconfig/docs/releases/v0.7.0.md
Normal 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)
|
||||||
19
integrations/ckconfig/docs/releases/v0.8.0.md
Normal file
19
integrations/ckconfig/docs/releases/v0.8.0.md
Normal 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)
|
||||||
102
integrations/ckconfig/errors.go
Normal file
102
integrations/ckconfig/errors.go
Normal 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
|
||||||
|
}
|
||||||
|
}
|
||||||
93
integrations/ckconfig/errors_test.go
Normal file
93
integrations/ckconfig/errors_test.go
Normal 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")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -176,11 +176,11 @@ func TestSimpleFailedLoadReportsEvidence(t *testing.T) {
|
|||||||
t.Fatalf("fixture failure = %v", failure)
|
t.Fatalf("fixture failure = %v", failure)
|
||||||
}
|
}
|
||||||
outcome, output, _ := executeSimple(t, "config", "validate", "--config=fixtures/invalid.yml", "--details", "--severity=error", "--format=json")
|
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)
|
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")
|
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)
|
t.Fatalf("source failure = %#v %q", outcome, output)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -108,11 +108,11 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
|
|||||||
name := selected.scope.scope.Name
|
name := selected.scope.scope.Name
|
||||||
reporter := invocation.Reporter()
|
reporter := invocation.Reporter()
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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 {
|
if selected.scope.scope.Acquire == nil {
|
||||||
cause := fmt.Errorf("configuration scope %q has no acquisition callback", name)
|
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{
|
acquired, acquireErr := selected.scope.scope.Acquire(invocation.Context, Request{
|
||||||
Operation: Explain,
|
Operation: Explain,
|
||||||
@@ -120,14 +120,14 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
|
|||||||
}, selected.input, state)
|
}, selected.input, state)
|
||||||
queueConfigAcquisition(reporter, acquired)
|
queueConfigAcquisition(reporter, acquired)
|
||||||
if acquireErr != nil {
|
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 {
|
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 plan.list {
|
||||||
if acquired.Value.Metadata == nil {
|
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{}}
|
report := pathDiscoveryReport{Scope: name, Paths: []pathDiscoveryEntry{}}
|
||||||
var prefix []string
|
var prefix []string
|
||||||
@@ -157,16 +157,16 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf
|
|||||||
}
|
}
|
||||||
if acquired.Value.Explanation == nil {
|
if acquired.Value.Explanation == nil {
|
||||||
cause := fmt.Errorf("configuration scope %q did not provide an explanation reader", name)
|
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)
|
explanation, found := acquired.Value.Explanation.Explain(plan.path)
|
||||||
if !found {
|
if !found {
|
||||||
cause := fmt.Errorf("configuration path %q is not known in scope %q", plan.path.String(), name)
|
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 {
|
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)
|
report := makeExplanationReport(name, explanation)
|
||||||
if acquired.Value.Metadata != nil {
|
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})
|
renderErr := reporter.Report(commandkit.Report{Value: report, TextTemplate: explanationTemplate})
|
||||||
if renderErr != nil && invocation.Context.Err() != nil {
|
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()
|
return commandkit.Success()
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -3,8 +3,8 @@ module go.maximumdirect.net/ckconfig
|
|||||||
go 1.27.0
|
go 1.27.0
|
||||||
|
|
||||||
require (
|
require (
|
||||||
go.maximumdirect.net/commandkit v0.5.0
|
go.maximumdirect.net/commandkit v0.6.0
|
||||||
go.maximumdirect.net/configkit v1.1.0
|
go.maximumdirect.net/configkit v1.2.0
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
@@ -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.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 h1:Ln+bCp+FwCg4tZD3NaMKQXUDB3mPusgwsnRZmb0+3cM=
|
||||||
go.maximumdirect.net/commandkit v0.5.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
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 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
|
||||||
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
|
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 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
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=
|
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||||
|
|||||||
@@ -1,6 +1,8 @@
|
|||||||
package ckconfig
|
package ckconfig
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
"fmt"
|
"fmt"
|
||||||
"io"
|
"io"
|
||||||
|
|
||||||
@@ -15,7 +17,7 @@ func runConfigOperation[I, S any](invocation commandkit.Invocation, operation Op
|
|||||||
return invocation.Help()
|
return invocation.Help()
|
||||||
}
|
}
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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
|
plan := input.plan
|
||||||
var state S
|
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 {
|
if explanation.Message != "" || len(explanation.Details) > 0 {
|
||||||
message = explanation.Message
|
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...)
|
outcome := commandkit.Failure(message, explanation.Details...)
|
||||||
|
if cause != nil && ClassifyConfigurationError(cause) == commandkit.OutcomeUsage {
|
||||||
|
outcome = commandkit.Usage(message, explanation.Details...)
|
||||||
|
}
|
||||||
if cause != nil {
|
if cause != nil {
|
||||||
outcome = outcome.WithCause(cause)
|
outcome = outcome.WithCause(cause)
|
||||||
}
|
}
|
||||||
@@ -76,6 +90,7 @@ func configFailure(message string, explanation commandkit.Explanation, cause err
|
|||||||
}
|
}
|
||||||
|
|
||||||
func configAcquisitionFailure(
|
func configAcquisitionFailure(
|
||||||
|
ctx context.Context,
|
||||||
reporter *commandkit.Reporter,
|
reporter *commandkit.Reporter,
|
||||||
operation, scope string,
|
operation, scope string,
|
||||||
acquired commandkit.Acquired[View],
|
acquired commandkit.Acquired[View],
|
||||||
@@ -83,7 +98,7 @@ func configAcquisitionFailure(
|
|||||||
) commandkit.Outcome {
|
) commandkit.Outcome {
|
||||||
queueConfigAcquisition(reporter, acquired)
|
queueConfigAcquisition(reporter, acquired)
|
||||||
message := fmt.Sprintf("Unable to %s configuration scope %q.", operation, scope)
|
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.
|
// Preserve the preparation/delivery cancellation checkpoint for buffered reports.
|
||||||
@@ -105,7 +120,7 @@ func renderPreparedConfigReport(invocation commandkit.Invocation, explanation co
|
|||||||
canceled = invocation.Context.Err()
|
canceled = invocation.Context.Err()
|
||||||
}
|
}
|
||||||
if canceled != nil {
|
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 {
|
if renderErr == nil {
|
||||||
_ = invocation.Reporter().Report(commandkit.Report{Value: value})
|
_ = invocation.Reporter().Report(commandkit.Report{Value: value})
|
||||||
|
|||||||
@@ -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})
|
result = app.Execute(context.Background(), []string{"config", "validate", "--set==1"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
|
||||||
var loadErr *configkit.LoadError
|
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)
|
t.Fatalf("native invalid root override: %#v", result)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -19,29 +19,29 @@ func runConfigShow[I, S any](invocation commandkit.Invocation, plan *configOpera
|
|||||||
reporter := invocation.Reporter()
|
reporter := invocation.Reporter()
|
||||||
for _, selected := range plan.scopes {
|
for _, selected := range plan.scopes {
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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 {
|
if selected.scope.scope.Acquire == nil {
|
||||||
return commandkit.Failure(fmt.Sprintf("Configuration scope %q has no acquisition callback.", selected.scope.scope.Name))
|
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)
|
acquired, acquireErr := selected.scope.scope.Acquire(invocation.Context, Request{Operation: Show, Selection: selected.selection}, selected.input, state)
|
||||||
if acquireErr != nil {
|
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)
|
queueConfigAcquisition(reporter, acquired)
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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 plan.pathSet {
|
||||||
if acquired.Value.Explanation == nil {
|
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)
|
explanation, found := acquired.Value.Explanation.Explain(plan.path)
|
||||||
if !found || !explanation.Effective.Present {
|
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 {
|
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
|
var value any
|
||||||
err := reporter.RenderOutput(func(io.Writer) error {
|
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 err == nil {
|
||||||
if canceled := invocation.Context.Err(); canceled != 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})
|
_ = 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})
|
documents = append(documents, effectiveDocument{name: selected.scope.scope.Name, view: acquired.Value})
|
||||||
}
|
}
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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 value any
|
||||||
var canceled error
|
var canceled error
|
||||||
@@ -92,16 +92,16 @@ func runConfigShow[I, S any](invocation commandkit.Invocation, plan *configOpera
|
|||||||
return nil
|
return nil
|
||||||
})
|
})
|
||||||
if canceled != 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 err != nil {
|
||||||
if canceled := invocation.Context.Err(); canceled != 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()
|
return commandkit.Success()
|
||||||
}
|
}
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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})
|
_ = reporter.Report(commandkit.Report{Value: value})
|
||||||
return commandkit.Success()
|
return commandkit.Success()
|
||||||
|
|||||||
@@ -59,11 +59,11 @@ func runConfigSources[I, S any](invocation commandkit.Invocation, plan *configOp
|
|||||||
name := selected.scope.scope.Name
|
name := selected.scope.scope.Name
|
||||||
reporter := invocation.Reporter()
|
reporter := invocation.Reporter()
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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 {
|
if selected.scope.scope.Acquire == nil {
|
||||||
cause := fmt.Errorf("configuration scope %q has no acquisition callback", name)
|
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{
|
acquired, acquireErr := selected.scope.scope.Acquire(invocation.Context, Request{
|
||||||
Operation: Sources,
|
Operation: Sources,
|
||||||
@@ -72,15 +72,15 @@ func runConfigSources[I, S any](invocation commandkit.Invocation, plan *configOp
|
|||||||
queueConfigAcquisition(reporter, acquired)
|
queueConfigAcquisition(reporter, acquired)
|
||||||
if acquireErr == nil && invocation.Context.Err() != nil {
|
if acquireErr == nil && invocation.Context.Err() != nil {
|
||||||
err := invocation.Context.Err()
|
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 acquired.Value.Sources == nil {
|
||||||
if acquireErr != nil {
|
if acquireErr != nil {
|
||||||
explanation := sourceSelectionExplanation(acquired.Explanation, "Source inventory is unavailable.")
|
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)
|
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()
|
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 {
|
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)
|
message := fmt.Sprintf("Source ID %q was not found in configuration scope %q.", plan.sourceID.Value, name)
|
||||||
if acquireErr != nil {
|
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 {
|
if acquireErr == nil && invocation.Context.Err() != nil {
|
||||||
err := invocation.Context.Err()
|
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})
|
_ = reporter.Report(commandkit.Report{Value: document, TextTemplate: sourceTextTemplate})
|
||||||
if acquireErr != nil {
|
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()
|
return commandkit.Success()
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -71,7 +71,7 @@ func runConfigValidation[I, S any](invocation commandkit.Invocation, plan *confi
|
|||||||
}
|
}
|
||||||
for _, selected := range plan.scopes {
|
for _, selected := range plan.scopes {
|
||||||
if err := invocation.Context.Err(); err != nil {
|
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
|
break
|
||||||
}
|
}
|
||||||
name := selected.scope.scope.Name
|
name := selected.scope.scope.Name
|
||||||
@@ -109,7 +109,7 @@ func runConfigValidation[I, S any](invocation commandkit.Invocation, plan *confi
|
|||||||
if entry.Outcome == "canceled" {
|
if entry.Outcome == "canceled" {
|
||||||
message = "Configuration validation was canceled."
|
message = "Configuration validation was canceled."
|
||||||
}
|
}
|
||||||
outcome = configFailure(message, acquired.Explanation, err)
|
outcome = configFailure(invocation.Context, message, acquired.Explanation, err)
|
||||||
break
|
break
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -12,8 +12,7 @@ does not install commands.
|
|||||||
|
|
||||||
The module path is `go.maximumdirect.net/ckprompt`. See the
|
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)
|
[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
|
for compatible releases and Go requirements.
|
||||||
alignment requirement.
|
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
|
|||||||
@@ -196,7 +196,8 @@ func WithRequestValidation[I, S any](
|
|||||||
if build != nil {
|
if build != nil {
|
||||||
built, err := build(ctx, request, input, state)
|
built, err := build(ctx, request, input, state)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return commandkit.Acquired[struct{}]{}, err
|
messages := promptKitLoadErrorDiagnostics(err, "")
|
||||||
|
return commandkit.Acquired[struct{}]{Diagnostics: messages.diagnostics, Explanation: messages.explanation}, err
|
||||||
}
|
}
|
||||||
concreteRequest = built
|
concreteRequest = built
|
||||||
}
|
}
|
||||||
@@ -476,12 +477,7 @@ func loadPromptKitEngine[I, S any](
|
|||||||
) (*promptkit.Engine, *promptkit.ConfigurationInspection, promptKitAcquisition, error) {
|
) (*promptkit.Engine, *promptkit.ConfigurationInspection, promptKitAcquisition, error) {
|
||||||
engine, err := load(ctx, selection, input, state)
|
engine, err := load(ctx, selection, input, state)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
var loadErr *configkit.LoadError
|
return nil, nil, promptKitLoadErrorDiagnostics(err, side), err
|
||||||
if errors.As(err, &loadErr) {
|
|
||||||
messages := promptKitDiagnostics("promptkit", side, loadErr.Sources(), loadErr.Diagnostics())
|
|
||||||
return nil, nil, messages, err
|
|
||||||
}
|
|
||||||
return nil, nil, promptKitAcquisition{}, err
|
|
||||||
}
|
}
|
||||||
if engine == nil {
|
if engine == nil {
|
||||||
return nil, nil, promptKitAcquisition{}, errors.New("PromptKit configuration loader returned a nil engine")
|
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
|
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 {
|
func promptKitDiagnostics(scope, side string, sources []configkit.SourceInfo, records []configkit.Diagnostic) promptKitAcquisition {
|
||||||
heading := "Configuration scope " + strconv.Quote(scope)
|
heading := "Configuration scope " + strconv.Quote(scope)
|
||||||
if side != "" {
|
if side != "" {
|
||||||
|
|||||||
@@ -202,7 +202,7 @@ func newCatalogListCommand[I, S any](suite Suite[I, S], name string) commandkit.
|
|||||||
}
|
}
|
||||||
return runCatalogList(invocation, suite, input, name, list, collectionCatalogReport)
|
return runCatalogList(invocation, suite, input, name, list, collectionCatalogReport)
|
||||||
default:
|
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 {
|
) commandkit.Outcome {
|
||||||
if invocation.Context != nil {
|
if invocation.Context != nil {
|
||||||
if err := invocation.Context.Err(); err != 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
|
var state S
|
||||||
@@ -377,18 +377,18 @@ func runCatalogList[T any, I, S any](
|
|||||||
}
|
}
|
||||||
if invocation.Context != nil {
|
if invocation.Context != nil {
|
||||||
if err := invocation.Context.Err(); err != 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)
|
acquired, err := list(invocation.Context, CatalogRequest{Selection: input.selection, Filter: input.filter}, input.selected, state)
|
||||||
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
||||||
if err != nil {
|
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 invocation.Context != nil {
|
||||||
if err := invocation.Context.Err(); err != 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)})
|
_ = 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 {
|
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 {
|
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
|
var state S
|
||||||
if suite.NewState != nil {
|
if suite.NewState != nil {
|
||||||
state = suite.NewState()
|
state = suite.NewState()
|
||||||
}
|
}
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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 value any
|
||||||
var diagnostics []commandkit.Diagnostic
|
var diagnostics []commandkit.Diagnostic
|
||||||
@@ -435,13 +435,13 @@ func runDefinitionInspection[I, S any](invocation commandkit.Invocation, suite S
|
|||||||
}
|
}
|
||||||
queuePromptDiagnostics(invocation.Reporter(), diagnostics)
|
queuePromptDiagnostics(invocation.Reporter(), diagnostics)
|
||||||
if err != nil {
|
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 {
|
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 {
|
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})
|
_ = invocation.Reporter().Report(commandkit.Report{Value: value})
|
||||||
return commandkit.Success()
|
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 {
|
func runRequirementsInspection[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *requirementsInput[I]) commandkit.Outcome {
|
||||||
if invocation.Context != nil {
|
if invocation.Context != nil {
|
||||||
if err := invocation.Context.Err(); err != 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
|
var state S
|
||||||
@@ -529,7 +529,7 @@ func runRequirementsInspection[I, S any](invocation commandkit.Invocation, suite
|
|||||||
}
|
}
|
||||||
if invocation.Context != nil {
|
if invocation.Context != nil {
|
||||||
if err := invocation.Context.Err(); err != 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)
|
acquired, err := suite.InspectRequirements(invocation.Context, request, input.selected, state)
|
||||||
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
||||||
if err != nil {
|
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 {
|
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 invocation.Context != nil {
|
||||||
if err := invocation.Context.Err(); err != 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)})
|
_ = 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)
|
outcome := commandkit.Failure(message)
|
||||||
|
if cause != nil && ckconfig.ClassifyConfigurationError(cause) == commandkit.OutcomeUsage {
|
||||||
|
outcome = commandkit.Usage(message)
|
||||||
|
}
|
||||||
if explanation.Message != "" || len(explanation.Details) > 0 {
|
if explanation.Message != "" || len(explanation.Details) > 0 {
|
||||||
outcome = outcome.WithExplanation(explanation.Message, explanation.Details...)
|
outcome = outcome.WithExplanation(explanation.Message, explanation.Details...)
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -154,7 +154,7 @@ func TestPublicConfigDiffUsesPromptKitPairAndPreparedInputs(t *testing.T) {
|
|||||||
|
|
||||||
var diagnostics bytes.Buffer
|
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})
|
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())
|
t.Fatalf("installed load failure = %#v, diagnostics %q", failure, diagnostics.String())
|
||||||
}
|
}
|
||||||
var loadFailure *configkit.LoadError
|
var loadFailure *configkit.LoadError
|
||||||
|
|||||||
100
integrations/ckprompt/configuration_composition_outcomes_test.go
Normal file
100
integrations/ckprompt/configuration_composition_outcomes_test.go
Normal 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())
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
209
integrations/ckprompt/configuration_outcomes_test.go
Normal file
209
integrations/ckprompt/configuration_outcomes_test.go
Normal 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)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,29 +2,29 @@
|
|||||||
|
|
||||||
## PromptKit
|
## 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
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-or-later
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
License and notices: [LGPL v3.0](../../LICENSE) |
|
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
|
## 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
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-or-later
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
License and notices: [LGPL v3.0](../../LICENSE) |
|
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
|
## ReleaseKit
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
CommandKit ckprompt v0.5.0 adds PromptKit v0.20.0 support, including request
|
||||||
preview, namespace selection, and shared text, YAML, and JSON output. It uses
|
preview, namespace selection, and shared text, YAML, and JSON output. It requires
|
||||||
ConfigKit v1.1.0 and requires Go 1.27.0.
|
CommandKit core v0.5.0, ckconfig v0.5.0, ConfigKit v1.1.0, and Go 1.27.0.
|
||||||
|
|
||||||
## Operator features
|
## 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
|
adds the standard commands with their shorter flag aliases. Literal and file
|
||||||
inputs keep their command-line order.
|
inputs keep their command-line order.
|
||||||
|
|
||||||
## Compatibility and preparation
|
## Correctness improvements
|
||||||
|
|
||||||
This candidate changes resource report shapes, input flags, formatting, and
|
Aggregate smoke testing retains cancellation when it stops remaining tests,
|
||||||
configuration comparison behavior. Review the current
|
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
|
[CLI reference](../../../../docs/cli.md#promptkit-definition-inspection) and
|
||||||
[consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
|
[consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
|
||||||
when updating declarations or code that reads reports. Applications continue to
|
when updating declarations or code that reads reports. Applications continue to
|
||||||
own engine construction, credentials, and execution.
|
own engine construction, credentials, and execution.
|
||||||
|
|
||||||
The current source requires `ckconfig.AdaptDiagnostics`, which is absent from
|
Upgrade all three CommandKit modules to v0.5.0 together. This release follows
|
||||||
its selected ckconfig v0.4.0 dependency. Before publication, complete
|
published ckprompt v0.2.0 and adopts the vanity imports
|
||||||
[dependency alignment](../../../../docs/roadmap/future.md#pending-release-and-integration-work)
|
`go.maximumdirect.net/configkit` and `go.maximumdirect.net/promptkit`.
|
||||||
and update this candidate's dependency guidance to the selected releases.
|
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)
|
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) |
|
[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.3.0/integrations/ckprompt/LICENSE) |
|
[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.3.0/integrations/ckprompt/docs/oss/attribution.md)
|
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/docs/oss/attribution.md)
|
||||||
16
integrations/ckprompt/docs/releases/v0.6.0.md
Normal file
16
integrations/ckprompt/docs/releases/v0.6.0.md
Normal 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)
|
||||||
21
integrations/ckprompt/docs/releases/v0.7.0.md
Normal file
21
integrations/ckprompt/docs/releases/v0.7.0.md
Normal 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)
|
||||||
25
integrations/ckprompt/docs/releases/v0.8.0.md
Normal file
25
integrations/ckprompt/docs/releases/v0.8.0.md
Normal 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)
|
||||||
@@ -4,11 +4,10 @@ This example combines application and PromptKit configuration, resource
|
|||||||
inspection, request checks, and smoke tests. It uses local fixtures and an
|
inspection, request checks, and smoke tests. It uses local fixtures and an
|
||||||
in-memory model client. **No model service or credentials are required.**
|
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
|
Use Go 1.27.0 on `PATH`. An aligned workspace containing all three local modules
|
||||||
modules. Follow the [workspace setup](../../../../docs/development.md#documentation-validation)
|
exercises their current sources; follow the [workspace setup](../../../../docs/development.md#documentation-validation)
|
||||||
from the repository root first. Current ckprompt source needs a helper in local
|
from the repository root. The example also builds independently with
|
||||||
ckconfig source that its released dependency does not yet contain; independent
|
`GOWORK=off` against its module's released dependencies.
|
||||||
builds remain pending [release alignment](../../../../docs/roadmap/future.md#pending-release-and-integration-work).
|
|
||||||
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
|
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
|
||||||
version and compatibility details.
|
version and compatibility details.
|
||||||
|
|
||||||
@@ -168,5 +167,5 @@ for suite composition, builders, and ownership, and the [source](main.go) for
|
|||||||
the complete application.
|
the complete application.
|
||||||
|
|
||||||
Run `GOWORK=auto GOTOOLCHAIN=local go test ./...` from this example directory
|
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.
|
`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases.
|
||||||
|
|||||||
@@ -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})
|
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)
|
t.Fatalf("overlapping native overrides: %#v", outcome)
|
||||||
}
|
}
|
||||||
loads := 0
|
loads := 0
|
||||||
|
|||||||
@@ -3,10 +3,10 @@ module go.maximumdirect.net/ckprompt
|
|||||||
go 1.27.0
|
go 1.27.0
|
||||||
|
|
||||||
require (
|
require (
|
||||||
go.maximumdirect.net/ckconfig v0.4.0
|
go.maximumdirect.net/ckconfig v0.8.0
|
||||||
go.maximumdirect.net/commandkit v0.4.0
|
go.maximumdirect.net/commandkit v0.6.0
|
||||||
go.maximumdirect.net/configkit v1.1.0
|
go.maximumdirect.net/configkit v1.2.0
|
||||||
go.maximumdirect.net/promptkit v0.20.0
|
go.maximumdirect.net/promptkit v0.21.0
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
@@ -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=
|
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 h1:7MpI/jIy+3BZrVME5rhKQibh5U9IA3s97BUJ2EOG41s=
|
||||||
go.maximumdirect.net/ckconfig v0.4.0/go.mod h1:Mk6QOfHrFy00uE0/gw9h6/Y9LcdTShVEzM/oI/HGDns=
|
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 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
|
||||||
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
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 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
|
||||||
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
|
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 h1:ZpwbjiCZWXdnnZ26RuWKoOco0jFnaAX8m2tQAX7ZlnM=
|
||||||
go.maximumdirect.net/promptkit v0.20.0/go.mod h1:kCoyvI0xSax9K9aRPCEkpkyAP5YLs157oBLFLdzgRbM=
|
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 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
||||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
||||||
|
|||||||
@@ -43,7 +43,8 @@ func WithRequestPreparation[I, S any](
|
|||||||
if build != nil {
|
if build != nil {
|
||||||
built, err := build(ctx, request, input, state)
|
built, err := build(ctx, request, input, state)
|
||||||
if err != nil {
|
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
|
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 {
|
func runRequestPreparation[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *concreteRequestInput[I]) commandkit.Outcome {
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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
|
var state S
|
||||||
if suite.NewState != nil {
|
if suite.NewState != nil {
|
||||||
state = suite.NewState()
|
state = suite.NewState()
|
||||||
}
|
}
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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}
|
request := PreparationRequest{Selection: input.request.Selection, Request: input.request.Request, Namespaces: input.request.Namespaces}
|
||||||
acquired, err := suite.PrepareRequest(invocation.Context, request, input.selected, state)
|
acquired, err := suite.PrepareRequest(invocation.Context, request, input.selected, state)
|
||||||
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
||||||
if err != nil {
|
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 {
|
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 {
|
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})
|
_ = invocation.Reporter().Report(commandkit.Report{Value: acquired.Value})
|
||||||
return commandkit.Success()
|
return commandkit.Success()
|
||||||
|
|||||||
@@ -51,7 +51,8 @@ func WithSmokeTesting[I, S any](
|
|||||||
if build != nil {
|
if build != nil {
|
||||||
built, err := build(ctx, request, input, state)
|
built, err := build(ctx, request, input, state)
|
||||||
if err != nil {
|
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
|
concreteRequest = built
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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 {
|
func runSmokeTest[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *smokeCommandInput[I]) commandkit.Outcome {
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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
|
var state S
|
||||||
if suite.NewState != nil {
|
if suite.NewState != nil {
|
||||||
state = suite.NewState()
|
state = suite.NewState()
|
||||||
}
|
}
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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" {
|
if input.kind == "all" {
|
||||||
return runSmokeAggregate(invocation, suite, input, state)
|
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 {
|
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)})
|
_ = invocation.Reporter().Report(commandkit.Report{Value: smokeReportFromNative(acquired.Value)})
|
||||||
if operationErr != nil {
|
if operationErr != nil {
|
||||||
return definitionFailure(smokeFailureMessage(input.kind), acquired.Explanation, operationErr)
|
return definitionFailure(invocation.Context, smokeFailureMessage(input.kind), acquired.Explanation, operationErr)
|
||||||
}
|
}
|
||||||
return commandkit.Success()
|
return commandkit.Success()
|
||||||
}
|
}
|
||||||
@@ -146,7 +146,7 @@ func runSmokeAggregate[I, S any](invocation commandkit.Invocation, suite Suite[I
|
|||||||
for _, kind := range kinds {
|
for _, kind := range kinds {
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
if err := promptKitContextError(invocation.Context); err != nil {
|
||||||
if len(results) == 0 {
|
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)
|
operationErrors = append(operationErrors, err)
|
||||||
break
|
break
|
||||||
@@ -182,11 +182,11 @@ func runSmokeAggregate[I, S any](invocation commandkit.Invocation, suite Suite[I
|
|||||||
}
|
}
|
||||||
|
|
||||||
if len(results) == 0 {
|
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)})
|
_ = invocation.Reporter().Report(commandkit.Report{Value: smokeResultsReport(results)})
|
||||||
if len(operationErrors) > 0 {
|
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()
|
return commandkit.Success()
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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 {
|
func runRequestValidation[I, S any](invocation commandkit.Invocation, suite Suite[I, S], input *concreteRequestInput[I]) commandkit.Outcome {
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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
|
var state S
|
||||||
if suite.NewState != nil {
|
if suite.NewState != nil {
|
||||||
state = suite.NewState()
|
state = suite.NewState()
|
||||||
}
|
}
|
||||||
if err := promptKitContextError(invocation.Context); err != nil {
|
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)
|
acquired, err := suite.ValidateRequest(invocation.Context, input.request, input.selected, state)
|
||||||
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
queuePromptDiagnostics(invocation.Reporter(), acquired.Diagnostics)
|
||||||
if err != nil {
|
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 {
|
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}})
|
_ = invocation.Reporter().Report(commandkit.Report{Value: requestValidationReport{PromptID: input.promptID, Valid: true}})
|
||||||
return commandkit.Success()
|
return commandkit.Success()
|
||||||
|
|||||||
@@ -409,7 +409,7 @@ func TestValidationCommandRetainsProviderDiagnosticsAndClassifiesFailures(t *tes
|
|||||||
}, nil)))
|
}, nil)))
|
||||||
outcome = loadApp.Execute(context.Background(), []string{"promptkit", "requirements", "validate", "briefing"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
|
outcome = loadApp.Execute(context.Background(), []string{"promptkit", "requirements", "validate", "briefing"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
|
||||||
var retained *configkit.LoadError
|
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)
|
t.Fatalf("loader failure = %#v, want retained ConfigKit error and diagnostics", outcome)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -77,9 +77,7 @@ func (session *Session) Parse(argv []string) commandmeta.Result {
|
|||||||
}
|
}
|
||||||
|
|
||||||
remaining := append(commandpath.CloneTokens(unconsumed), tail...)
|
remaining := append(commandpath.CloneTokens(unconsumed), tail...)
|
||||||
localFlags := make([]commandmeta.Flag, 0, len(selectedNode.Flags)+len(selectedNode.CoreFlags))
|
localFlags := commandmeta.EffectiveFlags(selectedNode.Flags, selectedNode.CoreFlags)
|
||||||
localFlags = append(localFlags, selectedNode.Flags...)
|
|
||||||
localFlags = append(localFlags, selectedNode.CoreFlags...)
|
|
||||||
aliases := session.flagAliases
|
aliases := session.flagAliases
|
||||||
if session.flagAliasesForPath != nil {
|
if session.flagAliasesForPath != nil {
|
||||||
aliases = session.flagAliasesForPath(result.Path)
|
aliases = session.flagAliasesForPath(result.Path)
|
||||||
@@ -254,7 +252,7 @@ func displayCommandPath(rootName string, path []string) string {
|
|||||||
return strings.Join(parts, " ")
|
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) {
|
func (session *Session) UsageLine(path []string) (string, *commandmeta.Failure) {
|
||||||
if session == nil || session.root == nil {
|
if session == nil || session.root == nil {
|
||||||
return "", &commandmeta.Failure{Message: "command tree is 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() {
|
if selected.HasSubCommands() {
|
||||||
line += " [command]"
|
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
|
return line, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -316,7 +330,7 @@ func buildTree(root *commandmeta.Command) (*spfcobra.Command, map[*spfcobra.Comm
|
|||||||
helpFlag := backend.Flags().Lookup("help")
|
helpFlag := backend.Flags().Lookup("help")
|
||||||
helpFlag.NoOptDefVal = "true"
|
helpFlag.NoOptDefVal = "true"
|
||||||
helpFlag.Usage = "help for this command (default: false)"
|
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}
|
value := &rawValue{boolean: declarationFlag.Boolean}
|
||||||
backend.Flags().VarP(value, declarationFlag.Name, declarationFlag.Short, flagUsage(declarationFlag))
|
backend.Flags().VarP(value, declarationFlag.Name, declarationFlag.Short, flagUsage(declarationFlag))
|
||||||
backendFlag := backend.Flags().Lookup(declarationFlag.Name)
|
backendFlag := backend.Flags().Lookup(declarationFlag.Name)
|
||||||
|
|||||||
@@ -281,3 +281,14 @@ func TestMissingSessionTreeReturnsNeutralFailures(t *testing.T) {
|
|||||||
t.Fatalf("missing-tree usage failure = %#v", failure)
|
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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -2,6 +2,8 @@
|
|||||||
// its command-line backend.
|
// its command-line backend.
|
||||||
package commandmeta
|
package commandmeta
|
||||||
|
|
||||||
|
import "strings"
|
||||||
|
|
||||||
// Key identifies one command inside one routing snapshot.
|
// Key identifies one command inside one routing snapshot.
|
||||||
type Key uint64
|
type Key uint64
|
||||||
|
|
||||||
@@ -100,6 +102,35 @@ func ReportingFlags() []Flag {
|
|||||||
return flags
|
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.
|
// IsReportingFlag reports whether name is reserved for a shared reporting flag.
|
||||||
func IsReportingFlag(name string) bool {
|
func IsReportingFlag(name string) bool {
|
||||||
for _, flag := range reportingFlags {
|
for _, flag := range reportingFlags {
|
||||||
|
|||||||
@@ -1,6 +1,9 @@
|
|||||||
package commandmeta
|
package commandmeta
|
||||||
|
|
||||||
import "testing"
|
import (
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
func TestReportingFlagsAreBooleanAndReturnedIndependently(t *testing.T) {
|
func TestReportingFlagsAreBooleanAndReturnedIndependently(t *testing.T) {
|
||||||
flags := ReportingFlags()
|
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")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
40
reporter.go
40
reporter.go
@@ -10,13 +10,19 @@ import (
|
|||||||
commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
|
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 (
|
const (
|
||||||
modeOrdinary reportingMode = iota
|
// ReportingModeOrdinary uses ordinary reporting visibility.
|
||||||
modeQuiet
|
ReportingModeOrdinary ReportingMode = iota
|
||||||
modeVerbose
|
// ReportingModeQuiet suppresses ordinary output and messages.
|
||||||
modeDebug
|
ReportingModeQuiet
|
||||||
|
// ReportingModeVerbose enables verbose reporting.
|
||||||
|
ReportingModeVerbose
|
||||||
|
// ReportingModeDebug enables debug reporting.
|
||||||
|
ReportingModeDebug
|
||||||
)
|
)
|
||||||
|
|
||||||
type reportingDestination uint8
|
type reportingDestination uint8
|
||||||
@@ -41,7 +47,7 @@ type reportingState struct {
|
|||||||
diagnostics destinationState
|
diagnostics destinationState
|
||||||
closed bool
|
closed bool
|
||||||
deferredClosed bool
|
deferredClosed bool
|
||||||
mode reportingMode
|
mode ReportingMode
|
||||||
format Format
|
format Format
|
||||||
progress bool
|
progress bool
|
||||||
progressSet bool
|
progressSet bool
|
||||||
@@ -109,7 +115,7 @@ func newReporter(streams Streams) *Reporter {
|
|||||||
return &Reporter{state: &reportingState{
|
return &Reporter{state: &reportingState{
|
||||||
output: destinationState{writer: streams.Out},
|
output: destinationState{writer: streams.Out},
|
||||||
diagnostics: destinationState{writer: streams.Err},
|
diagnostics: destinationState{writer: streams.Err},
|
||||||
mode: modeOrdinary,
|
mode: ReportingModeOrdinary,
|
||||||
}}
|
}}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -125,13 +131,13 @@ func (r *Reporter) applySelection(selection commandmeta.ReportingSelection) {
|
|||||||
}
|
}
|
||||||
switch selection.Mode {
|
switch selection.Mode {
|
||||||
case commandmeta.ReportingModeQuiet:
|
case commandmeta.ReportingModeQuiet:
|
||||||
state.mode = modeQuiet
|
state.mode = ReportingModeQuiet
|
||||||
case commandmeta.ReportingModeVerbose:
|
case commandmeta.ReportingModeVerbose:
|
||||||
state.mode = modeVerbose
|
state.mode = ReportingModeVerbose
|
||||||
case commandmeta.ReportingModeDebug:
|
case commandmeta.ReportingModeDebug:
|
||||||
state.mode = modeDebug
|
state.mode = ReportingModeDebug
|
||||||
default:
|
default:
|
||||||
state.mode = modeOrdinary
|
state.mode = ReportingModeOrdinary
|
||||||
}
|
}
|
||||||
state.progress = selection.Progress
|
state.progress = selection.Progress
|
||||||
state.progressSet = selection.ProgressSet
|
state.progressSet = selection.ProgressSet
|
||||||
@@ -189,7 +195,7 @@ func (r *Reporter) RenderOutput(write func(io.Writer) error) error {
|
|||||||
destination.submitted = true
|
destination.submitted = true
|
||||||
writer := &coordinatedWriter{state: state, destination: destinationOutput}
|
writer := &coordinatedWriter{state: state, destination: destinationOutput}
|
||||||
renderErr := write(writer)
|
renderErr := write(writer)
|
||||||
if state.mode == modeQuiet {
|
if state.mode == ReportingModeQuiet {
|
||||||
destination.suppressed = true
|
destination.suppressed = true
|
||||||
} else if renderErr == nil && writer.writeError == nil {
|
} else if renderErr == nil && writer.writeError == nil {
|
||||||
destination.delivered = true
|
destination.delivered = true
|
||||||
@@ -489,17 +495,17 @@ func renderDetailsLocked(state *reportingState, details []Detail, visible bool)
|
|||||||
func (state *reportingState) visible(category messageCategory) bool {
|
func (state *reportingState) visible(category messageCategory) bool {
|
||||||
switch category {
|
switch category {
|
||||||
case categoryInfo, categoryWarning:
|
case categoryInfo, categoryWarning:
|
||||||
return state.mode == modeVerbose || state.mode == modeDebug
|
return state.mode == ReportingModeVerbose || state.mode == ReportingModeDebug
|
||||||
case categoryDebug:
|
case categoryDebug:
|
||||||
return state.mode == modeDebug
|
return state.mode == ReportingModeDebug
|
||||||
case categoryProgress:
|
case categoryProgress:
|
||||||
if state.mode == modeQuiet {
|
if state.mode == ReportingModeQuiet {
|
||||||
return false
|
return false
|
||||||
}
|
}
|
||||||
if state.progressSet {
|
if state.progressSet {
|
||||||
return state.progress
|
return state.progress
|
||||||
}
|
}
|
||||||
return state.mode == modeDebug
|
return state.mode == ReportingModeDebug
|
||||||
default:
|
default:
|
||||||
return false
|
return false
|
||||||
}
|
}
|
||||||
@@ -617,7 +623,7 @@ func (state *reportingState) destination(destination reportingDestination) *dest
|
|||||||
|
|
||||||
func (state *reportingState) suppressed(destination reportingDestination) bool {
|
func (state *reportingState) suppressed(destination reportingDestination) bool {
|
||||||
if destination == destinationOutput {
|
if destination == destinationOutput {
|
||||||
return state.mode == modeQuiet
|
return state.mode == ReportingModeQuiet
|
||||||
}
|
}
|
||||||
return false
|
return false
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -10,7 +10,7 @@ import (
|
|||||||
)
|
)
|
||||||
|
|
||||||
func TestHiddenSimpleDeferredMessagesDoNotAccumulate(t *testing.T) {
|
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) {
|
t.Run(fmt.Sprint(mode), func(t *testing.T) {
|
||||||
reporter := newReporter(Streams{})
|
reporter := newReporter(Streams{})
|
||||||
setReporterVisibility(reporter, mode, false, false)
|
setReporterVisibility(reporter, mode, false, false)
|
||||||
@@ -45,7 +45,7 @@ func TestHiddenSimpleDeferredMessagesDoNotAccumulate(t *testing.T) {
|
|||||||
func TestHiddenDeferredDetailsRemainDeferredAndCaptured(t *testing.T) {
|
func TestHiddenDeferredDetailsRemainDeferredAndCaptured(t *testing.T) {
|
||||||
var diagnostics bytes.Buffer
|
var diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Err: &diagnostics})
|
reporter := newReporter(Streams{Err: &diagnostics})
|
||||||
setReporterVisibility(reporter, modeQuiet, false, false)
|
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
|
||||||
failure := errors.New("hidden rendering failed")
|
failure := errors.New("hidden rendering failed")
|
||||||
var order []string
|
var order []string
|
||||||
details := []Detail{func(w io.Writer) error {
|
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{})}
|
writer := &gatedDiagnosticWriter{entered: make(chan struct{}), release: make(chan struct{})}
|
||||||
entered := writer.entered
|
entered := writer.entered
|
||||||
reporter := newReporter(Streams{Err: writer})
|
reporter := newReporter(Streams{Err: writer})
|
||||||
setReporterVisibility(reporter, modeVerbose, false, false)
|
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
|
||||||
deferred := reporter.AtEnd()
|
deferred := reporter.AtEnd()
|
||||||
if err := deferred.Warn("accepted"); err != nil {
|
if err := deferred.Warn("accepted"); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
|
|||||||
@@ -16,7 +16,7 @@ func TestReporterExplainsItsOwnFailuresWithoutExposingCauses(t *testing.T) {
|
|||||||
var diagnostics bytes.Buffer
|
var diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Err: &diagnostics})
|
reporter := newReporter(Streams{Err: &diagnostics})
|
||||||
if quiet {
|
if quiet {
|
||||||
setReporterVisibility(reporter, modeQuiet, false, false)
|
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
|
||||||
}
|
}
|
||||||
failure := errors.New("private rendering detail")
|
failure := errors.New("private rendering detail")
|
||||||
render := func(io.Writer) error { return failure }
|
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"))
|
writeErr := errors.Join(errors.New("sink failure"), errors.New("sink detail"))
|
||||||
destination := &reporterTestWriter{err: writeErr}
|
destination := &reporterTestWriter{err: writeErr}
|
||||||
reporter := newReporter(Streams{Out: destination, Err: destination})
|
reporter := newReporter(Streams{Out: destination, Err: destination})
|
||||||
setReporterVisibility(reporter, modeVerbose, false, false)
|
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
|
||||||
render := func(w io.Writer) error {
|
render := func(w io.Writer) error {
|
||||||
_, err := io.WriteString(w, "report")
|
_, err := io.WriteString(w, "report")
|
||||||
return test.combine(renderErr, err)
|
return test.combine(renderErr, err)
|
||||||
|
|||||||
@@ -12,7 +12,7 @@ import (
|
|||||||
func TestReporterReportQuietAndClosed(t *testing.T) {
|
func TestReporterReportQuietAndClosed(t *testing.T) {
|
||||||
var out bytes.Buffer
|
var out bytes.Buffer
|
||||||
reporter := newReporter(Streams{Out: &out})
|
reporter := newReporter(Streams{Out: &out})
|
||||||
reporter.state.mode = modeQuiet
|
reporter.state.mode = ReportingModeQuiet
|
||||||
err := reporter.Report(Report{Value: make(chan int)})
|
err := reporter.Report(Report{Value: make(chan int)})
|
||||||
if err == nil {
|
if err == nil {
|
||||||
t.Fatal("expected serialization error")
|
t.Fatal("expected serialization error")
|
||||||
|
|||||||
@@ -80,7 +80,7 @@ func TestReporterLeavesCallerWriterOpen(t *testing.T) {
|
|||||||
func TestReporterQuietOutputDiscardsSuccessfully(t *testing.T) {
|
func TestReporterQuietOutputDiscardsSuccessfully(t *testing.T) {
|
||||||
var destination bytes.Buffer
|
var destination bytes.Buffer
|
||||||
reporter := newReporter(Streams{Out: &destination})
|
reporter := newReporter(Streams{Out: &destination})
|
||||||
setReporterVisibility(reporter, modeQuiet, false, false)
|
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
|
||||||
writer := reporter.Output()
|
writer := reporter.Output()
|
||||||
|
|
||||||
if n, err := writer.Write([]byte("hidden")); err != nil || n != len("hidden") {
|
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
|
var destination bytes.Buffer
|
||||||
reporter := newReporter(Streams{Out: &destination})
|
reporter := newReporter(Streams{Out: &destination})
|
||||||
writer := reporter.Output()
|
writer := reporter.Output()
|
||||||
setReporterVisibility(reporter, modeQuiet, false, false)
|
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
|
||||||
_ = reporter.finalize(Success(), nil)
|
_ = reporter.finalize(Success(), nil)
|
||||||
|
|
||||||
if n, err := writer.Write([]byte("late")); n != 0 || !errors.Is(err, ErrReporterClosed) {
|
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 {
|
if reporter.state.output.writer != io.Discard || reporter.state.diagnostics.writer != io.Discard {
|
||||||
t.Fatalf("nil destinations were not normalized: %#v", reporter.state)
|
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)
|
t.Fatalf("initial visibility = mode %v, progress %v (set %v)", reporter.state.mode, reporter.state.progress, reporter.state.progressSet)
|
||||||
}
|
}
|
||||||
setReporterVisibility(reporter, modeDebug, true, true)
|
setReporterVisibility(reporter, ReportingModeDebug, true, true)
|
||||||
if reporter.state.mode != modeDebug || !reporter.state.progress || !reporter.state.progressSet {
|
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)
|
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) {
|
func TestReporterMessageVisibilityAndProgressPrecedence(t *testing.T) {
|
||||||
tests := []struct {
|
tests := []struct {
|
||||||
name string
|
name string
|
||||||
mode reportingMode
|
mode ReportingMode
|
||||||
progress bool
|
progress bool
|
||||||
progressSet bool
|
progressSet bool
|
||||||
want string
|
want string
|
||||||
}{
|
}{
|
||||||
{name: "ordinary", mode: modeOrdinary},
|
{name: "ordinary", mode: ReportingModeOrdinary},
|
||||||
{name: "verbose", mode: modeVerbose, want: "not used\nWARN: not used\n"},
|
{name: "verbose", mode: ReportingModeVerbose, want: "not used\nWARN: not used\n"},
|
||||||
{name: "debug", mode: modeDebug, want: "not used\nWARN: not used\nDEBUG: DEBUG\nPROGRESS\n"},
|
{name: "debug", mode: ReportingModeDebug, want: "not used\nWARN: not used\nDEBUG: DEBUG\nPROGRESS\n"},
|
||||||
{name: "quiet overrides progress", mode: modeQuiet, progress: true, progressSet: true},
|
{name: "quiet overrides progress", mode: ReportingModeQuiet, progress: true, progressSet: true},
|
||||||
{name: "explicit ordinary progress", mode: modeOrdinary, progress: true, progressSet: true, want: "PROGRESS\n"},
|
{name: "explicit ordinary progress", mode: ReportingModeOrdinary, 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: "explicit debug disable", mode: ReportingModeDebug, progressSet: true, want: "not used\nWARN: not used\nDEBUG: DEBUG\n"},
|
||||||
}
|
}
|
||||||
|
|
||||||
for _, test := range tests {
|
for _, test := range tests {
|
||||||
@@ -237,7 +237,7 @@ func TestReporterMessageVisibilityAndProgressPrecedence(t *testing.T) {
|
|||||||
func TestReporterFormatsMessagesAndPreservesDetailOrder(t *testing.T) {
|
func TestReporterFormatsMessagesAndPreservesDetailOrder(t *testing.T) {
|
||||||
var diagnostics bytes.Buffer
|
var diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Err: &diagnostics})
|
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,
|
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 one\n"); return err },
|
||||||
func(w io.Writer) error { _, err := io.WriteString(w, "detail two\n"); return err }); err != nil {
|
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) {
|
func TestReporterHiddenRenderersRunAgainstDiscardAndRetainErrors(t *testing.T) {
|
||||||
var diagnostics bytes.Buffer
|
var diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Err: &diagnostics})
|
reporter := newReporter(Streams{Err: &diagnostics})
|
||||||
setReporterVisibility(reporter, modeQuiet, false, false)
|
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
|
||||||
renderErr := errors.New("native renderer failed")
|
renderErr := errors.New("native renderer failed")
|
||||||
calls := 0
|
calls := 0
|
||||||
err := reporter.Warn("hidden warning", func(w io.Writer) error {
|
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")
|
renderErr := errors.New("output renderer failed")
|
||||||
diagnosticErr := errors.New("diagnostic renderer failed")
|
diagnosticErr := errors.New("diagnostic renderer failed")
|
||||||
reporter := newReporter(Streams{Out: io.Discard, Err: io.Discard})
|
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.RenderOutput(func(io.Writer) error { return renderErr })
|
||||||
_ = reporter.Warn("warning", func(io.Writer) error { return diagnosticErr })
|
_ = reporter.Warn("warning", func(io.Writer) error { return diagnosticErr })
|
||||||
|
|
||||||
@@ -297,7 +297,7 @@ func TestReporterRecordsIgnoredRenderErrors(t *testing.T) {
|
|||||||
func TestReporterRenderOutputRunsInQuietAndRetainsFailure(t *testing.T) {
|
func TestReporterRenderOutputRunsInQuietAndRetainsFailure(t *testing.T) {
|
||||||
destination := &reporterTestWriter{}
|
destination := &reporterTestWriter{}
|
||||||
reporter := newReporter(Streams{Out: destination})
|
reporter := newReporter(Streams{Out: destination})
|
||||||
setReporterVisibility(reporter, modeQuiet, false, false)
|
setReporterVisibility(reporter, ReportingModeQuiet, false, false)
|
||||||
renderErr := errors.New("quiet encoder failed")
|
renderErr := errors.New("quiet encoder failed")
|
||||||
calls := 0
|
calls := 0
|
||||||
_ = reporter.RenderOutput(func(w io.Writer) error {
|
_ = 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 {
|
if err := reporter.RenderOutput(func(io.Writer) error { return nil }); err != nil {
|
||||||
t.Fatal(err)
|
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 {
|
if err := reporter.Warn("", func(io.Writer) error { return nil }); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
@@ -409,7 +409,7 @@ func TestReporterConcurrentOperationsRemainWhole(t *testing.T) {
|
|||||||
t.Run("render callback and message", func(t *testing.T) {
|
t.Run("render callback and message", func(t *testing.T) {
|
||||||
var output bytes.Buffer
|
var output bytes.Buffer
|
||||||
reporter := newReporter(Streams{Out: &output, Err: &output})
|
reporter := newReporter(Streams{Out: &output, Err: &output})
|
||||||
setReporterVisibility(reporter, modeVerbose, false, false)
|
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
|
||||||
start := make(chan struct{})
|
start := make(chan struct{})
|
||||||
ready := make(chan struct{}, 2)
|
ready := make(chan struct{}, 2)
|
||||||
done := 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) {
|
t.Run("message details and render callback", func(t *testing.T) {
|
||||||
var output bytes.Buffer
|
var output bytes.Buffer
|
||||||
reporter := newReporter(Streams{Out: &output, Err: &output})
|
reporter := newReporter(Streams{Out: &output, Err: &output})
|
||||||
setReporterVisibility(reporter, modeVerbose, false, false)
|
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
|
||||||
start := make(chan struct{})
|
start := make(chan struct{})
|
||||||
ready := make(chan struct{}, 2)
|
ready := make(chan struct{}, 2)
|
||||||
done := make(chan struct{}, 2)
|
done := make(chan struct{}, 2)
|
||||||
@@ -481,7 +481,7 @@ func TestReporterConcurrentOperationsRemainWhole(t *testing.T) {
|
|||||||
func TestReporterEmptyHeadingDoesNotAddPrefixOrBlankLine(t *testing.T) {
|
func TestReporterEmptyHeadingDoesNotAddPrefixOrBlankLine(t *testing.T) {
|
||||||
var diagnostics bytes.Buffer
|
var diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Err: &diagnostics})
|
reporter := newReporter(Streams{Err: &diagnostics})
|
||||||
setReporterVisibility(reporter, modeVerbose, false, false)
|
setReporterVisibility(reporter, ReportingModeVerbose, false, false)
|
||||||
if err := reporter.Warn("", func(w io.Writer) error {
|
if err := reporter.Warn("", func(w io.Writer) error {
|
||||||
_, err := io.WriteString(w, "native multiline\nsecond line\n")
|
_, err := io.WriteString(w, "native multiline\nsecond line\n")
|
||||||
return err
|
return err
|
||||||
@@ -499,7 +499,7 @@ func TestReporterEmptyHeadingDoesNotAddPrefixOrBlankLine(t *testing.T) {
|
|||||||
func TestReporterFinalizesDeferredMessagesBeforeCompletionAndExplanation(t *testing.T) {
|
func TestReporterFinalizesDeferredMessagesBeforeCompletionAndExplanation(t *testing.T) {
|
||||||
var output, diagnostics bytes.Buffer
|
var output, diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Out: &output, Err: &diagnostics})
|
reporter := newReporter(Streams{Out: &output, Err: &diagnostics})
|
||||||
setReporterVisibility(reporter, modeDebug, false, false)
|
setReporterVisibility(reporter, ReportingModeDebug, false, false)
|
||||||
if err := reporter.Info("started"); err != nil {
|
if err := reporter.Info("started"); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
@@ -525,7 +525,7 @@ func TestReporterFinalizesDeferredMessagesBeforeCompletionAndExplanation(t *test
|
|||||||
func TestReporterDeferredSubmissionCopiesDetailsAndRetainsDeferredFailures(t *testing.T) {
|
func TestReporterDeferredSubmissionCopiesDetailsAndRetainsDeferredFailures(t *testing.T) {
|
||||||
var diagnostics bytes.Buffer
|
var diagnostics bytes.Buffer
|
||||||
reporter := newReporter(Streams{Err: &diagnostics})
|
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 })
|
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 })
|
writeSecond := Detail(func(w io.Writer) error { _, err := io.WriteString(w, "second detail\n"); return err })
|
||||||
details := []Detail{writeFirst}
|
details := []Detail{writeFirst}
|
||||||
@@ -545,7 +545,7 @@ func TestReporterDeferredSubmissionCopiesDetailsAndRetainsDeferredFailures(t *te
|
|||||||
|
|
||||||
renderErr := errors.New("deferred renderer failed")
|
renderErr := errors.New("deferred renderer failed")
|
||||||
failedReporter := newReporter(Streams{Err: io.Discard})
|
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 {
|
if err := failedReporter.AtEnd().Warn("hidden", func(io.Writer) error { return renderErr }); err != nil {
|
||||||
t.Fatal(err)
|
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}
|
selection := commandmeta.ReportingSelection{Progress: progress, ProgressSet: progressSet}
|
||||||
switch mode {
|
switch mode {
|
||||||
case modeQuiet:
|
case ReportingModeQuiet:
|
||||||
selection.Mode = commandmeta.ReportingModeQuiet
|
selection.Mode = commandmeta.ReportingModeQuiet
|
||||||
case modeVerbose:
|
case ReportingModeVerbose:
|
||||||
selection.Mode = commandmeta.ReportingModeVerbose
|
selection.Mode = commandmeta.ReportingModeVerbose
|
||||||
case modeDebug:
|
case ReportingModeDebug:
|
||||||
selection.Mode = commandmeta.ReportingModeDebug
|
selection.Mode = commandmeta.ReportingModeDebug
|
||||||
}
|
}
|
||||||
reporter.applySelection(selection)
|
reporter.applySelection(selection)
|
||||||
|
|||||||
205
shared_debug_external_test.go
Normal file
205
shared_debug_external_test.go
Normal 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)
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user