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

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