101 Commits

Author SHA1 Message Date
857c0bae20 Retire completed roadmaps and preserve future work 2026-11-20 15:16:33 +00:00
f5573f7c8f Verify the complete native CLI cutover and record roadmap completion 2026-11-20 05:17:05 +00:00
bd7136ceeb Retire the legacy CLI and document native operator workflows 2026-11-20 05:08:40 +00:00
10387d4aea Track entrypoint identity and status tests alongside the binary ignore 2026-11-20 04:55:54 +00:00
7b570ed49d Wire process identity cancellation and shared HTTP server lifecycle 2026-11-20 04:55:27 +00:00
41dc1f5517 Add independent native run report delivery 2026-11-20 04:48:04 +00:00
6f39bca841 Implement positional prompt execution with native reporting and outcomes 2026-11-20 04:42:59 +00:00
f9b5121432 Expose native PromptKit discovery preparation and smoke testing 2026-11-20 04:37:18 +00:00
f2f807e87b Expose native configuration scopes and independent comparisons 2026-11-20 04:32:01 +00:00
733540f936 Adopt native configuration discovery and a single PromptKit entry file 2026-11-20 04:26:17 +00:00
adbe62a1e9 Settle native discovery and single-file PromptKit configuration 2026-11-20 04:15:49 +00:00
f88c679a06 Keep configuration commands native and refine discovery direction 2026-11-20 04:07:40 +00:00
9e5cc60d09 Plan native ConfigKit discovery conventions 2026-11-20 03:56:11 +00:00
d903a1aa4e Adopt ConfigKit native override conflict behavior 2026-11-20 03:47:30 +00:00
26ac62fbb7 Establish native CommandKit command composition 2026-11-20 03:35:49 +00:00
83d33777e7 Clarify verbosity and collection discovery for migration handoff 2026-11-20 03:28:54 +00:00
69d2ba7038 Allow native format selection for separate reports 2026-11-20 03:14:07 +00:00
fbe7dd56e3 Use stdout redirection for main generation output 2026-11-20 02:16:44 +00:00
99b0ebfc03 Plan the CommandKit adoption sprint 2026-11-20 01:07:52 +00:00
bcb1a76e34 Record native operator interface ownership and align documentation 2026-11-20 00:49:27 +00:00
6ed4ac624a Clarify configuration authority and native inspection boundaries 2026-11-20 00:32:12 +00:00
c7b9c30c43 Add CommandKit adoption roadmap 2026-11-19 18:53:19 +00:00
5f32a4f2ad Settle application commands and prefer native convenience aliases 2026-11-19 18:20:17 +00:00
8078c6ecc7 Align Narratio requirements with native CommandKit reports 2026-11-19 18:16:28 +00:00
66a0954b52 Settle native configuration and namespace conventions 2026-11-19 18:07:53 +00:00
5eeb09d1ec Replace render with native prepared request preview in migration plan 2026-11-19 18:02:26 +00:00
f31dec61ef Settle output destination and native verbosity conventions 2026-11-19 17:54:57 +00:00
293374d7a7 Record native result and report file decisions 2026-11-19 16:20:45 +00:00
b3a0a73416 Record generation output and subprocess requirements 2026-11-19 16:11:00 +00:00
3f5e441756 Include comparison smoke tests and completion in migration scope 2026-11-19 16:01:20 +00:00
23108bd2f0 Record CommandKit migration direction and open decisions 2026-11-19 15:56:29 +00:00
d97e2b8e30 Remove completed PromptKit planning documents 2026-11-19 15:21:14 +00:00
3105f4d62f Prevent HTTP artifact limit overflow 2026-11-19 15:19:39 +00:00
6562d63a02 Write framework explanations in one pass 2026-11-19 15:18:26 +00:00
dd1915735f Clarify precedence for discovered collections 2026-11-19 15:17:46 +00:00
a2f3588639 Link the Go Text patent notice 2026-11-19 15:17:23 +00:00
3f481ea432 Clarify source-relative message paths 2026-11-19 15:17:02 +00:00
ac858be2a2 Bound the HTTP timeout regression tests 2026-11-19 15:16:33 +00:00
cf50650e55 Record PromptKit algorithm audit findings 2026-11-19 15:13:00 +00:00
7afe6ba333 Record collection discovery integration finding 2026-11-19 15:01:37 +00:00
16197ae9dd Record PromptKit adoption review findings 2026-11-19 14:54:28 +00:00
c5e54edaa5 Adopt PromptKit timeout fix and complete verification 2026-11-19 14:39:10 +00:00
78bcf86619 Remove obsolete dependency checksums 2026-11-18 19:33:58 +00:00
5d372dd37d Clarify runtime dependencies and attribution format 2026-11-18 19:33:16 +00:00
9bd1629a9e Correct timeout and dependency license notices 2026-11-18 19:32:26 +00:00
50c65adac4 Update documentation for PromptKit adoption 2026-11-18 19:25:54 +00:00
a2205db152 Demonstrate independent collection discovery 2026-11-18 19:20:55 +00:00
27db6b6f47 Migrate maintained PromptKit definitions and fixtures 2026-11-18 19:19:24 +00:00
f858d57322 Refactor the single-run HTTP contract 2026-11-18 19:12:07 +00:00
de7c866662 Adapt inspection to native PromptKit records 2026-11-18 19:08:41 +00:00
77f168c660 Migrate CLI execution and terminal reports 2026-11-18 19:04:15 +00:00
e7a8b0db04 Unify PromptKit and ConfigKit source wiring 2026-11-18 19:01:17 +00:00
ae5344a77d Plan the PromptKit adoption sprint 2026-11-18 18:52:40 +00:00
247b67312e Clarify optional collection discovery globs 2026-11-18 18:46:12 +00:00
ca7c7faf5c Limit inspection work during PromptKit adoption 2026-11-18 18:43:01 +00:00
a0134ea49a Document collection discovery in the PromptKit adoption roadmap 2026-11-18 18:39:10 +00:00
95a94249f1 Record the HTTP API cutover decision 2026-11-18 15:11:58 +00:00
87d7240f31 Document the PromptKit upgrade roadmap 2026-11-18 15:08:38 +00:00
1b1d967fc7 Remove completed ConfigKit planning documents 2026-11-18 14:31:37 +00:00
932fd6da25 Clarify source selector clearing behavior 2026-11-18 00:29:33 +00:00
65bd2da51a Record ConfigKit review finding 2026-11-17 23:51:33 +00:00
eec4fa2d91 Complete ConfigKit adoption validation 2026-11-17 22:18:13 +00:00
2c3d8e4c8b Document native application configuration adoption 2026-11-17 22:15:10 +00:00
79dfe0a3ef Update integration fixtures and collection examples 2026-11-17 22:12:10 +00:00
03b479b4d7 Test native application configuration behavior 2026-11-17 22:06:58 +00:00
5c780a4cc0 Separate application and framework configuration types 2026-11-17 22:03:08 +00:00
d79e23739f Use native ConfigKit application loading 2026-11-17 22:00:43 +00:00
49461b18e4 Select ConfigKit and Go toolchain versions 2026-11-17 21:58:07 +00:00
222f4056e6 Plan native ConfigKit migration 2026-11-17 20:40:57 +00:00
a5d8394313 Plan interim ConfigKit upgrade 2026-11-17 20:27:12 +00:00
ba24b7a879 Adopt updated standard repository policies 2026-11-17 20:09:23 +00:00
723fee9c46 Record ConfigKit configuration ownership 2026-10-04 18:58:51 +00:00
0cd95f6e8e Request prompt requirement inspection for Narratio 2026-10-04 17:15:59 +00:00
c233d03371 Advertise framework inspection commands in usage 2026-10-04 14:31:17 +00:00
907fc51236 Correct composed configuration example description 2026-10-04 14:26:46 +00:00
cd0811a49e Clarify definition inspection loading 2026-10-04 14:25:38 +00:00
1c8494ec20 Record PromptKit adoption review findings 2026-10-04 13:57:36 +00:00
58cb02f973 Complete PromptKit adoption audit 2026-10-04 13:17:16 +00:00
beaaea2f1a Align PromptKit architecture documentation 2026-10-04 13:11:48 +00:00
b913ef0d07 Document PromptKit source migration 2026-10-04 13:04:02 +00:00
411a67b241 Explain framework configuration paths safely 2026-10-04 12:46:12 +00:00
2ba2ce1b91 Add captured framework configuration inspection 2026-10-04 12:37:02 +00:00
c2e2b74f83 Protect PromptKit source and definition semantics 2026-10-04 12:30:38 +00:00
9ea9d0706d Migrate HTTP and report fixtures to PromptKit sources 2026-10-04 12:20:43 +00:00
5c302f18ac Migrate CLI execution tests to native definitions 2026-10-04 12:15:10 +00:00
54c8e9011e Migrate CLI tests to native PromptKit sources 2026-10-04 12:04:14 +00:00
2027b80311 Migrate maintained PromptKit definitions and examples 2026-10-04 11:41:00 +00:00
0df2aad3a8 Wire native PromptKit sources into CLI commands 2026-10-04 11:36:00 +00:00
0d5ecfa842 Replace legacy framework config with source selectors 2026-10-04 11:26:40 +00:00
c8e2b972f3 Upgrade PromptKit and catalog modules 2026-10-04 11:15:34 +00:00
b1bb55a9a0 Plan PromptKit configuration upgrade 2026-10-04 00:44:47 +00:00
82b0f231b6 Confirm PromptKit adoption decisions 2026-10-04 00:16:24 +00:00
15e7c1aed9 Plan PromptKit configuration adoption 2026-10-03 18:08:09 +00:00
bb5006517b Record ConfigKit adoption review finding 2026-10-03 17:52:18 +00:00
bcf2ddf246 Complete ConfigKit inheritance implementation handoff 2026-10-03 17:46:56 +00:00
ddcba9c639 Document backend configuration inheritance 2026-10-03 17:43:58 +00:00
70f7e96d02 Test CLI inheritance inspection and use 2026-10-03 17:40:35 +00:00
ea964707f7 Test inherited configuration resolution 2026-10-03 17:35:55 +00:00
bbb473a3d9 Adopt ConfigKit v0.5.0 inheritance 2026-10-03 17:33:35 +00:00
e1ce526114 Plan ConfigKit inheritance implementation 2026-10-03 17:26:28 +00:00
8b6c12f912 Plan ConfigKit inheritance adoption 2026-10-03 17:16:02 +00:00
133 changed files with 4862 additions and 8168 deletions

2
.gitignore vendored
View File

@@ -29,7 +29,7 @@ go.work.sum
.env .env
# Ignore local test directory and complied binary # Ignore local test directory and complied binary
scriptorium /scriptorium
local-test/ local-test/
# ---> VisualStudio # ---> VisualStudio

View File

@@ -3,12 +3,15 @@ when:
steps: steps:
- name: build-release-assets - name: build-release-assets
image: golang:1.25 image: golang:1.27.4
commands: commands:
- | - |
set -eu set -eu
export GOTOOLCHAIN=local
version="$CI_COMMIT_TAG" version="$CI_COMMIT_TAG"
revision="$CI_COMMIT_SHA"
dist="dist" dist="dist"
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium" pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
notes="docs/releases/$version.md" notes="docs/releases/$version.md"
@@ -29,7 +32,7 @@ steps:
output="$dist/scriptorium-$version-$goos-$goarch$suffix" output="$dist/scriptorium-$version-$goos-$goarch$suffix"
CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \ CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
go build -trimpath -ldflags "-s -w" \ go build -trimpath -ldflags "-s -w -X main.version=$version -X main.revision=$revision" \
-o "$output" "$pkg" -o "$output" "$pkg"
} }

View File

@@ -5,8 +5,11 @@ an HTTP service. It prepares prompt requests, runs them against
OpenAI-compatible model endpoints, and returns generated output with validation OpenAI-compatible model endpoints, and returns generated output with validation
metadata. metadata.
CommandKit supplies native configuration, resource discovery, preview, reporting,
and completion interfaces alongside application generation and HTTP startup.
The application uses The application uses
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/) [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/)
for prompt, profile, schema, preparation, generation, and validation behavior. for prompt, profile, schema, preparation, generation, and validation behavior.
Scriptorium owns executable configuration, CLI and HTTP mapping, process Scriptorium owns executable configuration, CLI and HTTP mapping, process
behavior, output presentation, and HTTP artifact-containment policy. behavior, output presentation, and HTTP artifact-containment policy.
@@ -16,11 +19,10 @@ behavior, output presentation, and HTTP artifact-containment policy.
From the repository root: From the repository root:
```bash ```bash
go run ./cmd/scriptorium render \ go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
--config ./examples/config.yml \ --config ./examples/config.yml \
--prompt generic.markdown_summary \ --input-file transcript=./examples/fixtures/transcript.md \
--input transcript=./examples/fixtures/transcript.md \ --input-file glossary=./examples/fixtures/glossary.yml \
--input glossary=./examples/fixtures/glossary.yml \
--format json --format json
``` ```
@@ -33,20 +35,26 @@ a model. For complete invocation and output behavior, see the
- [CLI reference](docs/cli.md) - [CLI reference](docs/cli.md)
- [Configuration reference](docs/config.md) - [Configuration reference](docs/config.md)
- [Application configuration inspection](docs/cli.md#application-configuration-inspection) - [Application configuration inspection](docs/cli.md#application-configuration-inspection)
- [Framework configuration inspection](docs/cli.md#framework-configuration-inspection)
- [HTTP API reference](docs/api.md) - [HTTP API reference](docs/api.md)
- [Operations guide](docs/operations.md) - [Operations guide](docs/operations.md)
- [Consumer integration overview](docs/consumers/api.md) - [Consumer integration overview](docs/consumers/api.md)
- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md) - [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
- [Native CLI migration](docs/consumers/upgrading-cli.md)
- [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md)
- [Subprocess integration](docs/integrations/subprocess.md) - [Subprocess integration](docs/integrations/subprocess.md)
- [Architecture policy](docs/policy/architecture.md) - [Architecture policy](docs/policy/architecture.md)
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) - [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) - [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
## Examples ## Examples
- [Minimal configuration](examples/config.yml) and - [Minimal configuration](examples/config.yml) and
[complete configuration](examples/config.full.yml), plus a [complete configuration](examples/config.full.yml), plus a
[composed import/overlay example](examples/config.composed.yml) [composed import/overlay example](examples/config.composed.yml), a
[collection composition example](examples/config.collections.yml), a
[collection checkout discovery example](examples/config.discovery.yml), and a
[backend inheritance example](examples/config.inheritance.yml)
- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), - [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/),
[schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/) [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
- [Render script](examples/render-markdown-summary.sh) - [Render script](examples/render-markdown-summary.sh)

View File

@@ -1,11 +1,29 @@
package main package main
import ( import (
"context"
"io"
"os" "os"
"os/signal"
"syscall"
"gitea.maximumdirect.net/eric/scriptorium/internal/adapter/cli" "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/cli"
"go.maximumdirect.net/commandkit"
) )
var version = "dev"
var revision = ""
func main() { func main() {
os.Exit(cli.Run(os.Args[1:], os.Stdout, os.Stderr)) os.Exit(runWithSignals(os.Args[1:], os.Stdout, os.Stderr))
}
func runWithSignals(args []string, stdout, stderr io.Writer) int {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
return run(ctx, args, stdout, stderr)
}
func run(ctx context.Context, args []string, stdout, stderr io.Writer) int {
return cli.Execute(ctx, commandkit.Identity{Name: "scriptorium", Version: version, Revision: revision}, args, stdout, stderr).Status
} }

View File

@@ -0,0 +1,113 @@
package main
import (
"bytes"
"context"
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"path/filepath"
"runtime"
"slices"
"strings"
"syscall"
"testing"
"time"
)
func TestProcessIdentityAndNativeStatus(t *testing.T) {
var output, diagnostics bytes.Buffer
if status := run(context.Background(), []string{"version"}, &output, &diagnostics); status != 0 || !strings.Contains(output.String(), version) {
t.Fatalf("version status=%d output=%q diagnostics=%q", status, output.String(), diagnostics.String())
}
output.Reset()
diagnostics.Reset()
if status := run(context.Background(), []string{"run"}, &output, &diagnostics); status != 2 {
t.Fatalf("native usage status=%d diagnostics=%q", status, diagnostics.String())
}
ctx, cancel := context.WithCancel(context.Background())
cancel()
if status := run(ctx, []string{"run", "any"}, &output, &diagnostics); status != 1 {
t.Fatalf("canceled status=%d diagnostics=%q", status, diagnostics.String())
}
}
func TestProcessSignalCancellation(t *testing.T) {
if os.Getenv("SCRIPTORIUM_SIGNAL_CHILD") == "1" {
separator := slices.Index(os.Args, "--")
if separator < 0 {
os.Exit(2)
}
os.Exit(runWithSignals(os.Args[separator+1:], os.Stdout, os.Stderr))
}
if runtime.GOOS == "windows" {
t.Skip("process interrupt/SIGTERM integration is Unix-specific")
}
for _, signal := range []os.Signal{os.Interrupt, syscall.SIGTERM} {
t.Run(signal.String(), func(t *testing.T) {
started, stopped, release := make(chan struct{}), make(chan struct{}), make(chan struct{})
provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = io.Copy(io.Discard, r.Body)
close(started)
select {
case <-r.Context().Done():
close(stopped)
case <-release:
}
}))
defer provider.Close()
defer close(release)
root := t.TempDir()
framework := filepath.Join(root, "framework.yml")
content := fmt.Sprintf("profiles:\n - id: local\n endpoint: %q\n model: controlled\nprompts:\n - id: selected\n default_profile: local\n messages:\n - role: user\n content: Signal test\n output:\n format: text\n validation_mode: none\n", provider.URL+"/v1")
if err := os.WriteFile(framework, []byte(content), 0600); err != nil {
t.Fatal(err)
}
config := filepath.Join(root, "app.yml")
if err := os.WriteFile(config, []byte(fmt.Sprintf("promptkit:\n configuration: %q\ntransient_retries: 0\n", framework)), 0600); err != nil {
t.Fatal(err)
}
executable, err := os.Executable()
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
command := exec.CommandContext(ctx, executable, "-test.run=^TestProcessSignalCancellation$", "--", "run", "selected", "--config="+config, "--timeout-seconds=0")
command.Env = append(os.Environ(), "SCRIPTORIUM_SIGNAL_CHILD=1")
var output, diagnostics bytes.Buffer
command.Stdout, command.Stderr = &output, &diagnostics
if err := command.Start(); err != nil {
t.Fatal(err)
}
defer func() {
cancel()
if command.ProcessState == nil {
_ = command.Wait()
}
}()
select {
case <-started:
case <-ctx.Done():
t.Fatal("child did not reach controlled provider")
}
if err := command.Process.Signal(signal); err != nil {
t.Fatal(err)
}
err = command.Wait()
var exit *exec.ExitError
if !errors.As(err, &exit) || exit.ExitCode() != 1 || output.Len() != 0 || diagnostics.Len() == 0 {
t.Fatalf("signal outcome: %v stdout=%q stderr=%q", err, output.String(), diagnostics.String())
}
select {
case <-stopped:
case <-time.After(5 * time.Second):
t.Fatal("signal did not cancel provider request")
}
})
}
}

View File

@@ -0,0 +1,71 @@
# ADR 0005: Adopt ConfigKit's Configuration Boundary
## Status
Accepted.
## Date
2026-10-04.
## Context
Scriptorium uses ConfigKit to resolve application configuration. Adopting its
standard semantics across the application suite gives operators a consistent
configuration model and keeps configuration processing under a single owner.
The application supplies its schema and domain rules through ConfigKit's public
definition API. ConfigKit returns the resolved configuration and inspection
information for use by Scriptorium.
## Decision
ConfigKit owns configuration loading and resolution semantics, including
decoding, imports, composition, precedence, overlays, inheritance, and
inspection. Scriptorium adopts those semantics through ConfigKit's supported
public APIs.
Scriptorium owns its application schema, defaults, value normalization, and
domain validation. It supplies these rules through ConfigKit's definition
callbacks so they participate in the library's resolution and validation flow.
Scriptorium consumes the final, fully resolved configuration returned by that
flow.
Scriptorium also owns application-facing choices: default discovery locations,
source and option selection, and the mapping of CLI inputs to ConfigKit options
and overrides. ConfigKit determines how the selected inputs are processed.
Scriptorium may expose ConfigKit's inspection APIs through operator interfaces
when demand warrants them. ConfigKit owns the underlying inspection semantics;
Scriptorium owns their application-facing presentation.
Resolution establishes configuration values. Runtime credentials, artifacts,
and downstream resources retain their respective preparation and execution
lifecycle. Promptkit owns its framework schema and domain rules when using
ConfigKit, consistent with [ADR 0004](0004-definition-boundary.md).
## Alternatives Considered
### Application-Owned Configuration Processing
Scriptorium could implement loading and composition locally. This offers
application-specific flexibility, but duplicates ConfigKit's responsibilities
and creates recurring maintenance and semantic drift across applications.
### ConfigKit-Owned Application Choices
Scriptorium could delegate discovery conventions and domain defaults to the
library. This reduces local decisions, but places application-specific behavior
in a shared configuration mechanism. The selected boundary keeps those choices
with the application while using the library's processing semantics.
## Consequences
Configuration changes follow the ownership boundary: processing capabilities
belong in ConfigKit, and application rules use its supported extension points.
ConfigKit upgrades are evaluated for their effects on Scriptorium's selected
inputs, domain callbacks, and operator interfaces.
The [architecture policy](../policy/architecture.md) owns current architectural
constraints, and the [configuration contract](../config.md) owns observable
application behavior. This ADR records the rationale for the ownership boundary.

View File

@@ -0,0 +1,54 @@
# ADR 0006: Adopt CommandKit's Native Operator Interfaces
## Status
Accepted. Complements [ADR 0004](0004-definition-boundary.md) and
[ADR 0005](0005-configkit-boundary.md). Both remain accepted and are not
superseded.
## Date
2026-11-19.
## Context
Scriptorium is adopting CommandKit's native operator interfaces within the
PromptKit and ConfigKit boundaries established by ADRs 0004 and 0005.
## Decision
Scriptorium adopts CommandKit's native operator interfaces.
ConfigKit owns configuration policy and everything in the configuration
lifecycle before the final, fully resolved configuration handoff. Application
schema and domain callbacks operate through ConfigKit's supported extension
points within that lifecycle.
PromptKit owns prompt definitions, preparation, execution, validation, and
inspection semantics. Its configuration is resolved through ConfigKit, with
PromptKit supplying its domain schema and rules through ConfigKit's supported
extension points.
Scriptorium owns the domain. After the handoff, it interprets the resolved
configuration values and uses them to perform useful work that satisfies the
user's request. It does not revise what constitutes effective configuration.
It supplies requests through PromptKit's supported APIs and uses the returned
results without redefining their meaning.
CommandKit's `ckconfig` and `ckprompt` integrations expose upstream ConfigKit
and PromptKit features. Scriptorium neutrally makes those features available
through the native interfaces, preserving upstream semantics.
## Alternatives Considered
Retaining custom configuration and prompt inspection would duplicate upstream
behavior and create another owner for its semantics. Use the native integrations
instead.
## Consequences
Standard inspection exposes the upstream result without constructing a different
effective document, reconciling separate explanation trees, or reinterpreting
upstream paths. The completed
[adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md)
remains in Git history.

View File

@@ -43,7 +43,6 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| Field | Required | Meaning | | Field | Required | Meaning |
| --- | --- | --- | | --- | --- | --- |
| `prompt_id` | yes | Non-blank prompt ID. | | `prompt_id` | yes | Non-blank prompt ID. |
| `prompt_version` | no | Prompt version filter. |
| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. | | `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
| `session_id` | no | Optional direct, non-secret session identifier. | | `session_id` | no | Optional direct, non-secret session identifier. |
| `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. | | `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
@@ -52,7 +51,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| `include_raw_output` | no | Include `raw_model_output` when true. | | `include_raw_output` | no | Include `raw_model_output` when true. |
| `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. | | `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. |
| `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. | | `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. |
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second limit for engine execution. Omitted, `null`, or `0` adds no deadline; positive values shorten the caller context deadline. | | `run_timeout_seconds` | no | Optional signed 64-bit whole-second engine operation budget. Omitted, `null`, or `0` adds no deadline. |
An input reference has a required `type` of `file` or `inline`. A `file` An input reference has a required `type` of `file` or `inline`. A `file`
reference requires `uri`; an `inline` reference requires `body`. reference requires `uri`; an `inline` reference requires `body`.
@@ -68,16 +67,17 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and `reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
framework credential semantics are defined by the framework credential semantics are defined by the
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). [PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
Explicit zero values for the numeric fields are overrides; zero Explicit zero values for the numeric fields are overrides; zero
`timeout_seconds` disables the per-attempt generation deadline only, retaining the `timeout_seconds` disables the per-attempt generation deadline only, retaining the
request context and configured transport cap. The timeout layers are defined in request context and configured transport cap. The timeout layers are defined in
the [Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation). the [PromptKit v0.23.3 outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
Each built-in transient retry gets a fresh generation timeout; the caller's Each built-in transient retry gets a fresh generation timeout; the caller's
request context remains the outer cancellation boundary. request context remains the outer cancellation boundary.
Raw API-key values are not accepted. `api_key` and any other unknown model Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
field cause `400 invalid_json`. and any other unknown field cause `400 invalid_json`. Prompt and profile IDs
are passed unchanged, including qualified collection IDs.
`model.reasoning_effort` is an optional JSON string with three states: omission `model.reasoning_effort` is an optional JSON string with three states: omission
inherits the selected profile, a non-empty string replaces its value, and an inherits the selected profile, a non-empty string replaces its value, and an
@@ -116,14 +116,14 @@ validation contract. The response contains:
optional `uri`; optional `uri`;
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus - `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
optional `errors` and `schema_path`; optional `errors` and `schema_path`;
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage, - `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
timing, validation, and repair-attempt metadata; and model parameters, input hashes, usage, and timing; and
- optional `raw_model_output` when requested. - optional `raw_model_output` when requested.
- optional `execution` when requested and a terminal observation exists. - optional `execution` when requested and a terminal observation exists.
`metadata.model_params` has `endpoint`, `model`, `temperature`, `metadata.model_params` has `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional `max_tokens`, `top_p`, and `timeout_seconds`, plus optional
`backend_id`, `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`. `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
`metadata.usage` always includes `prompt_tokens`, `completion_tokens`, `metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable `total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
cache usage is reported as zero. cache usage is reported as zero.
@@ -132,10 +132,11 @@ When Promptkit resolves a direct or definition-rendered session ID,
`metadata.session_id` contains that effective result value. It is omitted when `metadata.session_id` contains that effective result value. It is omitted when
no effective session ID exists. no effective session ID exists.
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report `metadata.selected_backend_id` is omitted for an endpoint-only profile;
the corresponding Promptkit result fields independently when present. Both are Scriptorium does not infer backend identity from an endpoint. The redundant
omitted for an endpoint-only profile; Scriptorium does not infer backend `prompt_version`, `model_name`, `endpoint`, `validation_mode`,
identity from an endpoint. `validation_status`, `repair_attempts_used`, and `model_params.backend_id`
metadata members are not returned: use `model_params` and `validation`.
A validation failure has `validation.status: "failed"`, `is_valid: false`, A validation failure has `validation.status: "failed"`, `is_valid: false`,
and any available diagnostic errors, while still returning the artifact and and any available diagnostic errors, while still returning the artifact and
@@ -150,7 +151,7 @@ call was dispatched; if there is no terminal event, `execution` is omitted.
| Field | Meaning | | Field | Meaning |
| --- | --- | | --- | --- |
| `run_id`, `prompt_id`, `prompt_version`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. | | `run_id`, `prompt_id`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
| `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. | | `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. |
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. | | `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
| `status_code` | Provider status, omitted when unavailable. | | `status_code` | Provider status, omitted when unavailable. |
@@ -201,7 +202,7 @@ exceed it, the response is the compact `413 response_too_large` error without
| `400` | `prompt_render_failed` | Prompt template rendering failed. | | `400` | `prompt_render_failed` | Prompt template rendering failed. |
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. | | `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
| `404` | `not_found` | Route does not exist. | | `404` | `not_found` | Route does not exist. |
| `404` | `prompt_not_found` | Prompt ID or version does not exist. | | `404` | `prompt_not_found` | Prompt ID does not exist. |
| `404` | `profile_not_found` | Profile ID does not exist. | | `404` | `profile_not_found` | Profile ID does not exist. |
| `405` | `method_not_allowed` | The route does not accept the method. | | `405` | `method_not_allowed` | The route does not accept the method. |
| `408` | `request_canceled` | The caller context was canceled during a failed run. | | `408` | `request_canceled` | The caller context was canceled during a failed run. |
@@ -212,10 +213,11 @@ exceed it, the response is the compact `413 response_too_large` error without
| `500` | `internal_error` | Unclassified server failure. | | `500` | `internal_error` | Unclassified server failure. |
| `502` | `llm_failed` | Outbound model request failed. | | `502` | `llm_failed` | Outbound model request failed. |
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. | | `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. |
| `504` | `deadline_exceeded` | The execution context's deadline expired during a failed run. | | `504` | `deadline_exceeded` | PromptKit reports an operation timeout, or the parent deadline expired and the failed run wraps that deadline. |
These context outcomes require the execution context to have ended. A provider An operation timeout is checked before parent cancellation; a failed run
attempt timeout while it remains live retains `502 llm_failed`. A successful wrapping cancellation returns `408` when the parent is canceled. A provider
attempt timeout while the parent remains live retains `502 llm_failed`. A successful
run remains successful even if cancellation races with response formatting; run remains successful even if cancellation races with response formatting;
delivery after a client disconnect cannot be guaranteed. delivery after a client disconnect cannot be guaranteed.

View File

@@ -1,304 +1,186 @@
# CLI Reference # CLI Reference
This is the canonical contract for invoking Scriptorium. Configuration discovery, Scriptorium uses CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0.
precedence, application source locations, and server settings are defined in the This document owns application invocation and delivery behavior. The pinned
[configuration reference](config.md). The [HTTP API reference](api.md) owns [upstream CLI contract][native-cli] owns standard family grammar and reports.
service request and response behavior. [Configuration](config.md) owns discovery, settings, and source composition;
the [HTTP API](api.md) owns the service contract.
## Shortest Useful Command Existing callers should read the [CLI migration guide](consumers/upgrading-cli.md).
```bash
go run ./cmd/scriptorium render \
--config ./examples/config.yml \
--prompt generic.markdown_summary \
--input transcript=./examples/fixtures/transcript.md \
--input glossary=./examples/fixtures/glossary.yml
```
`render` prepares a request without calling an LLM.
## Commands ## Commands
- `scriptorium run`: prepare a prompt, call the configured LLM, and write the
generated artifact.
- `scriptorium render`: prepare a prompt and write prepared-run output.
- `scriptorium serve`: start the HTTP server.
- `scriptorium inspect prompt`: inspect one prompt definition without model execution.
- `scriptorium inspect profile`: inspect one effective profile without model execution.
- `scriptorium config validate`: validate application configuration without building an engine.
- `scriptorium config show`: show the resolved application configuration.
- `scriptorium config sources`: show the ordered configuration sources.
- `scriptorium config explain`: explain one effective or historical configuration path.
All commands accept `--config <path>` and `--config-overlay <name>` and reject
positional arguments. `--config-overlay` selects one application configuration
overlay; it is separate from `--profile`, which selects a Promptkit execution
profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
for name, root, and no-base behavior. `run`,
`render`, `serve`, and `inspect prompt` require an effective `prompt_dir`;
`inspect profile` does not. Supply the directory through the configuration
contract or a supported `--prompt-dir` flag. Explicit application flags,
including empty values, override file settings. Configuration load diagnostics
go to stderr and exit with status 1; successful load warnings are printed once
before command work.
## `scriptorium run`
```text
scriptorium run [flags]
```
Required flags:
| Flag | Meaning |
| --- | --- |
| `--prompt <id>` | Prompt ID to execute. |
Optional flags:
| Flag | Meaning |
| --- | --- |
| `--config <path>` | Application configuration file. |
| `--config-overlay <name>` | Selected application configuration overlay. |
| `--prompt-dir <dir>` | Prompt-definition directory override. |
| `--profile-dir <dir>` | Custom profile-directory override. |
| `--schema-dir <dir>` | Schema base-directory override. |
| `--prompt-version <version>` | Optional prompt-definition version selector. |
| `--profile <id>` | Execution-profile override. |
| `--session-id <id>` | Optional direct session identifier. |
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
| `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
| `--out <path>` | Write generated content to this file instead of stdout. |
| `--execution-report <path>` | Write an opt-in terminal execution report as newline-terminated JSON to a separate file. |
| `--llm-base-url <url>` | Runtime endpoint override. |
| `--model <name>` | Runtime model override. |
| `--api-key-env <name>` | Runtime API-key environment-variable name override. |
| `--temperature <float>` | Runtime temperature override. |
| `--max-tokens <int>` | Runtime maximum-token override. |
| `--top-p <float>` | Runtime top-p override. |
| `--reasoning-effort <value>` | Runtime reasoning-effort override. |
| `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
| `--run-timeout <duration>` | Optional whole-run engine deadline using Go duration syntax; zero or omission adds no deadline, negative values are invalid. |
| `--transient-retries <integer>` | Nonnegative additional transient attempt count for this request; `0` disables additional attempts. |
Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
`--profile`.
Omitted numeric runtime flags preserve the selected effective value; explicit
zero values override it. `--timeout 0s` disables the per-attempt generation deadline
only; the caller context and configured transport cap remain active. CLI
durations are converted to whole seconds by truncation toward zero, so any
duration whose absolute value is below one second becomes an explicit
zero-second override. The timeout layers are defined in the
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
With the built-in client, each transient retry gets a fresh generation timeout;
this flag does not limit the complete run.
`--run-timeout` keeps subsecond precision and starts immediately before engine
execution. It bounds preparation, capacity waits, retry waits, generation, and
repairs where they honor context. Parsing, engine construction, and output
writes are outside that interval. A failed run whose execution context reaches
this deadline exits 1 with a safe deadline diagnostic; a completed invalid
output still exits 2. It does not promise immediate interruption of synchronous
work.
Omitting `--transient-retries` inherits the application setting or Promptkit's
current default of two additional attempts. The flag overrides only this
request; it does not alter the configured engine. Structural repair generations
have separate transient retry budgets.
There is no raw API-key flag. Use `--api-key-env`.
`--prompt-version` is passed directly to Promptkit. When it is omitted, the
selected prompt ID must have exactly one available version. `--input` is
optional at the CLI boundary: Promptkit decides whether the selected definition
requires declared inputs or template-referenced values.
`--session-id` supplies a direct, non-secret session identifier. A nonblank
value replaces a definition-rendered session ID; an omitted or blank value lets
the definition supply one. Promptkit trims direct values and limits them to 256
Unicode code points. Use stable, non-sensitive identifiers because effective
session IDs may appear in prepared output, run metadata, and provider-facing
requests.
`--reasoning-effort` is presence-aware: omitting it inherits the selected
profile value, a nonblank value replaces that value, and
`--reasoning-effort=` explicitly clears inherited reasoning. Promptkit treats
nonblank values as provider-specific opaque strings.
### Execution report file
`--execution-report` requires a nonempty path. It is available only for `run`;
`-` is an ordinary filename. Parent directories are not created. An existing
file is replaced through ordinary file writing, without rollback or an atomic
replacement guarantee. Generated content still goes to stdout or `--out`.
Equal output/report paths, including existing paths that refer to the same
file, are rejected before execution.
The file is written after engine execution when Promptkit supplies a terminal
event, including for a failed run or invalid generated output. A failure before
invocation leaves the report path untouched. If no terminal event is supplied,
Scriptorium leaves the path untouched and emits a diagnostic; an existing file
may therefore contain an older report. Artifact output is attempted first on a
successful run, and report writing is attempted even if artifact writing fails.
Any output or report write failure exits 1; already-written output is not
undone. Without a write failure, the actual run keeps its usual exit status.
The [HTTP API reference](api.md#execution-report) defines the shared report
fields and usage-presence semantics. The file contains that JSON object followed
by a newline.
The report excludes content, credentials, URLs, headers, and raw errors, but
its identifiers can still be sensitive. The caller owns file retention and
access.
## `scriptorium render`
```text
scriptorium render [flags]
```
`--prompt <id>` is required. The following optional flags are supported:
`--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, `--schema-dir`, `--prompt-version`, `--profile`,
`--input`, `--var`, `--out`, `--llm-base-url`,
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
`--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, and `--format text|json`. Their meanings match the corresponding
`run` flags; `--format` selects prepared-run output and otherwise uses
`defaults.render_format`.
The same deprecated aliases and numeric/timeout behavior as `run` apply.
The same session and reasoning inheritance, replacement, and clearing behavior
also applies.
`render` validates the retry override but does not generate model output or
include a retry field in prepared output.
`render` resolves profiles and schemas as part of preparation but
does not call an LLM.
## `scriptorium serve`
```text ```text
scriptorium run PROMPT_ID [flags]
scriptorium serve [flags] scriptorium serve [flags]
scriptorium config scopes
scriptorium config validate|show|sources|explain|diff [flags]
scriptorium promptkit list prompts|profiles|backends|namespaces|collections [flags]
scriptorium promptkit show prompt|profile|backend ID [flags]
scriptorium promptkit requirements show|validate PROMPT_ID [flags]
scriptorium promptkit show prepared PROMPT_ID [flags]
scriptorium promptkit test KIND [flags]
scriptorium help [COMMAND ...]
scriptorium version
scriptorium completion bash|zsh|fish
``` ```
Optional flags: Native help is also available with `--help`. Help, version, scope discovery,
and static completion do not load configuration or contact a provider.
Version/revision metadata is supplied by the build; ordinary builds identify
themselves as `dev` with no revision. Release build mechanics belong to the
[release procedure](release.md).
Commands that consume configuration accept `--config PATH` and `--overlay NAME`.
An explicitly empty config value remains explicit; overlay names follow
[ConfigKit selection](config.md#explicit-imports-and-selected-overlays).
There are no source/schema convenience flags or legacy command aliases.
Native shared `--format`, `--quiet`, `--verbose`, `--debug`, and progress
controls retain their upstream meanings. Diagnostics use stderr, not stdout.
Verbose exposes emitted Info and Warning messages without changing result bytes.
## Generation
`run` requires exactly one positional prompt ID. It has no duplicate prompt
flag or direct backend-selection flag; choose a profile for backend routing.
It uses these native bindings, with the preferred aliases below. Canonical
spellings prepend `llm-` (for example, `--llm-profile`).
| Preferred flags | Meaning |
| --- | --- |
| `--profile ID`, `--session-id ID` | Profile selection and optional non-secret session context. |
| `--var KEY=VALUE` | Repeatable caller-variable mappings. |
| `--input-text NAME=TEXT`, `--input NAME=TEXT` | Repeatable literal input mappings; `--llm-input` is also a literal-text alias. |
| `--input-file NAME=PATH` | Repeatable file references. |
| `--endpoint URL`, `--model NAME` | Native endpoint/model overrides. |
| `--temperature N`, `--max-tokens N`, `--top-p N` | Presence-aware numeric overrides, including zero. |
| `--timeout-seconds N` | Integer per-attempt generation timeout; zero disables that deadline, not caller cancellation or the transport cap. |
| `--reasoning-effort VALUE`, `--service-tier VALUE` | Native provider controls; an explicit empty reasoning value is preserved. |
| `--api-key-env NAME` | Credential environment-variable name, never raw key bytes. |
| `--extra-params JSON` | Native JSON-object provider parameters. |
| `--transient-retries N` | Request retry override; omission leaves the engine default. |
| `--prompt-namespace NAME`, `--profile-namespace NAME`, `--backend-namespace NAME` | Independent native namespace views. Qualified resource IDs remain exact; stored references are not rewritten. |
Mappings split at the first `=`; commas and subsequent equals signs are literal.
Repeat flags for multiple mappings. The last text/file occurrence for the same
input wins in command-line order. PromptKit validates selected definitions,
inputs, namespaces, provider settings, and credential requirements; Scriptorium
does not add an execution-readiness preflight or configurable default namespace.
Native string/pointer override semantics remain upstream-owned.
Application-owned generation controls:
| Flag | Meaning | | Flag | Meaning |
| --- | --- | | --- | --- |
| `--config <path>` | Application configuration file. | | `--run-timeout DURATION` | Go duration passed unchanged to PromptKit's operation budget. Positive values cover engine preparation/execution, including cooperative waits and repairs. Zero, omission, and negative values add no budget. Parsing, configuration/engine setup, and delivery are outside it. |
| `--config-overlay <name>` | Selected application configuration overlay. | | `--report PATH` | Additionally write the returned native result to a separate file. |
| `--addr <listen-address>` | HTTP listen-address override. | | `--report-format text\|yaml\|json` | Explicit separate-report format; omission leaves native automatic rendering selected. |
| `--prompt-dir <dir>` | Prompt-definition directory override. |
| `--profile-dir <dir>` | Custom profile-directory override. |
| `--schema-dir <dir>` | Schema base-directory override. |
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
| `--max-artifact-bytes <n>` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
| `--max-response-bytes <n>` | Maximum encoded HTTP response bytes; `0` disables the limit. |
`serve` accepts no runtime model override flags. HTTP request fields, response The operation budget is independent of the integer per-attempt timeout.
schemas, and error codes are defined in the [HTTP API reference](api.md). Earlier parent cancellation/deadlines still apply. Cancellation is cooperative;
synchronous work that ignores context cannot be forcibly interrupted.
## `scriptorium inspect prompt` ### Results And Separate Reports
```text The main report goes through the invocation reporter to stdout. Automatic/text
scriptorium inspect prompt --prompt ID [--prompt-version VERSION] output is exactly `Artifact.Body`, with no added newline, header, escaping, or
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH] summary. JSON/YAML output is the full native PromptKit `RunResult`, without a
``` Scriptorium envelope. In native structured serialization, artifact bytes use
the upstream representation (JSON base64), not an application text projection.
`--prompt` is required. Inspection uses normal configuration discovery and a Save main output with shell redirection or the subprocess stdout destination.
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`, There is no `--output` or `--out` flag. Omit `--quiet` when capturing the main
and writes to stdout unless `--out` is supplied. It loads and normalizes the result: native quiet suppresses it even when stdout is redirected.
selected definition but does not resolve a profile, load a schema, render a
template, reserve backend capacity, or call a model.
## `scriptorium inspect profile` `--report` renders the same result through CommandKit without the artifact-only
text template. Its format is independent of stdout's `--format` and the filename
extension. Omission passes an unset format to the upstream renderer; it currently
renders structured values as YAML in automatic/text mode. Choose an explicit
format when required rather than relying on that upstream default.
```text The requested file is written even in quiet mode. Omission creates no separate
scriptorium inspect profile --profile ID report. An explicitly empty path is a usage error before generation; `-` is an
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH] ordinary filename. New files use mode 0644 subject to umask, existing files use
``` normal OS replacement behavior, and parent directories are not created.
Render, write, and close failures are reported.
`--profile` is required; built-in profiles need no prompt directory. Inspection Only a returned result is eligible for delivery. A resultless failure leaves an
resolves profile inheritance and backend defaults, but never reads a credential existing report untouched; it does not synthesize an invocation-error result.
value, loads a prompt, reserves capacity, or calls a model. Unset provider Main delivery is attempted first, then the requested report even if main
controls are shown as zero values when Promptkit leaves them unspecified. delivery fails. Writes are nontransactional; bytes already written remain.
Callers own redirected paths, retention, and keeping main and report destinations
separate. A shell may truncate its redirected file before the process starts.
## Application configuration inspection ## Application Configuration Inspection
```text The native `config` family defaults to `app`; select `--scope promptkit` for
scriptorium config validate [flags] captured framework configuration or use native scope discovery/all-scope modes.
scriptorium config show [flags] `app` uses the actual completed ConfigKit result and does not construct an engine.
scriptorium config sources [flags]
scriptorium config explain --path JSON_POINTER [flags]
```
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, Native `--set POINTER=JSON` is enabled only for `app`. Records go directly to
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`, ConfigKit: duplicate and ancestor/descendant-overlapping paths are rejected,
`--max-artifact-bytes`, and `--max-response-bytes`. These are application not resolved by flag order. No application-specific configuration flags or
configuration selectors and overrides; request, credential, backend-editing, custom `--against-*` counterparts are installed.
output-format, and output-file flags are not accepted. Positional arguments
are rejected.
`validate` writes no success output; status 0 means the application configuration Native diff uses independent `--against-config`, `--against-overlay`, and
loaded and passed its own validation. It does not establish that a prompt supported `--against-set` selections. Omitted right-side values do not inherit
directory exists, credentials are present, or Promptkit can construct an the left side. See the [upstream contract][native-cli] for focused paths,
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources` metadata discovery, source IDs, findings, explanations, and detailed comparisons.
writes one newline-terminated JSON array of source records in load order. Each
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
overrides appear as synthetic sources. Defaults-only input without overrides
produces `[]` for `sources`.
`explain` requires an explicitly supplied `--path` in JSON Pointer syntax. ## Framework Configuration Inspection
The empty string selects the root; `/server/addr` selects a field; `~1` and
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
according to the containing mapping or sequence. Dotted paths, file paths,
and URL fragments are not accepted. ConfigKit writes a human-readable account
of the effective value and its chronological default, base, overlay, CLI,
and normalization history, including removed historical values. This is not a
JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths
exit 1 without successful explanation output.
Diagnostics and warnings go to stderr, never into successful stdout. Parse, The `promptkit` config scope loads application settings selected by `--config`
load, output, and diagnostic-write failures exit 1. Ordinary output writes may and `--overlay`, constructs an engine, and exposes its captured native view.
leave partial data on failure. The inspection output can contain paths, It does not accept temporary overrides; native capability checks also apply
identifiers, `api_key_env` reference names, and ordinary `extra_params` values, when an all-scope operation requests them.
including displaced historical values in explanations;
protect it accordingly. Raw API-key values are not read or emitted by these
commands.
## Input And Variable Syntax Framework effective/explanation views retain native classified-field redaction,
including history. Environment-reference names and ordinary values remain
visible. This is not arbitrary secret detection and does not redact all prompt,
prepared, application, or generated content. Protect reports accordingly.
`--input name=path` maps an input name to a local file; `--var name=value` ## Discovery, Preview, And Explicit Smoke Testing
maps a template variable to a string. Both flags can be repeated or contain
comma-separated mappings. Values may contain `=` after the first separator.
Empty names and values are rejected.
CLI inputs are file references. HTTP inline inputs are defined by the Inventories retain native defaults and `--namespace`/`--all-namespaces` filters.
[HTTP API reference](api.md). Named inspections expose native prompt messages and profile/backend values;
prepared preview exposes rendered content, not a summary projection.
## Output And Exit Behavior Requirements discovery works before input artifacts exist and without schema
loading, credential resolution, message rendering, or provider access. It still
loads configuration and captured message resources. Reports preserve exact names,
metadata, variable presence (including empty values), completeness, and issue
codes. Partial discovery may succeed with status zero; completeness is not
binding satisfaction or execution readiness. Concrete validation and preview
keep their native preparation-time prerequisites and make no generation call.
- `run` writes generated content to stdout, or to `--out` when supplied, and Smoke-test kinds are `reachability`, `authentication`, `text_inference`,
writes a concise summary to stderr. The summary includes `backend=<id>` when `structured_output`, or `all`, with native aliases as documented upstream.
Promptkit selected a backend; endpoint-only profiles omit it. These explicit commands may contact providers and incur cost. Their presence
- `render` writes prepared-run output to stdout, or to `--out` when supplied, does not add a startup/provider probe. Read the native findings: unsuccessful or
without a success summary. Text output includes `selected_backend_id` after unsupported checks are not automatically invocation failures.
`selected_profile_id` when Promptkit selected one; endpoint-only profiles
omit it.
- `serve` writes startup and server errors to stderr.
Exit statuses: ## Server And Statuses
`serve` accepts configuration selection and presence-aware HTTP controls:
`--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`,
and `--max-response-bytes`. It has no generation request controls. Values and
defaults belong to [configuration](config.md).
Interrupt/SIGTERM cancels the invocation context. The server closes its listener
and active connections; canceled shutdown returns operational status, with no
graceful-drain deadline or guarantee that context-ignoring work has finished.
| Status | Meaning | | Status | Meaning |
| --- | --- | | --- | --- |
| `0` | Success. | | 0 | Native success, subject to successful presentation/delivery. |
| `1` | Parse, configuration, loading, rendering, generation, output-write, or other runtime error. | | 1 | Operational failure, including lookup/preparation/generation/capacity, cancellation/timeouts, unclassified load errors, and delivery failure for an otherwise successful run. |
| `2` | `run` generated and wrote output, but validation failed. | | 2 | Native usage/declaration-input errors, or configuration errors classified as invalid input by native diagnostic evidence. |
| 3 | Native `config diff --check` found differences. |
| 4 | Completed generation returned `ValidationFailed`; artifact and native result remain deliverable. |
A backend admission rejection is a runtime error and prints `run error: model Native finalization handles presentation errors: success/usage become operational;
backend capacity is exhausted`. The HTTP capacity response is defined in the an already nonzero domain outcome retains its classification/status. A report-file
[HTTP API reference](api.md). failure preserves completed-validation status 4 while adding its explanation and
cause. An operational failure to perform validation is status 1, not status 4.
JSON selection does not turn failures into a separate JSON error envelope.
## Workflows And Examples [native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
The [maintained render script](../examples/render-markdown-summary.sh) is a
copyable render workflow. The [HTTP request example](../examples/http-run.json)
is for a running `serve` process.

View File

@@ -1,207 +1,158 @@
# Configuration Reference # Configuration Reference
This is the canonical reference for Scriptorium application settings. Prompt, This document owns Scriptorium's application settings, discovery, and source
profile, schema, execution-setting, built-in profile, and framework credential selection. [CLI syntax](cli.md) and the [HTTP API](api.md) have separate owners.
semantics are defined by the Framework definitions and execution semantics belong to the pinned
[Promptkit v0.11.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). [PromptKit v0.23.3 formats][formats]; ConfigKit v1.2.1 owns
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and [native composition and inspection][configkit].
outcomes, see the [HTTP API reference](api.md).
## Discovery And Precedence ## Discovery And Precedence
Application settings are resolved in this order: An explicit `--config` selects that file, including an explicitly empty value
(which fails rather than falling back). With no selection, ConfigKit searches
these native presets in order, selecting one main file:
1. built-in Scriptorium defaults; | Preset | Directories in order | Filename groups |
2. a configuration file; then | --- | --- | --- |
3. CLI overrides. | WorkingDirectory | Current working directory | Named only |
| UserConfigDirectory | Go user-config directory / `scriptorium`, then the user-config directory | Named then Generic in the application directory; Named only in the base |
| HomeDirectory | Go home directory / `.scriptorium`, then the home directory | Named then Generic in the application directory; Named only in the base |
| UnixSystemDirectories | `/usr/local/etc/scriptorium`, `/etc/scriptorium`, then `/etc` | Named then Generic in application directories; Named only in `/etc` |
When `--config` is omitted, Scriptorium searches Named means `scriptorium.yml`, then `scriptorium.yaml`. Generic means
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`. `config.yml`, `config.yaml`, `main.yml`, then `main.yaml`.
If neither exists, it uses built-in defaults. An explicit `--config` path must ConfigKit uses native Go directory resolution (including its user-config/home
exist and decode successfully. environment behavior) and checks every filename in one directory before the next.
Candidates are not configuration layers. Optional exhaustion uses application
defaults; a selected-file acquisition/decoding error is terminal.
The maintained [minimal configuration](../examples/config.yml), ConfigKit assembles the main, enabled imports, and selected overlay, applies its
[complete configuration](../examples/config.full.yml), and inheritance/composition rules, creates typed defaults and strictly decodes, applies
[composed configuration](../examples/config.composed.yml) are copyable examples. explicit override records, then runs application normalization and validation.
An override can correct a decoded value before validation, but cannot repair
source/composition/decoding errors. The completed result is authoritative:
runtime settings conversion does not merge, default, or normalize again.
## Application Configuration File ## Application Settings
Configuration is decoded by ConfigKit v0.4.2 as strict YAML. Unknown fields, Complete copyable configurations are maintained under
empty files, multiple YAML documents, and YAML aliases/anchors are rejected. [examples](../examples/config.yml), including [full settings](../examples/config.full.yml),
An explicit empty string is a value: it clears a file-provided optional path [application imports](../examples/config.composed.yml),
or, for required `prompt_dir`, fails the command's prerequisite. A scalar [framework fragment composition](../examples/config.collections.yml),
`null` is not an empty string and is rejected for scalar fields; nullable [collection checkout discovery](../examples/config.discovery.yml), and
fields such as `transient_retries` retain their documented meaning. Raw [framework inheritance](../examples/config.inheritance.yml).
API-key fields are not accepted.
ConfigKit applies defaults, the selected file, then only explicitly supplied ```yaml
application CLI flags before validating the result. Paths in the application promptkit:
document remain relative to the process working directory, not to the file's configuration: ./examples/promptkit.yml
directory. Load diagnostics are printed safely on stderr; invalid application schema_dir: ./examples/schemas
configuration exits with status 1.
### Explicit imports and selected overlays
A file-backed configuration may declare `configkit.imports` with relative
`path` or `glob` entries. Each entry is explicit; Scriptorium does not scan
for fragments on its own. ConfigKit composes the selected file and imports by
conflict, so two fragments cannot define the same field merely to establish
precedence. A required missing import fails; an entry may use
`optional: true` to suppress target nonexistence. Imports are resolved from
the declaring file's canonical directory and remain within the selected
file's canonical directory by default. Scriptorium does not widen that root.
`--config-overlay NAME` selects one file at `overlays/NAME.yml` below that
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
and exact lowercase `default` select no overlay. There is no fallback,
case folding, inherited stack, or automatic selection; a missing selected
overlay fails. ConfigKit merges mapping fields and replaces other values,
including sequences and explicit nulls, before applying explicit CLI flags.
An active overlay needs a selected base file. No-source defaults-only loads
cannot use imports or an active overlay.
The [composed example](../examples/config.composed.yml) imports two fragments
and has a selectable [local overlay](../examples/overlays/local.yml). From the
repository root:
```bash
go run ./cmd/scriptorium render \
--config ./examples/config.composed.yml --config-overlay local \
--prompt generic.markdown_summary \
--input transcript=./examples/fixtures/transcript.md \
--input glossary=./examples/fixtures/glossary.yml
``` ```
Import and overlay file locations are constrained by ConfigKit; The `promptkit` section contains acquisition settings, not embedded framework
*application path values* such as `prompt_dir` remain relative definitions. Profiles, prompts, backends, and collections belong in the separate
to the process working directory even when authored in a fragment or overlay. framework document. The retired `promptkit_sources`, top-level `schema_dir`,
These source constraints are separate from HTTP artifact containment. and `defaults.render_format` fields have no compatibility conversion and are
rejected by strict decoding, as are unknown/raw credential fields.
| Field | Default | Meaning | | Field | Default | Meaning |
| --- | --- | --- | | --- | --- | --- |
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. | | `promptkit.configuration` | empty | One external framework file; omission/empty selects no external main. |
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. | | `promptkit.schema_dir` | `.` | Schema base directory passed to PromptKit. |
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. | | `transient_retries` | upstream default | Optional nonnegative engine retry count. Omitted/null delegates upstream; zero disables additional transient attempts. |
| `server.addr` | `:8080` | Address used by `serve`. | | `server.addr` | `:8080` | HTTP listen address. |
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. | | `server.artifact_root` | empty | Root enabling HTTP file-artifact references. |
| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request-body bytes; `0` disables the limit. | | `server.max_request_bytes` | `16777216` | Encoded HTTP request limit; zero is unlimited. |
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. | | `server.max_artifact_bytes` | `16777216` | HTTP file-artifact limit; zero is unlimited. |
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. | | `server.max_response_bytes` | `16777216` | Encoded HTTP response limit; zero is unlimited. |
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
| `backends` | unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. |
| `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. |
The size fields must be zero or greater. The [HTTP API](api.md) defines how Size fields are nonnegative signed 64-bit values. [HTTP behavior](api.md) defines
each limit is enforced and reported. `server.artifact_root` configures an HTTP their enforcement; [operations](operations.md) covers safe deployment choices.
deployment boundary; see [operations](operations.md) for deployment handling.
The `config validate`, `config show`, `config sources`, and `config explain` ConfigKit strictly decodes application YAML: empty files, unknown fields,
commands inspect this multiple documents, aliases/anchors, and incompatible/null values fail under its
application configuration without creating a Promptkit engine. `show` is a schema rules. Explicit empty strings and numeric zeros remain values. The
resolved inspection snapshot, not necessarily a reloadable file. Application nullable retry field preserves null. Application paths are trimmed/cleaned and
validation does not check framework sources, backend connectivity, or credential the server address is trimmed within ConfigKit's resolver, with native
availability. `api_key_env` is an environment-variable *name* and remains normalization evidence. Paths remain relative to process cwd, not the application
visible in inspection; its environment value is never read by ConfigKit. file's directory. No general environment-variable override layer is installed.
Ordinary backend `extra_params` values also remain visible, so keep secrets out
of those fields and protect inspection output as potentially sensitive.
`config explain --path /server/addr` uses JSON Pointer syntax to show the
selected field's current value and history from defaults, files, overlays,
explicit CLI overrides, and normalization. `--path ''` selects the root.
History includes replaced and removed values; `show` presents the final
resolved snapshot. Neither renderer looks up credential bytes, and neither
claims to identify arbitrary secrets in unclassified parameter values.
## Custom Backends ## Explicit Imports And Selected Overlays
Use `backends` when a profile selects an application-defined backend ID: Application imports use native root `config.imports` and are enabled during
loading. ConfigKit owns paths/directories/globs, requiredness, destination/item
placement, inheritance, sequence policy, and source-root confinement; consult its
[pinned contract][configkit]. Scriptorium does not widen the selected file's
canonical source root or implement another traversal/merge policy.
```yaml `--overlay NAME` passes the name unchanged to ConfigKit. At the selected release,
backends: empty and exact lowercase `default` select none; other names use letters,
local-gpu: digits, underscores, or hyphens and select `overlays/NAME.yml` beneath the main
endpoint: http://localhost:11434/v1 source root. A missing selected overlay fails. It is not a filesystem-path flag,
api_key_env: LOCAL_GPU_API_KEY inherited stack, or fallback-root mechanism. An active overlay after absent-main
extra_params: search exhaustion has no independent filesystem root in this application.
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0
```
Each mapping key is the case-sensitive backend ID. `endpoint` is required; Only `serve` has named application override flags, for its HTTP settings.
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are Native application-scope `--set` records are passed directly to ConfigKit.
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting Nonconflicting records are supported; duplicate and ancestor/descendant paths
`queue_capacity` lets Promptkit use its default for a limited backend, while are rejected rather than resolved by order. Configuration commands have no
an explicit `queue_capacity: 0` disables queueing. application-defined source/schema/HTTP selectors or comparison counterparts.
Native comparison selections and supported overrides are independent on each side.
Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
validates backend IDs, endpoints, environment-variable names, extra parameters,
and capacity relationships when Scriptorium constructs its engine. There are no
backend command-line overrides. Store only an environment-variable name in
`api_key_env`; raw API-key fields are not accepted.
## Framework Source Mapping ## Framework Source Mapping
Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit A nonempty resolved `promptkit.configuration` becomes an import-enabled
when constructing its engine. Scriptorium does not redefine or independently `configkit.File` main input to PromptKit. An empty value leaves its main absent.
parse those framework file formats. The native bundled OpenRouter underlay remains enabled; no application source
list, directory expansion, or local precedence interpreter is installed.
- Prompt selection, versions, message templates, inputs, output contracts, and Imports in that external document compose framework definitions using PromptKit's
session IDs are Promptkit contracts. schema and ConfigKit's native rules. The [maintained entry file](../examples/promptkit.yml)
- Profile fields, numeric ranges, execution defaults, overlay precedence, imports the application's maintained prompt/profile fragments and backend
built-in profiles, and credential rules are Promptkit contracts. definitions. Peer conflicts are errors, not filename-order precedence.
- Schema path behavior and generated-content validation are Promptkit Native whole-record replacement and inheritance remain framework-owned.
contracts. Application settings do not embed or re-decode framework definitions.
See the PromptKit captures message-file resources with their defining source context
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) when constructing the engine. Schema/artifact reads, credential resolution, and
for all of those definitions. The files under provider work retain native preparation/runtime lifecycles. The server keeps one
[`examples/prompts`](../examples/prompts/), engine until restarted; later CLI invocations perform fresh loads.
[`examples/profiles`](../examples/profiles/), and
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium
application inputs using that tagged format.
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and ### Collection Checkout Discovery
`promptkit-openrouter-auto`. They can be selected as a prompt default or request
profile, and custom profile sources retain precedence. Their effective model
settings may change with a catalog upgrade; use a complete application-owned
profile when fixed settings are required. See the tagged format reference for
the maintained-profile contract.
## Credentials And Outbound Behavior The [discovery configuration](../examples/config.discovery.yml) selects
[one framework entry](../examples/discovery/framework.yml) with two optional imports:
Scriptorium maps `--api-key-env` and HTTP `model.api_key_env` into Promptkit ```yaml
request overrides. Keep secret values in environment variables and store only config:
their names in configuration or framework source files. Do not place raw keys imports:
in configuration, prompts, profiles, CLI arguments, examples, or HTTP - glob: collections/*/collection.yml
payloads. - glob: collections/*/collection.yaml
```
An optional `api_key_env` whose environment value is absent or empty can result Each independently maintained checkout declares its namespace and explicitly
in an unauthenticated provider request. A profile that declares credentials imports its own definitions relative to its entry file. Checkout names do not
required still fails as an invalid request when no credential source is determine resource IDs. The [support example](../examples/discovery/collections/support-repo/collection.yml)
selected, and fails with `ErrAPIKeyEnvMissing` when its selected environment imports multiple profiles/prompts and a source-relative message; the
source is absent or empty. Scriptorium never reads or emits the environment [review example](../examples/discovery/collections/review-repo/collection.yaml)
value itself. uses the other spelling. Arbitrary checkout YAML is not loaded implicitly.
Unset optional provider controls are omitted from compatible provider requests. Either glob may have no matches. New checkouts become visible on a later
A positive Promptkit `repair_attempts` budget can add provider calls, latency, invocation, not through server hot reload. Entries in one discovery document are
token use, and cost; see the tagged format reference for its permitted values peers: conflicting qualified IDs fail instead of relying on glob order.
and validation-mode requirements.
Promptkit's built-in client makes up to two additional attempts for eligible ## Inspection And Credentials
transient HTTP statuses by default. The application `transient_retries` setting
changes that budget for its constructed engine; an explicit `run` request
override takes precedence. This can increase latency, request count, and cost.
Each initial or repair generation has its own transient budget; an injected
client retains its own retry behavior. The tagged integration contract owns
eligibility and timing.
Promptkit's The native `app` scope exposes the actual application result without acquiring
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) framework definitions or credentials. The `promptkit` scope exposes the captured
defines outbound authentication, provider request mapping, transport limits, framework result selected by the application config/overlay. They are not merged
and timeout layering. into one synthetic document. See [CLI inspection](cli.md#application-configuration-inspection)
for operations and independent comparison.
## Related References PromptKit owns profiles, namespaces, provider controls, repairs, retries, and
credential resolution. Store credential environment-variable names, not raw
values; supply the selected environment to the process. Native framework
redaction is limited to classified fields and history, not arbitrary sensitive
content. Protect application, prompt, prepared, and generated reports as data.
- [CLI reference](cli.md) [formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md
- [HTTP API reference](api.md) [configkit]: https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md
- [Operations guide](operations.md)
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)

View File

@@ -11,10 +11,11 @@ and the HTTP service according to the boundary your application needs.
- CLI subprocess: [subprocess integration](../integrations/subprocess.md) - CLI subprocess: [subprocess integration](../integrations/subprocess.md)
- HTTP service: [HTTP API reference](../api.md) - HTTP service: [HTTP API reference](../api.md)
- Application configuration: [configuration reference](../config.md) - Application configuration: [configuration reference](../config.md)
- Existing CLI callers: [native CLI migration](upgrading-cli.md)
Go applications that need an in-process prompt framework should import Go applications that need an in-process prompt framework should import
Promptkit directly. The tagged `go.maximumdirect.net/promptkit` directly. The tagged
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
owns that interface; Scriptorium does not provide a Go library package. owns that interface; Scriptorium does not provide a Go library package.
Consumers arriving from the former Scriptorium Go API should follow the Consumers arriving from the former Scriptorium Go API should follow the
[migration guide](migrating-to-promptkit.md). [migration guide](migrating-to-promptkit.md).
@@ -27,7 +28,7 @@ Consumers are responsible for:
- supplying required inputs and template variables; - supplying required inputs and template variables;
- supplying credentials through the chosen interface; - supplying credentials through the chosen interface;
- protecting rendered prompts and generated artifacts as potentially - protecting rendered prompts and generated artifacts as potentially
sensitive; sensitive, including native inspection and full result reports;
- deciding whether validation-failed output is usable; and - deciding whether validation-failed output is usable; and
- retrying only when another model call is acceptable. - retrying only when another model call is acceptable.
@@ -35,4 +36,4 @@ Scriptorium does not persist run state. A retry can produce different output
and can incur another provider request. CLI exits belong to the and can incur another provider request. CLI exits belong to the
[CLI reference](../cli.md), HTTP status behavior belongs to the [CLI reference](../cli.md), HTTP status behavior belongs to the
[HTTP API reference](../api.md), and framework semantics belong to [HTTP API reference](../api.md), and framework semantics belong to
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).

View File

@@ -1,5 +1,11 @@
# Migrate From Scriptorium To Promptkit # Migrate From Scriptorium To Promptkit
This historical first hop targets Promptkit v0.11.1 and its former module
path. For the current public module `go.maximumdirect.net/promptkit` and the
ID-only configuration cutover, follow the
[current upgrade guide](upgrading-promptkit.md) afterward and consult the
[current Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
## Supported Migration Boundary ## Supported Migration Boundary
Scriptorium `v0.11.1` at Scriptorium `v0.11.1` at

View File

@@ -0,0 +1,95 @@
# Migrate To The Native CLI
This guide covers Scriptorium's breaking CommandKit-native CLI cutover. It does
not select a release version or change historical release notes. The
[CLI reference](../cli.md) owns current syntax, streams, and statuses;
[configuration](../config.md) owns source discovery and settings.
The earlier [PromptKit upgrade](upgrading-promptkit.md) covers framework formats,
not a compatibility layer for this interface.
## Replace Commands And Selections
| Former interface | Current interface |
| --- | --- |
| `run --prompt ID` / `--prompt-id` | `run ID`; exactly one positional prompt ID. |
| `render --prompt ID` | `promptkit show prepared ID`. |
| `inspect prompt --prompt ID` | `promptkit show prompt ID`. |
| `inspect profile --profile ID` | `promptkit show profile ID`. |
| `inspect configuration ...` | Native `config ... --scope promptkit`. |
| Application `config ...` | Native `config ... --scope app` (the default scope), including diff. |
| `--config-overlay` | `--overlay NAME`; a native overlay name, not an arbitrary path. |
| `--input NAME=PATH` | `--input-file NAME=PATH`; `--input` now means literal text. |
| `--llm-base-url` | `--endpoint` (canonical `--llm-endpoint`). |
| Duration-valued `--timeout` | Integer `--timeout-seconds` for each generation attempt. |
| `--out` / output-file flags | Caller stdout redirection. |
| `--execution-report` | `--report PATH` with native result rendering. |
Prefer native short aliases such as `--profile`, `--var`, `--input-text`, and
`--input-file`; canonical `--llm-*` spellings remain available.
There is no duplicate prompt flag, direct backend-ID override, or retained
`--profile-id` alias on generation.
Repeat mappings rather than comma-separating them. The first equals sign splits
each mapping; commas and later equals signs are literal. Input text/file
occurrences share native last-occurrence precedence.
## Migrate Application Configuration
Replace the source-selector list and top-level schema directory with
`promptkit.configuration` and `promptkit.schema_dir`.
The [maintained example](../../examples/config.yml) selects a separate framework
entry file that imports prompt/profile/backend definitions through native
ConfigKit composition. No source/schema CLI flags or compatibility conversion
remain. Do not embed framework definitions inside the application section.
Discovery now uses native cwd, user-config, home, then Unix-system presets and
their filename conventions. It is no longer limited to the two former
`config.yml` paths. Set an explicit config path when migrating unattended jobs.
Overlays remain native name selections. Application-scope native `--set` records
retain conflict rejection; order does not make duplicate paths authoritative.
There are no custom source/schema/HTTP selectors under `config`.
## Capture Artifacts And Reports
For an artifact file plus full native report, from the repository root:
```sh
scriptorium run generic.markdown_summary --config examples/config.yml \
--input-file transcript=examples/fixtures/transcript.md \
--input-file glossary=examples/fixtures/glossary.yml \
--report run-result.json --report-format json > summary.md
```
This generation example contacts the configured provider. Use native prepared
preview instead when only checking inputs/settings.
Main automatic/text output is the artifact alone, with no added newline.
Main JSON/YAML is the native result; artifact bytes use native structured
serialization. Separate reports contain that full native result, not the old
observer-derived metadata shape. `--report-format` independently chooses
text/YAML/JSON; omission leaves the format unset for native automatic rendering
(currently YAML for structured values). Extensions do not select formats.
Omit quiet to capture main output, including redirected stdout. Quiet still
allows an explicitly requested report file. Reports are available only when a
result is returned; resultless failures do not replace an existing report.
Partial delivery can leave one or both destinations written. Keep paths separate
and check status/diagnostics before treating files as fresh.
## Adjust Status And Sensitivity Handling
Completed generated-content validation failure is now domain status 4, not the
old status 2. Native usage/invalid-configuration input is 2, diff-check
differences are 3, and operational failures are 1. Presentation/file failures
can change success into failure while preserving an already nonzero domain
classification. The [CLI status table](../cli.md#server-and-statuses) owns details.
Native prompt inspection includes messages; prepared reports include rendered
content; full run reports include generated content and metadata. Framework
classified-field redaction does not make arbitrary report data safe to expose.
Requirements discovery is separate from validation/preparation: it can run
before artifacts exist, and a partial report may succeed. Read its native
completeness/issue fields. Smoke tests are explicit provider operations, not
startup checks. See [subprocess guidance](../integrations/subprocess.md) for
stream capture, cancellation, and caller responsibilities.

View File

@@ -0,0 +1,100 @@
# Upgrade PromptKit Sources And Definitions
This guide covers the earlier framework configuration cutover to
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/configuration-migration.md)
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
for the full upstream contract. The subsequent [native CLI migration](upgrading-cli.md)
owns command, reporting, application-discovery, and source-setting changes.
Removing version selectors and changing framework definition shapes are
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
## Application configuration
Framework definition migration and application acquisition are separate changes.
Rewrite older framework files as below, then select their entry file using the
current [application configuration](../config.md#application-settings).
The old source-selector list and top-level schema root are not current aliases;
follow the [CLI migration guide](upgrading-cli.md#migrate-application-configuration).
Scriptorium does not provide a legacy definition reader or embedded-definition
extraction/reload path.
## Rewrite framework definitions
Replace version-keyed prompts and keyed profile/backend mappings with lists
of records containing `id`. For example, before:
```yaml
prompts:
report:
"1":
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
fast:
endpoint: https://example.invalid/v1
model: synthetic-model
```
After:
```yaml
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
- id: fast
endpoint: https://example.invalid/v1
model: synthetic-model
```
Select prompts by exact ID; `--prompt-version` is rejected. If multiple former
versions must remain independently selectable, give them distinct IDs and
update callers. Qualified IDs such as `support/answer` are passed unchanged.
PromptKit resolves `content_file` relative to the source that supplied the
field, including imported or inherited definitions. The
[framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md#messages-and-templates)
describes which paths are allowed within the source root.
Convert framework source controls from `configkit:` to `config:` and add
`required: true` for imports that must exist. An optional framework source
header, if present, is `version: 2`. Use sibling inheritance such as
`extends: {id: base}`.
The single external framework entry uses native ConfigKit import composition;
there is no application-managed source-list precedence. Native record replacement
and inheritance remain upstream-owned. Checkouts imported by the same
[discovery file](../config.md#collection-checkout-discovery) are peers:
conflicting definitions of the same ID fail instead of overriding one another.
Null profile endpoint, credential, or provider-map settings can fall
back to the selected backend; review behavior rather than assuming null clears
backend values. Keep JSON schemas self-contained instead of depending on remote
schema references. Application selectors remain separate from these framework
semantics.
## Replace catalog selections
The default-on OpenRouter bundle supplies actual profiles such as `auto` and
`gpt-sol-latest`. Former catalog and `promptkit-openrouter-*` IDs are not
compatibility aliases. Choose an intended current bundled profile explicitly,
or define a complete local profile with the endpoint, model, and settings you
need. Do not assume a new default model. The bundle is an underlay and caller
records can replace it through ordinary composition.
For multiple independently maintained repositories, see the
[collection-discovery example](../../examples/config.discovery.yml). Its
entry files declare their own namespaces; checkout names do not become IDs.
The [CLI reference](../cli.md) defines qualified selection and prepared preview; the
[operations guide](../operations.md) describes when updates take effect.

View File

@@ -2,9 +2,13 @@
This is the contributor entry point for Scriptorium. Scriptorium is an This is the contributor entry point for Scriptorium. Scriptorium is an
application that consumes the public application that consumes the public
[Promptkit v0.11.2 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md); [PromptKit v0.23.3 package](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md);
framework implementation work belongs in Promptkit. Application configuration framework implementation work belongs in Promptkit. Application configuration
uses ConfigKit v0.4.2; keep Scriptorium's schema and source selection local. uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local.
Operator interfaces use CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0;
standard command families and presentation remain upstream-owned.
PromptKit uses the same ConfigKit release to load framework sources under its
own separate schema and format contract.
## Initial Orientation ## Initial Orientation
@@ -44,22 +48,32 @@ Before recommending, planning, or implementing work:
| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) | | CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) |
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) | | HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests | | Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` | | Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and the [native CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md) |
| Prompt, profile, schema, generation, or validation semantics | [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) | | Promptkit source selection or captured framework inspection | [Configuration contract](config.md#framework-source-mapping), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) |
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) | | Prompt, profile, schema, generation, or validation semantics | [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md) and the [Promptkit consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md) |
| OpenAI-compatible outbound behavior or timeout layering | [PromptKit v0.23.3 integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md) |
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) | | Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
| Runtime operation or recovery | [Operations](operations.md) | | Runtime operation or recovery | [Operations](operations.md) |
| Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) | | Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) |
| Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) | | Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) |
| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md), and the related files under `examples/` | | Examples or copyable assets | The owning Scriptorium contract, the relevant [PromptKit v0.23.3 format contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md), and the related files under `examples/` |
| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents | | Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents |
Cross-project changes land and release in Promptkit before Scriptorium adopts Cross-project changes land and release in Promptkit before Scriptorium adopts
the tagged version. Do not commit a Go workspace, local replacement, vendored the tagged version. Do not commit a Go workspace, local replacement, vendored
Promptkit source, or an import of a Promptkit `internal` package. Promptkit source, or an import of a Promptkit `internal` package.
The module graph can include upstream maintainer tools such as ReleaseKit and
their dependencies even though those graph-only packages are not linked into
the Scriptorium runtime; use `go list -deps ./cmd/scriptorium` to distinguish
the linked packages.
## Baseline Validation ## Baseline Validation
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0,
required by application ConfigKit v1.2.1. Running a published binary does not
require a Go installation. Release validation and builds use
the separately selected toolchain in the [release procedure](release.md).
For code changes, run: For code changes, run:
```bash ```bash

View File

@@ -1,63 +1,67 @@
# Subprocess Integration # Subprocess Integration
This document covers process-boundary behavior for callers that invoke Use the executable when a local process boundary is appropriate.
Scriptorium as a child process. Command syntax, flags, output, and exit codes The [CLI contract](../cli.md) owns exact command/flag/status syntax; the
are defined by the [CLI reference](../cli.md). Interface selection belongs in [consumer overview](../consumers/api.md) compares subprocess and HTTP use.
the [consumer integration overview](../consumers/api.md).
## Process Contract ## Artifact-First Execution And Inspection
Use `scriptorium render` when the caller needs prepared output without a model Select a stored prompt and capture its generated artifact from stdout. Use native
call, and `scriptorium run` for generation. Pass an explicit `--config` or requirements discovery before generated input files exist, concrete validation
make the configuration search paths available to the child process; configuration once bindings exist, and prepared preview to render without a model call.
discovery, fields, profile selection, and credential mechanisms are defined in The [CLI migration guide](../consumers/upgrading-cli.md) explains replacements
the [configuration reference](../config.md). for older command and file-output conventions.
Pass required API-key environment variables through the child environment. Do Pass an explicit application configuration or deliberately arrange the child's
not place raw API keys in arguments. Keep the environment limited to the values [configuration discovery](../config.md). Supply only the environment needed for
needed for the selected profile. selected credentials; never put raw keys in arguments.
For application-only preflight, invoke `scriptorium config validate`; it exits Discovery completeness is distinct from binding satisfaction and execution
0 with empty stdout when the application configuration loads, but does not readiness. Partial reports can succeed. Consumers own their binding graph and
prove that Promptkit sources or credentials are usable. `config show` emits policy for incomplete findings; Scriptorium supplies no workflow state.
resolved YAML and `config sources` emits newline-terminated JSON provenance.
All three use the same source selection and explicit overrides as execution
commands and require separate stderr capture for diagnostics. Their output can
include source paths, identifiers, credential reference names, and ordinary
backend parameters; treat it as potentially sensitive.
## Streams And Output Ownership ## Streams, Reports, And Availability
Capture stdout and stderr separately. Stdout contains the requested artifact or Capture stdout and stderr separately. Diagnostics are not a machine-readable
prepared output unless the caller selects an output file; stderr contains error protocol, even when structured result output is selected. Prefer exit
summaries, diagnostics, and server messages. The exact destinations and status classification and native report fields; do not parse diagnostic prose.
meanings are part of the [CLI reference](../cli.md), not a stable stderr data
protocol.
When using `--out`, the caller owns the output path, its permissions, and The default generated result is artifact content. Native structured results and
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as optional separate reports carry the full returned result, including content and
potentially sensitive. metadata. They are not the former metadata-only CLI observation report. Native
prompt/prepared inspection also carries content. Treat all captured streams and
reports as potentially sensitive.
For `run`, an optional [execution report file](../cli.md) contains terminal To save main output, supply a file as the subprocess stdout destination or use
metadata separate from generated stdout or `--out`. The caller owns that shell redirection. Omit quiet when that main result is needed: quiet suppresses
path's permissions and retention. Output and report files are not a it even for redirected stdout. A separately requested report remains an
transaction: one may be written when the other fails, and a preexisting report application file effect independent of quiet and main format selection.
may remain when the invocation has no terminal event. Check the exit status
and diagnostics rather than assuming a report path contains this run's data. A completed content-validation failure can still deliver an artifact/result;
consumers decide whether it is usable. An operational failure with no result
produces diagnostics and a nonzero status, not a synthesized result/error
envelope. An existing separate report may then describe an older invocation.
## Partial Delivery And Caller Responsibility
Main output is attempted before a requested report, and report delivery is
attempted even after main presentation failure. Either destination may contain
partial data after an error. File delivery is not transactional and has no
rollback or atomic-replacement promise.
Callers own redirected file creation/truncation, permissions, retention, and
keeping destinations separate. A shell may truncate its file before the process
starts, unlike a separate report that is opened only after a result exists.
Check the finalized exit status and diagnostic stream; do not infer success or
freshness from a file's existence.
## Cancellation And Recovery ## Cancellation And Recovery
A CLI invocation performs one synchronous request and creates no durable run Interrupt/SIGTERM cancels the child's invocation context. Engine cancellation is
state. A supervising process that needs cancellation must terminate the child cooperative. The [whole-operation budget](../cli.md#generation) is separate from
process according to its own process-management policy. A later invocation is a per-attempt provider timeouts and excludes process/configuration setup and
new request and can make another model call; there is no resume or checkpoint delivery. Supervisors still own forced process termination when required.
protocol.
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the A new invocation is a new request that may incur another provider call/cost.
engine invocation. It is separate from the per-attempt generation timeout and There is no checkpoint, archive, conversation, or resume protocol. Deployment and
does not include child startup or output writing. A deadline failure exits 1; sensitive-data handling belong to [operations](../operations.md).
supervisors still own process termination when they need to stop the child
outside that engine interval.
For deployment, filesystem permissions, and sensitive-artifact handling, see
the [operations guide](../operations.md).

View File

@@ -1,136 +1,89 @@
# Adapter Internals # Adapter Internals
## Purpose Adapters map executable inputs and effects through public upstream values.
The [CLI](../cli.md), [HTTP API](../api.md), and [architecture policy](../policy/architecture.md)
own their external contracts and boundaries.
Scriptorium adapters translate executable inputs into Promptkit public requests ## CLI Composition And Acquisition
and translate Promptkit results or errors back to CLI or HTTP behavior. They
own IO and presentation mechanics, not framework decisions.
External contracts are canonical in the [CLI reference](../cli.md) and `app.go` composes application run/serve declarations with native configuration,
[HTTP API reference](../api.md). Promptkit's public engine contract is PromptKit, completion, help, and version support. CommandKit owns parsing,
described by its tagged declaration-input checks, reporting selection, presentation, and finalization.
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md).
## Components And Collaborators `selection.go` maps explicit native config/overlay choices and server-only HTTP
bindings into `internal/config.Load`. It preserves supplied empty/zero values.
Native application `--set` records remain upstream records with native conflict
handling. No application selectors are installed under configuration commands.
- `cmd/scriptorium` passes process arguments and streams to `native_config.go` adapts the actual application result through
`internal/adapter/cli`. `ckconfig.FromConfigKit` and framework inspection through `ckprompt.ConfigScope`.
- `internal/adapter/cli` resolves settings through `internal/config`, Native views own effective values, paths, metadata, sources, findings, explanations,
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`, redaction, and comparison. Application inspection does not construct an engine.
and owns output files, summaries, and exit codes. Comparison loads each side from that side's selection; there is no config/engine
- `internal/config` delegates application YAML decoding, default resolution, cache or effective-document reconstruction.
overrides, and validation ordering to ConfigKit. The CLI supplies only
explicitly visited application flags as overrides and renders safe structured
load diagnostics on stderr.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
public values, calls its adapter-owned `Runner` interface, and maps results
and errors to HTTP DTOs.
- `internal/format` renders `promptkit.PreparedRun` values as deterministic text
or JSON.
- `internal/report` maps Promptkit's terminal execution event to a small
application-owned value without invoking the engine or writing output.
## Wiring Flows `acquisitionState` contains application diagnostic evidence only, never loaded
configuration or engines. Callback decorators forward it through native
`Acquired` channels. An application LoadError is transported separately while
the framework adapter runs, then its original typed cause is restored before
native outcome classification. This prevents app findings from becoming
framework findings. Native framework evidence remains unchanged; comparison
application messages identify left/right context. Callback marks prevent replay
when operations share invocation state.
### CLI `native_prompt.go` installs all twelve ckprompt callbacks, nil request builders,
and empty-default native namespace views. Inventories, named resources,
requirements, validation, preparation, and smoke testing retain their upstream
lifecycles and reports.
`run` calls `promptkit.Engine.Run`; `render` calls ## Generation And Delivery
`promptkit.Engine.Prepare`. Both share request mapping for prompt ID/version
and profile selection, optional file inputs, variables, and presence-aware
execution overrides. Omitted framework settings remain zero values so Promptkit
resolves its own defaults and definition-required inputs.
The application retry setting enters shared engine construction, while a
run/render flag enters only the mapped request. The server uses the same engine
setting and retains one backend admission state. Render prepares without
generation.
`inspect prompt` maps the selected ID and optional version to `native_run.go` binds the required operand and reusable resource/input/execution
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection flags into a native RunRequest. Ordinary typed namespace flags feed
data. It constructs the same configuration-aware engine but does not perform `Engine.WithNamespaces`; stored references are not rewritten. One `Engine.Run`
preparation or generation. call receives the invocation context and unchanged operation duration. PromptKit
owns preparation, credentials, admission, retries, repairs, and content validation.
`inspect profile` maps an explicit profile ID to `Engine.InspectProfile` and `outcomes.go` maps typed failures and native configuration evidence to native
formats a safe application-owned effective profile view. It intentionally does outcomes, preserving causes while keeping provider payloads out of terminal
not require prompt, schema, or artifact sources. explanations. A returned completed validation failure remains a domain outcome;
an unexpected nil successful result is an integration failure.
The `config` family loads the same application ConfigKit result once and uses `delivery.go` submits the actual RunResult to the invocation reporter with a
its validation, effective-output, source, and explanation views directly. It reusable artifact-byte text template. The optional file renders that same value
does not construct a Promptkit engine. The CLI maps source records into a small without the template through CommandKit's writer API, outside reporter callbacks
JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers. to avoid reentrancy. File failures add explanations/causes while reporter
presentation failures remain native. See [delivery semantics](../cli.md#results-and-separate-reports).
`serve` constructs Scriptorium's restricted HTTP artifact reader, injects it ## Server And HTTP
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
adapter's consumer-owned `Runner` interface, and starts the server.
The command paths assemble the engine from the same resolved prompt, profile, `server.go` loads application settings, injects the restricted artifact reader
and schema directories plus configured custom backends. Each backend is mapped into one engine, installs the existing HTTP handler/limits, and opens a listener.
to Promptkit's public `Backend` value and registered during engine construction, It retains the header timeout and engine retry defaults. Context cancellation
so one constructed server engine retains one immutable backend registry and its calls Server.Close; callback coordination finishes connection/listener closing
associated capacity state. before return, without waiting for arbitrary context-ignoring application work.
### HTTP The HTTP handler strictly decodes DTOs and applies transport policy before
mapping to PromptKit requests. Its Runner interface is a consumer-side external
boundary using native values. Request controls do not mutate shared engine
defaults; shared backend capacity accounting remains in that engine.
The handler enforces transport limits and strict JSON decoding before mapping HTTP optional reports use one per-request `internal/report.Collector`, attached
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and only for opted-in requests. It copies terminal aggregates, not event history,
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact, and is never the CLI result report. Success/error attachment and encoded-size
validation, model, usage, and metadata values directly. handling retain the [HTTP contract](../api.md#execution-report). Reader sentinel
The optional HTTP retry count maps to `RunRequest.TransientRetries` without identities survive PromptKit wrapping for status mapping.
mutating the shared engine. Negative values are rejected before invocation;
Promptkit controls retries and backend admission for concurrent requests.
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader
errors preserve their identity through Promptkit's artifact-load boundary.
The report collector is per invocation. It ignores nonterminal events and
copies terminal aggregates once, including usage presence and completeness.
It retains no history or shared state; adapters decide whether to attach it and
how to present its snapshot.
CLI `run` attaches one only when a report path is selected, writes generated
output first on success, and then writes the terminal snapshot when present.
Its report path remains untouched for pre-invocation failures or absent
terminal observations; report and artifact writes are independent.
HTTP `POST /v1/runs` attaches a separate collector to each invocation only when
`include_execution_report` is true. Its optional top-level `execution` field
appears in success or error envelopes only when Promptkit emits a terminal
event. Pre-invocation adapter errors and absent terminal events leave it out.
The complete serialized success or report-bearing error response is subject to
the configured response-size limit; overflow returns the compact 413 error
without a report. Field meanings are owned by the [API contract](../api.md#execution-report).
## Package-Local Guarantees
- Adapters contain no copied framework types or orchestration.
- Configuration is resolved before Promptkit engine construction.
- Explicit numeric overrides preserve presence, including zero.
- HTTP DTO and error mapping remains stable and transport-owned.
- Resolved secrets are not serialized or printed.
- No adapter creates durable run state.
## Verification ## Verification
Inspect: Native composition/configuration/prompt/run/delivery/lifecycle tests protect the
application's integration choices using real libraries and controlled local
providers. Checkout-discovery tests cover fresh invocations and entry-file
spellings. Entrypoint tests protect identity/status mapping; HTTP reader/DTO/
report/capacity regressions and the architecture guard remain their own owners.
Do not duplicate upstream parsers, analyzers, serializers, or exhaustive format
matrices to change an adapter.
- `internal/adapter/cli/run_test.go` When changing behavior, update its canonical external contract and focused
- `internal/adapter/http/handler_test.go` integration protection. Required shared capabilities belong upstream before
- `internal/adapter/http/artifact_reader_test.go` tagged adoption, not in a resurrected application framework facade.
- `internal/format/prepared_run_test.go`
- `internal/adapter/dependency_test.go`
The adapter tests protect parsing, configuration mapping, output, status
mapping, restricted artifacts, and representative real Promptkit-engine
workflows. The dependency test protects the repository boundary.
## Change Recipes
For a CLI or HTTP change:
1. identify the Scriptorium-owned external contract;
2. map through Promptkit public values without copying framework semantics;
3. add or update the narrow application-owned test;
4. update the canonical Scriptorium contract; and
5. coordinate and tag Promptkit first if a required public capability is
genuinely absent.
Update [source internals](sources.md) when application source locations or HTTP
artifact containment changes.

View File

@@ -1,19 +1,18 @@
# Internal Component Overview # Internal Component Overview
This is the complete inventory of Scriptorium's implemented Go components. This inventory describes implemented Go components. The
The [architecture policy](../policy/architecture.md) owns normative boundaries; [architecture policy](../policy/architecture.md) owns normative boundaries;
public behavior belongs in the linked contracts. public behavior belongs in the linked contracts.
| Component | Implemented responsibility | References | | Component | Implemented responsibility | References |
| --- | --- | --- | | --- | --- | --- |
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) | | `cmd/scriptorium` | Build identity, signal-aware context, native status-to-process exit. | [CLI](../cli.md), [adapters](adapters.md) |
| `internal/adapter/cli` | Parses execution and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) | | `internal/adapter/cli` | CommandKit composition, ckconfig/ckprompt acquisition, application loading, native request mapping, run/report effects, and HTTP process lifecycle. | [CLI](../cli.md), [adapters](adapters.md), [sources](sources.md) |
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) | | `internal/adapter/http` | Routes, strict DTO decoding, transport limits, public request/result/error mapping, and restricted artifact reader. | [HTTP API](../api.md), [adapters](adapters.md), [sources](sources.md) |
| `internal/config` | Selects application sources, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md) | | `internal/config` | ConfigKit application schema, discovery/selection, defaults/resolution/validation callbacks, and completed-value conversion. | [Configuration](../config.md), [sources](sources.md) |
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) | | `internal/defaults` | Application and HTTP default constants. | [Configuration](../config.md) |
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) | | `internal/report` | HTTP terminal-observation metadata projection. It is not used for CLI native result reports. | [HTTP execution report](../api.md#execution-report), [adapters](adapters.md) |
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
Framework implementation packages are provided by CommandKit, ckconfig, ckprompt, ConfigKit, and PromptKit are released upstream
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) dependencies, not local framework packages. There is no custom CLI formatter
and are not part of this repository. package or compatibility dispatch surface.

View File

@@ -1,101 +1,55 @@
# Source Internals # Source Internals
## Purpose This document covers application acquisition and the restricted HTTP artifact
reader. [Configuration](../config.md) owns field/discovery/composition contracts;
the [PromptKit formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
own framework resources and execution semantics.
This document covers Scriptorium-owned source locations and the restricted HTTP ## Application Boundary And Engine Construction
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
## Application Source Locations `internal/config.Load` selects an explicit File or the ordered native SearchConfig
presets and performs one ConfigKit load with imports, overlay selection, and
explicit overrides. It returns the actual Result with native inspection evidence.
Definition callbacks supply application defaults, record actual path/address
normalizations through ConfigKit, and validate retry/HTTP-size domains. Settings
conversion consumes completed values without another merge or normalization pass.
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from The typed application PromptKit section selects acquisition only. In
Scriptorium defaults, configuration files, and CLI overrides. It also resolves `engine.go`, a nonempty resolved configuration path becomes an import-enabled
the application-owned `backends` mapping into sorted engine settings. main Input; an empty path leaves Main nil. The schema base and retry default are
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps passed directly, retaining the bundled underlay. There is no source-list parser,
each configured backend to Promptkit's public engine registration when directory classification/expansion, or one-underlay-per-selector algorithm.
constructing an engine shared by the command path.
Scriptorium does not search, parse, validate, or overlay framework source files Framework imports resolve within the native source context. Message resources
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema are captured from their defining contexts at engine construction. Schema and
resolution, ordinary file artifacts, and the related error identities. request-artifact acquisition retain their preparation-time behavior.
Independent collection checkouts are discovered by native file import globs,
not application traversal. New invocations reload normally; a server retains
its single engine until restart.
The [configuration reference](../config.md) owns Scriptorium's source-location Application-only inspection uses its completed result without framework
fields and precedence. Maintained files under `examples/` are application acquisition. Framework inspection exposes the native captured view separately.
inputs that use Promptkit's tagged formats. Diagnostic decoration in the [CLI adapter](adapters.md) carries application
messages without combining evidence trees or effective documents. There is no
## Application Configuration Boundary per-invocation engine/config cache or cross-invocation snapshot guarantee.
`internal/config` contains a ConfigKit-native `Document` definition. Its
fresh defaults come from Scriptorium's existing default constants; its resolver
records only actual trimming, path cleaning, and render-format normalization.
The validator reports application retry, size-limit, and format errors without
mutating the document or exposing rejected values. Application path values keep
working-directory-relative meaning. ConfigKit owns strict YAML decoding and
presence semantics, including dynamic integer values in backend parameters.
The `Load` boundary selects an explicit file, the first existing implicit
configuration file, or ConfigKit's defaults-only source. Only absence advances
implicit discovery. One ConfigKit load applies explicit application overrides
before validation and returns a result containing the resolved document and
its frozen inspection records. `Settings` converts that document into the
existing runtime settings with backend IDs sorted; it does not read files or
apply another merge. File-backed loads enable explicit ConfigKit imports and
select one named overlay when requested. ConfigKit uses the selected file's
canonical directory as the source root; the application does not widen it.
Application path values retain process-working-directory-relative meaning.
Every configuration-loading command uses this boundary. The CLI maps only
explicitly visited application flags to ConfigKit overrides and prints
structured load diagnostics before engine construction. The old application
YAML decoder and merge path have been removed.
Application `config` inspection reuses the result's frozen effective,
provenance, and history views without constructing an engine or reloading
sources. It does not resolve API-key environment values; ordinary backend
parameters remain visible by the selected inspection policy.
## Restricted HTTP Artifact Reader ## Restricted HTTP Artifact Reader
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP The HTTP adapter implements `promptkit.ArtifactReader`; server construction
requests. The `serve` path injects it with injects it through the public option. Ordinary CLI artifact loading remains
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for upstream-owned.
inbound HTTP inputs.
The reader: The reader accepts inline content without a root. File references need a root;
relative paths resolve below it and absolute paths must be lexically contained.
Traversal outside is rejected and the configured file byte limit applies, with
zero unlimited. Reads preserve native artifact metadata and honor cancellation.
- accepts inline references without an artifact root; Containment does not resolve symlinks. The OS may follow a symlink inside the
- denies file references when no root is configured; root to an outside target; this is not a filesystem sandbox or a defense against
- resolves relative paths below the configured root; privileged concurrent filesystem modification. Reader errors retain identity
- accepts absolute paths only when they are lexically within that root; through upstream artifact-load wrapping, enabling the existing HTTP mapping.
- rejects lexical traversal outside the root;
- applies the configured file byte limit, with zero meaning unlimited;
- preserves content type, body, size, hash, name, and URI metadata; and
- honors context cancellation.
Containment is lexical and does not resolve symlinks. The operating system The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
follows symlinks after the check. The [HTTP API](../api.md) owns observable safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
request outcomes, and [operations](../operations.md) owns safe deployment reader/handler tests own their respective boundaries; upstream owns exhaustive
permissions and root selection. source traversal, format parsing, ordinary artifacts, and inspection semantics.
Reader errors remain identifiable after Promptkit wraps them as artifact-load
failures, allowing the HTTP adapter to preserve Scriptorium status and error
codes.
## Verification And Change Recipe
Inspect:
- `internal/config/document_test.go`
- `internal/config/load_test.go`
- `internal/adapter/cli/run_test.go`
- `internal/adapter/http/artifact_reader_test.go`
- `internal/adapter/http/handler_test.go`
When changing an application source location or HTTP artifact policy:
1. preserve strict configuration precedence and the Promptkit public boundary;
2. keep containment and size policy in Scriptorium;
3. update focused configuration, reader, and handler tests;
4. update the [configuration](../config.md), [HTTP](../api.md), and
[operations](../operations.md) contracts as applicable; and
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.

View File

@@ -1,229 +1,120 @@
# Operations Guide # Operations Guide
## Scope And References This runbook covers deployment, normal operation, capacity, sensitive data, and
recovery. Exact [CLI syntax/statuses](cli.md), [configuration](config.md), and
[HTTP wire behavior](api.md) remain in their canonical references.
See the [CLI migration guide](consumers/upgrading-cli.md) for changed jobs and
the [framework upgrade guide](consumers/upgrading-promptkit.md) for definitions.
This runbook covers deployment, normal operation, capacity planning, and safe ## Deploy Sources And Process
recovery for Scriptorium. It does not redefine invocation syntax, configuration
fields, or HTTP wire behavior.
- [CLI reference](cli.md): commands, output destinations, and exit codes. Provide readable application configuration, its selected framework entry file,
- [Configuration reference](config.md): application settings, source and explicitly imported definitions/resources. Set cwd deliberately: application
locations, defaults, and credential mapping. path values are cwd-relative, while framework imports and message resources keep
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md): their native source contexts. ConfigKit confines source imports/overlays to the
prompt, profile, schema, execution-setting, and framework credential selected main's canonical root; Scriptorium does not widen it.
contracts.
- [HTTP API reference](api.md): route, request/response schema, status codes,
limits, and HTTP artifact access.
- [Consumer integration overview](consumers/api.md): caller responsibilities.
## Operational Model And State Engine construction validates selected effective definitions and captures message
resources/template syntax, including definitions not used by a particular request.
Schema/artifact reads, credential resolution, and model work retain their native
preparation/runtime lifecycles. A server constructs one engine at startup and
does not hot-reload changed files; restart to capture updates. Separate CLI
invocations load afresh rather than sharing an immutable snapshot.
Scriptorium handles one prompt request for each CLI invocation or HTTP request. For independent collections, install checkouts beneath the layout selected by
It has no durable run store, archive, checkpoint, cache, or resume mechanism. the [discovery entry](../examples/discovery/framework.yml). Each checkout declares
A failed or interrupted request is recovered by correcting its inputs, its namespace and explicit fragment imports; arbitrary YAML is not a framework
configuration, or environment and submitting a new request. source. The maintained [discovery example](../examples/config.discovery.yml)
supports both entry-file spellings and multiple definitions. New checkouts or
updates become visible to later invocations or a restarted server.
Generated artifacts, rendered prompts, model output, and run metadata are Supply only needed credential environment variables through a supervisor or
caller-owned data. Retention, encryption, backup, and deletion are deployment secret-management mechanism. Confirm presence without printing their values.
responsibilities. Raw keys do not belong in arguments or checked-in configuration.
Optional [CLI execution reports](cli.md) also belong to the caller. They can
contain sensitive identifiers even though they omit prompt and response bodies.
Keep report paths separate from generated output and apply the same access and
retention controls. Output and report writes are not transactional; an older
report may remain when no terminal observation was produced.
HTTP callers may also request a [terminal execution report](api.md#execution-report).
It shares the same identifier sensitivity and should receive response access
and retention controls. An opted-in report increases the encoded response size;
an oversized success or report-bearing error becomes the compact 413 response
without a report.
## Deploy The Filesystem And Process ## Normal Operator Workflow
Provide the process with readable configured Promptkit prompt, profile, and 1. Validate application configuration through the native application scope.
schema sources that follow the tagged framework formats. For an HTTP deployment This does not acquire framework sources or prove provider readiness.
that accepts file artifacts, use a dedicated, narrow artifact directory rather 2. Inspect framework configuration/resources and discover requirements for the
than a general-purpose or sensitive filesystem tree. selected prompt/profile/namespaces. Discovery can precede generated input
artifacts; completeness does not establish satisfied bindings.
3. Once artifacts exist, validate the concrete request or inspect prepared
content. These are provider-free preparation checks with native prerequisites.
4. Invoke a smoke test only when its provider effects are intended. Findings
can be unsupported or unsuccessful while the command itself succeeds.
Smoke tests are not an automatic startup or release prerequisite.
5. Generate with the same selections and bindings, then inspect the finalized
status and any returned validation result before accepting the output.
If application configuration uses explicit imports or a selected overlay, Use the [maintained preview script](../examples/render-markdown-summary.sh)
deploy those files beneath the selected configuration file's canonical for a provider-free example, and the [CLI contract](cli.md) for commands.
directory. ConfigKit keeps imported and overlay files within that root; A complete discovery report can still list required inputs that are not bound;
Scriptorium does not widen it. Application path values inside those files still a partial report can still be useful. Consumers own their policy for incomplete
resolve from the process working directory, so set that directory deliberately findings and changed resources between invocations.
in the service manager. This configuration-source boundary is distinct from
the HTTP artifact root and does not constrain prompt or schema directories.
When upgrading existing definitions, review selected profile IDs. ## Sensitive Data And Retention
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro` were removed from the
selected catalog. Choose an available catalog profile, one of Promptkit's
maintained names, or a complete application-owned profile. New DeepSeek names
are not aliases for the removed ones; see the
[v0.10 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md).
Run Scriptorium under an identity that can: Artifacts, prompt messages, prepared content, native run reports, metadata,
diagnostics, and redirected streams are caller-owned potentially sensitive data.
The separate CLI report contains the full returned result, not metadata alone.
Control access, retention, encryption, backup, and deletion accordingly.
Framework effective/explanation views apply native classified-field redaction,
including history, but do not detect arbitrary secrets. Other content-bearing
reports are not automatically made safe for publication.
- read only the prompt, profile, schema, and allowed input-artifact paths it Keep main output and report destinations separate. Delivery is nontransactional:
needs; one destination or partial bytes can remain after failure. An existing report
- read the required credential environment variables without writing them to can remain on a resultless error; check status and report identity, not just file
files or logs; and existence. A shell can truncate a redirected destination before the child starts.
- write only caller-selected output locations when CLI output files are used. Omit quiet if main stdout must be captured; the separate report effect remains
independent. Exact delivery behavior belongs to [CLI results](cli.md#results-and-separate-reports).
Do not make the HTTP artifact directory writable by untrusted users. The HTTP HTTP's optional [execution report](api.md#execution-report) remains a distinct
artifact containment behavior is lexical and the operating system follows terminal-observation projection. Protect its identifiers and any response data.
symlinks; account for that when choosing ownership and mount boundaries. See It increases encoded response size and remains subject to the configured limit.
the [HTTP API reference](api.md) for the externally observable behavior.
## Supply Credentials And Protect Runtime Data ## HTTP Deployment And Shutdown
Set secret values in the process environment and configure only their The service has no built-in authentication/authorization. Deploy on a trusted
environment-variable names. Do not put raw keys in configuration, prompt or network or behind appropriate authenticated proxy/gateway controls. Use a narrow,
profile files, process arguments, HTTP payloads, captured command lines, or dedicated artifact root with controlled ownership and permissions when accepting
debug dumps. file inputs; this is lexical containment, not a symlink sandbox.
Treat stdout, stderr, prepared-run output, generated artifacts, and HTTP Use a supervisor for cwd, environment, restart policy, and stream capture.
responses as potentially sensitive. Send service logs to a controlled collector Startup information uses native Info reporting, not stdout banners.
and apply the same retention and access rules as for model input and output. Interrupt/SIGTERM cancels the invocation and closes the listener and active
connections. Canceled shutdown is nonzero operational termination. There is no
graceful-drain deadline or promise that context-ignoring work has finished;
supervisors own forced termination when necessary.
## Run A Normal Workflow ## Capacity, Limits, And Recovery
Before changing production inputs, profiles, or schemas: One server engine shares backend admission/queue state across concurrent requests.
That state is transient operational coordination, not a durable workflow or
queue of resumable runs. HTTP capacity exhaustion retains its
[API outcome](api.md); callers decide whether another model call is safe.
1. use `config validate`, `config show`, or `config sources` to check the Plan for input/output sizes, schema complexity, provider latency, retries, and
application configuration and its selected sources without constructing an repair costs. Native transient attempts and repair generations can add calls and
engine; this does not verify prompt files, provider access, or credentials; waiting; engine defaults and per-request overrides belong to
2. confirm the deployed configuration selects the intended sources and model [configuration](config.md) and the [CLI](cli.md)/[HTTP](api.md) contracts.
credentials; Whole-operation budgets are distinct from per-attempt generation timeouts.
3. use [`render`](cli.md) with the same request inputs and variables to confirm They remain cooperative and do not include configuration/setup or delivery.
preparation without a model call;
4. use [`run`](cli.md) for generation; and
5. retain or discard validation-failed output according to the caller's
policy.
Inspection output can include configuration paths, names, and ordinary backend Before increasing HTTP byte limits, measure representative requests/artifacts/
parameters. `config explain --path` uses JSON Pointer paths and can show responses, confirm memory/network/provider capacity, retain authentication and
displaced historical values as well as the final value. Protect both the upstream request controls, and test a representative workload. Do not widen the
selected paths and the output, especially when backend parameters contain artifact root just to make an arbitrary host path accessible.
sensitive identifiers; ConfigKit does not infer arbitrary secrets in those
parameters. Apply
access and retention controls; the application stores only API-key environment
reference names, not the resolved credential bytes.
The [maintained render script](../examples/render-markdown-summary.sh) is a For failures, capture diagnostics without publishing sensitive data. Verify
copyable preflight example. The CLI reference owns its complete invocation and selected configuration, resource identity, readable inputs, profile/credentials,
exit semantics. and schema deployment. Use native prepared preview to isolate pre-generation
problems. A completed content-validation failure is distinct from an operational
failure to validate; consumers choose whether failed content is usable.
Correct the cause, then issue a new request only when another provider call and
its cost are acceptable.
## Expose The HTTP Service There is no durable run store, archive, checkpoint, or resume mechanism.
Cleanup concerns caller-owned files/logs only. Rotate/delete them under the
The HTTP service has no built-in authentication or authorization. Place it on a deployment's normal retention policy; recovery starts from a new request.
trusted network or behind an authenticated reverse proxy, API gateway, or
equivalent access control. Restrict who can reach it and who can read the
artifact root.
Use a service manager or supervisor appropriate to the deployment to manage
process lifetime, restart policy, log capture, and environment injection. The
[HTTP API reference](api.md) owns client request shapes, status behavior, and
artifact-access outcomes.
## Plan Capacity And Limits
Capacity is primarily determined by concurrent model calls, input and output
sizes, schema complexity, provider latency, and network behavior. Size limits
protect request bodies, HTTP file artifacts, and encoded responses; configure
them through the [configuration reference](config.md) and rely on the
[HTTP API reference](api.md) for their response effects.
Configured backend concurrency and queue capacity are enforced per constructed
Promptkit engine. A `serve` process constructs one engine for its handler, so
concurrent HTTP requests share that transient admission state. Scriptorium does
not retain workflow state: capacity is neither durable nor a queue of resumable
runs. When admission is exhausted, HTTP returns `503 capacity_exceeded` without
retry timing; callers choose any retry policy that is safe for another model
call.
Promptkit's built-in client now allows two additional attempts for eligible
transient provider statuses by default. Account for added calls, latency, and
cost when planning capacity. Each repair generation has its own transient
budget, separate from the structural repair count. Configure the engine budget
with [`transient_retries`](config.md); `run` and `render` accept a request
override described in the [CLI contract](cli.md), and HTTP callers can select
one through the [API contract](api.md). Omission inherits the engine
setting and then Promptkit's default, while explicit zero disables additional
attempts. Existing generation timeouts apply
per attempt, while the caller context covers the complete operation. Provider
`Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
for details.
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must
be bounded. The existing generation timeout applies afresh to each attempt and
does not cap retry waits or the complete invocation. The whole-run interval
covers the engine call, including capacity waiting and repairs as supported by
context cancellation; it excludes parsing, engine setup, and output writes.
HTTP callers can use [`run_timeout_seconds`](api.md) to shorten their request
context for the same engine interval. The API distinguishes an expired
execution deadline from caller cancellation and from a provider-attempt
timeout. A canceled capacity waiter releases its Promptkit admission state.
Before increasing a limit:
1. measure representative input, generated-output, and optional raw-output
sizes;
2. confirm memory, network, and upstream-provider capacity;
3. retain an upstream request-size and authentication boundary; and
4. test the intended workload in a non-production environment.
For large local inputs, prefer a controlled file-artifact directory over
placing arbitrary paths on the service host. Avoid disabling a limit unless an
equivalent trusted control exists elsewhere.
## Diagnose And Recover
### Preparation Or Configuration Failure
Capture the CLI diagnostic or HTTP error response, then verify the selected
configuration, prompt ID, profile selection, source readability, and input
mapping. Use `render` with the same request when it is unclear whether failure
occurs before model execution. Consult the [CLI reference](cli.md), the
[configuration reference](config.md), and the [HTTP API reference](api.md) for
the exact interface contract.
### Credential Or Provider Failure
Confirm that the process environment contains the configured credential name
without printing the secret. Check endpoint reachability and provider health
from the process network. If preparation succeeds but generation fails, inspect
the selected model settings in prepared output and the service's controlled
logs. Correct the deployment or provider issue, then submit a new request.
### Artifact Or Permission Failure
Verify that the process can read the intended local input. For HTTP file
artifacts, verify the deployment's artifact root, ownership, path layout, and
file size. Do not widen filesystem permissions or the allowed root merely to
make an arbitrary path work; move or copy the required artifact into the
controlled location instead.
### Validation Failure
A generated-content validation failure is distinct from a runtime failure.
CLI `run` reports the validation result and error count in its success summary;
it does not print the individual validation messages. For HTTP, inspect the
validation object in the response according to the [HTTP API reference](api.md).
Use rendered input and generated output to determine whether prompt instructions,
the selected model, or the schema needs correction. If schema loading or
compilation itself fails, correct the source deployment or schema document
before rerunning.
### HTTP Limit Or Request Failure
Compare the request, artifact, or expected response size with the deployed
configuration, and validate the request against the [HTTP API reference](api.md).
Reduce the payload, use an appropriate controlled artifact source, omit
unneeded raw output, or adjust the deployment limit after capacity review.
## Cleanup And Reruns
Because no run state is retained, cleanup concerns caller-owned output files,
logs, and artifacts only. Remove or rotate them using the deployment's normal
retention policy. After a correction, rerun the request from the beginning;
there is no safe resume point.

View File

@@ -5,23 +5,22 @@
Material: `docs/policy/oss.md`, `docs/policy/meta.md`, Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
`docs/policy/agents.md`, `docs/policy/documentation.md`, `docs/policy/agents.md`, `docs/policy/documentation.md`,
`docs/policy/architecture.md`, `docs/policy/testing.md`, `docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/policy/release.md`, `AGENTS.md`, and the `docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section
Policy Reading Guide section of `docs/development.md`, adapted for this of `docs/development.md`, adapted for this repository.
repository.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: CC-BY-SA-4.0 SPDX-License-Identifier: CC-BY-SA-4.0
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) | License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE). [LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## Promptkit ## PromptKit
Selected module: `gitea.maximumdirect.net/eric/promptkit` at `v0.11.2`. Selected module: `go.maximumdirect.net/promptkit` at `v0.23.3`.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
@@ -29,14 +28,14 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) | [GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/COPYRIGHT) | [COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/LICENSE). [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2). [Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f).
## ConfigKit ## ConfigKit
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.4.2`. Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
@@ -44,87 +43,125 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) | [GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/COPYRIGHT) | [COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/LICENSE). [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f). [Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
## Promptkit OpenRouter Catalog ## CommandKit
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2` at `v2.20260926.0`. Selected module: `go.maximumdirect.net/commandkit` at `v0.7.0`.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [MIT](licenses/MIT.txt) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/COPYRIGHT) | [GPL 3.0](licenses/GPL-3.0.txt) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/LICENSE). [COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3). [Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4).
## Promptkit Rakestrawhome Catalog ## CommandKit ckconfig
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2` at `v2.20260926.0`. Selected module: `go.maximumdirect.net/ckconfig` at `v0.9.0`.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [MIT](licenses/MIT.txt) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/COPYRIGHT) | [GPL 3.0](licenses/GPL-3.0.txt) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/LICENSE). [COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596). [Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig).
## jsonschema/v6 ## CommandKit ckprompt
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2`. Selected module: `go.maximumdirect.net/ckprompt` at `v0.10.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt).
## Cobra
Selected module: `github.com/spf13/cobra` at `v1.10.2` (transitive dependency).
Copyright 2013-2023 The Cobra Authors
SPDX-License-Identifier: Apache-2.0 SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) | License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE). [LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71). [Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## golang.org/x/text ## pflag
Selected module: `golang.org/x/text` at `v0.14.0`. Selected module: `github.com/spf13/pflag` at `v1.1.0` (transitive dependency).
Copyright (c) 2009 The Go Authors. All rights reserved. Copyright (c) 2012 Alex Ogier. All rights reserved.
Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) | License and notices: [BSD 3-Clause](licenses/pflag-BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE). [LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353). [Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).
## gopkg.in/yaml.v3 ## mousetrap
Selected module: `gopkg.in/yaml.v3` at `v3.0.1`. Selected module: `github.com/inconshreveable/mousetrap` at `v1.1.0` (Windows transitive dependency).
Copyright (c) 2006-2010 Kirill Simonov Copyright 2022 Alan Shreve (@inconshreveable)
Copyright (c) 2006-2011 Kirill Simonov SPDX-License-Identifier: Apache-2.0
Copyright (c) 2011-2019 Canonical Ltd License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/inconshreveable/mousetrap/blob/4e8053ee7ef85a6bd26368364a6d27f1641c1d21/LICENSE).
Copyright 2011-2016 Canonical Ltd. [Source](https://github.com/inconshreveable/mousetrap/tree/4e8053ee7ef85a6bd26368364a6d27f1641c1d21).
SPDX-License-Identifier: MIT AND Apache-2.0 ## jsonschema/v6
License and notices: [MIT](licenses/MIT.txt) | Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51). SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
## golang.org/x/text
Selected module: `golang.org/x/text` at `v0.44.0`.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/go-x-text-BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
[PATENTS](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
[Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
## go.yaml.in/yaml/v4 ## go.yaml.in/yaml/v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`. Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov Copyright 2006-2010 Kirill Simonov
@@ -136,7 +173,7 @@ SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT.txt) | License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) | [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) | [LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE). [NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125). [Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).

View File

@@ -0,0 +1,27 @@
Copyright 2009 The Go Authors.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google LLC nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

View File

@@ -0,0 +1,28 @@
Copyright (c) 2012 Alex Ogier. All rights reserved.
Copyright (c) 2012 The Go Authors. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md
## Purpose ## Purpose

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-20
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md
## Purpose And Ownership ## Purpose And Ownership
@@ -39,8 +39,8 @@ Do not promote incidental implementation choices into architectural invariants.
## Scriptorium's Purpose And System Shape ## Scriptorium's Purpose And System Shape
Scriptorium is an executable application with CLI `run`, `render`, Scriptorium is an executable application with CLI `run`, native `promptkit`
`inspect`, and `config` command families and an HTTP service started by and `config` families, and an HTTP service started by
`serve`. It offers simple, request-independent execution of predefined `serve`. It offers simple, request-independent execution of predefined
prompts, not a reusable Scriptorium root Go API or a workflow framework. prompts, not a reusable Scriptorium root Go API or a workflow framework.
The [internal overview](../internal/overview.md) owns the concrete package The [internal overview](../internal/overview.md) owns the concrete package
@@ -50,22 +50,40 @@ inventory; [adapter internals](../internal/adapters.md) and
## Framework And Application Boundaries ## Framework And Application Boundaries
Scriptorium consumes Scriptorium consumes
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
through its supported public root package. Promptkit owns prompt execution, through its supported public root package. Promptkit owns prompt execution,
preparation, prompt and profile formats, built-in profiles, model-client preparation, prompt and profile formats, built-in profiles, model-client
behavior, validation, and framework defaults. Scriptorium owns application behavior, validation, inspection semantics, and framework defaults. Scriptorium
configuration, executable CLI and HTTP adapters, prepared-run and owns the application domain, executable CLI and HTTP adapters, process behavior,
definition-inspection presentation, process behavior, and HTTP deployment and HTTP deployment policy. It interprets resolved configuration and uses
policy. The [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) PromptKit's supported APIs and results to satisfy user requests. The [format
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
remain Promptkit's contracts. remain Promptkit's contracts.
Scriptorium uses ConfigKit v0.4.2 for strict application YAML decoding, ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
resolution, and validation flow. Scriptorium retains its application schema, fully resolved configuration handoff. Scriptorium supplies application schema
defaults, normalization, validation rules, source selection, and CLI override and domain callbacks through ConfigKit's supported extension points and consumes
mapping. ConfigKit does not own Promptkit framework sources or HTTP artifact the completed result without redefining effective configuration. PromptKit's
containment. The [configuration contract](../config.md) owns externally configuration is also resolved through ConfigKit, with PromptKit supplying its
observable configuration behavior. domain schema and rules. The [configuration contract](../config.md) owns
externally observable application behavior; PromptKit owns framework formats.
As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to
neutrally expose upstream features and semantics. CommandKit owns shared command,
parsing, presentation, and outcome mechanics; application commands and effects
remain local. Standard configuration inspection uses native adapters without
custom effective documents or evidence reconciliation. This decision complements
ADRs 0004 and 0005; the completed
[adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md)
remains in Git history.
The CLI exposes Promptkit's captured framework configuration inspection. Its
`show` and `explain` reports use Promptkit's native redaction for classified
credential-shaped fields, including historical values. This scoped behavior is
not a general-purpose filter for arbitrary sensitive content and does not
extend to application configuration or existing prompt/profile inspection.
Application code may import Promptkit's public root package, but not its Application code may import Promptkit's public root package, but not its
`internal` packages or catalog modules. It must not recreate the removed `internal` packages or catalog modules. It must not recreate the removed

View File

@@ -1,10 +1,10 @@
# Documentation Policy # Documentation Policy
**Base Policy Version:** 1.11 **Base Policy Version:** 1.12
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md
## Purpose ## Purpose
@@ -87,8 +87,8 @@ secret values.
| Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. | | Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | | Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | | Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | | Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. | | Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. | | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. | | Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
@@ -154,8 +154,15 @@ Use sequentially numbered ADR filenames such as
Treat the decision content of an accepted ADR as immutable. When a decision Treat the decision content of an accepted ADR as immutable. When a decision
changes, create a new ADR and update the earlier ADR's status to superseded. changes, create a new ADR and update the earlier ADR's status to superseded.
Rejected architectural alternatives belong in the ADR; rejected product ideas
belong in the roadmap. ADRs should be reserved for major architectural decisions, such as ownership
boundaries, large-scale architectural features, or invariants that rise to
the level of architectural significance. Routine choices, implementation
decisions, and rejected suggestions do not warrant an ADR unless they
otherwise represent a significant architectural decision.
Roadmaps should preserve plausible future work, not rejected product
ideas.
## Maintenance ## Maintenance

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.0 **Base Policy Version:** 1.0
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md
## Origin And Local Authority ## Origin And Local Authority

View File

@@ -1,10 +1,10 @@
# Open Source Licensing And Attribution Policy # Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.8 **Base Policy Version:** 1.9
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md
## Purpose And Scope ## Purpose And Scope
@@ -64,6 +64,9 @@ individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT) Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT) or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
to create the project’s root `COPYRIGHT` file. to create the project’s root `COPYRIGHT` file.
Use the COPYRIGHT examples exactly as provided, except for placeholder
substitutions and changes expressly required or authorized by this policy or
the author.
Use verified project names, contribution years, and copyright holders. Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant. text references together to reflect the author's selected grant.

View File

@@ -1,10 +1,10 @@
# Release Policy # Release Policy
**Base Policy Version:** 1.4 **Base Policy Version:** 1.7
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md
## Purpose ## Purpose
@@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
intended source revision under a fresh version. Releases should require little intended source revision under a fresh version. Releases should require little
routine intervention, avoid repeated work, and preserve published contents. routine intervention, avoid repeated work, and preserve published contents.
Adopt stronger verification or reproducibility requirements through an explicit
project-specific decision justified by the intended audience and support needs.
The repository-specific commands belong in `docs/release.md`. Historical release The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements. policy and link to it rather than introduce additional release requirements.
@@ -59,9 +62,14 @@ requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`: For releases at or after `v1.0.0`:
- a major release may make intentional incompatible changes; - a major release may make intentional incompatible changes;
- a minor release may add backward-compatible behavior; and - a minor release may add backward-compatible behavior or raise the Go consumer
minimum as described below; and
- a patch release may make backward-compatible fixes. - a patch release may make backward-compatible fixes.
In this context, "backward-compatible" means only that pre-existing, valid
configurations will continue to work following the relase. Behavior need not
remain strictly identical.
Before `v1.0.0`, a minor release may change a documented public, operational, Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must note explains the impact and required consumer action. A patch release must
@@ -71,6 +79,36 @@ 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.
## Consumer Minimum And Release Toolchain
Distinguish the minimum toolchain supported for consumers from the toolchain
maintainers use to build and validate a release. Record the consumer minimum in
the language's standard metadata and explain its support meaning in canonical
documentation. Define the selected release toolchain and its setup commands in
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
choices.
For Go repositories, normally declare the initial stable release of the selected
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
when a dependency or an identified correctness fix requires it, and document
the reason.
For release-policy purposes, successful build and release validation on the
selected Go patch release are sufficient to presume support across that Go
series, subject to the declared consumer minimum and concrete evidence of
incompatibility. Investigate specific compatibility concerns as they arise.
Use the selected release toolchain for candidate validation and release builds,
including CI jobs performing those tasks. A newer validation patch version alone
leaves the consumer minimum unchanged.
A minor release may raise the Go consumer minimum, including from one Go series
to the next, both before and after `v1.0.0`. This is an explicit exception to the
backward-compatibility requirement for minor releases. Patch releases preserve
the consumer minimum. Explain an increase's impact and required consumer action
in the release note. Other incompatible changes remain subject to the versioning
rules above.
## Release Documentation And Preparation ## Release Documentation And Preparation
Every new release must include `docs/releases/<version>.md` in the tagged Every new release must include `docs/releases/<version>.md` in the tagged
@@ -186,7 +224,8 @@ release without replacing its contents or reusing its version.
Maintain `docs/release.md` as a short, executable maintainer runbook. It must Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify: identify:
1. prerequisites, primary branch, and authoritative remote; 1. prerequisites, selected release toolchain, primary branch, and authoritative
remote;
2. version and release-note preparation; 2. version and release-note preparation;
3. one publication command with its selected local checks and automated guards; 3. one publication command with its selected local checks and automated guards;
4. declared deliverables, required build targets, and automation responsibilities; 4. declared deliverables, required build targets, and automation responsibilities;

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-19
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md
## Purpose ## Purpose
@@ -178,12 +178,15 @@ Give each layer its distinct responsibility and keep expectation updates localiz
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal, diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
import and overlay composition, provenance, and inspection renderers. import and overlay composition, provenance, and inspection renderers.
- CLI tests own argument mapping, streams, output, exit behavior, and - CLI tests own argument mapping, streams, output, exit behavior, and
representative run, render, inspect, serve, and config workflows. representative native run, PromptKit resource/requirements/preview/smoke,
serve, and configuration comparison workflows.
- HTTP tests own DTO decoding, transport limits, status and error mapping, - HTTP tests own DTO decoding, transport limits, status and error mapping,
restricted artifact reading, and representative server workflows. restricted artifact reading, and representative server workflows.
- Formatting tests own prepared-run and definition-inspection text and JSON - CommandKit and its integrations own standard parsing and presentation.
presentation. Architecture guards own dependency direction and removed Scriptorium's integration tests protect native adoption, byte-preserving main
framework-package boundaries. output, separate report effects, outcomes, and acquisition boundaries without
reproducing the upstream formatting matrix. Architecture guards own dependency
direction and removed framework-package boundaries.
- Promptkit owns framework parsing, orchestration, validation, profiles, and - Promptkit owns framework parsing, orchestration, validation, profiles, and
model-client behavior. Scriptorium's definition and execution fixtures model-client behavior. Scriptorium's definition and execution fixtures
protect adoption through its public adapter boundary without duplicating protect adoption through its public adapter boundary without duplicating

View File

@@ -9,11 +9,31 @@ discoverability requirements.
## Prepare The Candidate ## Prepare The Candidate
Use a POSIX shell, Git with a configured tagger identity and access to Use a POSIX shell, Git with a configured tagger identity and access to
`origin`, and a Go toolchain compatible with `go.mod`. The native host must `origin`, and the selected release toolchain, Go 1.27.4. The native host must
support Go's race detector and have its required C compiler. If Git is support Go's race detector and have its required C compiler. If Git is
configured to sign tags, its signing tool and key must be available. Run from the configured to sign tags, its signing tool and key must be available. Run from the
repository root. Provision the toolchain and module cache before offline repository root. The [developer guide](development.md#baseline-validation)
validation; when dependencies are not cached: explains the separate Go consumer minimum; selecting a release toolchain does
not raise that minimum.
Install Go 1.27.4 from the [official downloads](https://go.dev/dl/) or an
equivalent package source before validation. Set `release_go_root` to its
installation directory, replacing the illustrative path below, and select it
in the release shell:
```sh
release_go_root=/path/to/go1.27.4
export PATH="$release_go_root/bin:$PATH"
export GOTOOLCHAIN=local
go version
```
The version output should identify `go1.27.4`. Keep this selection and the
hosted workflow's Go image in step when deliberately updating the release
toolchain. Ordinary contributor checks may use another compatible toolchain.
Provision the module cache before offline validation; when dependencies are
not cached:
```sh ```sh
GOWORK=off go mod download GOWORK=off go mod download
@@ -66,8 +86,9 @@ The source-boundary guards reject committed workspaces, vendor trees, and
module replacements. module replacements.
It then runs the complete suite once with the race detector and builds Linux It then runs the complete suite once with the race detector and builds Linux
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and linker flags
`-ldflags '-s -w'`. The native test run uses the host platform and enables cgo. `-s -w -X main.version=<version> -X main.revision=<candidate-commit>`.
The native test run uses the host platform and enables cgo.
Validation disables workspaces, uses read-only module mode, and disables module Validation disables workspaces, uses read-only module mode, and disables module
and toolchain downloads. Missing dependencies must be provisioned separately; and toolchain downloads. Missing dependencies must be provisioned separately;
fix the environment and rerun the command. No persistent validation cache is fix the environment and rerun the command. No persistent validation cache is
@@ -91,6 +112,8 @@ publishes:
The matching checked-in note supplies the hosted release body. The workflow The matching checked-in note supplies the hosted release body. The workflow
owns image selection, packaging, checksum generation, and upload configuration. owns image selection, packaging, checksum generation, and upload configuration.
Its binaries receive the tag and source commit as the same version/revision
metadata used by local candidate builds.
Its upload step skips existing files and does not overwrite the release. Its upload step skips existing files and does not overwrite the release.
Source-publication success does not attest to workflow success or asset Source-publication success does not attest to workflow success or asset
availability. availability.

View File

@@ -1,232 +0,0 @@
# ConfigKit Adoption
## Status And Intent
Implemented feature direction, drafted on 2026-09-26 and delivered through the
historical plan at
`git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`.
This roadmap records the target behavior and changes from the reviewed baseline;
that Git record owns sequencing, concrete interfaces, and verification evidence.
The user is adopting ConfigKit across an application suite to standardize
configuration semantics. Scriptorium will make a clean cutover to ConfigKit's
native conventions, including intentional breaking changes. Preserving the
legacy loader's behavior is not a goal: there will be no parallel legacy loader,
compatibility mode, or recreation of the old merging rules.
Alignment applies to application configuration, not to Promptkit-owned prompt,
profile, or schema definitions. Departures from ConfigKit conventions require an
application-specific reason or a genuine ownership boundary, not backward
compatibility alone. The [architecture policy](../policy/architecture.md) and
[ADR 0004](../adr/0004-definition-boundary.md) remain the scope boundaries.
## Reviewed Baseline (Historical)
Scriptorium consumes Promptkit v0.11.0. Its `internal/config` package uses
yaml.v3 directly and manually applies defaults, file settings, and CLI overrides.
It has a parser-specific integer decoder, ignores empty string overrides, and
treats an empty configuration file as defaults-only input. It has no application
configuration imports, selected overlays, or provenance/inspection interface.
The [configuration reference](../config.md), [CLI reference](../cli.md), and
[source internals](../internal/sources.md) own the current behavior.
The reviewed ConfigKit release is v0.4.0 at commit
`e6ced0d3d1194b58e0b3dc8970089471ba175258`. Adopt that published release as the
initial target, rather than a sibling checkout or unpublished replacement.
Its canonical references are:
- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/config.md).
- [Consumer adoption guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/consumers/README.md).
- [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/releases/v0.4.0.md).
ConfigKit requires Go 1.25, within Scriptorium's existing toolchain requirement.
It selects `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Removing Scriptorium's direct parser
usage does not remove yaml.v3 from the dependency graph: Promptkit still uses it.
The initial review passed ConfigKit's default test suite and Scriptorium's
configuration and CLI tests; that is baseline evidence, not migration validation.
## Target Ownership And Loading Model
| Owner | Responsibility |
| --- | --- |
| ConfigKit | Application YAML policy, source acquisition, composition, overlays, typed decoding, explicit override application, provenance, and redacted inspection. |
| Scriptorium | Source discovery, application schema and defaults, CLI parsing, recorded application normalization, semantic validation, command prerequisites, and runtime conversion. |
| Promptkit | Framework definition formats, backend semantics, credential lookup, engine defaults, and prompt execution. |
`internal/config` becomes a small application-specific ConfigKit integration,
not a second general-purpose configuration framework. Execution and inspection
share one configuration definition and loading pipeline. Defaults, selected base
and imports, selected overlay, and explicit application CLI overrides participate
in ConfigKit's lifecycle; resolution and validation follow its upstream rules.
Normalization that changes inspected values is recorded through its resolver.
Runtime conversion does not perform a hidden second merge or apply new defaults
after the inspection snapshot has been created.
Scriptorium retains its application field names and domain meanings unless a
specific change below requires otherwise. ConfigKit's public root API replaces
direct YAML decoding and parser-specific hooks. Application defaults remain
Scriptorium-owned; omitted framework settings still delegate to Promptkit.
Backend conversion retains deterministic registration and engine-scoped shared
capacity state. This work does not change the HTTP request contract or move
configuration loading into each HTTP request.
## Native Configuration Semantics
The target accepts ConfigKit's upstream YAML grammar, schema binding, limits,
composition, and value-presence rules without a legacy preprocessing layer.
Migration-visible changes include:
- An existing empty file is invalid; `{}` expresses an empty application mapping.
Defaults-only operation with no discovered file uses `NoSource` instead.
- Explicit empty strings, false values, and zeroes replace defaults. They are
not silently treated as omission. Application validation still decides whether
a resulting value is meaningful for its field or selected command.
- Null follows the application's declared nullable types. It is not a universal
spelling for omission. Scalars and structs do not accept null merely because
the former parser tolerated it.
- Anchors, aliases, merge keys, explicit tags, additional documents, unsupported
scalar spellings, and coercions rejected by ConfigKit are rejected here too.
- ConfigKit's reserved `configkit` key and resource limits apply, including in
dynamic application data. These constraints do not apply to independently
loaded Promptkit definitions or HTTP request bodies.
- Dynamic integers in backend `extra_params` use ConfigKit's `int64`
representation. Runtime mapping preserves their supported value semantics
rather than reserializing through YAML or demanding the old Go scalar type.
Presence remains meaningful at the framework boundary: omitted/null
`transient_retries` delegates to Promptkit, while explicit zero disables retries;
omitted backend queue capacity differs from explicit zero. Application HTTP
size defaults and zero-as-unlimited behavior remain. No new value ranges or
backend restrictions are introduced merely to adopt the library.
## Discovery, Imports, Overlays, And Paths
Source discovery remains Scriptorium-owned. The target retains the documented
explicit `--config` selection and ordered system-location search. An explicitly
empty config path is invalid rather than an implicit request for a default file.
If neither implicit candidate exists, loading uses defaults only; a selected
file that fails loading is not silently replaced with defaults. No implicit
working-directory configuration search, environment overlay, or directory scan
is added.
Application configuration supports ConfigKit's explicit path and glob imports.
Imports compose disjoint definitions; repeated non-mapping definitions are
conflicts, not last-writer-wins overrides. There is no implicit `conf.d` scan.
An optional `--config-overlay` selects ConfigKit's one named overlay using its
standard `overlays/<name>.yml` location, naming rules, and merge behavior. No
overlay is selected by default. Selecting an active overlay without a base
source follows ConfigKit's rejection of overlays with `NoSource`; Scriptorium
does not invent a root. Application overlays do not replace `--profile`,
`profile_dir`, or Promptkit's execution-profile selection.
Use the selected file's canonical directory as ConfigKit's default import and
overlay root. This root governs configuration source traversal only. Values of
`prompt_dir`, `profile_dir`, `schema_dir`, and `server.artifact_root` retain
working-directory-relative interpretation; absolute values remain absolute.
This is an explicit application path policy, not an upstream requirement or a
legacy parsing mode. ConfigKit's consumer examples demonstrate alternatives but
do not mandate source-file-relative application paths. This adoption does not
extend import containment to application data or alter HTTP artifact containment.
## CLI Overrides And Configuration Inspection
Only flags explicitly supplied by the user become ConfigKit application
override records. Parser defaults do not overwrite file or overlay settings.
Explicit empty values are not dropped. The existing invocation-specific prompt,
profile, input, model, timeout, output, and reporting options remain invocation
state rather than new application configuration fields. In particular, the
run/render retry flag remains a request override; it does not mutate the engine's
application retry setting or backend state.
Expose application configuration validation, effective redacted YAML, source
provenance, and explanation of an individual configuration path. These are
included features, not merely library capabilities available for future work.
They use ConfigKit diagnostics and inspection records from the shared loading
pipeline, including defaults, imports, overlays, explicit CLI values, and
recorded normalization. No separate inspection-only interpretation is maintained.
Configuration inspection does not execute prompts, make provider calls, or
resolve API-key values. Application validation is not a promise that every
Promptkit backend or definition is valid or that a provider is reachable.
Command-specific execution prerequisites remain with the relevant command;
inspection can explain an incomplete application configuration without requiring
an executable prompt selection. The interface is a CLI configuration command
family, not a second CLI framework or an HTTP configuration endpoint; the
implementation plan specifies its concrete commands and mappings.
Safe diagnostics must not restore raw parser errors or configuration values
that ConfigKit deliberately suppresses. Effective output and explanation use
the upstream redacted renderers; they are inspection output, not guaranteed
reloadable configuration. Under the maintainer's selected policy, backend
`extra_params` are visible in effective output and explanation, including
historical values. There is no blanket container masking, sensitive-key heuristic,
or new selective-redaction configuration surface.
## Credential Boundary And Deferred Features
Existing `api_key_env` values remain environment-name strings passed to Promptkit.
They do not become ConfigKit `Secret` fields. ConfigKit eagerly resolves effective
typed references and requires nonempty values; that would change Promptkit's
optional/required and selected-credential behavior. This departure from the
secret-reference feature is an ownership decision, not compatibility plumbing.
Raw API-key fields remain unsupported under the existing architecture policy.
API-key values are the only secrets requiring ConfigKit redaction in this
adoption. The application configuration holds environment-variable names, not
those values, so inspection neither resolves nor contains the actual keys.
Reference names remain visible. Do not tag `api_key_env` as secret merely to
hide its name, add an eager key lookup, or mask unrelated application settings.
The existing raw-key prohibition and Promptkit boundary provide the protection
without introducing a redundant credential-bearing configuration field.
Secrets-directory bootstrap and application schema versioning are deferred until
there is a concrete application need. Their availability in ConfigKit does not
make them mandatory. Hot reload, runtime resource replacement, remote imports,
automatic migrations, and general environment-variable overlays are outside
this adoption. These are scope limits for this feature, not new permanent
prohibitions on future explicitly requested work.
## Required Changes And Completion Criteria
- Replace manual decoding/default/override machinery with the shared ConfigKit
integration and retain only application-specific discovery, rules, and mapping.
- Support imports and selected overlays across commands that load application
configuration, and deliver the configuration inspection capabilities above.
- Update application configuration types, presence handling, CLI explicit-set
mapping, and diagnostics to match the selected native semantics.
- Update maintained examples and canonical configuration, CLI, operations,
architecture, and internal documentation when behavior lands. Upstream generic
contracts remain linked rather than copied into a competing specification.
- Add proportionate integration coverage for the cutover: defaults-only input,
explicit values and nulls, imports/conflicts, overlays, CLI precedence,
inspection agreement and API-key non-disclosure, visible dynamic backend
parameters, unchanged credential ownership, and representative
execution/server startup.
ConfigKit owns exhaustive parser and composition tests; Scriptorium tests its
adoption and application boundaries.
- Pin the published dependency and maintain ConfigKit and YAML attribution under
the [OSS policy](../policy/oss.md), using imported-commit source/notice links
and applicable standard and companion license texts.
- Document migration in a release appropriate for the intentional breaking
configuration changes under the [release policy](../policy/release.md).
Release selection and publication remain separate preparation work; this
roadmap adds no release gate, network probe, or new distribution format.
Completion means one ConfigKit-native application configuration path serves
execution and inspection, the selected user-facing features work, and migrated
examples and regression coverage demonstrate the documented semantics. It does
not require adopting every ConfigKit feature or changing Promptkit definitions.
## Resolved Inspection Policy
On 2026-09-26 the maintainer selected no redaction for `extra_params` and limited
the relevant secret to the API key. Inspection therefore preserves parameter
values and environment-reference names, while actual API-key values remain
outside the application configuration pipeline. Visibility is intentional;
this is not a promise to detect secrets placed inside arbitrary parameter values.
The delivered `config show` and `config explain` commands use ConfigKit's
inspection writers without secret tags or a second redaction path. Both
effective and historical parameter values remain visible; `api_key_env` names
remain visible while Promptkit alone resolves selected credential values.

27
docs/roadmap/future.md Normal file
View File

@@ -0,0 +1,27 @@
# Future Work
The completed CommandKit adoption, implementation plan, Narratio request, and
earlier adoption/policy roadmaps remain available in
[Git history](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap).
Current behavior belongs to the [CLI](../cli.md), [configuration](../config.md),
[HTTP API](../api.md), and other canonical contracts.
## Deferred Directions
- **HTTP design review:** separate work before v1.0; CommandKit adoption retained
the existing HTTP interface and execution-report representation.
- **Embedded framework configuration:** deferred pending upstream support for a
native handoff preserving resource context and inspection evidence. The current
application settings select a separate PromptKit entry file.
- **Dynamic resource completion:** possible enhancement beyond native command,
flag, static-value, and path completion.
- **Configurable namespace defaults and automatic report collection:** possible
enhancements if concrete operator needs arise. Current callers select explicit
namespaces and report paths and own retention.
- **Selected-format accessor:** optional upstream CommandKit capability; not a
prerequisite for the completed stdout-based generation/report interface.
These directions do not select additional APIs, command syntax, implementation
order, or delivery dates. Independently versioned report envelopes and
programmatic invocation-failure categories remain potential upstream discussions
if a concrete consumer need emerges, not missing migration requirements.

View File

@@ -1,303 +0,0 @@
# Policy Alignment Implementation Plan
## Status, Scope, And Authority
Planned on 2026-09-28 against Scriptorium
`8452b54809b99425a97940da485daaa48c77aeb8`. All five stages are complete.
The ordered stages below retain the implementation instructions and completion
evidence for this delivered work set.
The [feature roadmap](policy.md) owns the agreed end state, scope, and reasons
for local exceptions. This plan owns execution steps and acceptance checks.
This is documentation work, not application, dependency, or release-tool work.
The selected public upstream revision is
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Start with its
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Retrieve source files at this revision, not whatever main contains when a
stage runs. A verified checkout of this exact revision is acceptable; no
sibling checkout is a prerequisite. If source retrieval fails, report that
blocker rather than inventing source content or provenance.
Read the current local agent policy and developer orientation before work,
then policies governing the stage. Once Stage 2 lands, use the new selective
reading guide. Reuse unchanged policy text already available in context.
## Historical Implementation Records
This filename previously held completed application plans. Preserve their
records through Git rather than carrying their implementation steps forward:
- ConfigKit adoption and release handoff:
`git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`.
- Earlier PromptKit plans are referenced within that historical document.
Those stages must not be rerun. Existing release notes, including
[the v0.14.0 note](../releases/v0.14.0.md), record prior delivered features.
Do not infer a new release obligation from an old prospective handoff.
The new policy and licensing changes still need a concise summary in the next
release, including the already-selected GPL-3.0-or-later application grant and
the separately licensed policy material. Version selection and publication
are not part of this plan.
## Common Execution Rules
1. Inspect status and relevant diffs before each stage. Preserve unrelated
changes; do not silently include them in the stage commit.
2. Read the selected upstream files completely before adopting them. Compare
directly with local files; do not reconstruct historical adoption baselines.
3. Start from upstream text, remove the complete Base Policy Template section,
and apply only the customizations selected below. Preserve shared language
verbatim, including its meaning and strength. Do not retain old paraphrases
merely because they are familiar or add prohibitions for hypothetical risks.
4. For each policy adopted in that stage, set the target Base Policy Version,
the actual adoption date, and an Upstream Source link:
`https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md`.
Substitute the actual filename. Do not stamp a source on a policy before
incorporating it. Intermediate commits may legitimately have mixed versions.
5. Update the single policy-attribution entry as its copied/adapted scope grows.
Do not claim later-stage material has already been adopted.
6. Validate affected text, links, notices, and diff; record concise completion
evidence under the completed stage here. Commit each coherent stage with a
short plain-English message under the agent policy. Do not push or publish.
Do not change Go code, module pins, tests, release scripts, CI, accepted ADR
decisions, or published release notes. Do not introduce recurring sync checks,
license approval rounds, release gates, or blanket source headers. Preserve
the application grant and dependency terms. Standard license text must remain
verbatim even if a generic whitespace check dislikes publisher formatting.
## Stage 1: Adopt OSS Rules And Establish Licensing Notices
**Status: Complete.** OSS language was compared with the pinned source after
the approved metadata and example changes. The CC-BY-SA text matches its pinned
source byte-for-byte; attribution and navigation were checked against the
specified format and local paths.
Files: `docs/policy/oss.md`, `docs/oss/attribution.md`,
`docs/oss/licenses/CC-BY-SA-4.0.txt`, `COPYRIGHT`, `README.md`,
and the footer portion of `docs/release.md`.
1. Read upstream OSS v1.8, COPYRIGHT, the canonical
`examples/licensing/policy-attribution.md`, and referenced licensing
examples at their pinned URLs. Adopt OSS v1.8 with metadata as above.
Remove template-only content; retain upstream common wording and its
existing commit-pinned example links. Customize the README example to
Scriptorium and GPL v3 or later. No other OSS exception is selected.
2. Copy the complete CC-BY-SA-4.0 reference text from the selected revision
into the named local license file and compare it byte-for-byte with that
source. Do not copy the rest of the reference collection or add CC0 merely
because example formatting is used.
3. Reformat the attribution document to the exact v1.8 House Format. Use
`# Open Source Attribution Notices`, immediately followed by entries.
Place Standard Repository Policies first, using the canonical entry,
with its COPYRIGHT, LICENSE, and Source URLs pinned to the selected full
commit. In this stage identify `docs/policy/oss.md` as the newly adapted
material. Do not research or make claims about prior adoption provenance.
4. Preserve the eight existing dependency entries and their imported commits,
copyright wording, SPDX expressions, and required notices. Optional module
identification paragraphs may retain versions currently in source labels.
Remove the introductory prose, missing-copyright filler, and editorial
YAML license explanations. Preserve the factual MIT AND Apache-2.0
expressions. Use actual upstream filename labels, local license names,
terminal periods, and the exact `[Source](COMMIT_URL).` source form.
Do not upgrade dependencies or relabel their grants.
5. Add a scoped paragraph to COPYRIGHT stating that material adapted from
Standard Repository Policies remains CC-BY-SA-4.0, with
`docs/oss/attribution.md` identifying affected material and links. This
covers the scoped material as stages add it; it does not relicense unrelated
application code or documentation. Keep the existing GPL grant and LICENSE.
6. Correct the README ending to link GPL v3 or later to COPYRIGHT and keep
the attribution link. Change the release-procedure footer to absolute
immutable-tag COPYRIGHT, LICENSE, and ATTRIBUTION links, updating the
references to the number of URLs. Change no publication commands.
Do not retrofit published notes or create a release note/version now.
Acceptance: OSS text matches the pinned source except the approved project
example and metadata; attribution follows the prescribed format; the added
license text is faithful; project and dependency grants remain unchanged.
Check affected local paths and upstream notice/example destinations. Missing
copyright fields are omitted, not explained with agent-authored commentary.
## Stage 2: Adopt Provenance, Agent Guidance, And Documentation Ownership
**Status: Complete.** The three policies carry the selected versions, source
links, and local adoption date; shared text and the orientation template were
compared with the pinned source. The seven-link reading guide and local links
were checked, and attribution names only the incorporated material.
Files: new `docs/policy/meta.md`, `docs/policy/agents.md`,
`docs/policy/documentation.md`, root `AGENTS.md`,
`docs/development.md`, and the policy attribution entry.
1. Adopt meta v1.0 and agents v1.3 verbatim after template-section removal
and metadata substitution. Keep meta's live project and main-branch
adoption-guide discovery URLs; its own Upstream Source is commit-pinned.
Retain local relative links to developer guidance and attribution.
2. Adopt documentation v1.11. Customize only applicable topic-map rows:
configuration remains application configuration, framework formats belong
to PromptKit, consumers cover executable use and migration rather than a
Scriptorium public Go API, and integrations cover Scriptorium-owned
executable/process contracts. Keep upstream rows for meta, COPYRIGHT,
LICENSE, and attribution. Remove instructional “if applicable” qualifiers
from selected rows. Preserve the rest of the shared language.
3. Use the upstream ADR lifecycle and examples guidance without retaining
generic local expansions. This does not edit accepted ADRs or change their
decisions. Metadata maintenance follows the adoption guide through meta,
rather than a duplicate custom rule set.
4. Adapt upstream `agents/AGENTS.md` into root AGENTS.md. Preserve any actual
repository-specific code-discovery instructions; do not copy environment-
injected instructions into the file just because they appeared in a session.
Do not copy upstream's own root AGENTS.md.
5. Add the adoption guide's Policy Reading Guide table and selection bullets
verbatim to the developer guide with the seven local links. Replace its
unconditional architecture-reading instruction and duplicated policy-reading
prose with this selective guide. Retain project orientation, task-specific
contract rows, dependency boundaries, and baseline validation commands.
Avoid maintaining competing policy trigger rules in multiple places.
6. Expand the policy entry's Material sentence to identify the adopted OSS,
meta, agents, and documentation policies plus adapted root AGENTS.md and
the copied Policy Reading Guide section of docs/development.md. Mark them
adapted for this repository; do not imply the whole developer guide or
unrelated tooling instructions have changed license.
Acceptance: all stage policies have their own correct source link and version;
orientation selects policies by task, including meta for adoption work; local
links resolve; no upstream handbook or example collection was copied.
Generic language differences from upstream are eliminated, not rephrased.
## Stage 3: Adopt Architecture And Testing With Narrow Local Decisions
**Status: Complete.** The three shared architecture sections and the common
testing text match the pinned source. Local architecture decisions were checked
against the accepted ADRs and internal guides; focused test ownership and the
expanded attribution scope were reviewed without changing application code.
Files: `docs/policy/architecture.md`, `docs/policy/testing.md`,
policy attribution entry, and focused internal docs only if moving existing
implementation detail requires it.
1. Read the existing architecture, relevant accepted ADRs, source/adapter
internal guides, and the pinned architecture v1.3 template. Retain upstream
Purpose And Ownership, Architectural Approach, and Adopted Constraints And
Implemented Structure text verbatim. Replace the Application-Specific
Topics placeholder with Scriptorium's existing substantive decisions.
2. Preserve public PromptKit/ConfigKit responsibility boundaries, definition
support, strict decoding, presence handling, HTTP artifact containment,
request independence and concurrency-safe shared capacity, credential/error
boundaries, dependency restrictions, and explicit workflow non-goals.
Retain the existing lexical containment and privileged-host threat scope,
not a stronger filesystem-sandbox promise. Customize the trust discussion
to those decisions rather than retaining instructional example prose.
3. Correct system shape to include run, render, serve, inspect, and config.
Link to internal documentation for concrete package inventory/mechanics.
Where material moves, preserve it in its canonical internal owner without
duplicating it. Do not introduce new wrappers, ports, orchestration, or
package constraints merely to “implement” the architectural recommendation.
4. Adopt testing v1.3 common text verbatim. Add one clearly identified local
test-ownership section for configuration, CLI, HTTP, formatting, architecture
guards, and PromptKit/ConfigKit boundaries. Preserve the existing distinction
between adoption/integration fixtures and upstream exhaustive tests.
Retain a short application-specific note explaining HTTP containment and
shared-state risks where useful; do not replace upstream risk-based coverage
guidance or create percentage targets, quotas, or new test requirements.
5. Add accurate source/version/date metadata and extend the policy attribution
scope to architecture and testing. Record any moved adapted prose in the
Material scope if it is placed outside the already identified files.
Acceptance: direct comparison isolates only the roadmap's justified local
decisions; shared text matches upstream. Architecture describes existing
behavior accurately without implementation work. Testing preserves ownership
without duplicating upstream matrices or imposing new coverage gates.
## Stage 4: Adopt Release Policy Without Changing Publication Behavior
**Status: Complete.** The shared release language matches the pinned source;
the local selections match the existing script, hosted workflow, and runbook.
Commands, build targets, recovery behavior, and the three-link footer remain
unchanged. Attribution now names all seven adopted policies.
Files: `docs/policy/release.md`, `docs/release.md`, attribution entry.
1. Read the current release policy, procedure, script, and hosted workflow;
inspect them read-only. Adopt upstream release v1.4 common wording.
2. Add a compact Scriptorium-specific section preserving the established
selections: main/origin, branch-before-tag publication with exact remote
candidate agreement, annotated tags derived from the checked-in note,
stable releases only, asynchronous Linux binaries/checksums, one race-enabled
offline test invocation, and source-boundary guards. Keep rationale for
selected gates in policy and command/target details in the procedure.
3. Retain upstream's general alternatives verbatim but state which existing
approach Scriptorium selects. Atomic push and source-only release remain
template-supported alternatives, not newly supported Scriptorium workflows.
Preserve successful tag publication as completion; no CI polling, artifact
availability, or consumer installation gate is added.
4. Align the procedure with this allocation without changing its commands,
required checks, supported platforms, or failure-recovery behavior. Confirm
the Stage 1 three-link footer survives hosted-body reuse. Do not run the
publication command or mutate remote state to validate documentation.
5. Add metadata and expand the policy attribution scope to all seven policies.
The final Material description also identifies adapted AGENTS.md and the
developer-guide reading section, plus any actually moved adapted text.
Acceptance: the existing release workflow still satisfies the resulting policy
with no script/CI changes. Source completion, delivery status, immutability,
tag type, and validation obligations are unchanged. All seven source links
identify their own file at the selected full commit.
## Stage 5: Verify Language Parity And Complete The Documentation Handoff
**Status: Complete.** All seven policies were compared directly with the pinned
upstream files; differences are limited to metadata, removed template text,
the selected project example and topic rows, and the identified local sections.
The copied license matches byte-for-byte. A Markdown-aware check resolved 86
local links; historical plan references resolve to Git objects. Attribution,
notice scope, release navigation, and the final documentation-only diff were
reviewed without changing application or publication artifacts.
Files: this plan, the feature roadmap, and only affected documentation needing
correction within the preceding stages' scope.
1. Compare all seven adopted documents directly with their selected upstream
counterparts. Account for metadata, removed template sections, approved
substitutions, and the narrow local sections. Correct every remaining
non-substantive wording difference. Do not turn this comparison into a
permanent script, CI requirement, or release gate.
2. Check there are no adoption placeholders, copied template-only instructions,
absent local example links, stale BSD descriptions of Scriptorium itself,
or contradictory selective-reading directions. Legitimate BSD dependency
attribution remains. Validate links using Markdown-aware handling so
illustrative syntax in inline code is not treated as a broken real link.
3. Confirm per-document source metadata, the policy entry's exact scope,
COPYRIGHT's scoped license treatment, existing dependency grants/notices,
and the byte-for-byte new license text. Keep example/source links pinned
and public discovery links current. Check footer paths in the candidate;
unpublished release tags need not resolve online.
4. Review affected roadmap references to implementation.md. Where a link
specifically means an old completed plan, replace it with a clear historical
Git reference from this plan, not this new policy sequence. Preserve
deferred application features and historical completion evidence.
Current release directions link to the canonical procedure, not an old
two-link footer. Do not rewrite published release notes.
5. Mark only actually delivered stages complete with concise evidence here.
Update the feature roadmap's status to delivered and keep its end-state
focus. Record the next-release summary described above without choosing a
version, creating a tag, or claiming publication.
6. Run diff/whitespace and affected-document/link checks. Do not reformat
verbatim license text to satisfy a style check. No Go test/build rerun is
necessary for this documentation-only work; no executable example or
publication command needs changing. Inspect status and staged diff, commit,
and report the commit and remaining work under the agent policy.
Acceptance: policy language is standardized with only justified local
customization; notice/provenance arrangements describe reality; no runtime,
dependency, publication, or historical-release change slipped into the diff.
## Open Questions
None. The maintainer approved the public discovery URLs, the standard
CC-BY-SA arrangement for copied policy material, the selected upstream revision,
and the justified local variations. The existing application grant, dependency
grants, and release approach remain unchanged; do not reopen them merely to
perform this adoption.

View File

@@ -1,223 +0,0 @@
# Standard Repository Policy Alignment
## Status And Intent
Agreed and delivered on 2026-09-28. This roadmap replaces the
earlier licensing-only proposal with alignment of the complete applicable
policy set and its supporting documentation. It defines the targeted end state
and required changes; the [implementation plan](implementation.md) owns ordered
stages and their verification.
The next release summary should mention the policy and licensing alignment,
the already-selected GPL-3.0-or-later application grant, and the separate
CC-BY-SA-4.0 treatment of adapted policy material. Version selection and
publication remain release preparation, not part of this delivery.
The goal is identical policy language across adopting projects except where a
substantive, locally significant requirement or decision warrants customization.
Adopt upstream wording verbatim for non-substantive differences. Existing local
phrasing is not, by itself, a reason to retain a variation.
## Review Revision And Current Baseline
The fixed upstream review revision is
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Use the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
for this adoption. The review compared current local documents directly with
that revision; reconstruction or assessment of historical adoption baselines
is not required.
The reviewed Scriptorium revision is
`d6aecf5c50269b7d130dbf19f416a67454cd9778`. It has six adopted policies,
without per-document Upstream Source metadata, and no `docs/policy/meta.md`.
The policy targets below supersede the earlier roadmap's narrower version
targets.
| Policy and proposed Upstream Source | Current base | Target base | Target treatment |
| --- | --- | --- | --- |
| [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md) | 1.1 | 1.3 | Adopt shared rules verbatim, including commit discipline. |
| [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) | 1.1 | 1.3 | Adopt common principles and customize for Scriptorium's established boundaries. |
| [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) | 1.4 | 1.11 | Adopt shared language and tailor the canonical topic map. |
| [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md) | 1.1 | 1.3 | Adopt shared guidance with focused local test ownership. |
| [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) | 1.2 | 1.4 | Adopt common rules and retain justified release choices. |
| [oss.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md) | 1.1 | 1.8 | Adopt licensing, attribution, and reference-example conventions. |
| [meta.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md) | Not adopted | 1.0 | Add provenance, local authority, and upstream discovery. |
Every existing policy needs language and provenance updates. No adopted policy
is entirely update-free, but established application decisions, dependency
licenses, and release mechanics need no substantive change.
Current supporting-document gaps include the README's obsolete BSD project
license statement, the release procedure's two-link footer, an attribution
document that does not follow the new exact House Format, and orientation
guidance that requires architecture reading even for unrelated work.
The architecture policy's command inventory also omits the implemented
`config` command family.
## Target Policy Language And Local Customizations
Remove every `Base Policy Template` section and its adoption instructions.
Replace instructional application-specific placeholders with actual decisions;
do not leave template examples describing nonexistent components.
Use upstream common language verbatim. Keep necessary local requirements
clearly identifiable rather than paraphrasing entire shared sections.
The following customizations are justified:
- **Architecture:** preserve PromptKit and ConfigKit ownership, full support
for valid PromptKit definitions, public dependency boundaries, HTTP artifact
containment, and simple predefined-prompt execution. Preserve caller-visible
request independence alongside shared engine and backend capacity state.
These are deliberate product and safety decisions, not generic template
choices. Adopt upstream architectural principles proportionately; they do
not require a wrapper or interface for every library. Correct the command
inventory and keep concrete package mechanics in internal documentation.
- **Documentation ownership:** tailor the topic map to the executable CLI and
HTTP application. Scriptorium does not offer a reusable public Go API;
consumer guidance covers executable use and migration to PromptKit.
PromptKit remains the owner of framework formats. Use upstream wording for
generic ownership, example, and ADR guidance instead of retaining redundant
local paraphrases. Preserve accepted ADR decisions and their history.
- **Testing:** retain a short project-specific ownership section distinguishing
Scriptorium's integration and adapter tests from upstream framework/parser
tests. This prevents duplication of PromptKit and ConfigKit test matrices.
HTTP containment and shared-capacity behavior justify focused adapter
coverage. Upstream observations about domain coverage are not quotas or a
hierarchy that displaces risk-based testing.
- **Release:** preserve branch-before-tag publication, annotated tags,
Linux amd64/arm64 binaries and checksums, and asynchronous artifact delivery.
Retain race testing because the server shares concurrent engine state and
source guards because local replacements, workspaces, or vendoring can hide
unpublished dependency substitutions. Keep gate rationale in policy and
concrete commands, targets, and publication choices in the release procedure.
Upstream's optional atomic-push approach does not require a new feature.
- **OSS:** use Scriptorium's actual GPL-3.0-or-later grant in the project
example. Preserve dependency grants and the settled House Format
interpretation for upstream notice links. The code grant does not extend
to separately licensed copied policy material.
No agent-policy exception is needed: upstream already preserves the local
commit authorization and safety boundaries. Stylistic preferences, alternate
wording, and generic elaboration do not justify additional exceptions.
## Provenance And Public Discovery
When adoption lands, each of the seven policies records its target
`Base Policy Version`, actual local adoption date in `Last Updated`, and
`Upstream Source` pointing to the exact corresponding file linked in the
table above. Do not substitute a repository homepage, moving branch, another
policy's URL, or a historical source revision for that per-document link.
Retain accurate provenance in later local edits.
The new local `docs/policy/meta.md` follows upstream language after removing
its template section. It establishes that adopted local policies govern the
repository and that upstream changes require deliberate adoption. Its public
discovery links remain current:
- [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
- [Current adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
Adopted-source and example links remain commit-pinned. Preserve the valid
commit-pinned example links supplied in the selected OSS policy; their asset
revision need not be rewritten merely to match the policy review revision.
Public discovery and attribution in this agreed adoption supersede the earlier
instruction not to reference the policy repository.
## Orientation And Selective Reading
Adapt [the upstream agent orientation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/agents/AGENTS.md)
into [root AGENTS.md](../../AGENTS.md), preserving applicable existing
code-discovery instructions. It points to the local contributor guide and
requires the agent policy before recommendations, planning, or implementation;
it does not require reading the entire suite by default.
The [contributor guide](../development.md) gains the upstream Policy Reading
Guide table and associated selection rules, including the new meta policy.
Retain Scriptorium's task-specific contract guide alongside it. Architecture
reading becomes task-triggered rather than unconditional. Relevant policies
are read before governed decisions, multiple policies may apply, material
already available in context may be reused, and expanded scope triggers
expanded reading. Policy-reading triggers live here, not in the documentation
topic map.
## Licensing And Attribution
Follow the [canonical copied-policy attribution entry](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/policy-attribution.md).
Insert it directly beneath the prescribed attribution title and replace all
three placeholder URLs with the full review commit. Identify the actual
copied/adapted scope, including agent-orientation material and copied reading
guidance where used, rather than describing only policy files if additional
material is incorporated. Preserve creator, copyright, license, disclaimer,
and modification information through the supplied notices and links.
Required supporting changes:
- Add the complete, unmodified `docs/oss/licenses/CC-BY-SA-4.0.txt` from the
selected revision.
- Extend [COPYRIGHT](../../COPYRIGHT) to identify the adapted policy material
as CC-BY-SA-4.0 and point to attribution for exact scope. Preserve
Scriptorium's GPL-3.0-or-later code grant and existing [LICENSE](../../LICENSE).
Unrelated application documentation is not automatically relicensed.
- Reformat [attribution](../oss/attribution.md) to the v1.8 House Format:
`# Open Source Attribution Notices`, followed directly by component entries;
factual optional identification; supplied copyrights; SPDX expressions;
license/notice links with actual filename labels and terminal periods;
and `[Source](COMMIT_URL).`.
- Remove its introductory policy prose, missing-copyright filler, and
agent-authored license-scope explanations. Omit an unavailable copyright
field instead of explaining that none was invented. Preserve actual
required upstream notices, applicable license expressions, and imported
dependency revisions.
- Correct [README](../../README.md) to link its GPL v3 or later statement to
`COPYRIGHT`, followed by the attribution link.
- Update [the release procedure](../release.md) to use the prospective
`COPYRIGHT | LICENSE | ATTRIBUTION` footer, with absolute immutable-release
URLs for all three destinations. The existing hosted workflow continues
copying the checked-in release note unchanged.
The documented CC-BY-SA arrangement is agreed for this adoption. Original
licensing-example formatting has upstream's CC0 permission; using it alone
does not require a separate attribution entry. Reproduced license texts and
third-party notices retain their own terms.
## Local Materials And Upstream References
Keep applicable adopted policies, Scriptorium's adapted root orientation and
developer guide, actual project notices, attribution entries, and required
license texts locally.
Keep the upstream adoption guide, README, root AGENTS.md, developer guide, and
example collection upstream. Link to them as appropriate rather than copying
them into a parallel local handbook. The upstream `agents/AGENTS.md` is the
downstream orientation template, distinct from upstream's own root AGENTS.md.
Copy only needed standard license texts, not the entire reference collection.
## Scope And Completion Criteria
This work updates policy and supporting documentation. It does not change
application code, dependency versions or grants, release scripts, publication
mechanics, or accepted ADR decisions. No new scanner, recurring synchronization
check, license approval, publication-time network probe, or release gate is
introduced. Published releases, tags, notes, and assets remain unchanged.
Completion means:
- All seven policy files use the selected versions, accurate source links,
adoption dates, and upstream common wording, with template-only content
removed and local variations limited to the justified decisions above.
- Orientation and selective reading agree, and local links resolve without
depending on a sibling checkout.
- Policy attribution and document-license scope match the material actually
incorporated; required standard texts are complete and unmodified.
- README, attribution, release navigation, and still-operative roadmap
handoffs agree with the new conventions. Historical implementation evidence
remains available through the Git references in the implementation plan,
without making old footer directions current policy. The earlier
author-selected license change remains in the next release's preparation
context; publication remains separate work.
- Review checks the resulting rules, source/example URLs, notice facts, local
links, license-text fidelity, and final diff. Runtime tests are unnecessary
for documentation-only changes. A Git adoption record is sufficient; no
additional provenance database or recurring audit is required.
There are no unresolved policy choices for this scope.

View File

@@ -1,352 +0,0 @@
# Promptkit v0.9.0 Adoption Roadmap
## Status
Complete. This document records the delivered feature scope and targeted end
state. The completed delivery plan is preserved at
`git show e4405966c87c8a7843b340146e90cc1e515bef42:docs/roadmap/implementation.md`;
current behavior remains defined by
the canonical application contracts linked below.
The durable product and integration boundary for this work is established by
[ADR 0004](../adr/0004-definition-boundary.md). This roadmap applies that
decision to Promptkit v0.9.0 and owns implementation scope and completion
status.
## Objective
Bring Scriptorium from Promptkit v0.1.0 to v0.9.0 and expose the newer
framework capabilities that fit Scriptorium's existing CLI, HTTP,
configuration, presentation, and process boundaries.
Scriptorium must accept the complete Promptkit v0.9.0 feature set expressed by
directory-backed prompt, profile, and schema definitions. Application adapters
must not narrow that format contract by requiring request values that the
selected definition does not require or by omitting selection values needed to
address a valid definition. Promptkit's tagged
[framework format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.9.0/docs/formats.md)
remains canonical; Scriptorium must delegate parsing and framework validation
rather than reproduce those rules.
The completed application will retain Promptkit as the owner of reusable
prompt execution, source formats, profiles, backend definitions, capacity,
inspection, generation, and validation. Scriptorium will continue to own
application configuration, command and HTTP contracts, error and exit mapping,
output presentation, and deployment policy.
## Targeted End State
When this roadmap is complete:
- Scriptorium pins the released Promptkit v0.9.0 module without a workspace,
replacement, vendored source, direct catalog import, or Promptkit internal
import.
- Existing valid CLI, HTTP, configuration, prompt, profile, schema, and render
workflows remain supported subject to Promptkit's documented v0.2.0 through
v0.9.0 compatibility corrections.
- Every Promptkit v0.9.0 prompt and profile feature expressible in definitions
under Scriptorium's configured directory sources is usable through the
executable application, including prompts with no inputs and explicitly
selected prompt versions.
- CLI and HTTP requests can supply a direct non-secret session ID.
- HTTP requests and a presence-aware CLI flag can inherit, replace, or
explicitly clear reasoning effort.
- Prepared output, CLI run summaries, and HTTP result metadata expose effective
backend identity when Promptkit supplies one.
- HTTP capacity rejection has a stable Scriptorium-owned overload response.
- Application configuration can register reusable engine-scoped custom
backends, including bounded concurrency and queue policy, for selection by
Promptkit profiles.
- CLI users can inspect prompt and profile definitions without supplying
placeholder inputs or invoking a model.
- Scriptorium's contracts and examples point to Promptkit v0.9.0 and accurately
describe its current credential, validation-repair, provider-control,
message-role, backend, and source-validation semantics.
## Feature Scope
### Complete Prompt And Profile Definition Compatibility
Scriptorium will treat the tagged Promptkit v0.9.0 format contract as one
indivisible downstream compatibility boundary. This includes prompt identity
and version selection, optional and required input declarations, message and
content-file templates, supported roles, cache control, session templates,
default profiles, output contracts, schemas, and repair budgets. It also
includes standalone and inherited profiles, built-in and custom backend
selection, endpoint overrides, execution controls, optional credential
environment sources, and JSON-compatible extra parameters.
Most of this support is provided by passing configured prompt, profile, and
schema directories directly to Promptkit. Scriptorium will not independently
decode these framework definitions or maintain a field-level subset. Two
current adapter restrictions must be removed so the executable interfaces do
not reject definitions that Promptkit accepts:
- `run` and `render` will accept an optional prompt-version flag and map it to
`promptkit.RunRequest.PromptVersion`; and
- `run`, `render`, and `POST /v1/runs` will permit omitted or empty input maps.
Promptkit will decide whether an input is required by the selected
definition or referenced template.
The HTTP API already carries `prompt_version`; its mapping must remain covered
by adapter tests. CLI and HTTP callers may continue to supply extra inputs,
subject to their existing file, containment, and size policies. Removing the
application-level nonempty-input requirement does not weaken Promptkit's
declared-required-input or template-reference validation.
Profiles that name built-in backend IDs require no application registration.
Profiles that name other backend IDs become fully usable through the custom
backend configuration in this roadmap. Profile inheritance and all other
profile-field resolution remain Promptkit responsibilities.
This compatibility requirement concerns fields and behavior expressed in
Promptkit YAML definitions. Go-consumer construction alternatives such as
single-file sources, injected `fs.FS` sources, in-memory profiles, fallback
profile filesystems, and prepared-execution handles are library-integration
features and are not required merely to support the complete definition
format.
### Promptkit v0.9.0 Compatibility Baseline
Required dependency and source changes:
- update `go.mod` and `go.sum` to select Promptkit v0.9.0 and its selected
OpenRouter and Rakestrawhome catalog dependencies;
- change Scriptorium's inbound HTTP reasoning-effort representation to preserve
Promptkit's pointer semantics;
- retain keyed Promptkit public struct literals and confirm no removed
`RunRequest.Metadata` use exists;
- update tagged Promptkit links and version references throughout Scriptorium;
and
- preserve Scriptorium's architecture guard against replacements, workspaces,
vendored Promptkit code, former facade packages, and Promptkit internal
imports.
Required compatibility review:
- verify application and maintained example endpoints satisfy Promptkit's
absolute HTTP/HTTPS endpoint rules;
- verify prompt content paths, file artifacts, identities, JSON documents, and
JSON-compatible extra parameters satisfy the v0.6.0 safety boundaries;
- verify maintained prompt roles are limited to `developer`, `system`, `user`,
and `assistant`;
- verify every positive repair budget is no greater than three and is paired
with `basic`, `json`, or `json_schema` validation;
- document that positive repair budgets authorize additional provider calls,
latency, token use, and cost;
- document that unset optional provider controls are omitted and that a zero
effective value can represent an unspecified provider control unless an
explicit request override supplied it; and
- update credential guidance for Promptkit's optional environment lookup
behavior, profile `api_key_env` semantics, and Scriptorium's prohibition on
raw API-key inputs.
### Session And Reasoning Request Controls
The CLI `run` and `render` commands will accept a direct session-ID flag and map
it to `promptkit.RunRequest.SessionID`. The value remains non-secret
application correlation metadata and is subject to Promptkit's normalization
and length rules.
The HTTP run request will accept `session_id` and map it through the existing
strict DTO boundary. Successful HTTP metadata will report the effective
session ID when present.
The CLI `run` and `render` commands will also accept a presence-aware reasoning
effort flag. Omission inherits the selected profile, a nonblank value replaces
it, and an explicitly supplied empty value clears it. The existing HTTP
`model.reasoning_effort` field will gain the same three-state behavior while
remaining a JSON string when present.
These additions must not introduce raw direct API-key flags or fields.
### Backend Identity And Capacity Outcomes
Scriptorium presentation will expose `SelectedBackendID` and the effective
target's `BackendID` without deriving identity from endpoint text. Backend
identity will be included where applicable in:
- prepared-run text and JSON output;
- the CLI run summary; and
- HTTP response metadata and effective model parameters.
Endpoint-only profiles continue to have no backend ID, and empty identities
must remain distinguishable from registered built-in or custom backends.
The HTTP adapter will classify `promptkit.ErrCapacityExceeded` separately from
provider generation failures. The target public outcome is HTTP `503` with a
stable `capacity_exceeded` code and a generic message. Scriptorium will not
invent retry timing or expose an untrusted diagnostic. CLI capacity rejection
continues to be a runtime failure, with a clear safe diagnostic and the
existing runtime-error exit status.
The HTTP server will use one appropriately scoped Promptkit engine across its
requests so backend admission, active-generation limits, and queue capacity
apply across concurrent in-flight work. The server may retain the operational
state needed for those limits and for request cancellation and lifecycle
management. This does not create durable per-request, conversation, or resume
state.
Scriptorium will continue to return generic public model-generation failures.
Promptkit `GenerationError` provider code, type, and message values will not be
added to the public HTTP response because they are untrusted and potentially
sensitive.
### Custom Backend Configuration
The strict Scriptorium application configuration will gain an optional custom
backend collection. Each entry will support the application-owned mapping
needed to construct a public `promptkit.Backend`:
- backend ID;
- OpenAI-compatible endpoint;
- optional API-key environment-variable name;
- optional JSON-compatible request-wide extra parameters;
- non-negative concurrency limit; and
- queue capacity with presence preserved so omission and explicit zero remain
different.
Raw API-key values will remain invalid. Unknown fields will remain errors.
Configured backends will be registered through `promptkit.WithBackend` during
engine construction and will be immutable and engine-scoped. Promptkit will
remain the canonical validator for backend IDs, endpoints, reserved request
parameters, capacity bounds, duplicate or reserved IDs, environment-variable
names, and JSON-compatible values. Scriptorium will add context appropriate to
its configuration error boundary without copying those framework rules.
The collection will be configuration-file-owned. This roadmap does not add
per-backend CLI flags. Existing endpoint-only profiles remain valid, while
profiles may select configured custom backend IDs through Promptkit's existing
`backend` field. Promptkit's built-in OpenRouter and Rakestrawhome backends and
profiles remain available without Scriptorium registration.
The application configuration shape is a `backends` mapping whose keys are the
backend IDs registered with Promptkit:
```yaml
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0
```
`endpoint` is required for each entry. The other fields are optional. Omitted
`queue_capacity` uses Promptkit's default queue policy when concurrency is
bounded, while an explicit zero disables queuing. The configuration contract
and complete maintained configuration example will document this shape when
the feature is implemented.
### Prompt And Profile Inspection CLI
Scriptorium will add a CLI inspection command with prompt and profile modes.
The intended command family is:
- `scriptorium inspect prompt`, backed by `Engine.InspectPrompt`; and
- `scriptorium inspect profile`, backed by `Engine.InspectProfile`.
Prompt inspection will select an ID and optional version and report the
normalized prompt identity, opaque prompt hash, declared default profile,
declared inputs, and normalized output contract. It will not require input
artifacts, resolve a profile, load a schema, render templates, reserve backend
capacity, or contact a model.
Profile inspection will select an explicit profile ID and report its resolved
effective target, backend identity, optional credential source name, and
whether a later request must provide credential configuration. It will not
read credential values, load a prompt, reserve capacity, or contact a model.
Inspection will support deterministic Scriptorium-owned text and JSON output
and normal output-file handling. Scriptorium will define explicit output DTOs
rather than treating Promptkit inspection structs as stable wire formats.
Inspection failures will use existing public Promptkit error identities and
Scriptorium-owned CLI diagnostics and exit behavior.
The prompt form accepts `--prompt`, optional `--prompt-version`, `--config`,
`--prompt-dir`, `--format text|json`, and `--out`. The profile form accepts
`--profile`, `--config`, `--profile-dir`, `--format text|json`, and `--out`.
Both forms reject positional arguments and default to text output independently
of `defaults.render_format`. Configuration discovery and CLI-over-file source
precedence match the existing command family. Prompt inspection requires an
effective prompt directory; profile inspection does not, because Promptkit's
built-in profiles remain inspectable without one.
## Documentation And Example Changes
Implementation of this roadmap requires coordinated updates to the canonical
owners of affected behavior:
- `docs/cli.md` for session and reasoning flags, inspection commands, output,
prompt-version selection, optional inputs, and exit behavior;
- `docs/api.md` for `session_id`, effective backend/session metadata, reasoning
presence semantics, optional inputs, and the capacity response;
- `docs/config.md` for custom backend configuration and current Promptkit
credential and provider-default semantics;
- `docs/operations.md` for capacity and custom-backend operational guidance
where deployment handling is affected;
- `docs/internal/adapters.md` and `docs/internal/sources.md` for implemented
mapping and engine-assembly behavior;
- `docs/policy/architecture.md` and `docs/internal/overview.md` only if concrete
component responsibilities or durable boundaries change; and
- maintained examples for valid v0.9.0 prompt/profile formats and custom
backend configuration.
Current-state documents must not describe these features as implemented until
the corresponding code lands.
## Validation And Completion Criteria
The roadmap is complete only when:
- ordinary and race-enabled tests pass against the tagged Promptkit v0.9.0
dependency;
- `go vet ./...` and `go build ./cmd/scriptorium` pass;
- Go formatting and `git diff --check` pass;
- the architecture guard passes with no workspace, replacement, vendor tree,
former facade, or Promptkit internal import;
- maintained render, custom-backend, session, reasoning, and inspection
examples execute successfully without real credentials or provider calls;
- CLI tests cover explicit and omitted prompt versions for prompt IDs with one
or multiple definitions;
- CLI and HTTP tests cover prompts with no declared inputs, omitted optional
inputs, missing required inputs, and template-referenced inputs;
- HTTP tests cover omitted, replacement, and clearing reasoning states;
- CLI and HTTP tests cover session propagation and invalid session handling;
- presentation tests cover registered and endpoint-only backend identity;
- HTTP tests cover capacity rejection independently from provider failure;
- concurrent HTTP tests demonstrate that one server's requests share backend
admission and cannot bypass capacity through per-request engine creation;
- configuration tests cover strict decoding, precedence, queue-capacity
presence, invalid backends, and secret-field rejection;
- inspection tests cover deterministic text and JSON, source selection,
output-file handling, safe credential presentation, and public error
mapping;
- all maintained prompt roles and repair budgets are valid under Promptkit
v0.9.0; and
- representative definition fixtures cover inline and file-backed messages,
cache control, session templates, every output validation mode, schemas,
profile inheritance, built-in and custom backends, execution controls,
credential environment names, and extra parameters without Scriptorium
independently parsing those fields; and
- affected documentation links and copyable examples validate successfully.
## Explicit Non-Goals
This roadmap does not include:
- appended request messages in either executable interface;
- retained or durable prepared-execution handles;
- HTTP prompt or profile inspection routes;
- embedded application fallback profiles;
- single-file, injected `fs.FS`, or in-memory prompt and profile source
configuration;
- request-level output-contract replacement through the executable interfaces;
- public disclosure of structured provider error details;
- direct imports or configuration of Promptkit's external catalog modules;
- raw API-key configuration, CLI flags, or HTTP fields;
- durable run state, conversations, retries, archives, checkpoints, or resume;
or
- changes to Promptkit itself.

View File

@@ -1,77 +0,0 @@
# Promptkit Upgrade Review Remediation
## Scope And Status
Review baseline: `e177d7c`, covering implementation commits after `5c3b0cf`.
This document records a resolved test-contract issue; it does not authorize
unrelated implementation changes. No runtime defect or missing planned feature
was identified in this review. Release preparation remains separate work.
## R1: Remove The Unrequested Context-Identity Invariant
Priority: P3 (low). Status: Complete.
Original location: `internal/adapter/http/handler_test.go:334–349`,
`TestHandlerRunTimeoutValidationAndContextMapping`, introduced in `7de2b02`.
The test's `child` field and `(ctx != parent) != tc.child` assertion required
the exact parent context object for omitted/null/zero timeouts and a distinct
object for a positive timeout. The requested contract concerns effective
deadlines and cancellation propagation, not Go interface identity. In
particular, a harmless derived context that preserves the parent's deadline,
values, and cancellation would fail the omission cases despite satisfying the
application contract.
This elevated an incidental implementation choice into a test-enforced
invariant, contrary to the [agent policy](../policy/agents.md) and
[testing policy](../policy/testing.md). The current handler's context behavior
is correct; this is a maintainability issue, not a runtime cancellation bug.
### Required Change
Remove the identity comparison and the identity-only table field. Retain
behavioral assertions that an earlier parent deadline is not extended and
parent cancellation reaches execution. For omitted/null/zero values, verify
that no deadline is introduced when the parent has none. Retain coverage of
positive deadlines and the distinction between a canceled execution context
and a provider-attempt timeout while the execution context remains live.
Use the existing runner seam and focused cases; do not introduce a context
wrapper framework, timer abstraction, new public guarantee, or production
refactor solely to change this test.
### Completion Criteria
- Tests protect effective deadline/cancellation behavior without requiring
context object identity.
- A semantically equivalent derived context does not fail merely because it
is a different object.
- Existing timeout validation and HTTP outcome coverage remains intact.
### Resolution And Validation
Removed the identity-only table field and context comparisons. The test now
checks effective deadlines, including omitted/null/zero requests with no
parent deadline, and explicitly checks that parent cancellation reaches the
runner. Existing positive-deadline integration tests and live-context
provider-timeout mapping remain intact. No production code changed.
Focused HTTP timeout tests, `go test ./...`, `go test -race ./...`,
`go vet ./...`, a native build outside the repository, and `git diff --check`
all passed after remediation.
## Original Review Verification
- `go test -race -count=1 ./...` passed, including retry, shared-capacity,
deadline, report, definition-conformance, and architecture-boundary tests.
- `go vet ./...` passed.
- A native `cmd/scriptorium` build passed, with output outside the repository.
- The selected dependency is Promptkit v0.11.0 with its intended v2 catalogs.
- Application code, tests, release automation, and historical releases were
not changed during this review.
The runtime ownership boundaries remain as intended: Promptkit owns framework
formats, execution, retries, and backend admission; Scriptorium owns executable
adapters, application settings, HTTP artifact policy, deadlines, and terminal
report presentation. No additional runtime restrictions, durable workflow
state, or extra release compliance gates were identified in the reviewed diff.

View File

@@ -1,274 +0,0 @@
# Promptkit v0.11 Adoption
## Status And Intent
Accepted feature direction, recorded on 2026-09-26. Implementation is complete
to the pre-release boundary; version selection, release-candidate validation,
and publication remain separate release preparation. The baseline descriptions
below record the state when this roadmap was written, not current behavior.
Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening
v0.10.0 catalog transition. This document defines the desired end state and
the changes from the current baseline. The historical plan at
`git show 43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c:docs/roadmap/implementation.md`
owns sequencing, concrete interface choices, verification steps, and unresolved
implementation decisions.
The target is complete definition compatibility, controllable transient
retries, an optional whole-run deadline, and modest opt-in execution diagnostics.
This is a focused adapter and configuration update, not another architecture
migration. Optional diagnostics are included in the desired feature set.
“Optional” means callers opt in, not that diagnostics may be silently omitted
from the completed adoption or appear in default output.
[ADR 0004](../adr/0004-definition-boundary.md) and the
[architecture policy](../policy/architecture.md) govern scope. Promptkit remains
the parser, validator, execution engine, and owner of framework defaults.
Scriptorium remains a simple executable application for independent prompt
executions, with shared operational state where required for backend limits.
## Baseline And Upstream Changes
Scriptorium currently selects Promptkit v0.9.0 and the v1.0.0 backend catalog
modules. It already supports CLI execution, rendering, prompt/profile
inspection, HTTP execution, configured backends, and presence-aware execution
overrides. It does not expose transient retry settings, a whole-run deadline,
or execution observers. CLI execution currently supplies a background context.
The upstream review covered the local tagged release v0.11.0 at commit
`db05b56166ca2d8650dfaf660e1cf0eed3932e1d`. Its canonical references are:
- [v0.10.0 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md);
- [v0.11.0 release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/releases/v0.11.0.md);
- [definition formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md);
- [execution and retry integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md);
- [consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md); and
- [observation declarations](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/observations.go).
A diagnostic run using a temporary module file compiled Scriptorium against
v0.11.0. The existing test suite reported one failing profile-inspection case
that selects the removed `deepseek-4-flash` profile; other packages passed.
This establishes an initial migration issue, not proof of complete behavioral
compatibility or coverage of the new capabilities. The diagnostic did not
change the repository dependency pin.
Neither intervening release adds declarative prompt/profile fields requiring
new adapter plumbing. The definition-facing changes concern catalog contents
and resolution precedence. Retry and observer APIs are execution controls;
their adoption is a deliberate case-by-case choice under ADR 0004.
## Dependency And Definition Compatibility
### Target End State
Scriptorium uses tagged Promptkit v0.11.0 through its supported root package,
with the catalog versions selected by that release:
- `promptkit-backend-openrouter/v2` v2.20260922.1;
- `promptkit-backend-rakestrawhome/v2` v2.20260922.0.
Valid definitions for the selected Promptkit version remain usable through
Scriptorium's existing sources and adapters, subject to its established HTTP
artifact and deployment boundaries. Rendering and inspection remain offline
operations that do not generate model output.
The maintained names `promptkit-openrouter-standard` and
`promptkit-openrouter-auto` work wherever a profile ID is accepted, including
prompt defaults, explicit selection, inheritance, and profile inspection.
They are opt-in choices, not new Scriptorium defaults. Ordinary custom-source
precedence remains intact.
A stable maintained name is not a frozen model/settings selection. External
catalog entries can change or disappear across upgrades; inheriting from one
does not create a frozen copy. Complete application-owned profiles remain the
appropriate choice when an application owns its model and settings.
### Change From Baseline
The module graph and active definition fixtures reflect the released v0.11
catalogs rather than v0.9's catalogs. The selected catalog removes
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro`; newer DeepSeek names
are not compatibility aliases. Migration guidance offers an available catalog
profile, a maintained Promptkit name, or a complete application-owned definition.
Application-owned examples retain fixed settings where that is their purpose.
Definition conformance and focused resolution coverage protect Scriptorium's
adapter boundary without duplicating the upstream parser or catalog. Existing
dependency boundaries also apply to the new `/v2` module paths.
## Controllable Transient Retries
### Target End State
Expose `transient_retries` in application configuration, with a CLI execution
override and an HTTP request override. Preserve value presence throughout:
| Value | Meaning |
| --- | --- |
| Omitted | Inherit the engine setting, ultimately Promptkit's default. |
| Zero | Disable additional transient attempts. |
| Positive integer | Permit that many additional transient attempts. |
| Negative integer | Invalid configuration or request. |
Adopt Promptkit's default of two additional attempts rather than silently
pinning the previous single-attempt behavior. Users must be able to select zero
explicitly. Request overrides take precedence over application configuration;
omission must not accidentally become an explicit zero.
Promptkit alone owns eligible statuses, attempt execution, backoff,
`Retry-After`, and capacity coordination. Scriptorium adds no outer model retry
loop. Transient retries and structural repairs have distinct budgets: each
generation, including each repair generation, receives its transient budget.
Retries do not imply exactly-once generation or complete billing knowledge.
### Change From Baseline
Application settings reach `promptkit.Config.TransientRetries`, including the
shared server engine, and request overrides reach
`promptkit.RunRequest.TransientRetries`. This adds execution controls, not
prompt/profile schema fields or provider model parameters. Strict decoding and
presence-aware mapping preserve inheritance and explicit zero. User and
operations guidance makes the changed default, latency/cost implications, and
independent repair budget visible. Cancellation and shared backend limits
remain effective during retrying executions.
## Optional Whole-Run Deadline
### Target End State
Callers can opt into a total execution deadline independently of the existing
generation timeout. No new default deadline is imposed. Existing timeout
controls must not silently change meaning: in v0.11.0 they apply per generation
attempt, whereas a whole-run deadline bounds the overall operation, including
preparation, capacity waiting, retry delays, attempts, and repairs as supported
by the upstream context contract.
Expose this choice through CLI execution and HTTP execution. Derive any timeout
context from the caller's existing context, so a caller cancellation or earlier
deadline still wins. This is a cancellation boundary, not a guarantee of
instantaneous interruption of arbitrary callback or filesystem code.
### Change From Baseline
CLI execution can carry a selected deadline instead of always using an
unbounded background context. HTTP execution can shorten the incoming context
without losing parent cancellation or changing server lifecycle behavior.
Total-run duration handling is separate from existing attempt-timeout conversion.
The interval covers the engine invocation, not adapter parsing, engine creation,
or output writing. Provider retry timing can exceed local backoff limits;
per-attempt timeouts do not cap that complete invocation.
## Opt-In Execution Reports
### Target End State
Provide a modest terminal execution report for CLI and HTTP callers who opt
in. Capture selected metadata through `RunRequest.Observer`, including attempt,
retry, repair, timing, outcome, and presence-aware usage information. Reports
should be available for completed successful and failed execution invocations
when Promptkit supplies terminal observations. Do not invent execution data for
failures that occur before invocation.
Keep generated CLI content on stdout or the existing output path. Execution
reports use a separate destination. Ordinary CLI output and HTTP response
shapes remain unchanged when reporting is not requested.
The report has a Scriptorium-owned schema rather than serializing upstream
events directly: `ExecutionEvent` has no stable JSON contract. Preserve unknown
usage versus reported zero, and incomplete versus complete observed totals.
Existing successful-result usage semantics remain unchanged. A terminal total
is an aggregate, not another attempt to add to the bill; no report is a billing
ledger.
### Change From Baseline
Both adapters have opt-in reporting and explicit application-owned report DTOs.
Per-request collection adds no shared mutable report state, durable storage,
callback I/O, or event archive. Operational failures can carry reports without
manufacturing partial `RunResult` values. Default output remains unchanged.
Reports exclude prompt and response bodies, credentials, headers, endpoint URLs,
provider diagnostic text, and raw errors. Selected identifiers remain potentially
sensitive even when observations are content-free. Reports are concise terminal
metadata, not a general telemetry framework, event stream, or durable history.
## Errors And Compatibility
Preserve existing CLI exit classifications and HTTP `502 / llm_failed`
classification for generation failures. Keep safe public messages rather than
exposing provider error bodies or parsing diagnostic strings.
Promptkit adds `ErrTransport`, `ErrMalformedResponse`, `ErrRetriesExhausted`, and
`RetryExhaustedError`. Use their public identities to support optional structured
failure details in execution diagnostics, including actual attempts where
available. Retry exhaustion and the final cause are distinct facts; do not lose
the underlying failure category by flattening them into one label.
Capacity and validation behavior remains intact. Whole-run deadline and caller
cancellation outcomes are deliberate adapter classifications, distinct from a
provider-attempt timeout while the caller context is still live. The implementation
plan owns the exact presentation choices. Existing generation-error codes do
not need a breaking replacement for this upgrade.
## Licensing And Distribution Review
Promptkit v0.11.0 changes from GPLv3 to LGPL-3.0-or-later. Scriptorium's current
binary workflow produces statically linked Go executables, and upstream's
[license summary](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/README.md#license)
explicitly calls out distribution considerations for that model. Catalog and
other dependency licenses remain separate.
Before distributing the upgraded binaries, resolve the applicable notices,
license texts, source availability, and any required materials or permissions
for recombination with a modified library. Record the chosen distribution
approach and make any corresponding packaging/documentation changes. This
roadmap is not a legal determination or a complete compliance checklist.
Do not automatically relicense Scriptorium, assume that library source alone
settles every distribution requirement, or alter historical release contents.
Licensing review is a concrete adoption prerequisite, not a new blanket manual
approval gate for every future release.
## Documentation And Delivery
Current documentation links to the selected v0.11.0 contracts once implemented.
CLI, HTTP, configuration, and operations documents own their respective new
behavior; internal docs explain adapter mapping; release notes summarize
compatibility impact. Historical release notes and ADR decision content remain
unchanged. Current examples and migration guidance reflect the selected version.
The upgrade merits a minor Scriptorium release, not a compatibility patch,
with prominent migration guidance for removed profiles, changed retry behavior,
the explicit single-attempt option, and timeout layering. Any later decision to
defer part of the target leaves that feature visibly incomplete until delivered.
Use the existing [release policy](../policy/release.md) and
[runbook](../release.md). This roadmap authorizes no publication. No new ADR is
needed unless a later decision changes the established product or compatibility
boundaries.
## Completion Criteria
- The tagged dependency and selected catalog modules are adopted without
unsupported imports or local dependency substitutions.
- Existing definition conformance tests and focused maintained-profile tests
pass; removed profile IDs have explicit migration guidance, not silent aliases.
- Retry settings preserve omission and zero across configuration, CLI, and HTTP;
Promptkit remains the sole retry/capacity implementation.
- Optional total deadlines bound the caller operation without redefining
per-attempt timeouts or disabling parent cancellation.
- Opt-in terminal reports provide safe, isolated, presence-aware execution
metadata without changing default output or creating durable workflow state.
Any deferred reporting work remains visibly incomplete.
- Existing error classifications remain compatible, with deliberate handling
of the new public identities and context outcomes.
- The licensing/distribution approach is resolved before upgraded binary
distribution, and any required materials are included in the chosen workflow.
- Affected current contracts, examples, and migration guidance match
implemented behavior. Relevant tests remain offline and credential-free,
and normal development validation passes. Release-candidate validation and
the version-matched note remain release preparation.
Concrete interface decisions and the selected distribution approach are recorded
in that completed historical plan. They do not expand
the product into conversations, follow-up messages, application-owned semantic
retry loops, prepared-handle coordination, or multi-step workflows.

View File

@@ -0,0 +1,6 @@
config:
imports:
- path: collections.yml
required: true
- path: profiles/local-gpu.yml
required: true

5
examples/collections.yml Normal file
View File

@@ -0,0 +1,5 @@
config:
imports:
- dir: config-fragments/collections
pattern: '*.yml'
required: true

View File

@@ -1,4 +0,0 @@
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY

View File

@@ -0,0 +1,4 @@
config:
imports:
- path: ../../framework/backends.yml
required: true

View File

@@ -0,0 +1,4 @@
config:
imports:
- path: ../../profiles/local-fast.yaml
required: true

View File

@@ -0,0 +1,4 @@
config:
imports:
- path: ../../prompts/generic.markdown_summary.yaml
required: true

View File

@@ -1,3 +1,3 @@
prompt_dir: ./examples/prompts promptkit:
profile_dir: ./examples/profiles configuration: ./examples/promptkit.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas

View File

@@ -0,0 +1,3 @@
promptkit:
configuration: ./examples/collections.yml
schema_dir: ./examples/schemas

View File

@@ -1,8 +1,8 @@
# Select from the repository root; application paths remain working-directory-relative. # Select from the repository root; application paths remain working-directory-relative.
configkit: config:
imports: imports:
- path: config-fragments/sources.yml - path: config-fragments/sources.yml
- path: config-fragments/backend.yml required: true
server: server:
addr: :8080 addr: :8080

View File

@@ -0,0 +1,2 @@
promptkit:
configuration: ./examples/discovery/framework.yml

View File

@@ -1,15 +1,6 @@
prompt_dir: ./examples/prompts promptkit:
profile_dir: ./examples/profiles configuration: ./examples/promptkit.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0
server: server:
addr: 127.0.0.1:8080 addr: 127.0.0.1:8080
@@ -17,6 +8,3 @@ server:
max_request_bytes: 16777216 max_request_bytes: 16777216
max_artifact_bytes: 16777216 max_artifact_bytes: 16777216
max_response_bytes: 16777216 max_response_bytes: 16777216
defaults:
render_format: text

View File

@@ -0,0 +1,4 @@
# Application paths are relative to the repository invocation directory.
promptkit:
configuration: ./examples/inheritance.yml
schema_dir: ./examples/schemas

View File

@@ -1,10 +1,7 @@
prompt_dir: ./examples/prompts promptkit:
profile_dir: ./examples/profiles configuration: ./examples/promptkit.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas
server: server:
addr: :8080 addr: :8080
artifact_root: . artifact_root: .
defaults:
render_format: text

8
examples/definitions.yml Normal file
View File

@@ -0,0 +1,8 @@
config:
imports:
- dir: prompts
pattern: '*.yaml'
required: true
- dir: profiles
pattern: '*.y*ml'
required: true

View File

@@ -0,0 +1,12 @@
config:
imports:
- path: profiles/base.yaml
destination: [collections, review, profiles]
placement: sequence-item
required: true
- path: prompts/answer.yaml
destination: [collections, review, prompts]
placement: sequence-item
required: true
collections:
review: {}

View File

@@ -0,0 +1,3 @@
id: base
endpoint: https://example.invalid/v1
model: review-example

View File

@@ -0,0 +1,8 @@
id: answer
default_profile: review/base
messages:
- role: user
content: Review this material and report your findings.
output:
format: text
validation_mode: none

View File

@@ -0,0 +1,20 @@
config:
imports:
- path: profiles/base.yml
destination: [collections, support, profiles]
placement: sequence-item
required: true
- path: profiles/fast.yml
destination: [collections, support, profiles]
placement: sequence-item
required: true
- path: prompts/answer.yml
destination: [collections, support, prompts]
placement: sequence-item
required: true
- path: prompts/summarize.yml
destination: [collections, support, prompts]
placement: sequence-item
required: true
collections:
support: {}

View File

@@ -0,0 +1,2 @@
repository_metadata:
purpose: This file is not a PromptKit framework input.

View File

@@ -0,0 +1,4 @@
id: base
endpoint: https://example.invalid/v1
model: support-example
temperature: 0.2

View File

@@ -0,0 +1,3 @@
id: fast
extends: {id: base}
max_tokens: 256

View File

@@ -0,0 +1,3 @@
Answer the support request using this transcript:
{{input "transcript"}}

View File

@@ -0,0 +1,12 @@
id: answer
default_profile: support/fast
inputs:
- name: transcript
required: true
content_type: text/markdown
messages:
- role: user
content_file: ./answer.md
output:
format: text
validation_mode: none

View File

@@ -0,0 +1,8 @@
id: summarize
default_profile: support/fast
messages:
- role: user
content: Summarize the support request concisely.
output:
format: text
validation_mode: none

View File

@@ -0,0 +1,4 @@
config:
imports:
- glob: collections/*/collection.yml
- glob: collections/*/collection.yaml

View File

@@ -0,0 +1,8 @@
backends:
- id: local-gpu
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0

View File

@@ -0,0 +1,13 @@
backends:
- id: local-base
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
concurrency_limit: 2
queue_capacity: 4
extra_params:
provider_option: true
- id: local-gpu
extends: {id: local-base}
queue_capacity: 0
extra_params:
provider_option: false

View File

@@ -14,5 +14,6 @@
"vars": { "vars": {
"session_date": "2026-05-04" "session_date": "2026-05-04"
}, },
"include_raw_output": false "include_raw_output": false,
"include_execution_report": false
} }

6
examples/inheritance.yml Normal file
View File

@@ -0,0 +1,6 @@
config:
imports:
- path: definitions.yml
required: true
- path: framework/inheritance.yml
required: true

View File

@@ -0,0 +1,2 @@
promptkit:
configuration: ./examples/collection-gpu.yml

View File

@@ -1,4 +1,2 @@
defaults:
render_format: json
server: server:
addr: 127.0.0.1:8080 addr: 127.0.0.1:8080

View File

@@ -1,7 +1,8 @@
id: local-fast profiles:
endpoint: http://localhost:8000/v1 - id: local-fast
model: gpt-4o-mini endpoint: http://localhost:8000/v1
temperature: 0.2 model: gpt-4o-mini
max_tokens: 500 temperature: 0.2
top_p: 1.0 max_tokens: 500
timeout_seconds: 90 top_p: 1.0
timeout_seconds: 90

View File

@@ -1,4 +1,5 @@
id: local-gpu profiles:
backend: local-gpu - id: local-gpu
model: local-model backend: local-gpu
reasoning_effort: low model: local-model
reasoning_effort: low

View File

@@ -1,8 +1,9 @@
id: local-quality profiles:
endpoint: http://localhost:8000/v1 - id: local-quality
model: gpt-4.1 endpoint: http://localhost:8000/v1
temperature: 0.0 model: gpt-4.1
max_tokens: 1200 temperature: 0.0
top_p: 1.0 max_tokens: 1200
timeout_seconds: 180 top_p: 1.0
api_key_env: SCRIPTORIUM_API_KEY timeout_seconds: 180
api_key_env: SCRIPTORIUM_API_KEY

6
examples/promptkit.yml Normal file
View File

@@ -0,0 +1,6 @@
config:
imports:
- path: definitions.yml
required: true
- path: framework/backends.yml
required: true

View File

@@ -1,8 +1,8 @@
id: dnd.session_recap prompts:
version: "1.0.0" - id: dnd.session_recap
default_profile: local-quality default_profile: local-quality
description: Example D&D session recap prompt definition for demonstration only. description: Example D&D session recap prompt definition for demonstration only.
inputs: inputs:
- name: transcript - name: transcript
required: true required: true
content_type: text/markdown content_type: text/markdown
@@ -11,12 +11,12 @@ inputs:
required: false required: false
content_type: text/yaml content_type: text/yaml
description: Optional glossary context description: Optional glossary context
messages: messages:
- role: system - role: system
content_file: ./dnd.session_recap.system.md content_file: ./dnd.session_recap.system.md
- role: user - role: user
content_file: ./dnd.session_recap.user.md content_file: ./dnd.session_recap.user.md
output: output:
format: markdown format: markdown
validation_mode: basic validation_mode: basic
repair_attempts: 0 repair_attempts: 0

View File

@@ -1,8 +1,8 @@
id: generic.markdown_summary prompts:
version: "1.0.0" - id: generic.markdown_summary
default_profile: local-fast default_profile: local-fast
description: Generic markdown summary from transcript and glossary. description: Generic markdown summary from transcript and glossary.
inputs: inputs:
- name: transcript - name: transcript
required: true required: true
content_type: text/markdown content_type: text/markdown
@@ -11,12 +11,12 @@ inputs:
required: false required: false
content_type: text/yaml content_type: text/yaml
description: Optional glossary context description: Optional glossary context
messages: messages:
- role: system - role: system
content_file: ./generic.markdown_summary.system.md content_file: ./generic.markdown_summary.system.md
- role: user - role: user
content_file: ./generic.markdown_summary.user.md content_file: ./generic.markdown_summary.user.md
output: output:
format: markdown format: markdown
validation_mode: basic validation_mode: basic
repair_attempts: 0 repair_attempts: 0

View File

@@ -1,8 +1,8 @@
id: generic.structured_events prompts:
version: "1.0.0" - id: generic.structured_events
default_profile: local-quality default_profile: local-quality
description: Produce structured event JSON from a transcript. description: Produce structured event JSON from a transcript.
inputs: inputs:
- name: transcript - name: transcript
required: true required: true
content_type: text/markdown content_type: text/markdown
@@ -11,12 +11,12 @@ inputs:
required: false required: false
content_type: text/yaml content_type: text/yaml
description: Optional glossary context description: Optional glossary context
messages: messages:
- role: system - role: system
content_file: ./generic.structured_events.system.md content_file: ./generic.structured_events.system.md
- role: user - role: user
content_file: ./generic.structured_events.user.md content_file: ./generic.structured_events.user.md
output: output:
format: json format: json
validation_mode: json_schema validation_mode: json_schema
schema_path: structured_events.schema.json schema_path: structured_events.schema.json

View File

@@ -5,9 +5,8 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$repo_root" cd "$repo_root"
go run ./cmd/scriptorium render \ go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
--config ./examples/config.yml \ --config ./examples/config.yml \
--prompt generic.markdown_summary \ --input-file transcript=./examples/fixtures/transcript.md \
--input transcript=./examples/fixtures/transcript.md \ --input-file glossary=./examples/fixtures/glossary.yml \
--input glossary=./examples/fixtures/glossary.yml \
--format text --format text

View File

@@ -4,22 +4,18 @@ set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$repo_root" cd "$repo_root"
go run ./cmd/scriptorium render \ go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
--config ./examples/config.full.yml \ --config ./examples/config.full.yml \
--prompt generic.markdown_summary \
--prompt-version 1.0.0 \
--profile local-gpu \ --profile local-gpu \
--session-id example-session \ --session-id example-session \
--reasoning-effort= \ --reasoning-effort= \
--input transcript=./examples/fixtures/transcript.md \ --input-file transcript=./examples/fixtures/transcript.md \
--input glossary=./examples/fixtures/glossary.yml --input-file glossary=./examples/fixtures/glossary.yml
go run ./cmd/scriptorium inspect prompt \ go run ./cmd/scriptorium promptkit show prompt generic.markdown_summary \
--config ./examples/config.full.yml \ --config ./examples/config.full.yml \
--prompt generic.markdown_summary \
--format json --format json
go run ./cmd/scriptorium inspect profile \ go run ./cmd/scriptorium promptkit show profile local-gpu \
--config ./examples/config.full.yml \ --config ./examples/config.full.yml \
--profile local-gpu \
--format json --format json

21
go.mod
View File

@@ -1,17 +1,20 @@
module gitea.maximumdirect.net/eric/scriptorium module gitea.maximumdirect.net/eric/scriptorium
go 1.25.5 go 1.27.0
require ( require (
gitea.maximumdirect.net/eric/ConfigKit v0.4.2 go.maximumdirect.net/ckconfig v0.9.0
gitea.maximumdirect.net/eric/promptkit v0.11.2 go.maximumdirect.net/ckprompt v0.10.0
go.maximumdirect.net/commandkit v0.7.0
go.maximumdirect.net/configkit v1.2.1
go.maximumdirect.net/promptkit v0.23.3
go.yaml.in/yaml/v4 v4.0.0
) )
require ( require (
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0 // indirect github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect github.com/spf13/cobra v1.10.2 // indirect
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect github.com/spf13/pflag v1.1.0 // indirect
golang.org/x/text v0.14.0 // indirect golang.org/x/text v0.44.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
) )

43
go.sum
View File

@@ -1,20 +1,29 @@
gitea.maximumdirect.net/eric/ConfigKit v0.4.2 h1:ZMxmv8pOnLtAx2hFTf8Z+pHKUbR89xErkBhwjr4yK24= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
gitea.maximumdirect.net/eric/ConfigKit v0.4.2/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
gitea.maximumdirect.net/eric/promptkit v0.11.2 h1:2RqI+KtflvSh7vLQaTAQCmMaFQscEA7EPwPazyvXRoY=
gitea.maximumdirect.net/eric/promptkit v0.11.2/go.mod h1:onm/FBPUKQ8/NSPwTEk26Ut+dVX2iXcq8vEseB+g/0E=
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0 h1:wdab+R+lgMZxzYwhbAuCrW7zdSQ1cW9ovBR6UzLmZR4=
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0/go.mod h1:a3VBbh9oaGXD6ruxhtwHj+AWW6DY/SSyby1QtMmYSUo=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0 h1:baCCIB6Ee5t0S4Zc++NTBIPcJEv5UPS6DlSrpZfykwg=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0/go.mod h1:mtgD1E0SGm0e/I8Ffhz+AYX7GN7RKUWJXehNFIKHs4Y=
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
go.maximumdirect.net/ckconfig v0.9.0 h1:s9Ikga4wt4K1NpLCX9bLhm5vbcm1Fgqy9yk2lmO4Sss=
go.maximumdirect.net/ckconfig v0.9.0/go.mod h1:yGjFVr2UzjJjiwDdMwsKehuQfvvtv7rTEOIk5NQOY00=
go.maximumdirect.net/ckprompt v0.10.0 h1:t2UyWSke+bWH9aTDrw5/bteD+TO0y5LD0NWw0y2KniQ=
go.maximumdirect.net/ckprompt v0.10.0/go.mod h1:vx8lZnelASctQtyxY2yV4PuTZfLpE9EqDa+LPj3+SHM=
go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
go.maximumdirect.net/promptkit v0.23.3 h1:bKbrkluwfgXUsm0e/mxz/TpV9b60yUtJLVUROLsM3VU=
go.maximumdirect.net/promptkit v0.23.3/go.mod h1:vPFg76VXcffP0JBFMS2WADCHwV5FYvO2O4bvIoiDlwc=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/text v0.44.0 h1:YItdp/mQNGnsmrgpcdA5yQ3bnRxCfo/Tj/iByGW9GGo=
golang.org/x/text v0.44.0/go.mod h1:S4FR1waQ9LbjQTls97SyRjDaUUVkaM+cXwwuG/G+MwY=
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=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

View File

@@ -0,0 +1,59 @@
package cli
import (
"errors"
"fmt"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
type applicationAcquisition struct {
sources []configkit.SourceInfo
records []configkit.Diagnostic
err error
}
// acquisitionState holds only presentation evidence for this invocation, never
// configuration or engines. Each reached loader still performs a fresh load.
type acquisitionState struct{ applications []applicationAcquisition }
// Native PromptKit adapters interpret a ConfigKit LoadError as framework
// evidence. Transport application acquisition failure separately so it cannot
// become a finding in the framework view. The callback decorator restores the
// original typed cause before the native command classifies the outcome.
var errApplicationAcquisition = errors.New("application configuration acquisition failed")
func (state *acquisitionState) mark() int {
if state == nil {
return 0
}
return len(state.applications)
}
func attachApplicationEvidence[T any](acquired commandkit.Acquired[T], err error, state *acquisitionState, start int, comparison bool) (commandkit.Acquired[T], error) {
if state == nil {
return acquired, err
}
for index, application := range state.applications[start:] {
context := "Application configuration"
if comparison {
side := "left"
if index > 0 {
side = "right"
}
context += " (" + side + ")"
}
diagnostics, explanation := ckconfig.AdaptDiagnostics(context+":\n", application.sources, application.records)
acquired.Diagnostics = append(acquired.Diagnostics, diagnostics...)
if acquired.Explanation.Message == "" {
acquired.Explanation.Message = explanation.Message
}
acquired.Explanation.Details = append(acquired.Explanation.Details, explanation.Details...)
if application.err != nil && errors.Is(err, errApplicationAcquisition) {
err = fmt.Errorf("%s: %w", context, application.err)
}
}
return acquired, err
}

View File

@@ -0,0 +1,42 @@
package cli
import (
"context"
"io"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/ckprompt"
"go.maximumdirect.net/commandkit"
)
// Execute composes the native CLI and returns its finalized outcome. The caller
// owns the context, streams, and process exit.
func Execute(ctx context.Context, identity commandkit.Identity, args []string, stdout, stderr io.Writer) commandkit.Outcome {
app, err := newApp(identity)
if err != nil {
return commandkit.Failure("Could not compose application commands.").WithCause(err)
}
return app.Execute(ctx, args, commandkit.Streams{Out: stdout, Err: stderr})
}
func newApp(identity commandkit.Identity) (*commandkit.App, error) {
definitions := promptSuite()
declarations := []commandkit.Declaration{
commandkit.NewCommand(commandkit.CommandSpec[serveInput]{Name: "serve", Summary: "Serve the HTTP API.", Flags: serveFlags(), Run: serveHTTP}),
configurationCommand(),
commandkit.Completion("scriptorium"),
}
declarations = append(declarations, runDeclarations()...)
declarations = append(declarations, ckprompt.Declarations(definitions)...)
return commandkit.New(identity, declarations...)
}
type serveInput struct {
Selection ckconfig.Selection
Application applicationInput
}
func serveFlags() []commandkit.Flag[serveInput] {
flags := configurationSelectors(func(input *serveInput) *ckconfig.Selection { return &input.Selection })
return append(flags, serverSelectors(func(input *serveInput) *applicationInput { return &input.Application })...)
}

View File

@@ -0,0 +1,44 @@
package cli
import (
"bytes"
"context"
"strings"
"testing"
"go.maximumdirect.net/commandkit"
)
func TestNativeMetadataWithoutConfiguration(t *testing.T) {
t.Chdir(t.TempDir())
for _, args := range [][]string{
{"--help"}, {"version"}, {"run", "--help"}, {"serve", "--help"},
{"config", "scopes"}, {"config", "show", "--help"},
{"promptkit", "--help"}, {"promptkit", "list", "prompts", "--help"},
{"completion", "bash"}, {"completion", "zsh"}, {"completion", "fish"},
} {
t.Run(strings.Join(args, " "), func(t *testing.T) {
var out, diagnostics bytes.Buffer
outcome := Execute(context.Background(), commandkit.Identity{Name: "scriptorium", Version: "test-version", Revision: "test-revision"}, args, &out, &diagnostics)
if outcome.Status != 0 || out.Len() == 0 {
t.Fatalf("outcome=%#v stdout=%q stderr=%q", outcome, out.String(), diagnostics.String())
}
if args[0] == "version" && !strings.Contains(out.String(), "test-version") {
t.Fatalf("version identity missing: %q", out.String())
}
})
}
}
func TestRemovedSourceAndSchemaFlagsAreRejected(t *testing.T) {
for _, command := range [][]string{{"run"}, {"serve"}, {"config", "show"}, {"promptkit", "list", "prompts"}} {
for _, flag := range []string{"--promptkit-source=missing.yml", "--schema-dir=schemas"} {
args := append(append([]string{}, command...), flag)
var output, diagnostics bytes.Buffer
outcome := Execute(context.Background(), commandkit.Identity{Name: "scriptorium"}, args, &output, &diagnostics)
if outcome.Kind != commandkit.OutcomeUsage || outcome.Status != 2 {
t.Fatalf("%v: %+v", args, outcome)
}
}
}
}

View File

@@ -1,71 +0,0 @@
package cli
import (
"errors"
"flag"
"fmt"
"io"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
)
// applicationOverrides keeps explicit application flags separate from invocation state.
func applicationOverrides(fs *flag.FlagSet) []configkit.Override {
var overrides []configkit.Override
fs.Visit(func(selected *flag.Flag) {
var path configkit.Path
switch selected.Name {
case "prompt-dir":
path = configkit.Keys("prompt_dir")
case "profile-dir":
path = configkit.Keys("profile_dir")
case "schema-dir":
path = configkit.Keys("schema_dir")
case "addr":
path = configkit.Keys("server", "addr")
case "artifact-root":
path = configkit.Keys("server", "artifact_root")
case "max-request-bytes":
path = configkit.Keys("server", "max_request_bytes")
case "max-artifact-bytes":
path = configkit.Keys("server", "max_artifact_bytes")
case "max-response-bytes":
path = configkit.Keys("server", "max_response_bytes")
default:
return
}
overrides = append(overrides, configkit.Override{
Path: path, Value: selected.Value.(flag.Getter).Get(), Flag: "--" + selected.Name,
})
})
return overrides
}
func loadApplicationSettings(configPath, overlay string, explicit bool, overrides []configkit.Override) (appconfig.AppSettings, []configkit.Diagnostic, error) {
result, err := appconfig.Load(appconfig.LoadOptions{
Path: configPath, Overlay: overlay, Explicit: explicit, Overrides: overrides,
})
if err != nil {
return appconfig.AppSettings{}, nil, err
}
return appconfig.Settings(result.Config), result.Diagnostics(), nil
}
func writeApplicationError(output io.Writer, label string, err error) {
var loadError *configkit.LoadError
if errors.As(err, &loadError) {
if writeErr := configkit.WriteDiagnostics(output, loadError.Diagnostics()); writeErr != nil {
_, _ = fmt.Fprintf(output, "%s diagnostic write error: %v\n", label, writeErr)
}
return
}
_, _ = fmt.Fprintf(output, "%s error: %v\n", label, err)
}
func writeApplicationWarnings(output io.Writer, diagnostics []configkit.Diagnostic) error {
if len(diagnostics) == 0 {
return nil
}
return configkit.WriteDiagnostics(output, diagnostics)
}

View File

@@ -1,104 +0,0 @@
package cli
import (
"encoding/json"
"flag"
"fmt"
"io"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
)
type configurationSource struct {
ID string `json:"id"`
Label string `json:"label"`
Layer configkit.Layer `json:"layer"`
Path string `json:"path,omitempty"`
}
func configCommand(args []string, stdout, stderr io.Writer) int {
if len(args) == 0 {
fmt.Fprintln(stderr, "config parse error: configuration mode is required")
return ExitRuntimeError
}
mode := args[0]
if mode != "validate" && mode != "show" && mode != "sources" && mode != "explain" {
fmt.Fprintln(stderr, "config parse error: unknown configuration mode")
return ExitRuntimeError
}
fs := flag.NewFlagSet("config "+mode, flag.ContinueOnError)
fs.SetOutput(io.Discard)
var path, overlay, pointer string
registerConfigSelectionFlags(fs, &path, &overlay)
registerConfigurationOverrides(fs)
if mode == "explain" {
fs.StringVar(&pointer, "path", "", "configuration path as a JSON Pointer")
}
if err := fs.Parse(args[1:]); err != nil {
writeApplicationError(stderr, "config parse", err)
return ExitRuntimeError
}
if fs.NArg() != 0 {
fmt.Fprintln(stderr, "config parse error: positional arguments are not accepted")
return ExitRuntimeError
}
var explanationPath configkit.Path
if mode == "explain" {
if !flagWasSet(fs, "path") {
fmt.Fprintln(stderr, "config parse error: --path is required")
return ExitRuntimeError
}
var err error
explanationPath, err = configkit.ParsePath(pointer)
if err != nil {
fmt.Fprintln(stderr, "config parse error: --path must be a JSON Pointer")
return ExitRuntimeError
}
}
result, err := appconfig.Load(appconfig.LoadOptions{
Path: path, Explicit: flagWasSet(fs, "config"), Overlay: overlay,
Overrides: applicationOverrides(fs),
})
if err != nil {
writeApplicationError(stderr, "config", err)
return ExitRuntimeError
}
if err := writeApplicationWarnings(stderr, result.Diagnostics()); err != nil {
return ExitRuntimeError
}
switch mode {
case "validate":
return ExitOK
case "show":
err = result.WriteEffective(stdout)
case "sources":
sources := make([]configurationSource, 0, len(result.Sources()))
for _, source := range result.Sources() {
sources = append(sources, configurationSource{
ID: source.ID, Label: source.Label, Layer: source.Layer, Path: source.Path,
})
}
err = json.NewEncoder(stdout).Encode(sources)
case "explain":
err = result.WriteExplanation(stdout, explanationPath)
}
if err != nil {
fmt.Fprintf(stderr, "config output error: %v\n", err)
return ExitRuntimeError
}
return ExitOK
}
func registerConfigurationOverrides(fs *flag.FlagSet) {
fs.String("prompt-dir", "", "prompt-definition directory override")
fs.String("profile-dir", "", "profile directory override")
fs.String("schema-dir", "", "schema directory override")
fs.String("addr", "", "HTTP listen address override")
fs.String("artifact-root", "", "HTTP artifact root override")
fs.Int64("max-request-bytes", 0, "HTTP request byte limit override")
fs.Int64("max-artifact-bytes", 0, "HTTP artifact byte limit override")
fs.Int64("max-response-bytes", 0, "HTTP response byte limit override")
}

View File

@@ -1,207 +0,0 @@
package cli
import (
"bytes"
"encoding/json"
"errors"
"io"
"os"
"path/filepath"
"strings"
"testing"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
)
func TestConfigCommandsInspectApplicationWithoutEngine(t *testing.T) {
path := writeAppConfigFile(t, "{}\n")
for _, mode := range []string{"validate", "show", "sources"} {
code, stdout, stderr := runCLICommand(t, configCommand, []string{mode, "--config", path})
if code != ExitOK || stderr != "" {
t.Fatalf("%s failed: code=%d stdout=%q stderr=%q", mode, code, stdout, stderr)
}
switch mode {
case "validate":
if stdout != "" {
t.Fatalf("validation wrote stdout: %q", stdout)
}
case "show":
if !strings.Contains(stdout, "render_format: text") || !strings.Contains(stdout, "max_request_bytes: 16777216") {
t.Fatalf("effective defaults missing: %q", stdout)
}
case "sources":
var sources []configurationSource
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 1 || sources[0].Layer != "base" {
t.Fatalf("unexpected source records: %q (%v)", stdout, err)
}
}
}
}
func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
dir := t.TempDir()
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
t.Fatal(err)
}
base := filepath.Join(dir, "config.yml")
for path, body := range map[string]string{
base: "configkit:\n imports:\n - path: fragment.yml\nprompt_dir: ' ./before/../prompts '\nprofile_dir: ./profiles\n",
filepath.Join(dir, "fragment.yml"): "server:\n addr: :8081\n",
filepath.Join(dir, "overlays", "local.yml"): "server:\n addr: :9090\n",
} {
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
t.Fatal(err)
}
}
args := []string{"--config", base, "--config-overlay", "local", "--profile-dir=", "--addr", ":7070"}
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"show"}, args...))
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "prompt_dir: prompts") || !strings.Contains(stdout, "profile_dir: ''") || !strings.Contains(stdout, "addr: :7070") {
t.Fatalf("resolved effective output changed: code=%d out=%q err=%q", code, stdout, stderr)
}
code, stdout, stderr = runCLICommand(t, configCommand, append([]string{"sources"}, args...))
if code != ExitOK || stderr != "" || !strings.HasSuffix(stdout, "\n") {
t.Fatalf("source command failed: code=%d out=%q err=%q", code, stdout, stderr)
}
var sources []configurationSource
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 5 {
t.Fatalf("unexpected composed source records: %+v (%v)", sources, err)
}
for i, layer := range []string{"base", "base", "overlay", "cli", "cli"} {
if string(sources[i].Layer) != layer {
t.Fatalf("source %d layer = %q, want %q", i, sources[i].Layer, layer)
}
}
}
func TestConfigInspectionKeepsReferencesAndOrdinaryParameters(t *testing.T) {
const name = "SCRIPTORIUM_CONFIG_TEST_API_KEY"
const secret = "synthetic-secret-value-should-not-appear"
path := writeAppConfigFile(t, `backends:
synthetic:
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_CONFIG_TEST_API_KEY
extra_params:
visible_parameter: synthetic-ordinary-value
`)
t.Setenv(name, secret)
for _, present := range []bool{true, false} {
if !present {
if err := os.Unsetenv(name); err != nil {
t.Fatal(err)
}
}
code, stdout, stderr := runCLICommand(t, configCommand, []string{"show", "--config", path})
if code != ExitOK || stderr != "" || !strings.Contains(stdout, name) || !strings.Contains(stdout, "synthetic-ordinary-value") || strings.Contains(stdout, secret) {
t.Fatalf("credential boundary changed with present=%t: code=%d out=%q err=%q", present, code, stdout, stderr)
}
}
result, err := appconfig.Load(appconfig.LoadOptions{Path: path, Explicit: true})
if err != nil {
t.Fatal(err)
}
settings := appconfig.Settings(result.Config)
if len(settings.Backends) != 1 || settings.Backends[0].ExtraParams["visible_parameter"] != "synthetic-ordinary-value" {
t.Fatalf("runtime backend parameters changed: %+v", settings.Backends)
}
}
type errorOutputWriter struct{}
func (errorOutputWriter) Write([]byte) (int, error) { return 0, errors.New("output unavailable") }
func TestConfigCommandFailuresDoNotProduceSuccessfulOutput(t *testing.T) {
path := writeAppConfigFile(t, "server:\n max_request_bytes: -1\n")
for _, mode := range []string{"validate", "show", "sources"} {
code, stdout, stderr := runCLICommand(t, configCommand, []string{mode, "--config", path})
if code != ExitRuntimeError || stdout != "" || !strings.Contains(stderr, "validate.error") {
t.Fatalf("%s misclassified invalid config: code=%d out=%q err=%q", mode, code, stdout, stderr)
}
}
path = writeAppConfigFile(t, "{}\n")
var stderr bytes.Buffer
if code := configCommand([]string{"show", "--config", path}, errorOutputWriter{}, &stderr); code != ExitRuntimeError || !strings.Contains(stderr.String(), "output error") {
t.Fatalf("writer error not reported: code=%d stderr=%q", code, stderr.String())
}
if code := configCommand([]string{"sources", "--config", path}, errorOutputWriter{}, io.Discard); code != ExitRuntimeError {
t.Fatalf("source writer error returned %d", code)
}
}
func TestConfigExplainUsesResolvedHistoryAndKeepsParametersVisible(t *testing.T) {
dir := t.TempDir()
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
t.Fatal(err)
}
base := filepath.Join(dir, "config.yml")
for path, body := range map[string]string{
base: `prompt_dir: " ./prompts/../prompts "
server:
addr: :8080
backends:
"team/blue~1":
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_EXPLAIN_KEY
extra_params:
"0": base-parameter
`,
filepath.Join(dir, "overlays", "local.yml"): `server:
addr: :9090
backends:
"team/blue~1":
extra_params:
"0": overlay-parameter
`,
} {
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
t.Fatal(err)
}
}
const keyValue = "synthetic-key-bytes-must-not-appear"
t.Setenv("SCRIPTORIUM_EXPLAIN_KEY", keyValue)
args := []string{"--config", base, "--config-overlay", "local", "--addr", ":9090"}
for _, tc := range []struct {
pointer string
want []string
}{
{pointer: "/server/addr", want: []string{":8080", ":9090", "--addr"}},
{pointer: "/prompt_dir", want: []string{"normalized application path", "prompts"}},
{pointer: "/backends/team~1blue~01/extra_params/0", want: []string{"base-parameter", "overlay-parameter"}},
{pointer: "/backends/team~1blue~01/api_key_env", want: []string{"SCRIPTORIUM_EXPLAIN_KEY"}},
{pointer: "", want: []string{"base-parameter", "overlay-parameter", "SCRIPTORIUM_EXPLAIN_KEY"}},
} {
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", tc.pointer}, args...))
if code != ExitOK || stderr != "" || strings.Contains(stdout, keyValue) {
t.Fatalf("explain %q failed or disclosed key: code=%d out=%q err=%q", tc.pointer, code, stdout, stderr)
}
for _, want := range tc.want {
if !strings.Contains(stdout, want) {
t.Fatalf("explain %q lacks %q: %q", tc.pointer, want, stdout)
}
}
}
if err := os.Unsetenv("SCRIPTORIUM_EXPLAIN_KEY"); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", "/backends/team~1blue~01/api_key_env"}, args...))
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "SCRIPTORIUM_EXPLAIN_KEY") || strings.Contains(stdout, keyValue) {
t.Fatalf("absent credential changed reference explanation: code=%d out=%q err=%q", code, stdout, stderr)
}
}
func TestConfigExplainRejectsUnknownOrMalformedPaths(t *testing.T) {
path := writeAppConfigFile(t, "{}\n")
for _, args := range [][]string{
{"explain", "--config", path},
{"explain", "--config", path, "--path", "not-a-pointer"},
{"explain", "--config", path, "--path", "/missing"},
} {
code, stdout, stderr := runCLICommand(t, configCommand, args)
if code != ExitRuntimeError || stdout != "" || stderr == "" {
t.Fatalf("invalid explanation path accepted: args=%q code=%d out=%q err=%q", args, code, stdout, stderr)
}
}
var stderr bytes.Buffer
if code := configCommand([]string{"explain", "--config", path, "--path", ""}, errorOutputWriter{}, &stderr); code != ExitRuntimeError || !strings.Contains(stderr.String(), "output error") {
t.Fatalf("explanation writer failure not reported: code=%d err=%q", code, stderr.String())
}
}

View File

@@ -0,0 +1,73 @@
package cli
import (
"errors"
"fmt"
"io"
"os"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/promptkit"
)
func reportFlags() []commandkit.Flag[runInput] {
return []commandkit.Flag[runInput]{
commandkit.ValueFlag(commandkit.FlagMeta{Name: "report", Usage: "Additionally write the native run result to a file.", Completion: commandkit.CompleteFiles()}, (*string)(nil), parseString,
func(input *runInput, value commandkit.Supplied[string]) { input.ReportPath = value }),
commandkit.ValueFlag(commandkit.FlagMeta{Name: "report-format", Usage: "Select the separate report format (omission uses native automatic rendering).", Completion: commandkit.CompleteChoices(commandkit.CompletionChoice{Value: "text"}, commandkit.CompletionChoice{Value: "yaml"}, commandkit.CompletionChoice{Value: "json"})}, (*commandkit.Format)(nil), parseReportFormat,
func(input *runInput, value commandkit.Supplied[commandkit.Format]) { input.ReportFormat = value }),
}
}
func parseReportFormat(raw string) (commandkit.Format, error) {
format := commandkit.Format(raw)
switch format {
case commandkit.FormatText, commandkit.FormatYAML, commandkit.FormatJSON:
return format, nil
default:
return "", errors.New("report format must be text, yaml, or json")
}
}
func checkReportInput(path commandkit.Supplied[string]) error {
if path.Set && path.Value == "" {
return errors.New("report path must not be empty")
}
return nil
}
func deliverRunResult(invocation commandkit.Invocation, input runInput, result *promptkit.RunResult) commandkit.Outcome {
outcome := completedRunOutcome(result)
if result == nil {
return outcome
}
// The invocation reporter records its own presentation failures. A requested
// file remains an independent effect and is attempted even after stdout fails.
_ = invocation.Reporter().Report(commandkit.Report{Value: result, TextTemplate: artifactTextTemplate})
if input.ReportPath.Set {
if err := writeNativeReport(input.ReportPath.Value, result, input.ReportFormat.Value); err != nil {
if outcome.Status == 0 {
outcome = commandkit.Failure("The report file could not be delivered.")
} else {
outcome.Explanation.Message += " The report file could not be delivered."
}
outcome.Cause = errors.Join(outcome.Cause, err)
outcome.Explanation.Details = append(outcome.Explanation.Details, func(writer io.Writer) error { _, writeErr := fmt.Fprintln(writer, err); return writeErr })
}
}
_ = invocation.Reporter().Info("Prompt execution completed.")
return outcome
}
func writeNativeReport(path string, result *promptkit.RunResult, format commandkit.Format) error {
file, err := os.OpenFile(path, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644)
if err != nil {
return fmt.Errorf("open report %q: %w", path, err)
}
renderErr := commandkit.RenderReport(file, commandkit.Report{Value: result}, format)
closeErr := file.Close()
if err := errors.Join(renderErr, closeErr); err != nil {
return fmt.Errorf("deliver report %q: %w", path, err)
}
return nil
}

View File

@@ -0,0 +1,287 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"path/filepath"
"slices"
"strings"
"sync/atomic"
"testing"
"time"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/promptkit"
)
func deliveryArgs() []string {
return []string{"run", "support/summary", "--config=app.yml", "--profile=support/writer", "--session-id=session", "--var=mode=", "--var=title=Title", "--input-text=transcript=text", "--input-text=unlisted=literal"}
}
func TestSeparateReportsUseNativeFormats(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
fmt.Fprint(w, `{"choices":[{"message":{"content":"artifact"}}]}`)
}))
defer server.Close()
nativePromptFixture(t, server.URL+"/v1")
for _, format := range []commandkit.Format{"", commandkit.FormatText, commandkit.FormatYAML, commandkit.FormatJSON} {
path := "report-" + string(format) + ".different-extension"
writeNativeFile(t, path, "old-report-must-be-replaced-completely")
args := append(deliveryArgs(), "--format=json", "--report="+path)
if format != "" {
args = append(args, "--report-format="+string(format))
}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 {
t.Fatalf("%q: %+v %q", format, outcome, diagnostics)
}
var result promptkit.RunResult
if err := json.Unmarshal([]byte(output), &result); err != nil {
t.Fatal(err)
}
// Use the serialized native value rather than round-tripping timing
// metadata through RunResult: a positive sub-millisecond duration is
// serialized as zero but would be omitted after that typed round trip.
var nativeValue any
if err := json.Unmarshal([]byte(output), &nativeValue); err != nil {
t.Fatal(err)
}
var expected bytes.Buffer
if err := commandkit.RenderReport(&expected, commandkit.Report{Value: nativeValue}, format); err != nil {
t.Fatal(err)
}
actual, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if !bytes.Equal(actual, expected.Bytes()) || !bytes.Contains(actual, []byte(result.RunID)) || !bytes.Contains(actual, []byte("selected_profile_id")) {
t.Fatalf("report %q differs from native renderer:\n%s\nexpected:\n%s", format, actual, expected.Bytes())
}
}
outcome, output, diagnostics := executeNative(t, append(deliveryArgs(), "--format=text", "--report=metadata.yaml", "--report-format=json")...)
if outcome.Status != 0 || output != "artifact" {
t.Fatalf("independent formats: %+v %q %q", outcome, output, diagnostics)
}
data, err := os.ReadFile("metadata.yaml")
if err != nil {
t.Fatal(err)
}
var result promptkit.RunResult
if err := json.Unmarshal(data, &result); err != nil {
t.Fatal(err)
}
if string(result.Artifact.Body) != "artifact" || result.RunID == "" {
t.Fatalf("report lost full result: %+v", result)
}
outcome, output, diagnostics = executeNative(t, append(deliveryArgs(), "--quiet", "--report=-", "--report-format=json")...)
if outcome.Status != 0 || output != "" {
t.Fatalf("quiet report: %+v %q %q", outcome, output, diagnostics)
}
if data, err := os.ReadFile("-"); err != nil || !bytes.Contains(data, []byte("run_id")) {
t.Fatalf("literal dash report: %s %v", data, err)
}
}
func TestReportValidationAndResultlessFailureLeaveFilesUntouched(t *testing.T) {
var calls atomic.Int64
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls.Add(1)
w.Header().Set("Content-Type", "application/json")
fmt.Fprint(w, `{"choices":[{"message":{"content":"artifact"}}]}`)
}))
defer server.Close()
nativePromptFixture(t, server.URL+"/v1")
for _, flags := range [][]string{{"--report="}, {"--report=untouched", "--report-format=invalid"}, {"--report=untouched", "--report-format="}} {
outcome, _, diagnostics := executeNative(t, append(deliveryArgs(), flags...)...)
if outcome.Status != 2 || diagnostics == "" || calls.Load() != 0 {
t.Fatalf("preflight %v: %+v %q calls=%d", flags, outcome, diagnostics, calls.Load())
}
}
if _, err := os.Stat("untouched"); !errors.Is(err, os.ErrNotExist) {
t.Fatalf("validation created file: %v", err)
}
writeNativeFile(t, "existing-report", "keep-existing")
outcome, output, diagnostics := executeNative(t, "run", "missing", "--config=app.yml", "--report=existing-report")
if outcome.Status != 1 || output != "" || diagnostics == "" {
t.Fatalf("resultless failure: %+v %q %q", outcome, output, diagnostics)
}
if data, err := os.ReadFile("existing-report"); err != nil || string(data) != "keep-existing" {
t.Fatalf("resultless failure touched report: %q %v", data, err)
}
outcome, output, diagnostics = executeNative(t, append(deliveryArgs(), "--report=missing-parent/report")...)
if outcome.Status != 1 || output != "artifact" || !strings.Contains(diagnostics, "report") {
t.Fatalf("report failure after main output: %+v %q %q", outcome, output, diagnostics)
}
if _, err := os.Stat("missing-parent"); !errors.Is(err, os.ErrNotExist) {
t.Fatalf("created report parent: %v", err)
}
}
type failedDeliveryWriter struct{ cause error }
func (writer failedDeliveryWriter) Write([]byte) (int, error) { return 0, writer.cause }
type partialDeliveryWriter struct {
bytes.Buffer
cause error
}
func (writer *partialDeliveryWriter) Write(value []byte) (int, error) {
count := min(2, len(value))
_, _ = writer.Buffer.Write(value[:count])
return count, writer.cause
}
func TestPartialOutputAndDiagnosticFailureUseNativeFinalization(t *testing.T) {
t.Chdir(t.TempDir())
failure := errors.New("presentation failure")
app, err := commandkit.New(commandkit.Identity{Name: "delivery"}, commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
return deliverRunResult(inv, runInput{ReportPath: commandkit.Supplied[string]{Set: true, Value: "report"}}, &promptkit.RunResult{Artifact: promptkit.Artifact{Body: []byte("artifact")}})
}}))
if err != nil {
t.Fatal(err)
}
output := &partialDeliveryWriter{cause: failure}
var diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Out: output, Err: &diagnostics})
if outcome.Status != 1 || output.String() != "ar" || !errors.Is(outcome.Presentation.Output.WriteError, failure) {
t.Fatalf("partial output was lost: %+v %q", outcome, output.String())
}
if _, err := os.Stat("report"); err != nil {
t.Fatal("report was not attempted", err)
}
outcome = Execute(context.Background(), commandkit.Identity{Name: "scriptorium"}, []string{"run"}, io.Discard, failedDeliveryWriter{failure})
if outcome.Status != 1 || outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Presentation.Diagnostics.WriteError, failure) {
t.Fatalf("usage diagnostic failure not finalized: %+v", outcome)
}
}
func TestNativeDeliveryAttemptsReportAfterStdoutFailure(t *testing.T) {
t.Chdir(t.TempDir())
result := &promptkit.RunResult{RunID: "known-result", Artifact: promptkit.Artifact{Body: []byte("body")}}
stdoutFailure := errors.New("stdout failure")
for _, invalid := range []bool{false, true} {
result.Validation.Status = promptkit.ValidationPassed
if invalid {
result.Validation.Status = promptkit.ValidationFailed
}
for _, path := range []string{"report", "absent/report"} {
app, err := commandkit.New(commandkit.Identity{Name: "delivery"}, commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
return deliverRunResult(inv, runInput{ReportPath: commandkit.Supplied[string]{Set: true, Value: path}}, result)
}}))
if err != nil {
t.Fatal(err)
}
var diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Out: failedDeliveryWriter{stdoutFailure}, Err: &diagnostics})
want := 1
if invalid {
want = 4
}
if outcome.Status != want || !errors.Is(outcome.Presentation.Output.WriteError, stdoutFailure) {
t.Fatalf("delivery outcome: %+v %q", outcome, diagnostics.String())
}
if invalid && (outcome.Kind != commandkit.OutcomeDomain || outcome.Domain != "validation_failed") {
t.Fatalf("domain outcome lost: %+v", outcome)
}
if path == "report" {
if data, err := os.ReadFile(path); err != nil || !bytes.Contains(data, []byte("known-result")) {
t.Fatalf("report not attempted: %q %v", data, err)
}
} else {
var fileError *os.PathError
if !errors.As(outcome.Cause, &fileError) || !strings.Contains(diagnostics.String(), "report file") {
t.Fatalf("report error lost: %+v %q", outcome, diagnostics.String())
}
}
}
}
// Unsupported result data exercises native rendering failure, not a local
// replacement serializer. Both main and file delivery failures survive.
result.Validation.Status = promptkit.ValidationPassed
result.EffectiveModelParams.ExtraParams = map[string]any{"invalid": make(chan int)}
app, err := commandkit.New(commandkit.Identity{Name: "delivery"}, commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
return deliverRunResult(inv, runInput{ReportPath: commandkit.Supplied[string]{Set: true, Value: "render-failed"}}, result)
}}))
if err != nil {
t.Fatal(err)
}
var output, diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), []string{"run", "--format=json"}, commandkit.Streams{Out: &output, Err: &diagnostics})
if outcome.Status != 1 || outcome.Presentation.Output.RenderError == nil || outcome.Cause == nil || !strings.Contains(diagnostics.String(), "report file") {
t.Fatalf("render errors lost: %+v %q", outcome, diagnostics.String())
}
if _, err := os.Stat("render-failed"); err != nil {
t.Fatalf("file effect not attempted: %v", err)
}
}
func TestCLIProcessOutput(t *testing.T) {
if os.Getenv("SCRIPTORIUM_CLI_CHILD") == "1" {
separator := slices.Index(os.Args, "--")
if separator < 0 {
os.Exit(2)
}
outcome := Execute(context.Background(), commandkit.Identity{Name: "scriptorium"}, os.Args[separator+1:], os.Stdout, os.Stderr)
os.Exit(outcome.Status)
}
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
fmt.Fprint(w, `{"choices":[{"message":{"content":"redirected artifact"}}]}`)
}))
defer server.Close()
nativePromptFixture(t, server.URL+"/v1")
executable, err := os.Executable()
if err != nil {
t.Fatal(err)
}
for _, quiet := range []bool{false, true} {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
args := append([]string{"-test.run=^TestCLIProcessOutput$", "--"}, deliveryArgs()...)
args = append(args, "--report=process-report", "--report-format=json")
if quiet {
args = append(args, "--quiet")
}
command := exec.CommandContext(ctx, executable, args...)
command.Env = append(os.Environ(), "SCRIPTORIUM_CLI_CHILD=1")
path := filepath.Join(t.TempDir(), "redirected-output")
file, err := os.Create(path)
if err != nil {
cancel()
t.Fatal(err)
}
command.Stdout = file
var diagnostics bytes.Buffer
command.Stderr = &diagnostics
runErr := command.Run()
closeErr := file.Close()
cancel()
if runErr != nil || closeErr != nil {
t.Fatalf("subprocess: %v %v %q", runErr, closeErr, diagnostics.String())
}
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
want := "redirected artifact"
if quiet {
want = ""
}
if string(data) != want {
t.Fatalf("redirected quiet=%t: %q", quiet, data)
}
data, err = os.ReadFile("process-report")
if err != nil || !bytes.Contains(data, []byte("run_id")) {
t.Fatalf("independent process report: %s %v", data, err)
}
}
}

View File

@@ -0,0 +1,196 @@
package cli
import (
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"reflect"
"strings"
"testing"
"go.maximumdirect.net/promptkit"
)
func TestCollectionCheckoutDiscoveryAcrossInvocations(t *testing.T) {
fixture, err := filepath.Abs(filepath.Join("..", "..", "..", "examples", "discovery"))
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
name string
first string
second string
}{
{name: "yml then yaml", first: "support-repo", second: "review-repo"},
{name: "yaml then yml", first: "review-repo", second: "support-repo"},
} {
t.Run(tc.name, func(t *testing.T) {
root := t.TempDir()
framework, err := os.ReadFile(filepath.Join(fixture, "framework.yml"))
if err != nil {
t.Fatal(err)
}
frameworkPath := filepath.Join(root, "framework.yml")
if err := os.WriteFile(frameworkPath, framework, 0o644); err != nil {
t.Fatal(err)
}
collections := filepath.Join(root, "collections")
if err := os.MkdirAll(collections, 0o755); err != nil {
t.Fatal(err)
}
install := func(name string) {
t.Helper()
if err := os.CopyFS(filepath.Join(collections, name), os.DirFS(filepath.Join(fixture, "collections", name))); err != nil {
t.Fatal(err)
}
}
config := filepath.Join(root, "app.yml")
writeNativeFile(t, config, fmt.Sprintf("promptkit:\n configuration: %q\n", frameworkPath))
input := filepath.Join(root, "transcript.md")
if err := os.WriteFile(input, []byte("synthetic discovery transcript"), 0o644); err != nil {
t.Fatal(err)
}
args := func(name string) []string {
if name == "support-repo" {
return []string{"support/answer", "--config", config, "--profile", "support/fast", "--input-file", "transcript=" + input}
}
return []string{"review/answer", "--config", config, "--profile", "review/base"}
}
check := func(name string) {
t.Helper()
command := append([]string{"promptkit", "show", "prepared"}, args(name)...)
outcome, out, stderr := executeNative(t, append(command, "--format=json")...)
if outcome.Status != 0 {
t.Fatalf("prepare %s: outcome=%+v stderr=%s", name, outcome, stderr)
}
var prepared promptkit.PreparedRun
if err := json.Unmarshal([]byte(out), &prepared); err != nil {
t.Fatal(err)
}
if name == "support-repo" {
for _, want := range []string{"support/answer", "support/fast", "support-example", "Answer the support request", "synthetic discovery transcript"} {
if !strings.Contains(out, want) {
t.Fatalf("missing %q: %s", want, out)
}
}
if prepared.EffectiveModelParams.MaxTokens != 256 {
t.Fatalf("inherited profile setting missing: %+v", prepared)
}
} else if !strings.Contains(out, "review/answer") || !strings.Contains(out, "review-example") || !strings.Contains(out, "Review this material") {
t.Fatalf("unexpected review render: %s", out)
}
}
install(tc.first)
check(tc.first)
outcome, _, _ := executeNative(t, append([]string{"promptkit", "show", "prepared"}, args(tc.second)...)...)
if outcome.Status != 1 {
t.Fatal("uninstalled collection unexpectedly selected")
}
install(tc.second)
check(tc.first)
check(tc.second)
})
}
}
func TestMaintainedCollectionWorkflow(t *testing.T) {
root, err := filepath.Abs(filepath.Join("..", "..", ".."))
if err != nil {
t.Fatal(err)
}
t.Chdir(root)
requests := make(chan []promptkit.RenderedMessage, 2)
provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
var body struct {
Messages []promptkit.RenderedMessage `json:"messages"`
}
if err := json.NewDecoder(request.Body).Decode(&body); err != nil {
t.Error(err)
}
select {
case requests <- body.Messages:
default:
t.Error("unexpected provider dispatch")
}
w.Header().Set("Content-Type", "application/json")
fmt.Fprint(w, `{"choices":[{"message":{"content":"collection result"}}]}`)
}))
defer provider.Close()
const config = "examples/config.discovery.yml"
outcome, inventory, diagnostics := executeNative(t, "promptkit", "list", "prompts", "--all-namespaces", "--config="+config, "--format=json")
if outcome.Status != 0 || !strings.Contains(inventory, "support/answer") || !strings.Contains(inventory, "support/summarize") || !strings.Contains(inventory, "review/answer") {
t.Fatalf("collection discovery: %+v %q %q", outcome, inventory, diagnostics)
}
inputPath := filepath.Join(t.TempDir(), "future-transcript.md")
for _, namespace := range []string{"support", "review"} {
profile := "fast"
if namespace == "review" {
profile = "base"
}
outcome, output, diagnostics := executeNative(t, "promptkit", "requirements", "show", "answer", "--config="+config, "--prompt-namespace="+namespace, "--profile="+profile, "--profile-namespace="+namespace, "--format=json")
var report consumerRequirements
if err := json.Unmarshal([]byte(output), &report); err != nil {
t.Fatal(err)
}
if outcome.Status != 0 || !report.Complete || report.PromptID != namespace+"/answer" || report.ProfileID != namespace+"/"+profile {
t.Fatalf("requirements: %+v %+v %q", outcome, report, diagnostics)
}
if namespace == "support" && (len(report.Inputs) != 1 || report.Inputs[0].Name != "transcript" || report.Inputs[0].Kind != promptkit.RequirementRequired) {
t.Fatalf("required binding: %+v", report)
}
}
if _, err := os.Stat(inputPath); !os.IsNotExist(err) {
t.Fatalf("discovery created input artifact: %v", err)
}
writeNativeFile(t, inputPath, "generated collection transcript")
for _, namespace := range []string{"support", "review"} {
profile := "fast"
if namespace == "review" {
profile = "base"
}
flags := []string{"answer", "--config=" + config, "--prompt-namespace=" + namespace, "--profile=" + profile, "--profile-namespace=" + namespace, "--endpoint=" + provider.URL + "/v1", "--model=controlled", "--timeout-seconds=0", "--transient-retries=0", "--session-id=collection-session", "--format=json"}
if namespace == "support" {
flags = append(flags, "--input-file=transcript="+inputPath)
}
outcome, _, diagnostics := executeNative(t, append([]string{"promptkit", "requirements", "validate"}, flags...)...)
if outcome.Status != 0 {
t.Fatalf("validation: %+v %q", outcome, diagnostics)
}
outcome, output, diagnostics := executeNative(t, append([]string{"promptkit", "show", "prepared"}, flags...)...)
var prepared promptkit.PreparedRun
if err := json.Unmarshal([]byte(output), &prepared); err != nil {
t.Fatal(err)
}
if outcome.Status != 0 {
t.Fatalf("preview: %+v %q", outcome, diagnostics)
}
outcome, output, diagnostics = executeNative(t, append([]string{"run"}, flags...)...)
var result promptkit.RunResult
if err := json.Unmarshal([]byte(output), &result); err != nil {
t.Fatal(err)
}
if outcome.Status != 0 || result.PromptID != prepared.PromptID || result.SelectedProfileID != prepared.SelectedProfileID || result.RenderedPromptHash != prepared.RenderedPromptHash || !reflect.DeepEqual(result.InputHashes, prepared.InputHashes) || string(result.Artifact.Body) != "collection result" {
t.Fatalf("workflow selection/context diverged: prepared=%+v result=%+v outcome=%+v %q", prepared, result, outcome, diagnostics)
}
select {
case messages := <-requests:
if !reflect.DeepEqual(messages, prepared.Messages) {
t.Fatalf("provider saw different messages: %+v %+v", messages, prepared.Messages)
}
default:
t.Fatal("generation did not reach controlled provider")
}
}
for _, args := range [][]string{
{"config", "diff", "--scope=app", "--config=" + config, "--against-config=" + config, `--set=/promptkit/schema_dir="left"`, `--against-set=/promptkit/schema_dir="right"`, "--check"},
{"config", "diff", "--scope=promptkit", "--config=" + config, "--against-config=examples/config.yml", "--check"},
} {
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 3 || output == "" {
t.Fatalf("independent configuration sides: %+v %q %q", outcome, output, diagnostics)
}
}
}

View File

@@ -0,0 +1,24 @@
package cli
import (
"fmt"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
func newEngine(settings appconfig.AppSettings, options ...promptkit.Option) (*promptkit.Engine, error) {
var main *configkit.Input
if settings.PromptKitConfiguration != "" {
main = &configkit.Input{Source: configkit.File(settings.PromptKitConfiguration), Imports: true}
}
engine, err := promptkit.NewEngine(promptkit.Config{
Sources: promptkit.ConfigurationSources{Main: main},
SchemaDir: settings.SchemaDir, TransientRetries: settings.TransientRetries,
}, options...)
if err != nil {
return nil, fmt.Errorf("engine initialization from application configuration: %w", err)
}
return engine, nil
}

View File

@@ -0,0 +1,42 @@
package cli
import (
"os"
"path/filepath"
"strings"
"testing"
)
func TestMaintainedApplicationExamplesUseNativeLoading(t *testing.T) {
root, err := filepath.Abs(filepath.Join("..", "..", ".."))
if err != nil {
t.Fatal(err)
}
t.Chdir(root)
entries, err := os.ReadDir("examples")
if err != nil {
t.Fatal(err)
}
for _, entry := range entries {
if entry.IsDir() || !strings.HasPrefix(entry.Name(), "config") || !strings.HasSuffix(entry.Name(), ".yml") {
continue
}
path := filepath.Join("examples", entry.Name())
for _, scope := range []string{"app", "promptkit"} {
outcome, _, diagnostics := executeNative(t, "config", "validate", "--config="+path, "--scope="+scope)
if outcome.Status != 0 {
t.Fatalf("%s/%s: %+v %q", path, scope, outcome, diagnostics)
}
}
}
for _, test := range []struct{ config, overlay string }{{"examples/config.yml", ""}, {"examples/config.composed.yml", "local"}, {"examples/config.collections.yml", "collection"}, {"examples/config.inheritance.yml", ""}} {
args := []string{"promptkit", "show", "prepared", "generic.markdown_summary", "--config=" + test.config, "--profile=local-gpu", "--input-file=transcript=examples/fixtures/transcript.md", "--input-file=glossary=examples/fixtures/glossary.yml", "--format=json"}
if test.overlay != "" {
args = append(args, "--overlay="+test.overlay)
}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 || !strings.Contains(output, "generic.markdown_summary") || !strings.Contains(output, "Session Transcript") {
t.Fatalf("%+v: %+v %q %q", test, outcome, output, diagnostics)
}
}
}

View File

@@ -1,212 +0,0 @@
package cli
import (
"context"
"errors"
"flag"
"fmt"
"io"
"io/fs"
"path/filepath"
"strings"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/promptkit"
appformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
)
type promptInspectionConfig struct {
configPath, promptDir, promptID, promptVersion, outputPath string
configOverlay string
configExplicit bool
outputFormat appformat.OutputFormat
overrides []configkit.Override
diagnostics []configkit.Diagnostic
}
type profileInspectionConfig struct {
configPath, profileDir, profileID, outputPath string
configOverlay string
configExplicit bool
outputFormat appformat.OutputFormat
overrides []configkit.Override
diagnostics []configkit.Diagnostic
}
// emptyPromptDefinitionFS satisfies Promptkit's engine-level prompt-source
// requirement without exposing the caller's working directory. Profile
// inspection never reads this source.
type emptyPromptDefinitionFS struct{}
func (emptyPromptDefinitionFS) Open(name string) (fs.File, error) {
return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
}
func inspectCommand(args []string, stdout, stderr io.Writer) int {
if len(args) == 0 {
fmt.Fprintln(stderr, "inspect parse error: inspection mode is required")
return ExitRuntimeError
}
if args[0] == "profile" {
return inspectProfileCommand(args[1:], stdout, stderr)
}
if args[0] != "prompt" {
fmt.Fprintln(stderr, "inspect parse error: unknown inspection mode")
return ExitRuntimeError
}
cfg, err := parsePromptInspectionArgs(args[1:])
if err != nil {
writeApplicationError(stderr, "inspect parse", err)
return ExitRuntimeError
}
settings, err := resolveAppSettingsForPromptInspection(cfg)
if err != nil {
writeApplicationError(stderr, "inspect", err)
return ExitRuntimeError
}
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
return ExitRuntimeError
}
engine, err := newEngine(settings)
if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err)
return ExitRuntimeError
}
inspection, err := engine.InspectPrompt(context.Background(), cfg.promptID, cfg.promptVersion)
if err != nil {
fmt.Fprintf(stderr, "inspect error: %v\n", err)
return ExitRuntimeError
}
data, err := appformat.FormatPromptInspection(inspection, cfg.outputFormat)
if err != nil {
fmt.Fprintf(stderr, "inspect error: %v\n", err)
return ExitRuntimeError
}
if err := writeOutput(stdout, cfg.outputPath, data); err != nil {
fmt.Fprintf(stderr, "output write error: %v\n", err)
return ExitRuntimeError
}
return ExitOK
}
func inspectProfileCommand(args []string, stdout, stderr io.Writer) int {
cfg, err := parseProfileInspectionArgs(args)
if err != nil {
writeApplicationError(stderr, "inspect parse", err)
return ExitRuntimeError
}
settings, err := resolveAppSettingsForProfileInspection(cfg)
if err != nil {
writeApplicationError(stderr, "inspect", err)
return ExitRuntimeError
}
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
return ExitRuntimeError
}
engine, err := newEngine(settings, promptkit.WithPromptFS(emptyPromptDefinitionFS{}, "."))
if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err)
return ExitRuntimeError
}
inspection, err := engine.InspectProfile(context.Background(), cfg.profileID)
if err != nil {
fmt.Fprintf(stderr, "inspect error: %v\n", err)
return ExitRuntimeError
}
data, err := appformat.FormatProfileInspection(inspection, cfg.outputFormat)
if err != nil {
fmt.Fprintf(stderr, "inspect error: %v\n", err)
return ExitRuntimeError
}
if err := writeOutput(stdout, cfg.outputPath, data); err != nil {
fmt.Fprintf(stderr, "output write error: %v\n", err)
return ExitRuntimeError
}
return ExitOK
}
func parseProfileInspectionArgs(args []string) (*profileInspectionConfig, error) {
cfg := &profileInspectionConfig{outputFormat: appformat.DefaultOutputFormat}
fs := flag.NewFlagSet("inspect profile", flag.ContinueOnError)
fs.SetOutput(io.Discard)
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profiles")
fs.StringVar(&cfg.profileID, "profile", "", "profile ID to inspect")
rawFormat := ""
fs.StringVar(&rawFormat, "format", "", "output format: text or json")
fs.StringVar(&cfg.outputPath, "out", "", "optional output file path")
if err := fs.Parse(args); err != nil {
return nil, err
}
cfg.configExplicit = flagWasSet(fs, "config")
cfg.overrides = applicationOverrides(fs)
if fs.NArg() > 0 {
return nil, fmt.Errorf("unexpected positional args: %v", fs.Args())
}
if strings.TrimSpace(cfg.profileID) == "" {
return nil, errors.New("--profile is required")
}
format, err := appformat.ParseOutputFormat(rawFormat)
if err != nil {
return nil, err
}
cfg.outputFormat = format
if cfg.outputPath != "" {
cfg.outputPath = filepath.Clean(cfg.outputPath)
}
return cfg, nil
}
func resolveAppSettingsForProfileInspection(cfg *profileInspectionConfig) (engineSettings, error) {
settings, diagnostics, err := loadApplicationSettings(cfg.configPath, cfg.configOverlay, cfg.configExplicit, cfg.overrides)
if err != nil {
return engineSettings{}, err
}
cfg.diagnostics = diagnostics
return engineSettings{profileDir: settings.ProfileDir, backends: settings.Backends, transientRetries: settings.TransientRetries}, nil
}
func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) {
cfg := &promptInspectionConfig{outputFormat: appformat.DefaultOutputFormat}
fs := flag.NewFlagSet("inspect prompt", flag.ContinueOnError)
fs.SetOutput(io.Discard)
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definitions")
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to inspect")
fs.StringVar(&cfg.promptVersion, "prompt-version", "", "optional prompt version")
rawFormat := ""
fs.StringVar(&rawFormat, "format", "", "output format: text or json")
fs.StringVar(&cfg.outputPath, "out", "", "optional output file path")
if err := fs.Parse(args); err != nil {
return nil, err
}
cfg.configExplicit = flagWasSet(fs, "config")
cfg.overrides = applicationOverrides(fs)
if fs.NArg() > 0 {
return nil, fmt.Errorf("unexpected positional args: %v", fs.Args())
}
if strings.TrimSpace(cfg.promptID) == "" {
return nil, errors.New("--prompt is required")
}
format, err := appformat.ParseOutputFormat(rawFormat)
if err != nil {
return nil, err
}
cfg.outputFormat = format
if cfg.outputPath != "" {
cfg.outputPath = filepath.Clean(cfg.outputPath)
}
return cfg, nil
}
func resolveAppSettingsForPromptInspection(cfg *promptInspectionConfig) (engineSettings, error) {
settings, diagnostics, err := loadApplicationSettings(cfg.configPath, cfg.configOverlay, cfg.configExplicit, cfg.overrides)
if err != nil {
return engineSettings{}, err
}
cfg.diagnostics = diagnostics
if strings.TrimSpace(settings.PromptDir) == "" {
return engineSettings{}, errors.New(errPromptDirRequired)
}
return engineSettings{promptDir: settings.PromptDir, backends: settings.Backends, transientRetries: settings.TransientRetries}, nil
}

View File

@@ -0,0 +1,235 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net"
"net/http"
"net/http/httptest"
"strings"
"sync/atomic"
"testing"
"time"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/promptkit"
)
func TestRunCancellationAndNativeTimeoutLayers(t *testing.T) {
for _, test := range []struct {
name, operation, attempt string
cancelParent, localTimeout bool
parentDeadline bool
}{
{"parent cancellation", "10s", "0", true, false, false},
{"operation timeout", "500ms", "0", false, true, false},
{"zero operation budget", "0", "0", true, false, false},
{"negative operation budget", "-1s", "0", true, false, false},
{"attempt timeout", "0", "1", false, false, false},
{"earlier parent deadline", "10s", "0", false, false, true},
} {
t.Run(test.name, func(t *testing.T) {
started, stopped, release := make(chan struct{}), make(chan struct{}), make(chan struct{})
provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = io.Copy(io.Discard, r.Body)
close(started)
select {
case <-r.Context().Done():
close(stopped)
case <-release:
}
}))
defer provider.Close()
defer close(release)
nativePromptFixture(t, provider.URL+"/v1")
var ctx context.Context
var cancel context.CancelFunc
if test.parentDeadline {
ctx, cancel = context.WithTimeout(context.Background(), 500*time.Millisecond)
} else {
ctx, cancel = context.WithCancel(context.Background())
}
defer cancel()
var output, diagnostics bytes.Buffer
finished := make(chan commandkit.Outcome, 1)
args := append(deliveryArgs(), "--run-timeout="+test.operation, "--timeout-seconds="+test.attempt)
go func() {
finished <- Execute(ctx, commandkit.Identity{Name: "scriptorium"}, args, &output, &diagnostics)
}()
select {
case <-started:
case outcome := <-finished:
t.Fatalf("ended before provider dispatch: %+v %q", outcome, diagnostics.String())
case <-time.After(5 * time.Second):
t.Fatal("provider did not start")
}
if test.cancelParent {
cancel()
}
var outcome commandkit.Outcome
select {
case outcome = <-finished:
case <-time.After(5 * time.Second):
t.Fatal("run did not stop")
}
if outcome.Status != 1 || output.Len() != 0 || diagnostics.Len() == 0 || errors.Is(outcome.Cause, promptkit.ErrOperationTimeout) != test.localTimeout {
t.Fatalf("timeout/cancellation: %+v %q %q", outcome, output.String(), diagnostics.String())
}
if test.cancelParent && !errors.Is(outcome.Cause, context.Canceled) {
t.Fatalf("parent cause lost: %+v", outcome)
}
if !test.cancelParent && !errors.Is(outcome.Cause, context.DeadlineExceeded) {
t.Fatalf("deadline cause lost: %+v", outcome)
}
if !test.cancelParent && !test.parentDeadline && ctx.Err() != nil {
t.Fatal("engine deadline changed caller context")
}
select {
case <-stopped:
case <-time.After(5 * time.Second):
t.Fatal("provider request was not canceled")
}
})
}
}
func TestServeStartupHTTPAndCancellation(t *testing.T) {
var block atomic.Bool
started, stopped, release := make(chan struct{}), make(chan struct{}), make(chan struct{})
provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = io.Copy(io.Discard, r.Body)
if block.Load() {
close(started)
select {
case <-r.Context().Done():
close(stopped)
case <-release:
}
return
}
w.Header().Set("Content-Type", "application/json")
fmt.Fprint(w, `{"choices":[{"message":{"content":"served"}}]}`)
}))
defer provider.Close()
defer close(release)
nativePromptFixture(t, provider.URL+"/v1")
writeNativeFile(t, "artifacts/transcript.md", "file from restricted root")
ready := make(chan string, 1)
listen := func(ctx context.Context, network, addr string) (net.Listener, error) {
listener, err := (&net.ListenConfig{}).Listen(ctx, network, addr)
if err == nil {
ready <- listener.Addr().String()
}
return listener, err
}
app, err := commandkit.New(commandkit.Identity{Name: "scriptorium"}, commandkit.NewCommand(commandkit.CommandSpec[serveInput]{Name: "serve", Flags: serveFlags(), Run: func(inv commandkit.Invocation, input serveInput) commandkit.Outcome {
return serveWithListener(inv, input, listen)
}}))
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
var output, diagnostics bytes.Buffer
finished := make(chan commandkit.Outcome, 1)
go func() {
finished <- app.Execute(ctx, []string{"serve", "--config=app.yml", "--addr=127.0.0.1:0", "--artifact-root=artifacts", "--max-request-bytes=0", "--max-artifact-bytes=0", "--max-response-bytes=0", "--verbose"}, commandkit.Streams{Out: &output, Err: &diagnostics})
}()
var addr string
select {
case addr = <-ready:
case outcome := <-finished:
t.Fatalf("startup: %+v %q", outcome, diagnostics.String())
case <-time.After(5 * time.Second):
t.Fatal("server did not listen")
}
client := &http.Client{Timeout: 5 * time.Second}
defer client.CloseIdleConnections()
const payload = `{"prompt_id":"support/summary","profile_id":"support/writer","session_id":"server-session","vars":{"mode":"","title":"Title"},"inputs":{"transcript":{"type":"file","uri":"transcript.md"},"unlisted":{"type":"inline","body":"literal"}},"model":{"timeout_seconds":0},"include_execution_report":true}`
response, err := client.Post("http://"+addr+"/v1/runs", "application/json", strings.NewReader(payload))
if err != nil {
t.Fatal(err)
}
var value map[string]any
decodeErr := json.NewDecoder(response.Body).Decode(&value)
response.Body.Close()
if response.StatusCode != 200 || decodeErr != nil || value["execution"] == nil {
t.Fatalf("HTTP response: %d %+v %v", response.StatusCode, value, decodeErr)
}
metadata := value["metadata"].(map[string]any)
if metadata["selected_profile_id"] != "support/writer" || metadata["session_id"] != "server-session" {
t.Fatalf("HTTP contract changed: %+v", value)
}
block.Store(true)
requestFinished := make(chan error, 1)
go func() {
response, err := client.Post("http://"+addr+"/v1/runs", "application/json", strings.NewReader(payload))
if response != nil {
response.Body.Close()
}
requestFinished <- err
}()
select {
case <-started:
case <-time.After(5 * time.Second):
t.Fatal("active HTTP request did not reach engine")
}
cancel()
select {
case outcome := <-finished:
if outcome.Status != 1 || !errors.Is(outcome.Cause, context.Canceled) || output.Len() != 0 || diagnostics.Len() == 0 {
t.Fatalf("shutdown: %+v %q %q", outcome, output.String(), diagnostics.String())
}
case <-time.After(5 * time.Second):
t.Fatal("HTTP server did not close")
}
select {
case <-requestFinished:
case <-time.After(5 * time.Second):
t.Fatal("active HTTP connection remained open")
}
select {
case <-stopped:
case <-time.After(5 * time.Second):
t.Fatal("active engine work was not canceled")
}
if connection, err := net.DialTimeout("tcp", addr, time.Second); err == nil {
connection.Close()
t.Fatal("listener remained open")
}
}
func TestServeListenAndConfigurationFailures(t *testing.T) {
nativePromptFixture(t, "http://127.0.0.1:1/v1")
for _, args := range [][]string{
{"serve", "--config=app.yml", "--addr=invalid:address:syntax"},
{"serve", "--config=absent.yml"},
} {
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 1 || outcome.Cause == nil || output != "" || diagnostics == "" {
t.Fatalf("serve failure: %+v %q %q", outcome, output, diagnostics)
}
}
writeNativeFile(t, "invalid.yml", "server:\n max_request_bytes: -1\n")
outcome, _, diagnostics := executeNative(t, "serve", "--config=invalid.yml")
if outcome.Status != 2 || !strings.Contains(diagnostics, "validate.error") {
t.Fatalf("serve configuration classification: %+v %q", outcome, diagnostics)
}
writeNativeFile(t, "bad-framework.yml", "profiles: [\n")
writeNativeFile(t, "bad-framework-app.yml", "promptkit:\n configuration: bad-framework.yml\n")
for _, command := range []string{"run", "serve"} {
args := []string{command}
if command == "run" {
args = append(args, "any")
}
args = append(args, "--config=bad-framework-app.yml")
outcome, _, diagnostics := executeNative(t, args...)
if outcome.Status != 2 || !strings.Contains(diagnostics, "PromptKit configuration") || !strings.Contains(diagnostics, "yaml.invalid") {
t.Fatalf("framework diagnostics: %+v %q", outcome, diagnostics)
}
}
}

View File

@@ -0,0 +1,41 @@
package cli
import (
"context"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/ckprompt"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
func configurationCommand() commandkit.Command {
application := ckconfig.FromConfigKit("app", "Scriptorium application configuration.",
func(ctx context.Context, selection ckconfig.Selection, input applicationInput, _ *acquisitionState) (*configkit.Result[appconfig.Document], error) {
return loadApplication(ctx, selection, input, struct{}{})
})
application.Features.Overrides = true
framework := frameworkConfigurationScope()
return ckconfig.Command(ckconfig.Suite[applicationInput, *acquisitionState]{
NewInput: func() applicationInput { return applicationInput{} },
NewState: func() *acquisitionState { return &acquisitionState{} },
Scopes: []ckconfig.Scope[applicationInput, *acquisitionState]{application, framework},
})
}
func frameworkConfigurationScope() ckconfig.Scope[applicationInput, *acquisitionState] {
scope := ckprompt.ConfigScope(loadEngine)
acquire, compare := scope.Acquire, scope.Compare
scope.Acquire = func(ctx context.Context, request ckconfig.Request, input applicationInput, state *acquisitionState) (commandkit.Acquired[ckconfig.View], error) {
start := state.mark()
acquired, err := acquire(ctx, request, input, state)
return attachApplicationEvidence(acquired, err, state, start, false)
}
scope.Compare = func(ctx context.Context, request ckconfig.ComparisonRequest[applicationInput], state *acquisitionState) (commandkit.Acquired[[]configkit.Difference], error) {
start := state.mark()
acquired, err := compare(ctx, request, state)
return attachApplicationEvidence(acquired, err, state, start, true)
}
return scope
}

View File

@@ -0,0 +1,247 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"errors"
"io"
"os"
"path/filepath"
"strings"
"testing"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
func executeNative(t *testing.T, args ...string) (commandkit.Outcome, string, string) {
t.Helper()
var output, diagnostics bytes.Buffer
outcome := Execute(context.Background(), commandkit.Identity{Name: "scriptorium", Version: "test"}, args, &output, &diagnostics)
return outcome, output.String(), diagnostics.String()
}
func writeNativeFile(t *testing.T, path, content string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte(content), 0600); err != nil {
t.Fatal(err)
}
}
func nativeConfigurationFixture(t *testing.T) {
t.Helper()
t.Chdir(t.TempDir())
writeNativeFile(t, "left.yml", "promptkit:\n configuration: left-framework.yml\n schema_dir: ' ./a/../schemas '\nserver:\n addr: :1111\n")
writeNativeFile(t, "right.yml", "promptkit:\n configuration: right-framework.yml\nserver:\n addr: :2222\n")
writeNativeFile(t, "scriptorium.yml", "promptkit:\n configuration: right-framework.yml\nserver:\n addr: :3333\n")
writeNativeFile(t, "overlays/local.yml", "promptkit:\n configuration: right-framework.yml\nserver:\n addr: :4444\n")
for _, side := range []string{"left", "right"} {
writeNativeFile(t, side+"-framework.yml", "collections:\n custom:\n release_version: '1'\n profiles:\n - id: selected\n model: "+side+"-model\n extra_params:\n 'key/with~mark': visible\n password: "+side+"-password-canary\n")
}
}
func TestNativeApplicationScopeDoesNotLoadFramework(t *testing.T) {
nativeConfigurationFixture(t)
writeNativeFile(t, "unavailable.yml", "promptkit:\n configuration: missing.yml\n")
for _, operation := range []string{"validate", "show", "sources", "explain"} {
args := []string{"config", operation, "--scope=app", "--config=unavailable.yml", "--format=json"}
if operation == "explain" {
args = append(args, "--path=/promptkit/configuration")
}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 || output == "" {
t.Fatalf("%v: %+v %q %q", args, outcome, output, diagnostics)
}
}
// The native default scope remains application configuration.
outcome, output, diagnostics := executeNative(t, "config", "show", "--config=left.yml", "--path=/promptkit/schema_dir", "--format=json")
if outcome.Status != 0 || strings.TrimSpace(output) != `"schemas"` {
t.Fatalf("show: %+v %q %q", outcome, output, diagnostics)
}
outcome, output, diagnostics = executeNative(t, "config", "explain", "--scope=app", "--config=left.yml", "--path=/promptkit/schema_dir", "--format=json")
if outcome.Status != 0 || !strings.Contains(output, "schemas") || !strings.Contains(output, "normalization") {
t.Fatalf("explain: %+v %q %q", outcome, output, diagnostics)
}
outcome, output, diagnostics = executeNative(t, "config", "show", "--scope=promptkit", "--config=unavailable.yml")
if outcome.Status != 1 || output != "" || diagnostics == "" {
t.Fatalf("framework load: %+v %q %q", outcome, output, diagnostics)
}
}
func TestNativeConfigurationPathsAndRedaction(t *testing.T) {
nativeConfigurationFixture(t)
for _, test := range []struct{ operation, path, want string }{
{"show", "", "left-model"},
{"show", "/collections/custom/profiles/0/model", "left-model"},
{"show", "/collections/custom/profiles/0/extra_params/key~1with~0mark", "visible"},
{"explain", "/collections/custom/profiles/0/extra_params/key~1with~0mark", "visible"},
{"explain", "/collections/custom/profiles/0/extra_params/password", "redacted"},
} {
outcome, output, diagnostics := executeNative(t, "config", test.operation, "--scope=promptkit", "--config=left.yml", "--path="+test.path, "--format=json")
if outcome.Status != 0 || !strings.Contains(output, test.want) || strings.Contains(output+diagnostics, "left-password-canary") {
t.Fatalf("%+v: %+v %q %q", test, outcome, output, diagnostics)
}
var value any
if err := json.Unmarshal([]byte(output), &value); err != nil {
t.Fatal(err)
}
}
outcome, output, diagnostics := executeNative(t, "config", "explain", "--scope=promptkit", "--config=left.yml", "--list", "--under=/collections/custom/profiles", "--format=json")
if outcome.Status != 0 || !strings.Contains(output, "/collections/custom/profiles/0/model") {
t.Fatalf("paths: %+v %q %q", outcome, output, diagnostics)
}
outcome, output, diagnostics = executeNative(t, "config", "show", "--scope=promptkit", "--config=left.yml", "--overlay=local", "--path=/collections/custom/profiles/0/model", "--format=json")
if outcome.Status != 0 || !strings.Contains(output, "right-model") {
t.Fatalf("overlay selection: %+v %q %q", outcome, output, diagnostics)
}
}
func TestNativeConfigurationComparisonSelectionsAreIndependent(t *testing.T) {
nativeConfigurationFixture(t)
for _, test := range []struct {
scope string
right []string
before, after string
}{
{"app", []string{"--against-config=right.yml"}, ":1111", ":2222"},
{"app", nil, ":1111", ":3333"},
{"app", []string{"--against-config=left.yml", "--against-overlay=local"}, ":1111", ":4444"},
{"app", []string{"--against-config=right.yml", `--set=/server/addr="native-left"`, `--against-set=/server/addr="native-right"`}, "native-left", "native-right"},
{"promptkit", []string{"--against-config=right.yml"}, "left-model", "right-model"},
{"promptkit", nil, "left-model", "right-model"},
{"promptkit", []string{"--against-config=left.yml", "--against-overlay=local"}, "left-model", "right-model"},
} {
args := []string{"config", "diff", "--scope=" + test.scope, "--config=left.yml", "--details", "--check", "--format=json"}
args = append(args, test.right...)
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 3 || outcome.Kind != commandkit.OutcomeDomain || !strings.Contains(output, test.before) || !strings.Contains(output, test.after) {
t.Fatalf("%v: %+v %q %q", args, outcome, output, diagnostics)
}
if strings.Contains(output+diagnostics, "password-canary") {
t.Fatal("comparison disclosed classified value")
}
}
for _, scope := range []string{"app", "promptkit"} {
outcome, _, diagnostics := executeNative(t, "config", "diff", "--scope="+scope, "--config=left.yml", "--against-config=left.yml", "--overlay=local", "--check")
if outcome.Status != 3 {
t.Fatalf("left overlay inherited by right %s: %+v %q", scope, outcome, diagnostics)
}
outcome, _, diagnostics = executeNative(t, "config", "diff", "--scope="+scope, "--config=left.yml", "--against-config=left.yml", "--check")
if outcome.Status != 0 {
t.Fatalf("equal selections %s: %+v %q", scope, outcome, diagnostics)
}
}
}
func TestNativeConfigurationOverridesAndCapabilityChecks(t *testing.T) {
nativeConfigurationFixture(t)
outcome, output, diagnostics := executeNative(t, "config", "show", "--scope=app", "--config=left.yml", `--set=/server/addr="native"`, "--path=/server/addr", "--format=json")
if outcome.Status != 0 || strings.TrimSpace(output) != `"native"` {
t.Fatalf("override: %+v %q %q", outcome, output, diagnostics)
}
for _, args := range [][]string{
{"config", "show", "--scope=promptkit", `--set=/server/addr="native"`},
{"config", "show", "--scope=all", `--set=/server/addr="native"`},
{"config", "diff", "--scope=promptkit", `--against-set=/server/addr="native"`},
{"config", "show", "--addr=:9999"}, {"config", "show", "--max-request-bytes=0"},
{"config", "diff", "--against-addr=:9999"}, {"config", "diff", "--against-schema-dir=schemas"},
} {
outcome, _, diagnostics := executeNative(t, args...)
if outcome.Status != 2 || outcome.Kind != commandkit.OutcomeUsage || diagnostics == "" {
t.Fatalf("%v: %+v %q", args, outcome, diagnostics)
}
}
}
func TestApplicationFailureEvidenceIsNotFrameworkEvidence(t *testing.T) {
nativeConfigurationFixture(t)
writeNativeFile(t, "invalid.yml", "server:\n max_request_bytes: -1\n")
scope := frameworkConfigurationScope()
state := &acquisitionState{}
selection := ckconfig.Selection{Config: commandkit.Supplied[string]{Set: true, Value: "invalid.yml"}}
acquired, err := scope.Acquire(context.Background(), ckconfig.Request{Operation: ckconfig.Validate, Selection: selection}, applicationInput{}, state)
var native *configkit.LoadError
if !errors.As(err, &native) || errors.Is(err, errApplicationAcquisition) || ckconfig.ClassifyConfigurationError(err) != commandkit.OutcomeUsage {
t.Fatalf("typed application error lost: %v", err)
}
if acquired.Value.Findings != nil || acquired.Value.Sources != nil || acquired.Value.Effective != nil {
t.Fatalf("application evidence inserted into framework view: %+v", acquired.Value)
}
var details bytes.Buffer
for _, detail := range acquired.Explanation.Details {
if err := detail(&details); err != nil {
t.Fatal(err)
}
}
if !strings.Contains(details.String(), "Application configuration") || !strings.Contains(details.String(), "validate.error") || strings.Contains(details.String(), `scope "promptkit"`) {
t.Fatal(details.String())
}
outcome, output, diagnostics := executeNative(t, "config", "validate", "--scope=promptkit", "--config=invalid.yml", "--quiet")
if outcome.Status != 2 || output != "" || !strings.Contains(diagnostics, "Application configuration") || !strings.Contains(diagnostics, "validate.error") {
t.Fatalf("terminal evidence: %+v %q %q", outcome, output, diagnostics)
}
for _, side := range []string{"left", "right"} {
args := []string{"config", "diff", "--scope=promptkit", "--config=left.yml", "--against-config=right.yml"}
if side == "left" {
args[3] = "--config=invalid.yml"
} else {
args[4] = "--against-config=invalid.yml"
}
outcome, _, diagnostics := executeNative(t, args...)
if outcome.Status != 2 || !errors.As(outcome.Cause, &native) || !strings.Contains(diagnostics, "Application configuration ("+side+")") {
t.Fatalf("%s evidence: %+v %q", side, outcome, diagnostics)
}
}
// In contrast, a framework load failure keeps its native findings and sources.
writeNativeFile(t, "bad-framework.yml", "profiles: [\n")
writeNativeFile(t, "framework-app.yml", "promptkit:\n configuration: bad-framework.yml\n")
selection.Config.Value = "framework-app.yml"
acquired, err = scope.Acquire(context.Background(), ckconfig.Request{Operation: ckconfig.Validate, Selection: selection}, applicationInput{}, &acquisitionState{})
if err == nil || acquired.Value.Findings == nil || acquired.Value.Sources == nil || len(acquired.Value.Findings.Records) == 0 {
t.Fatalf("native framework evidence lost: %+v %v", acquired, err)
}
}
func TestAcquisitionDiagnosticsRetainBothComparisonSides(t *testing.T) {
state := &acquisitionState{}
for _, label := range []string{"left", "right"} {
result, err := configkit.Load(configkit.Mapping(label, map[string]any{"value": label}), configkit.Options[map[string]any]{
Definition: configkit.Definition[map[string]any]{Validate: func(_ *map[string]any, validation *configkit.Validation) {
validation.Warning(configkit.Keys("value"), "application finding")
}},
})
if err != nil {
t.Fatal(err)
}
state.applications = append(state.applications, applicationAcquisition{sources: result.Sources(), records: result.Diagnostics()})
}
native := commandkit.Acquired[int]{Value: 42, Diagnostics: []commandkit.Diagnostic{{Severity: commandkit.SeverityWarning, Write: func(writer io.Writer) error {
_, err := io.WriteString(writer, "framework finding\n")
return err
}}}}
acquired, err := attachApplicationEvidence(native, nil, state, 0, true)
if err != nil || acquired.Value != native.Value {
t.Fatalf("native value changed: %+v %v", acquired, err)
}
var output bytes.Buffer
for _, diagnostic := range acquired.Diagnostics {
if err := diagnostic.Write(&output); err != nil {
t.Fatal(err)
}
}
for _, fragment := range []string{"framework finding", "Application configuration (left)", "Application configuration (right)", "validate.warning"} {
if !strings.Contains(output.String(), fragment) {
t.Fatalf("lost %q: %s", fragment, output.String())
}
}
// A later callback sharing invocation state must not replay earlier evidence.
acquired, err = attachApplicationEvidence(native, nil, state, state.mark(), false)
if err != nil || len(acquired.Diagnostics) != len(native.Diagnostics) {
t.Fatalf("evidence replayed: %+v %v", acquired, err)
}
}

View File

@@ -0,0 +1,40 @@
package cli
import (
"context"
"go.maximumdirect.net/ckprompt"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/promptkit"
)
func promptSuite() ckprompt.Suite[applicationInput, *acquisitionState] {
suite := ckprompt.FromEngine(loadEngine)
suite.NewInput = func() applicationInput { return applicationInput{} }
suite.NewState = func() *acquisitionState { return &acquisitionState{} }
suite = ckprompt.WithRequestValidation(suite, loadEngine, nil)
suite = ckprompt.WithRequestPreparation(suite, loadEngine, nil)
suite = ckprompt.WithSmokeTesting(suite, loadEngine, nil)
suite = ckprompt.WithNamespaces(suite, promptkit.Namespaces{})
suite.ListPrompts = withApplicationEvidence(suite.ListPrompts)
suite.ListProfiles = withApplicationEvidence(suite.ListProfiles)
suite.ListBackends = withApplicationEvidence(suite.ListBackends)
suite.ListNamespaces = withApplicationEvidence(suite.ListNamespaces)
suite.ListCollections = withApplicationEvidence(suite.ListCollections)
suite.InspectPrompt = withApplicationEvidence(suite.InspectPrompt)
suite.InspectProfile = withApplicationEvidence(suite.InspectProfile)
suite.InspectBackend = withApplicationEvidence(suite.InspectBackend)
suite.InspectRequirements = withApplicationEvidence(suite.InspectRequirements)
suite.ValidateRequest = withApplicationEvidence(suite.ValidateRequest)
suite.PrepareRequest = withApplicationEvidence(suite.PrepareRequest)
suite.SmokeTest = withApplicationEvidence(suite.SmokeTest)
return suite
}
func withApplicationEvidence[R, V any](callback func(context.Context, R, applicationInput, *acquisitionState) (commandkit.Acquired[V], error)) func(context.Context, R, applicationInput, *acquisitionState) (commandkit.Acquired[V], error) {
return func(ctx context.Context, request R, input applicationInput, state *acquisitionState) (commandkit.Acquired[V], error) {
start := state.mark()
acquired, err := callback(ctx, request, input, state)
return attachApplicationEvidence(acquired, err, state, start, false)
}
}

View File

@@ -0,0 +1,368 @@
package cli
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"reflect"
"strings"
"sync/atomic"
"testing"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/promptkit"
)
func nativePromptFixture(t *testing.T, endpoint string) {
t.Helper()
t.Chdir(t.TempDir())
writeNativeFile(t, "app.yml", "promptkit:\n configuration: framework.yml\n schema_dir: nonexistent-schemas\ntransient_retries: 0\n")
writeNativeFile(t, "framework.yml", fmt.Sprintf(`collections:
support:
release_version: '1'
backends:
- id: local
endpoint: %q
profiles:
- id: writer
backend: support/local
model: controlled-model
temperature: 0.8
max_tokens: 99
top_p: 0.9
timeout_seconds: 4
reasoning_effort: high
extra_params:
stale: true
- id: protected
backend: support/local
model: controlled-model
api_key_required: true
prompts:
- id: summary
default_profile: support/protected
session_id: '{{.session_variable}}'
inputs:
- name: transcript
required: true
content_type: text/plain
description: Exact transcript binding
- name: glossary
required: false
description: ''
messages:
- role: user
content: 'template-canary {{input "transcript"}} {{input "unlisted"}} {{if .mode}}{{input "glossary"}}{{end}} {{.title}}'
output:
format: text
validation_mode: none
- id: dynamic
default_profile: support/protected
messages:
- role: user
content: '{{input .source}}'
output:
format: text
validation_mode: none
- id: unsupported
default_profile: support/protected
messages:
- role: user
content: '{{define "child"}}{{input "called"}}{{end}}{{template "child" .}}'
output:
format: text
validation_mode: none
- id: schema-needed
default_profile: support/protected
messages:
- role: user
content: 'Return JSON'
output:
format: json
validation_mode: json_schema
schema_path: missing.json
review:
release_version: '1'
profiles:
- id: writer
backend: support/local
model: alternate-model
prompts:
- id: summary
default_profile: review/writer
inputs:
- name: memo
required: true
messages:
- role: user
content: '{{input "memo"}}'
output:
format: text
validation_mode: none
`, endpoint))
}
type consumerRequirements struct {
PromptID string `json:"prompt_id"`
ProfileID string `json:"profile_id"`
Inputs []struct {
Name string `json:"name"`
Kind promptkit.RequirementKind `json:"kind"`
Declared bool `json:"declared"`
ContentType *string `json:"content_type"`
Description *string `json:"description"`
} `json:"inputs"`
Variables []struct {
Name string `json:"name"`
Supplied bool `json:"supplied"`
} `json:"variables"`
Complete bool `json:"complete"`
Issues []struct {
Code promptkit.RequirementIssueCode `json:"code"`
} `json:"issues"`
}
func discoverNative(t *testing.T, prompt string, flags ...string) consumerRequirements {
t.Helper()
args := []string{"promptkit", "requirements", "show", prompt, "--config=app.yml", "--format=json"}
args = append(args, flags...)
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 {
t.Fatalf("discovery: %+v %q %q", outcome, output, diagnostics)
}
var report consumerRequirements
if err := json.Unmarshal([]byte(output), &report); err != nil {
t.Fatal(err)
}
for _, excluded := range []string{"template-canary", "unrelated-variable-value", "schema_version"} {
if strings.Contains(output, excluded) {
t.Fatalf("unexpected discovery content %q: %s", excluded, output)
}
}
return report
}
func TestRequirementsExposeExactBindingsBeforeArtifactsExist(t *testing.T) {
nativePromptFixture(t, "http://127.0.0.1:1/v1")
report := discoverNative(t, "support/summary", "--var=mode=", "--var=unrelated=unrelated-variable-value", "--session-id=session")
if !report.Complete || report.PromptID != "support/summary" || report.ProfileID != "support/protected" {
t.Fatalf("discovery identity/completeness: %+v", report)
}
var names []string
for _, input := range report.Inputs {
names = append(names, input.Name)
switch input.Name {
case "transcript":
if input.Kind != promptkit.RequirementRequired || !input.Declared || input.ContentType == nil || *input.ContentType != "text/plain" || input.Description == nil {
t.Fatalf("required metadata: %+v", input)
}
case "unlisted":
if input.Kind != promptkit.RequirementRequired || input.Declared {
t.Fatalf("undeclared reference: %+v", input)
}
case "glossary":
if input.Kind != promptkit.RequirementOptional || input.Description == nil || *input.Description != "" {
t.Fatalf("optional metadata: %+v", input)
}
}
}
if !reflect.DeepEqual(names, []string{"glossary", "transcript", "unlisted"}) {
t.Fatalf("exact input names: %v", names)
}
var emptySupplied, absent bool
for _, variable := range report.Variables {
if variable.Name == "mode" {
emptySupplied = variable.Supplied
}
if variable.Name == "title" {
absent = !variable.Supplied
}
}
if !emptySupplied || !absent {
t.Fatalf("variable presence: %+v", report.Variables)
}
schemaIndependent := discoverNative(t, "support/schema-needed")
if !schemaIndependent.Complete || len(schemaIndependent.Inputs) != 0 {
t.Fatalf("schema-free discovery: %+v", schemaIndependent)
}
// Complete discovery does not assert that these required bindings exist.
outcome, _, diagnostics := executeNative(t, "promptkit", "requirements", "validate", "support/summary", "--config=app.yml", "--profile=support/writer", "--var=mode=", "--var=title=Title", "--session-id=session")
if outcome.Status == 0 || diagnostics == "" {
t.Fatalf("unbound request validated: %+v %q", outcome, diagnostics)
}
outcome, _, diagnostics = executeNative(t, "promptkit", "show", "prepared", "support/schema-needed", "--config=app.yml", "--profile=support/writer")
if outcome.Status == 0 || diagnostics == "" {
t.Fatalf("missing preparation schema accepted: %+v %q", outcome, diagnostics)
}
}
func TestRequirementsPreserveConditionalAndPartialDiscovery(t *testing.T) {
nativePromptFixture(t, "http://127.0.0.1:1/v1")
unknown := discoverNative(t, "support/summary", "--session-id=session")
if unknown.Complete || len(unknown.Issues) == 0 {
t.Fatalf("unknown condition claimed complete: %+v", unknown)
}
for _, input := range unknown.Inputs {
if input.Name == "glossary" && input.Kind != promptkit.RequirementConditional {
t.Fatalf("unknown branch: %+v", input)
}
}
known := discoverNative(t, "support/summary", "--var=mode=include", "--session-id=session")
if !known.Complete {
t.Fatalf("known branch incomplete: %+v", known)
}
for _, input := range known.Inputs {
if input.Name == "glossary" && input.Kind != promptkit.RequirementRequired {
t.Fatalf("known branch: %+v", input)
}
}
dynamic := discoverNative(t, "support/dynamic")
if dynamic.Complete || len(dynamic.Issues) == 0 {
t.Fatalf("dynamic name not partial: %+v", dynamic)
}
resolved := discoverNative(t, "support/dynamic", "--var=source=exact,name")
if !resolved.Complete || len(resolved.Inputs) != 1 || resolved.Inputs[0].Name != "exact,name" || resolved.Inputs[0].Declared {
t.Fatalf("resolved identifier: %+v", resolved)
}
unsupported := discoverNative(t, "support/unsupported")
var found bool
for _, issue := range unsupported.Issues {
found = found || issue.Code == promptkit.RequirementIssueUnsupportedConstruct
}
if unsupported.Complete || !found {
t.Fatalf("unsupported analysis not preserved: %+v", unsupported)
}
}
func TestRequirementsSelectionUsesNativeNamespacesAndFailures(t *testing.T) {
nativePromptFixture(t, "http://127.0.0.1:1/v1")
before := discoverNative(t, "summary", "--prompt-namespace=support", "--var=mode=", "--session-id=session")
after := discoverNative(t, "support/summary", "--prompt-namespace=review", "--profile=writer", "--profile-namespace=review", "--var=mode=", "--session-id=session")
if after.PromptID != "support/summary" || after.ProfileID != "review/writer" || !reflect.DeepEqual(before.Inputs, after.Inputs) {
t.Fatalf("identity/definition changed: before=%+v after=%+v", before, after)
}
other := discoverNative(t, "review/summary")
if other.PromptID != "review/summary" || other.ProfileID != "review/writer" || len(other.Inputs) != 1 || other.Inputs[0].Name != "memo" {
t.Fatalf("other definition: %+v", other)
}
for _, args := range [][]string{
{"promptkit", "requirements", "show", "missing", "--config=app.yml"},
{"promptkit", "requirements", "show", "support/summary", "--config=app.yml", "--profile=missing"},
} {
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status == 0 || output != "" || diagnostics == "" {
t.Fatalf("selection failure: %+v %q %q", outcome, output, diagnostics)
}
}
}
func TestNativeInventoriesInspectionAndPreparationDoNotGenerate(t *testing.T) {
var calls atomic.Int64
var fail atomic.Bool
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls.Add(1)
w.Header().Set("Content-Type", "application/json")
if fail.Load() {
w.WriteHeader(http.StatusServiceUnavailable)
fmt.Fprint(w, `{"error":{"message":"provider-private-canary"}}`)
return
}
fmt.Fprint(w, `{"choices":[{"message":{"role":"assistant","content":"controlled"}}]}`)
}))
defer server.Close()
nativePromptFixture(t, server.URL+"/v1")
for _, args := range [][]string{
{"promptkit", "list", "prompts", "--all-namespaces"},
{"promptkit", "list", "profiles", "--namespace=support"},
{"promptkit", "list", "backends", "--namespace=support"},
{"promptkit", "list", "namespaces"},
{"promptkit", "list", "collections"},
{"promptkit", "show", "prompt", "support/summary"},
{"promptkit", "show", "profile", "support/writer"},
{"promptkit", "show", "backend", "support/local"},
} {
args = append(args, "--config=app.yml", "--format=json")
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 || output == "" {
t.Fatalf("%v: %+v %q %q", args, outcome, output, diagnostics)
}
var value any
if err := json.Unmarshal([]byte(output), &value); err != nil {
t.Fatal(err)
}
if args[1] == "show" && args[2] == "prompt" && !strings.Contains(output, "template-canary") {
t.Fatalf("native prompt content omitted: %s", output)
}
}
engine, err := loadEngine(context.Background(), ckconfig.Selection{Config: commandkit.Supplied[string]{Value: "app.yml", Set: true}}, applicationInput{}, nil)
if err != nil {
t.Fatal(err)
}
nativePrompts, err := engine.ListPrompts(context.Background())
if err != nil {
t.Fatal(err)
}
outcome, output, diagnostics := executeNative(t, "promptkit", "list", "prompts", "--config=app.yml", "--format=json")
var listed []promptkit.PromptIdentity
if err := json.Unmarshal([]byte(output), &listed); err != nil {
t.Fatal(err)
}
if outcome.Status != 0 || !reflect.DeepEqual(listed, nativePrompts) {
t.Fatalf("native default listing changed: %+v %q %q", outcome, output, diagnostics)
}
outcome, output, diagnostics = executeNative(t, "promptkit", "list", "prompts", "--namespace=review", "--config=app.yml", "--format=json")
if outcome.Status != 0 || strings.Contains(output, "support/summary") || !strings.Contains(output, "review/summary") {
t.Fatalf("namespace filter lost: %+v %q %q", outcome, output, diagnostics)
}
writeNativeFile(t, "transcript.md", "artifact-payload-canary")
flags := []string{"summary", "--config=app.yml", "--prompt-namespace=support", "--profile=writer", "--profile-namespace=support", "--session-id=session", "--var=mode=", "--var=title=Title", "--input-file=transcript=transcript.md", "--input=unlisted=literal"}
for _, command := range [][]string{{"promptkit", "requirements", "validate"}, {"promptkit", "show", "prepared"}} {
args := append(append([]string{}, command...), flags...)
outcome, output, diagnostics := executeNative(t, append(args, "--format=json")...)
if outcome.Status != 0 {
t.Fatalf("%v: %+v %q %q", args, outcome, output, diagnostics)
}
if command[1] == "show" && (!strings.Contains(output, "artifact-payload-canary") || !strings.Contains(output, "support/writer") || !strings.Contains(output, "support/summary")) {
t.Fatalf("native prepared content/context lost: %s", output)
}
}
for _, format := range []string{"", "text", "yaml"} {
args := append([]string{"promptkit", "show", "prepared"}, flags...)
if format != "" {
args = append(args, "--format="+format)
}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 || !strings.Contains(output, "artifact-payload-canary") {
t.Fatalf("native preview %q: %+v %q %q", format, outcome, output, diagnostics)
}
}
if calls.Load() != 0 {
t.Fatal("inspection/preparation contacted provider")
}
// Smoke tests are the explicit provider-effect boundary. Native findings,
// not an application readiness policy, determine what the report says.
outcome, output, diagnostics = executeNative(t, "promptkit", "test", "text_inference", "--config=app.yml", "--profile=writer", "--profile-namespace=support", "--format=json")
if outcome.Status != 0 || calls.Load() != 1 || !strings.Contains(output, "text_inference") {
t.Fatalf("controlled smoke: %+v %q %q calls=%d", outcome, output, diagnostics, calls.Load())
}
fail.Store(true)
outcome, output, diagnostics = executeNative(t, "promptkit", "test", "text_inference", "--config=app.yml", "--profile=support/writer", "--format=json")
var findings struct {
Completed bool `json:"completed"`
Failure string `json:"failure"`
}
if err := json.Unmarshal([]byte(output), &findings); err != nil {
t.Fatal(err)
}
if outcome.Status != 0 || !findings.Completed || findings.Failure == "" || strings.Contains(output+diagnostics, "provider-private-canary") {
t.Fatalf("native unsuccessful finding changed: %+v %q %q", outcome, output, diagnostics)
}
writeNativeFile(t, "invalid-app.yml", "server:\n max_request_bytes: -1\n")
outcome, output, diagnostics = executeNative(t, "promptkit", "requirements", "show", "support/summary", "--config=invalid-app.yml", "--quiet")
if outcome.Kind != commandkit.OutcomeUsage || output != "" || !strings.Contains(diagnostics, "Application configuration") {
t.Fatalf("acquisition evidence: %+v %q %q", outcome, output, diagnostics)
}
}

View File

@@ -0,0 +1,102 @@
package cli
import (
"errors"
"text/template"
"time"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/ckprompt"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/promptkit"
)
type runInput struct {
Selection ckconfig.Selection
PromptID string
Resources ckprompt.ResourceInput
Inputs ckprompt.PromptInputs
Execution ckprompt.ExecutionInput
Namespaces promptkit.Namespaces
OperationTimeout time.Duration
ReportPath commandkit.Supplied[string]
ReportFormat commandkit.Supplied[commandkit.Format]
}
var artifactTextTemplate = template.Must(commandkit.ParseTextTemplate("artifact", `{{printf "%s" .Artifact.Body}}`, nil))
func runDeclarations() []commandkit.Declaration {
resources := ckprompt.NewResourceFlags(func(input *runInput) *ckprompt.ResourceInput { return &input.Resources })
inputs := ckprompt.NewPromptInputFlags(func(input *runInput) *ckprompt.PromptInputs { return &input.Inputs })
execution := ckprompt.NewExecutionFlags(func(input *runInput) *ckprompt.ExecutionInput { return &input.Execution })
flags := configurationSelectors(func(input *runInput) *ckconfig.Selection { return &input.Selection })
flags = append(flags, resources.Profile, resources.SessionID)
flags = append(flags, inputs.All()...)
flags = append(flags, execution.All()...)
flags = append(flags, reportFlags()...)
flags = append(flags, commandkit.ValueFlag(commandkit.FlagMeta{Name: "run-timeout", Usage: "Whole-operation timeout as a Go duration."}, (*time.Duration)(nil), time.ParseDuration,
func(input *runInput, value commandkit.Supplied[time.Duration]) { input.OperationTimeout = value.Value }))
for _, namespace := range []struct {
name string
field func(*runInput) *string
}{
{"prompt", func(input *runInput) *string { return &input.Namespaces.Prompt }},
{"profile", func(input *runInput) *string { return &input.Namespaces.Profile }},
{"backend", func(input *runInput) *string { return &input.Namespaces.Backend }},
} {
flags = append(flags, commandkit.ValueFlag(commandkit.FlagMeta{Name: "llm-" + namespace.name + "-namespace", Usage: "Select the " + namespace.name + " namespace."}, (*string)(nil), parseString,
func(input *runInput, value commandkit.Supplied[string]) { *namespace.field(input) = value.Value }))
}
command := commandkit.NewCommand(commandkit.CommandSpec[runInput]{
Name: "run", Summary: "Run a stored prompt.", Flags: flags,
Arguments: []commandkit.Argument[runInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "PROMPT_ID", Usage: "Stored prompt identifier."}, true, parseString,
func(input *runInput, value commandkit.Supplied[string]) { input.PromptID = value.Value })},
Run: runPrompt,
CheckInput: func(input runInput) error { return checkReportInput(input.ReportPath) },
})
declarations := []commandkit.Declaration{command}
for _, name := range []string{"profile", "session-id", "var", "input-text", "input-file", "endpoint", "model", "temperature", "max-tokens", "top-p", "timeout-seconds", "service-tier", "reasoning-effort", "api-key-env", "transient-retries", "extra-params", "prompt-namespace", "profile-namespace", "backend-namespace"} {
declarations = append(declarations, commandkit.FlagAliasFor("run", "--"+name, "--llm-"+name))
}
for _, name := range []string{"input", "llm-input"} {
declarations = append(declarations, commandkit.FlagAliasFor("run", "--"+name, "--llm-input-text"))
}
return declarations
}
func requestFromRunInput(input runInput) promptkit.RunRequest {
return promptkit.RunRequest{
PromptID: input.PromptID, ProfileID: input.Resources.Profile.Value, SessionID: input.Resources.SessionID.Value,
Inputs: input.Inputs.Inputs, Vars: input.Inputs.Vars, Execution: input.Execution.Execution,
TransientRetries: input.Execution.TransientRetries, OperationTimeout: input.OperationTimeout,
}
}
func runPrompt(invocation commandkit.Invocation, input runInput) commandkit.Outcome {
state := &acquisitionState{}
engine, err := loadEngine(invocation.Context, input.Selection, applicationInput{}, state)
applicationFailed := errors.Is(err, errApplicationAcquisition)
acquired, err := attachApplicationEvidence(commandkit.Acquired[*promptkit.Engine]{Value: engine}, err, state, 0, false)
queueDiagnostics(invocation.Reporter(), acquired.Diagnostics)
if err != nil {
if !applicationFailed {
return frameworkFailure(invocation.Reporter(), err, acquired.Explanation)
}
return requestFailure(err, acquired.Explanation)
}
inspection, err := engine.InspectConfiguration()
if err != nil {
return requestFailure(err, acquired.Explanation)
}
diagnostics, explanation := ckconfig.AdaptDiagnostics("PromptKit configuration:\n", inspection.Sources(), inspection.Diagnostics())
queueDiagnostics(invocation.Reporter(), diagnostics)
engine, err = engine.WithNamespaces(input.Namespaces)
if err != nil {
return requestFailure(err, explanation)
}
result, err := engine.Run(invocation.Context, requestFromRunInput(input))
if err != nil {
return requestFailure(err, explanation)
}
return deliverRunResult(invocation, input, result)
}

View File

@@ -0,0 +1,237 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"sync/atomic"
"testing"
"time"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
"go.yaml.in/yaml/v4"
)
func TestPositionalRunMapsNativeBindingsAndNamespaces(t *testing.T) {
requests := make(chan map[string]any, 1)
const content = " \x00<artifact>&\n尾-no-newline"
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var request map[string]any
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
t.Error(err)
}
request["authorization"] = r.Header.Get("Authorization")
select {
case requests <- request:
default:
t.Error("unexpected duplicate provider call")
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{"choices": []any{map[string]any{"message": map[string]any{"role": "assistant", "content": content}}}})
}))
defer server.Close()
nativePromptFixture(t, "http://127.0.0.1:1/v1")
t.Setenv("SCRIPTORIUM_CONTROLLED_KEY", "synthetic-credential-canary")
writeNativeFile(t, "note,part=1.txt", "file,transcript=body")
args := []string{"run", "summary", "--config=app.yml", "--prompt-namespace=support", "--profile=writer", "--profile-namespace=support", "--backend-namespace=review", "--session-id=caller-session",
"--input-file=transcript=note,part=1.txt", "--input-text=transcript=first,text=1", "--input-file=transcript=note,part=1.txt", "--input-file=unlisted=missing.txt", "--input=unlisted=last,literal=2", "--var=mode=", "--var=title=Title,with=equals",
"--endpoint=" + server.URL + "/v1", "--model=chosen-model", "--temperature=0", "--max-tokens=0", "--top-p=0", "--timeout-seconds=0", "--reasoning-effort=", "--service-tier=priority", `--extra-params={"seed":0,"test_payload":[0,"x"]}`, "--api-key-env=SCRIPTORIUM_CONTROLLED_KEY", "--transient-retries=0", "--run-timeout=5s", "--format=json"}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 || strings.Contains(output+diagnostics, "synthetic-credential-canary") {
t.Fatalf("run: %+v %q %q", outcome, output, diagnostics)
}
var result promptkit.RunResult
if err := json.Unmarshal([]byte(output), &result); err != nil {
t.Fatal(err)
}
if string(result.Artifact.Body) != content || result.PromptID != "support/summary" || result.SelectedProfileID != "support/writer" || result.SelectedBackendID != "support/local" || result.SessionID != "caller-session" {
t.Fatalf("native result/context: %+v", result)
}
params := result.EffectiveModelParams
if params.Model != "chosen-model" || params.Temperature != 0 || params.MaxTokens != 0 || params.TopP != 0 || params.TimeoutSeconds != 0 || params.ReasoningEffort != "" || params.ServiceTier != "priority" {
t.Fatalf("native explicit overrides: %+v", params)
}
select {
case request := <-requests:
messages := request["messages"].([]any)
message := messages[0].(map[string]any)["content"].(string)
for _, want := range []string{"file,transcript=body", "last,literal=2", "Title,with=equals"} {
if !strings.Contains(message, want) {
t.Fatalf("lost literal/mapping %q: %s", want, message)
}
}
for _, key := range []string{"temperature", "max_tokens", "top_p", "seed"} {
if value, exists := request[key]; !exists || value != float64(0) {
t.Fatalf("explicit zero %s lost: %+v", key, request)
}
}
if request["model"] != "chosen-model" || request["service_tier"] != "priority" || request["authorization"] != "Bearer synthetic-credential-canary" || request["stale"] != nil || request["reasoning_effort"] != nil {
t.Fatalf("provider overrides: %+v", request)
}
default:
t.Fatal("provider was not called")
}
}
func TestRunDeliversRawAndNativeStructuredResults(t *testing.T) {
const content = " <raw>&\x00\nno-final-newline"
var calls atomic.Int64
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls.Add(1)
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{"choices": []any{map[string]any{"message": map[string]any{"content": content}}}})
}))
defer server.Close()
nativePromptFixture(t, server.URL+"/v1")
flags := []string{"support/summary", "--config=app.yml", "--llm-profile=support/writer", "--llm-session-id=session", "--llm-input=transcript=text", "--llm-input-text=unlisted=literal", "--llm-var=mode=", "--llm-var=title=Title"}
for _, format := range []string{"", "text", "json", "yaml"} {
args := append([]string{"run"}, flags...)
if format != "" {
args = append(args, "--format="+format)
}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 0 {
t.Fatalf("%s: %+v %q %q", format, outcome, output, diagnostics)
}
if format == "" || format == "text" {
if output != content || diagnostics != "" {
t.Fatalf("raw output decorated: %q %q", output, diagnostics)
}
} else {
var report map[string]any
if err := yaml.Unmarshal([]byte(output), &report); err != nil {
t.Fatal(err)
}
if report["prompt_id"] != "support/summary" || report["run_id"] == nil || report["artifact"] == nil || report["result"] != nil || report["schema_version"] != nil {
t.Fatalf("non-native result: %+v", report)
}
}
}
outcome, output, diagnostics := executeNative(t, append(append([]string{"run"}, flags...), "--verbose")...)
if outcome.Status != 0 || output != content || diagnostics == "" {
t.Fatalf("verbose streams: %+v %q %q", outcome, output, diagnostics)
}
if calls.Load() != 5 {
t.Fatalf("generation dispatches=%d", calls.Load())
}
// The same selected prompt/profile/context used above is valid through the
// native preview and requirements paths (Narratio's consistency scenario).
discovered := discoverNative(t, "support/summary", "--profile=support/writer", "--session-id=session", "--var=mode=")
if discovered.PromptID != "support/summary" || discovered.ProfileID != "support/writer" {
t.Fatal(discovered)
}
}
func TestRunDistinguishesCompletedInvalidContentAndOperationalFailure(t *testing.T) {
var fail atomic.Bool
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
if fail.Load() {
w.WriteHeader(401)
fmt.Fprint(w, `{"error":{"message":"provider-private-canary"}}`)
return
}
fmt.Fprint(w, `{"choices":[{"message":{"content":"not-json"}}]}`)
}))
defer server.Close()
nativePromptFixture(t, server.URL+"/v1")
writeNativeFile(t, "invalid-content.yml", "profiles:\n - id: local\n endpoint: "+server.URL+"/v1\n model: controlled\nprompts:\n - id: json\n default_profile: local\n messages:\n - role: user\n content: Return JSON\n output:\n format: json\n validation_mode: json\n")
writeNativeFile(t, "json-app.yml", "promptkit:\n configuration: invalid-content.yml\ntransient_retries: 0\n")
args := []string{"run", "json", "--config=json-app.yml"}
outcome, output, diagnostics := executeNative(t, args...)
if outcome.Status != 4 || outcome.Kind != commandkit.OutcomeDomain || outcome.Domain != "validation_failed" || output != "not-json" || diagnostics == "" {
t.Fatalf("completed invalid content: %+v %q %q", outcome, output, diagnostics)
}
outcome, output, diagnostics = executeNative(t, append(args, "--format=json")...)
var result promptkit.RunResult
if err := json.Unmarshal([]byte(output), &result); err != nil {
t.Fatal(err)
}
if outcome.Status != 4 || result.Validation.Status != promptkit.ValidationFailed || string(result.Artifact.Body) != "not-json" {
t.Fatalf("invalid result lost: %+v %+v", outcome, result)
}
fail.Store(true)
outcome, output, diagnostics = executeNative(t, args...)
var generation *promptkit.GenerationError
if outcome.Status != 1 || output != "" || !errors.Is(outcome.Cause, promptkit.ErrLLMGenerate) || !errors.As(outcome.Cause, &generation) || diagnostics == "" || strings.Contains(diagnostics, "provider-private-canary") {
t.Fatalf("operational failure: %+v %q %q", outcome, output, diagnostics)
}
}
func TestRunUsageAndConfigurationFailures(t *testing.T) {
t.Chdir(t.TempDir())
for _, args := range [][]string{
{"render"}, {"inspect", "prompt"},
{"run"}, {"run", "one", "two"}, {"run", "one", "--prompt=two"}, {"run", "one", "--llm-prompt=two"},
{"run", "one", "--backend=local"}, {"run", "one", "--out=result"}, {"run", "one", "--execution-report=result"},
{"run", "one", "--llm-base-url=http://example.invalid"}, {"run", "one", "--timeout=1s"},
{"run", "one", "--prompt-id=two"}, {"run", "one", "--profile-id=local"}, {"run", "one", "--run-timeout=bad"},
{"run", "one", "--prompt-version=1"}, {"run", "one", "--prompt-dir=prompts"}, {"run", "one", "--profile-dir=profiles"},
{"run", "one", "--config-overlay=local"}, {"run", "one", "--output=file"},
} {
outcome, _, _ := executeNative(t, args...)
if outcome.Kind != commandkit.OutcomeUsage || outcome.Status != 2 {
t.Fatalf("%v: %+v", args, outcome)
}
}
writeNativeFile(t, "invalid.yml", "server:\n max_request_bytes: -1\n")
outcome, output, diagnostics := executeNative(t, "run", "one", "--config=invalid.yml")
if outcome.Status != 2 || output != "" || !strings.Contains(diagnostics, "validate.error") {
t.Fatalf("invalid config: %+v %q %q", outcome, output, diagnostics)
}
outcome, output, diagnostics = executeNative(t, "run", "one", "--config=absent.yml")
if outcome.Status != 1 || output != "" || diagnostics == "" {
t.Fatalf("missing config: %+v %q %q", outcome, output, diagnostics)
}
}
func TestTypedRequestFailureMapping(t *testing.T) {
_, invalid := configkit.Load(configkit.Bytes("invalid", []byte("[\n")), configkit.Options[map[string]any]{})
for _, test := range []struct {
err error
status int
}{
{fmt.Errorf("wrapped: %w", invalid), 2}, {promptkit.ErrInvalidConfig, 1},
{errors.Join(invalid, context.Canceled), 1}, {errors.Join(invalid, promptkit.ErrOperationTimeout, context.DeadlineExceeded), 1},
{promptkit.ErrCapacityExceeded, 1}, {promptkit.ErrValidation, 1}, {promptkit.ErrInvalidRequest, 1},
{promptkit.ErrPromptNotFound, 1}, {promptkit.ErrLLMGenerate, 1},
} {
outcome := requestFailure(test.err, commandkit.Explanation{})
if outcome.Status != test.status || !errors.Is(outcome.Cause, test.err) {
t.Fatalf("%v: %+v", test.err, outcome)
}
}
if outcome := completedRunOutcome(nil); outcome.Status != 1 || outcome.Cause == nil {
t.Fatalf("nil successful result accepted: %+v", outcome)
}
// Mapping a duration adds no local positivity policy or second timer.
for _, budget := range []time.Duration{-time.Second, 0, time.Second} {
request := requestFromRunInput(runInput{OperationTimeout: budget})
if request.OperationTimeout != budget {
t.Fatal("operation budget changed", budget)
}
}
}
func TestRunDiagnosticQueueKeepsArtifactOnStdout(t *testing.T) {
app, err := commandkit.New(commandkit.Identity{Name: "reporting"}, commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
queueDiagnostics(inv.Reporter(), []commandkit.Diagnostic{commandkit.MessageDiagnostic(commandkit.SeverityInfo, "acquisition-info"), commandkit.MessageDiagnostic(commandkit.SeverityWarning, "acquisition-warning")})
_ = inv.Reporter().Report(commandkit.Report{Value: &promptkit.RunResult{Artifact: promptkit.Artifact{Body: []byte("raw")}}, TextTemplate: artifactTextTemplate})
return commandkit.Success()
}}))
if err != nil {
t.Fatal(err)
}
var output, diagnostics bytes.Buffer
outcome := app.Execute(context.Background(), []string{"run", "--verbose"}, commandkit.Streams{Out: &output, Err: &diagnostics})
if outcome.Status != 0 || output.String() != "raw" || !strings.Contains(diagnostics.String(), "acquisition-info") || !strings.Contains(diagnostics.String(), "acquisition-warning") {
t.Fatalf("streams: %+v %q %q", outcome, output.String(), diagnostics.String())
}
}

View File

@@ -0,0 +1,87 @@
package cli
import (
"context"
"errors"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
func completedRunOutcome(result *promptkit.RunResult) commandkit.Outcome {
if result == nil {
return commandkit.Failure("Prompt execution returned no result.").WithCause(errors.New("engine returned neither a result nor an error"))
}
if result.Validation.Status == promptkit.ValidationFailed {
return commandkit.Domain("validation_failed", 4).WithExplanation("Generated content failed validation.")
}
return commandkit.Success()
}
func frameworkFailure(reporter *commandkit.Reporter, err error, explanation commandkit.Explanation) commandkit.Outcome {
var native *configkit.LoadError
if errors.As(err, &native) && native != nil {
diagnostics, terminal := ckconfig.AdaptDiagnostics("PromptKit configuration:\n", native.Sources(), native.Diagnostics())
queueDiagnostics(reporter, diagnostics)
explanation.Details = append(explanation.Details, terminal.Details...)
}
return requestFailure(err, explanation)
}
func requestFailure(err error, explanation commandkit.Explanation) commandkit.Outcome {
message := "The requested operation failed."
switch {
case errors.Is(err, promptkit.ErrOperationTimeout):
message = "The operation timeout expired."
case errors.Is(err, context.Canceled):
message = "The operation was canceled."
case errors.Is(err, context.DeadlineExceeded):
message = "A request deadline expired."
default:
if ckconfig.ClassifyConfigurationError(err) == commandkit.OutcomeUsage {
return commandkit.Usage("Invalid configuration.", explanation.Details...).WithCause(err)
}
switch {
case errors.Is(err, promptkit.ErrCapacityExceeded):
message = "Model backend capacity is exhausted."
case errors.Is(err, promptkit.ErrLLMGenerate):
message = "Model generation failed."
case errors.Is(err, promptkit.ErrValidation):
message = "The output validation operation failed."
case errors.Is(err, promptkit.ErrPromptNotFound):
message = "The selected prompt was not found."
case errors.Is(err, promptkit.ErrProfileNotFound):
message = "The selected profile was not found."
case errors.Is(err, promptkit.ErrArtifactLoad):
message = "Could not load request input artifacts."
case errors.Is(err, promptkit.ErrPromptRender):
message = "Could not render the selected prompt."
case errors.Is(err, promptkit.ErrInvalidRequest):
message = "The prompt request is invalid."
case errors.Is(err, promptkit.ErrInvalidConfig):
message = "Could not initialize PromptKit configuration."
}
}
return commandkit.Failure(message, explanation.Details...).WithCause(err)
}
func queueDiagnostics(reporter *commandkit.Reporter, diagnostics []commandkit.Diagnostic) {
deferred := reporter.AtEnd()
for _, diagnostic := range diagnostics {
if diagnostic.Write == nil {
continue
}
switch diagnostic.Severity {
case commandkit.SeverityInfo:
_ = deferred.Info("", diagnostic.Write)
case commandkit.SeverityDebug:
_ = deferred.Debug("", diagnostic.Write)
case commandkit.SeverityProgress:
_ = reporter.Progress("", diagnostic.Write)
default:
_ = deferred.Warn("", diagnostic.Write)
}
}
}

Some files were not shown because too many files have changed in this diff Show More