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

Add prepared request preview

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 04:19:58 +00:00
parent c3d5f551c3
commit 8e5e64c6e9
9 changed files with 297 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/cli.md
View File

@@ -555,6 +555,26 @@ performs a network probe. See the [PromptKit resource inspection contracts](http
A missing ID is a usage error; native lookup errors and cancellation retain
supported cause identity.
## PromptKit prepared-request preview
When `Suite.PrepareRequest` is present, `ckprompt.Command(suite)` installs
`promptkit show prepared PROMPT_ID` independently of validation and other
inspection commands. It accepts the same configuration, selector, profile,
session, variable, input, and execution flags as
[request validation](#concrete-request-validation):
```text
example promptkit show prepared briefing --llm-input-text topic=roadmap --format json
```
The command returns PromptKit's native prepared-run report using the shared
formats; automatic and explicit text use YAML. Preparation can read resources
and report rendered application content. It makes no model call and does not
guarantee a subsequent execution will succeed. Application callbacks and
loaders retain their own effects. Native preparation errors retain supported
cause identity. The [PromptKit Prepare API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go)
owns the prepared value and upstream preparation behavior.
## PromptKit requirements
When `Suite.InspectRequirements` is present, `ckprompt.Command(suite)` installs
@@ -676,7 +696,8 @@ contain `=`. CommandKit splits at the first separator and preserves the exact
key/name and remaining value. Empty names and values are passed to native
validation. Text becomes a `promptkit.Inline` reference; file paths become
`promptkit.File` references without being read, normalized, expanded, or
rebased during argument binding. Every occurrence is parsed.
rebased during argument binding. Every occurrence is parsed; for each input
name the last text or file occurrence wins, regardless of form.
On success, the confirmation contains only the requested prompt ID and
`valid: true`:

25
docs/consumers/guide.md
View File

@@ -260,17 +260,18 @@ it does not install PromptKit catalog, definition, or requirements commands.
`ckprompt.FromEngine(loadEngine)` supplies nine callbacks: prompt, profile,
backend, namespace, and collection catalogs; named prompt, profile, and backend
inspection; and native requirements discovery. Concrete request validation and
smoke testing are separate capabilities, added explicitly with
`ckprompt.WithRequestValidation` and `ckprompt.WithSmokeTesting`. The suite has
eleven independently optional callbacks in total. `ckprompt.Command(suite)` creates
only operations whose callbacks are present; discovery, validation, and smoke
testing can be installed independently. A composed suite can enable both
additional operations:
inspection; and native requirements discovery. Concrete request validation,
prepared-request preview, and smoke testing are separate capabilities, added
with `ckprompt.WithRequestValidation`, `ckprompt.WithRequestPreparation`, and
`ckprompt.WithSmokeTesting`. The suite has twelve independently optional
callbacks in total. `ckprompt.Command(suite)` creates only operations whose
callbacks are present; these capabilities can be installed independently. A
composed suite can enable the additional operations:
```go
suite := ckprompt.FromEngine(loadEngine)
suite = ckprompt.WithRequestValidation(suite, loadEngine, buildRequest)
suite = ckprompt.WithRequestPreparation(suite, loadEngine, nil)
suite = ckprompt.WithSmokeTesting(suite, loadEngine, nil)
suite.NewInput = newInput
suite.NewState = newState
@@ -300,7 +301,7 @@ 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.
The nine catalog and inspection callbacks and the two explicit additions are
The catalog and inspection callbacks and the explicit additions are
independently optional. For catalogs without named or requirements inspection,
narrow the suite before command capture:
@@ -313,7 +314,7 @@ definitions.InspectRequirements = nil
definitionCommand := ckprompt.Command(definitions)
```
Each selected inspection, requirements, validation, smoke, or catalog operation
Each selected inspection, requirements, validation, preparation, smoke, 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
@@ -326,6 +327,12 @@ and state. `FromEngine` uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`; validation must be opted into separately
and uses `Engine.ValidateRequest`.
`ckprompt.WithRequestPreparation` adds a separate callback backed by
`Engine.Prepare`. Its optional builder receives the seeded request and returns
the complete request to prepare. The resulting native report can contain
rendered application content. See the [CLI reference](../cli.md#promptkit-prepared-request-preview)
for operator behavior.
Application-owned commands can use `ckprompt.NewExecutionFlags`,
`ckprompt.NewResourceFlags`, and `ckprompt.NewPromptInputFlags` to bind the
same canonical request flags into their own input types. Each collection exposes

8
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# Shared reporting and PromptKit v0.20.0 implementation plan
Status: implementation in progress; Stages 1–10 complete.
Status: implementation in progress; Stages 1–11 complete.
## Scope, authority, and execution
@@ -398,6 +398,12 @@ forwarding, JSON object parsing, and builder replacement at the boundary.
## Stage 11: Ordered literal/file inputs and concrete preview
**Complete.** Text and file inputs follow command-line occurrence order, and
prepared-request preview is independently installable. The root, ckconfig, and
ckprompt workspace suites passed with Go 1.27.0; focused tests cover request
forwarding, native results and errors, builder replacement, and no model calls.
Scoped aliases are verified with their installation in Stage 13.
Use `OccurrenceFlag` for named text/file assignments. Split at the first `=`,
preserve literal empty text, construct native `Inline` or `File` references, and
assign into the same `PromptInputs.Inputs` map as occurrences are replayed.