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

Document PromptKit request validation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-12 22:25:43 +00:00
parent be8bd9c1ea
commit 88d4059e8d
10 changed files with 219 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -16,7 +16,7 @@ constructing them, and returns outcomes without exiting the process. Its
| --- | --- | --- |
| `gitea.maximumdirect.net/eric/CommandKit` | `commandkit` | Typed commands, bindings, execution, outcomes, help, and version. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes and inspection commands. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, and requirements discovery. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, requirements discovery, and concrete request validation. |
Importing an integration does not install commands. Pass its declaration to
`commandkit.New` or `App.Register` to install it. The integrations depend on the

77
docs/cli.md
View File

@@ -385,9 +385,8 @@ from its own inspection methods. Supported cancellation identity is preserved.
## PromptKit requirements
When `Suite.InspectRequirements` is present,
`ckprompt.Command(suite)` installs the following optional operation. It accepts
one required prompt ID and uses PromptKit's native selection and discovery
rules:
`ckprompt.Command(suite)` installs `promptkit requirements show`. It accepts one
required prompt ID and uses PromptKit's native selection and discovery rules:
```text
example promptkit requirements show briefing --campaign spring
@@ -471,6 +470,78 @@ Provider errors, native selection errors, cancellation, and report delivery
failures use the operational path (status `1`) with supported cause identity.
Syntax, operand, variable-assignment, and format errors use usage status `2`.
### Concrete request validation
When `Suite.ValidateRequest` is present, `ckprompt.Command(suite)` also installs
`promptkit requirements validate`. It can be installed without discovery, and
discovery can remain installed without validation. The command accepts one
required prompt ID and passes a concrete request to PromptKit's native
`Engine.ValidateRequest` preparation path:
```text
example promptkit requirements validate briefing --campaign spring --input topic=topic.txt
example promptkit requirements validate briefing --version 2 --profile editorial --session-id session-42 --var mode=full --input notes=notes.txt
```
The command accepts:
| Flag | Values | Default | Meaning |
| --- | --- | --- | --- |
| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
| `--version` | string | empty | Pass the prompt version to PromptKit. |
| `--profile` | string | empty | Pass the profile ID to PromptKit. |
| `--session-id` | string | empty | Pass session context to PromptKit. |
| `--var` | repeatable `KEY=VALUE` | none | Supply caller variables for the concrete request. |
| `--input` | repeatable `NAME=PATH` | none | Bind a file-backed PromptKit artifact. |
| `--format` | `yaml` | `yaml` | Select the success confirmation format. Other formats are usage errors. |
The built-in flags other than repeatable `--var` and `--input` are singleton
bindings; when repeated, the last value is used. Suite selectors retain their
declared binding behavior. Explicit empty `--config` or `--overlay` values keep
their supplied-presence information.
The version, profile, and session fields use native empty-string semantics:
an explicit empty string has the same meaning as omission. PromptKit owns their
interpretation and selection errors. The `promptkit` namespace identifies the
operation, so there is no built-in `--scope` flag.
Each `--var` and `--input` occurrence must contain `=`. CommandKit splits at
the first separator and preserves the exact key/name and remaining value/path.
Empty variable keys and values are passed to PromptKit. Empty input names and
paths are also passed to native validation. File paths are translated to
`promptkit.File(PATH)` references without reading, normalizing, expanding, or
rebasing them during argument binding. Duplicate keys or names use the last
value, but all occurrences are parsed, so any malformed occurrence is a usage
error even if a later assignment is valid. Syntax and path values after shell
processing are otherwise preserved.
On success, the YAML confirmation contains only the requested prompt ID and
`valid: true`:
```yaml
prompt_id: briefing
valid: true
```
Validation delegates concrete request preparation to PromptKit. Depending on
the request and configuration, native preparation may resolve prompt/profile
resources, load artifact and schema resources, render messages and session
context, and perform applicable configuration and credential checks. Native
errors are returned as encountered rather than as an exhaustive inventory.
Validation does not make a model call or retain a prepared execution snapshot.
A successful report means preparation passed for this invocation; it does not
certify provider acceptance or guarantee that later execution will succeed.
See PromptKit's [v0.15.0 `Engine.ValidateRequest` API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/635674c066d0b432187f96e72b9c03d085443ac5/engine.go)
for the native contract.
Builder, engine-loading, and native validation errors use the operational path
(status `1`) with supported error identity and acquired diagnostics retained.
Malformed syntax, missing operands, and unsupported formats use usage status
`2`. Input-check failures keep their existing shared handling. Successful
diagnostics and report-delivery failures follow the common delivery contract.
### PromptKit catalogs
An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by

82
docs/consumers/guide.md
View File

@@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`.
| --- | --- |
| `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, or requirements discovery. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, requirements discovery, or concrete request validation. |
The two integrations are independent optional imports. `ckprompt` uses the
public scope and error contracts from `ckconfig`; importing it does not add the
@@ -119,22 +119,54 @@ source inventory, path explanation, and ConfigKit-backed comparison for the
capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
owns operator syntax and report details.
## PromptKit configuration and definitions
## PromptKit configuration, definitions, and requirements
`ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
it under `config` with validate/show/sources/explain and native diff operations;
it does not install PromptKit catalog, definition, or requirements commands.
`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks,
named inspection callbacks, and native requirements callback. Set its
`NewInput`, `NewState`, selectors, or validation when the application needs
them, then pass `ckprompt.Command(suite)` to core. All five callbacks are
independently optional; `Command` creates each operation group only when its
callbacks are present. Applications can use the requirements callback alone,
clear it while retaining other operations, wrap it, or replace it with their
own provider. For catalogs without named or requirements inspection, narrow the
suite before command capture:
`ckprompt.FromEngine(loadEngine)` supplies five callbacks: prompt and profile
catalogs, named prompt and profile inspection, and native requirements
discovery. Concrete request validation is a sixth, independently optional
capability and is added explicitly with `ckprompt.WithRequestValidation`.
`ckprompt.Command(suite)` creates only operations whose callbacks are present;
discovery and validation share `promptkit requirements` but can be installed
independently. A composed suite can keep the standard five and add validation:
```go
suite := ckprompt.FromEngine(loadEngine)
suite = ckprompt.WithRequestValidation(suite, loadEngine, buildRequest)
suite.NewInput = newInput
suite.NewState = newState
suite.Selectors = selectors
definitionCommand := ckprompt.Command(suite)
```
A validation-only suite can start empty. With application types named `Input`
and `State`, a nil builder forwards the request fields populated by standard
flags directly to PromptKit:
```go
suite := ckprompt.WithRequestValidation(
ckprompt.Suite[Input, State]{}, loadEngine, nil,
)
validationCommand := ckprompt.Command(suite)
```
If the loader is nil, the returned suite retains a wiring issue for installation
to report, even if capabilities are narrowed later. A builder runs before the
engine loader and receives the seed request, selection, typed input, shared
state, and invocation context. It returns the
concrete request; the adapter does not merge seed fields back afterward. The
loader receives the original selection. Builders should start from the seed,
preserve operator values and bindings, and apply defaults only when a map key is
absent, so explicitly supplied empty values stay meaningful. Applications that
validate and then execute a request are encouraged to share their request
construction logic between those paths.
All six suite capabilities are independently optional. For catalogs without
named or requirements inspection, narrow the suite before command capture:
```go
definitions := ckprompt.FromEngine(loadEngine)
@@ -144,20 +176,28 @@ definitions.InspectRequirements = nil
definitionCommand := ckprompt.Command(definitions)
```
Each selected inspection, requirements, or catalog operation prepares one input,
applies its captured selectors, checks that input, and initializes one state
value when those steps are reached. See
Each selected inspection, requirements, validation, or catalog operation
prepares one input, applies its captured selectors, checks that input, and
initializes one state value when those steps are reached. The bundled validation
adapter delegates concrete request preparation to PromptKit and carries its
native errors plus engine-loading diagnostics through the acquisition. It does
not call the model or retain a prepared execution snapshot. See
[ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
timing, omitted-factory zero values, and caller-owned objects and effects.
The loader receives invocation context, explicitly supplied selection, input,
and state. The adapter uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`, and preserves acquisition diagnostics
and supported error identity.
and state. `FromEngine` uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`; validation must be opted into separately
and uses `Engine.ValidateRequest`.
CommandKit-owned listing and inspection code does not execute prompts, contact model
providers, or resolve credential values; application loaders and direct callbacks
retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
owns the command and report contracts.
Catalog, named definition inspection, and requirements discovery do not render
messages or load request artifacts. Concrete request validation follows native
PromptKit preparation, which can resolve prompt/profile resources, load
artifacts and schemas, render messages, and perform applicable configuration
and credential checks. It does not make a model call or certify that a later
execution will succeed. Application loaders and direct callbacks retain their
own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
and [requirements contract](../cli.md#promptkit-requirements) own operator
syntax and reports.
The [composed example](../../integrations/ckprompt/examples/composed/README.md)
combines app and PromptKit config scopes, comparison and catalogs, named and

7
docs/development.md
View File

@@ -4,8 +4,9 @@ CommandKit is distributed as a core Go module and two optional integration
modules. Core owns captured declarations, typed input preparation, installation,
dispatch, outcomes, help, and version. `integrations/ckconfig` owns ConfigKit
scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine,
definition inspection, and requirements discovery adapters. The maintained
[consumer guide](consumers/guide.md) links to the three maintained consumers.
definition inspection, requirements discovery, and concrete request validation.
The maintained [consumer guide](consumers/guide.md) links to the three maintained
consumers.
The [README](../README.md) provides project orientation; the
[documentation policy](policy/documentation.md#canonical-ownership) assigns
canonical documentation owners.
@@ -144,6 +145,8 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
(cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml)
(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
```

22
docs/internal/overview.md
View File

@@ -48,11 +48,13 @@ acquisitions or comparison callback.
`integrations/ckprompt` owns PromptKit engine loading, configuration-scope
adaptation and native comparison, plus optional prompt/profile catalogs, named
inspection, and native requirements discovery. It uses public core and ckconfig
contracts plus PromptKit's public APIs. It does not add a configuration family
when its declaration is installed; callers compose `ckprompt.ConfigScope` with
`ckconfig.Command` separately when they want configuration operations alongside
PromptKit commands.
inspection, native requirements discovery, and concrete request validation.
Validation delegates request preparation to PromptKit and is independently
opted into a suite. It uses public core and ckconfig contracts plus PromptKit's
public APIs. It does not add a configuration family when its declaration is
installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
separately when they want configuration operations alongside PromptKit
commands.
The three maintained consumers live at `examples/core`,
`integrations/ckconfig/examples/simple`, and
@@ -67,7 +69,9 @@ graph isolation.
ConfigKit owns configuration decoding, validation, source history, and path
explanations. PromptKit owns its captured engine configuration, prompt
definitions, profile inheritance, and named inspection semantics. CommandKit
adapts those public contracts without maintaining parallel schemas or invoking
prompt execution. Application loaders and domain behavior remain application
owned.
definitions, profile inheritance, named inspection, requirements discovery,
and concrete request validation semantics. CommandKit adapts those public
contracts without maintaining parallel schemas or invoking model generation.
Native request validation may load resources and artifacts, render messages,
and perform applicable configuration or credential checks through PromptKit.
Application loaders and domain behavior remain application owned.

11
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# PromptKit request validation implementation plan
Status: Stages 1–7 complete; implementation is ongoing.
Status: Stages 1–8 complete; implementation is ongoing.
## Authority, scope, and baseline
@@ -462,6 +462,15 @@ mandates.
capability under its assigned owners, with no stale five-callback or
metadata-only claims covering request validation.
**Completed:** 2026-10-12. Updated ckprompt GoDoc, the CLI reference, consumer
guidance, README module summary, development orientation and examples, and the
internal component inventory. The docs distinguish `FromEngine`'s five
callbacks from explicit validation composition, describe native preparation and
the minimal success YAML, and scope discovery-only statements to discovery.
`GOTOOLCHAIN=local go test -count=1 ./...` passed from `integrations/ckprompt`;
the Stage 7 consumer tests and commands remain unchanged and passed. Changed
Markdown links and anchors and Markdown whitespace checks passed.
## Stage 9: Validate the complete end state and finish
1. Format changed Go files and inspect the final diff for scope, generated junk,

65
integrations/ckprompt/adapters.go
View File

@@ -43,7 +43,7 @@ type RequirementsRequest struct {
}
// Suite describes application-owned input, shared state, and optional catalog,
// named inspection, requirements inspection, and concrete request validation
// named inspection, requirements discovery, and concrete request validation
// capabilities. Its private issues retain adapter construction failures.
// Factory results and callback effects remain caller-owned: Command does not
// deep-copy arbitrary objects or repair aliases returned by factories.
@@ -52,13 +52,14 @@ type RequirementsRequest struct {
// Factories are not invoked during construction, installation, help, or version,
// and need not run after failure.
type Suite[I, S any] struct {
// NewInput is called once when definition, requirements, validation, or catalog input
// preparation is reached, before applying selectors and calling CheckInput.
// NewInput is called once when definition, requirements, validation, or
// catalog input preparation is reached, before applying selectors and
// calling CheckInput.
// If nil, input is the zero value of I, including nil for pointer types.
NewInput func() I
// NewState is called once when an inspection, validation, or catalog callback is reached,
// after input checks pass. If nil, state is the zero value of S, including
// nil for pointer types.
// NewState is called once when an inspection, validation, or catalog
// callback is reached, after input checks pass. If nil, state is the zero
// value of S, including nil for pointer types.
NewState func() S
// Selectors declares the original typed flags accepted by definition,
// requirements, validation, and catalog commands.
@@ -71,12 +72,15 @@ type Suite[I, S any] struct {
// InspectProfile inspects the selected profile after input and state preparation.
InspectProfile func(context.Context, ProfileRequest, I, S) (commandkit.Acquired[*promptkit.ProfileInspection], error)
// InspectRequirements inspects native PromptKit requirements after input and
// state preparation. It is optional; a nil callback omits the requirements
// command without disabling other capabilities.
// state preparation. It is optional; a nil callback omits
// `promptkit requirements show` without disabling validation or other
// capabilities.
InspectRequirements func(context.Context, RequirementsRequest, I, S) (commandkit.Acquired[*promptkit.RequirementInspection], error)
// ValidateRequest validates a concrete PromptKit request after input and state
// preparation. It is optional; a nil callback omits request validation without
// disabling other capabilities.
// ValidateRequest validates a concrete PromptKit request after input and
// state preparation. It is optional; a nil callback omits
// `promptkit requirements validate` without disabling discovery or other
// capabilities. The acquisition carries diagnostics and an empty value on
// success; PromptKit errors are returned unchanged where supported.
ValidateRequest func(context.Context, ValidationRequest, I, S) (commandkit.Acquired[struct{}], error)
// ListPrompts lists prompt identities after input and state preparation.
// It is optional; a nil callback does not install a prompt catalog command.
@@ -89,13 +93,18 @@ type Suite[I, S any] struct {
}
// WithRequestValidation attaches PromptKit-backed concrete request validation
// to suite. The loader receives the request's original selection; the builder,
// when present, runs first and its returned request is passed to PromptKit
// unchanged. A nil builder forwards the seed request. PromptKit's native
// validation errors and the engine loader's configuration diagnostics are
// returned through the acquisition. A nil loader is retained as a suite wiring
// issue and does not install a validation callback. Caller-owned callback
// references and objects remain caller-owned.
// to suite while preserving its other capabilities and retained issues. Those
// issues remain attached if capabilities are narrowed before Command captures
// the suite. The
// builder, when present, runs before the engine loader and receives the seed,
// input, state, and invocation context. Its returned request is passed to
// PromptKit unchanged; the loader receives the seed's original configuration
// selection. A nil builder forwards the seed request unchanged. A builder
// failure prevents engine loading and preserves its supported error identity.
// Native validation errors are returned with supported identity, and
// configuration diagnostics from engine loading remain in the acquisition. A
// nil loader is retained as a suite wiring issue and does not install a
// validation callback. Callback references and objects remain caller-owned.
func WithRequestValidation[I, S any](
suite Suite[I, S],
load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error),
@@ -218,15 +227,17 @@ func promptKitContextError(ctx context.Context) error {
return ctx.Err()
}
// FromEngine supplies prompt and profile catalog callbacks, named inspection
// callbacks, and a requirements inspection callback backed by a PromptKit engine
// loader. The requirements callback forwards RequirementsRequest.Inspection to
// Engine.InspectRequirements. FromEngine does not call the loader during
// construction. Each selected operation passes its context, supplied
// selection, initialized input, and shared invocation state to the loader before
// calling PromptKit's public listing or inspection method. Applications can
// narrow, wrap, or replace these callbacks before Command captures them. A nil
// loader is retained as an adapter issue.
// FromEngine supplies five PromptKit-backed callbacks: prompt and profile
// catalogs, named prompt and profile inspection, and requirements discovery.
// The requirements callback forwards RequirementsRequest.Inspection to
// Engine.InspectRequirements. Concrete request validation is an independent
// capability and can be composed explicitly with WithRequestValidation.
// FromEngine does not call the loader during construction. Each selected
// operation passes its context, supplied selection, initialized input, and
// shared invocation state to the loader before calling PromptKit's public
// listing or inspection method. Applications can narrow, wrap, or replace these
// callbacks before Command captures them. A nil loader is retained as an
// adapter issue.
func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] {
if load == nil {
return Suite[I, S]{issues: []error{errors.New("PromptKit engine loader is nil")}}

18
integrations/ckprompt/command.go
View File

@@ -50,14 +50,16 @@ type inputAssignment struct {
}
// Command captures the optional PromptKit catalog, named inspection,
// requirements inspection, and concrete request validation callbacks and adds
// only supplied operations. An absent suite claims no namespace; attached
// construction issues remain reportable. It adds no configuration family;
// callers compose ConfigScope independently. Construction, installation, help,
// and version do not run suite factories or providers. Command captures suite
// callbacks and selector metadata; callback-referenced objects and effects
// remain caller-owned. Suite documents invocation input and state initialization,
// zero values, and caller ownership of returned objects.
// requirements discovery, and concrete request validation callbacks and adds
// only supplied operations. Discovery and validation share the
// `requirements` group and remain independently optional. An absent suite
// claims no namespace; attached construction issues remain reportable. It adds
// no configuration family; callers compose ConfigScope independently.
// Construction, installation, help, and version do not run suite factories or
// providers. Command captures suite callbacks and selector metadata;
// callback-referenced objects and effects remain caller-owned. Suite documents
// invocation input and state initialization, zero values, and caller ownership
// of returned objects.
// Catalog commands accept config/overlay selection and suite selectors, and
// render YAML with `yaml` as the only format and default. Named-show formats are
// unchanged.

6
integrations/ckprompt/doc.go
View File

@@ -1,5 +1,5 @@
// Package ckprompt provides optional PromptKit configuration comparison,
// definition catalogs, named inspections, and prompt requirements inspection
// for CommandKit. Importing ckprompt installs neither family; callers compose
// its declarations with core and ckconfig explicitly.
// definition catalogs, named inspections, requirements discovery, and concrete
// request validation for CommandKit. Importing ckprompt installs neither
// family; callers compose its declarations with core and ckconfig explicitly.
package ckprompt

8
integrations/ckprompt/validation.go
View File

@@ -5,12 +5,12 @@ import (
promptkit "gitea.maximumdirect.net/eric/promptkit"
)
// ValidationRequest carries the configuration selection and concrete
// PromptKit request to validate.
// ValidationRequest carries the configuration selection and seed PromptKit
// request populated by the standard validation command inputs.
type ValidationRequest struct {
// Selection identifies the configuration sources used to load the engine.
Selection ckconfig.Selection
// Request is the seed request, or the request returned by a validation
// builder when one is configured.
// Request contains the prompt identity, scalar context, variables, and
// artifact references supplied to the command.
Request promptkit.RunRequest
}