Compare commits
101 Commits
9849c6bda2
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 857c0bae20 | |||
| f5573f7c8f | |||
| bd7136ceeb | |||
| 10387d4aea | |||
| 7b570ed49d | |||
| 41dc1f5517 | |||
| 6f39bca841 | |||
| f9b5121432 | |||
| f2f807e87b | |||
| 733540f936 | |||
| adbe62a1e9 | |||
| f88c679a06 | |||
| 9e5cc60d09 | |||
| d903a1aa4e | |||
| 26ac62fbb7 | |||
| 83d33777e7 | |||
| 69d2ba7038 | |||
| fbe7dd56e3 | |||
| 99b0ebfc03 | |||
| bcb1a76e34 | |||
| 6ed4ac624a | |||
| c7b9c30c43 | |||
| 5f32a4f2ad | |||
| 8078c6ecc7 | |||
| 66a0954b52 | |||
| 5eeb09d1ec | |||
| f31dec61ef | |||
| 293374d7a7 | |||
| b3a0a73416 | |||
| 3f5e441756 | |||
| 23108bd2f0 | |||
| d97e2b8e30 | |||
| 3105f4d62f | |||
| 6562d63a02 | |||
| dd1915735f | |||
| a2f3588639 | |||
| 3f481ea432 | |||
| ac858be2a2 | |||
| cf50650e55 | |||
| 7afe6ba333 | |||
| 16197ae9dd | |||
| c5e54edaa5 | |||
| 78bcf86619 | |||
| 5d372dd37d | |||
| 9bd1629a9e | |||
| 50c65adac4 | |||
| a2205db152 | |||
| 27db6b6f47 | |||
| f858d57322 | |||
| de7c866662 | |||
| 77f168c660 | |||
| e7a8b0db04 | |||
| ae5344a77d | |||
| 247b67312e | |||
| ca7c7faf5c | |||
| a0134ea49a | |||
| 95a94249f1 | |||
| 87d7240f31 | |||
| 1b1d967fc7 | |||
| 932fd6da25 | |||
| 65bd2da51a | |||
| eec4fa2d91 | |||
| 2c3d8e4c8b | |||
| 79dfe0a3ef | |||
| 03b479b4d7 | |||
| 5c780a4cc0 | |||
| d79e23739f | |||
| 49461b18e4 | |||
| 222f4056e6 | |||
| a5d8394313 | |||
| ba24b7a879 | |||
| 723fee9c46 | |||
| 0cd95f6e8e | |||
| c233d03371 | |||
| 907fc51236 | |||
| cd0811a49e | |||
| 1c8494ec20 | |||
| 58cb02f973 | |||
| beaaea2f1a | |||
| b913ef0d07 | |||
| 411a67b241 | |||
| 2ba2ce1b91 | |||
| c2e2b74f83 | |||
| 9ea9d0706d | |||
| 5c302f18ac | |||
| 54c8e9011e | |||
| 2027b80311 | |||
| 0df2aad3a8 | |||
| 0d5ecfa842 | |||
| c8e2b972f3 | |||
| b1bb55a9a0 | |||
| 82b0f231b6 | |||
| 15e7c1aed9 | |||
| bb5006517b | |||
| bcf2ddf246 | |||
| ddcba9c639 | |||
| 70f7e96d02 | |||
| ea964707f7 | |||
| bbb473a3d9 | |||
| e1ce526114 | |||
| 8b6c12f912 |
2
.gitignore
vendored
2
.gitignore
vendored
@@ -29,7 +29,7 @@ go.work.sum
|
||||
.env
|
||||
|
||||
# Ignore local test directory and complied binary
|
||||
scriptorium
|
||||
/scriptorium
|
||||
local-test/
|
||||
|
||||
# ---> VisualStudio
|
||||
|
||||
@@ -3,12 +3,15 @@ when:
|
||||
|
||||
steps:
|
||||
- name: build-release-assets
|
||||
image: golang:1.25
|
||||
image: golang:1.27.4
|
||||
commands:
|
||||
- |
|
||||
set -eu
|
||||
|
||||
export GOTOOLCHAIN=local
|
||||
|
||||
version="$CI_COMMIT_TAG"
|
||||
revision="$CI_COMMIT_SHA"
|
||||
dist="dist"
|
||||
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
|
||||
notes="docs/releases/$version.md"
|
||||
@@ -29,7 +32,7 @@ steps:
|
||||
output="$dist/scriptorium-$version-$goos-$goarch$suffix"
|
||||
|
||||
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"
|
||||
}
|
||||
|
||||
|
||||
24
README.md
24
README.md
@@ -5,8 +5,11 @@ an HTTP service. It prepares prompt requests, runs them against
|
||||
OpenAI-compatible model endpoints, and returns generated output with validation
|
||||
metadata.
|
||||
|
||||
CommandKit supplies native configuration, resource discovery, preview, reporting,
|
||||
and completion interfaces alongside application generation and HTTP startup.
|
||||
|
||||
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.
|
||||
Scriptorium owns executable configuration, CLI and HTTP mapping, process
|
||||
behavior, output presentation, and HTTP artifact-containment policy.
|
||||
@@ -16,11 +19,10 @@ behavior, output presentation, and HTTP artifact-containment policy.
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium render \
|
||||
go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
|
||||
--config ./examples/config.yml \
|
||||
--prompt generic.markdown_summary \
|
||||
--input transcript=./examples/fixtures/transcript.md \
|
||||
--input glossary=./examples/fixtures/glossary.yml \
|
||||
--input-file transcript=./examples/fixtures/transcript.md \
|
||||
--input-file glossary=./examples/fixtures/glossary.yml \
|
||||
--format json
|
||||
```
|
||||
|
||||
@@ -33,20 +35,26 @@ a model. For complete invocation and output behavior, see the
|
||||
- [CLI reference](docs/cli.md)
|
||||
- [Configuration reference](docs/config.md)
|
||||
- [Application configuration inspection](docs/cli.md#application-configuration-inspection)
|
||||
- [Framework configuration inspection](docs/cli.md#framework-configuration-inspection)
|
||||
- [HTTP API reference](docs/api.md)
|
||||
- [Operations guide](docs/operations.md)
|
||||
- [Consumer integration overview](docs/consumers/api.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)
|
||||
- [Architecture policy](docs/policy/architecture.md)
|
||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
||||
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
||||
- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
- [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||
|
||||
## Examples
|
||||
|
||||
- [Minimal configuration](examples/config.yml) and
|
||||
[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/),
|
||||
[schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
|
||||
- [Render script](examples/render-markdown-summary.sh)
|
||||
|
||||
@@ -1,11 +1,29 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"io"
|
||||
"os"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"gitea.maximumdirect.net/eric/scriptorium/internal/adapter/cli"
|
||||
"go.maximumdirect.net/commandkit"
|
||||
)
|
||||
|
||||
var version = "dev"
|
||||
var revision = ""
|
||||
|
||||
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
|
||||
}
|
||||
|
||||
113
cmd/scriptorium/main_test.go
Normal file
113
cmd/scriptorium/main_test.go
Normal 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")
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
71
docs/adr/0005-configkit-boundary.md
Normal file
71
docs/adr/0005-configkit-boundary.md
Normal 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.
|
||||
54
docs/adr/0006-adopt-commandkit-native-operator-interfaces.md
Normal file
54
docs/adr/0006-adopt-commandkit-native-operator-interfaces.md
Normal 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.
|
||||
38
docs/api.md
38
docs/api.md
@@ -43,7 +43,6 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
|
||||
| Field | Required | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `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`. |
|
||||
| `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. |
|
||||
@@ -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_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. |
|
||||
| `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`
|
||||
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`,
|
||||
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
|
||||
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
|
||||
`timeout_seconds` disables the per-attempt generation deadline only, retaining the
|
||||
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
|
||||
request context remains the outer cancellation boundary.
|
||||
|
||||
Raw API-key values are not accepted. `api_key` and any other unknown model
|
||||
field cause `400 invalid_json`.
|
||||
Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
|
||||
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
|
||||
inherits the selected profile, a non-empty string replaces its value, and an
|
||||
@@ -116,14 +116,14 @@ validation contract. The response contains:
|
||||
optional `uri`;
|
||||
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
|
||||
optional `errors` and `schema_path`;
|
||||
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage,
|
||||
timing, validation, and repair-attempt metadata; and
|
||||
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
|
||||
model parameters, input hashes, usage, and timing; and
|
||||
- optional `raw_model_output` when requested.
|
||||
- optional `execution` when requested and a terminal observation exists.
|
||||
|
||||
`metadata.model_params` has `endpoint`, `model`, `temperature`,
|
||||
`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`,
|
||||
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
|
||||
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
|
||||
no effective session ID exists.
|
||||
|
||||
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report
|
||||
the corresponding Promptkit result fields independently when present. Both are
|
||||
omitted for an endpoint-only profile; Scriptorium does not infer backend
|
||||
identity from an endpoint.
|
||||
`metadata.selected_backend_id` is omitted for an endpoint-only profile;
|
||||
Scriptorium does not infer backend identity from an endpoint. The redundant
|
||||
`prompt_version`, `model_name`, `endpoint`, `validation_mode`,
|
||||
`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`,
|
||||
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 |
|
||||
| --- | --- |
|
||||
| `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. |
|
||||
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
|
||||
| `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` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
|
||||
| `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. |
|
||||
| `405` | `method_not_allowed` | The route does not accept the method. |
|
||||
| `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. |
|
||||
| `502` | `llm_failed` | Outbound model request failed. |
|
||||
| `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
|
||||
attempt timeout while it remains live retains `502 llm_failed`. A successful
|
||||
An operation timeout is checked before parent cancellation; a failed run
|
||||
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;
|
||||
delivery after a client disconnect cannot be guaranteed.
|
||||
|
||||
|
||||
418
docs/cli.md
418
docs/cli.md
@@ -1,304 +1,186 @@
|
||||
# CLI Reference
|
||||
|
||||
This is the canonical contract for invoking Scriptorium. Configuration discovery,
|
||||
precedence, application source locations, and server settings are defined in the
|
||||
[configuration reference](config.md). The [HTTP API reference](api.md) owns
|
||||
service request and response behavior.
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
```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.
|
||||
Scriptorium uses CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0.
|
||||
This document owns application invocation and delivery behavior. The pinned
|
||||
[upstream CLI contract][native-cli] owns standard family grammar and reports.
|
||||
[Configuration](config.md) owns discovery, settings, and source composition;
|
||||
the [HTTP API](api.md) owns the service contract.
|
||||
Existing callers should read the [CLI migration guide](consumers/upgrading-cli.md).
|
||||
|
||||
## 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
|
||||
scriptorium run PROMPT_ID [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 |
|
||||
| --- | --- |
|
||||
| `--config <path>` | Application configuration file. |
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--addr <listen-address>` | HTTP listen-address override. |
|
||||
| `--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. |
|
||||
| `--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. |
|
||||
| `--report PATH` | Additionally write the returned native result to a separate file. |
|
||||
| `--report-format text\|yaml\|json` | Explicit separate-report format; omission leaves native automatic rendering selected. |
|
||||
|
||||
`serve` accepts no runtime model override flags. HTTP request fields, response
|
||||
schemas, and error codes are defined in the [HTTP API reference](api.md).
|
||||
The operation budget is independent of the integer per-attempt timeout.
|
||||
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
|
||||
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
||||
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
The main report goes through the invocation reporter to stdout. Automatic/text
|
||||
output is exactly `Artifact.Body`, with no added newline, header, escaping, or
|
||||
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
|
||||
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`,
|
||||
and writes to stdout unless `--out` is supplied. It loads and normalizes the
|
||||
selected definition but does not resolve a profile, load a schema, render a
|
||||
template, reserve backend capacity, or call a model.
|
||||
Save main output with shell redirection or the subprocess stdout destination.
|
||||
There is no `--output` or `--out` flag. Omit `--quiet` when capturing the main
|
||||
result: native quiet suppresses it even when stdout is redirected.
|
||||
|
||||
## `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
|
||||
scriptorium inspect profile --profile ID
|
||||
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
The requested file is written even in quiet mode. Omission creates no separate
|
||||
report. An explicitly empty path is a usage error before generation; `-` is an
|
||||
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
|
||||
resolves profile inheritance and backend defaults, but never reads a credential
|
||||
value, loads a prompt, reserves capacity, or calls a model. Unset provider
|
||||
controls are shown as zero values when Promptkit leaves them unspecified.
|
||||
Only a returned result is eligible for delivery. A resultless failure leaves an
|
||||
existing report untouched; it does not synthesize an invocation-error result.
|
||||
Main delivery is attempted first, then the requested report even if main
|
||||
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
|
||||
scriptorium config validate [flags]
|
||||
scriptorium config show [flags]
|
||||
scriptorium config sources [flags]
|
||||
scriptorium config explain --path JSON_POINTER [flags]
|
||||
```
|
||||
The native `config` family defaults to `app`; select `--scope promptkit` for
|
||||
captured framework configuration or use native scope discovery/all-scope modes.
|
||||
`app` uses the actual completed ConfigKit result and does not construct an engine.
|
||||
|
||||
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
|
||||
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`,
|
||||
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
||||
configuration selectors and overrides; request, credential, backend-editing,
|
||||
output-format, and output-file flags are not accepted. Positional arguments
|
||||
are rejected.
|
||||
Native `--set POINTER=JSON` is enabled only for `app`. Records go directly to
|
||||
ConfigKit: duplicate and ancestor/descendant-overlapping paths are rejected,
|
||||
not resolved by flag order. No application-specific configuration flags or
|
||||
custom `--against-*` counterparts are installed.
|
||||
|
||||
`validate` writes no success output; status 0 means the application configuration
|
||||
loaded and passed its own validation. It does not establish that a prompt
|
||||
directory exists, credentials are present, or Promptkit can construct an
|
||||
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources`
|
||||
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`.
|
||||
Native diff uses independent `--against-config`, `--against-overlay`, and
|
||||
supported `--against-set` selections. Omitted right-side values do not inherit
|
||||
the left side. See the [upstream contract][native-cli] for focused paths,
|
||||
metadata discovery, source IDs, findings, explanations, and detailed comparisons.
|
||||
|
||||
`explain` requires an explicitly supplied `--path` in JSON Pointer syntax.
|
||||
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.
|
||||
## Framework Configuration Inspection
|
||||
|
||||
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
||||
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
||||
leave partial data on failure. The inspection output can contain paths,
|
||||
identifiers, `api_key_env` reference names, and ordinary `extra_params` values,
|
||||
including displaced historical values in explanations;
|
||||
protect it accordingly. Raw API-key values are not read or emitted by these
|
||||
commands.
|
||||
The `promptkit` config scope loads application settings selected by `--config`
|
||||
and `--overlay`, constructs an engine, and exposes its captured native view.
|
||||
It does not accept temporary overrides; native capability checks also apply
|
||||
when an all-scope operation requests them.
|
||||
|
||||
## 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`
|
||||
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.
|
||||
## Discovery, Preview, And Explicit Smoke Testing
|
||||
|
||||
CLI inputs are file references. HTTP inline inputs are defined by the
|
||||
[HTTP API reference](api.md).
|
||||
Inventories retain native defaults and `--namespace`/`--all-namespaces` filters.
|
||||
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
|
||||
writes a concise summary to stderr. The summary includes `backend=<id>` when
|
||||
Promptkit selected a backend; endpoint-only profiles omit it.
|
||||
- `render` writes prepared-run output to stdout, or to `--out` when supplied,
|
||||
without a success summary. Text output includes `selected_backend_id` after
|
||||
`selected_profile_id` when Promptkit selected one; endpoint-only profiles
|
||||
omit it.
|
||||
- `serve` writes startup and server errors to stderr.
|
||||
Smoke-test kinds are `reachability`, `authentication`, `text_inference`,
|
||||
`structured_output`, or `all`, with native aliases as documented upstream.
|
||||
These explicit commands may contact providers and incur cost. Their presence
|
||||
does not add a startup/provider probe. Read the native findings: unsuccessful or
|
||||
unsupported checks are not automatically invocation failures.
|
||||
|
||||
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 |
|
||||
| --- | --- |
|
||||
| `0` | Success. |
|
||||
| `1` | Parse, configuration, loading, rendering, generation, output-write, or other runtime error. |
|
||||
| `2` | `run` generated and wrote output, but validation failed. |
|
||||
| 0 | Native success, subject to successful presentation/delivery. |
|
||||
| 1 | Operational failure, including lookup/preparation/generation/capacity, cancellation/timeouts, unclassified load errors, and delivery failure for an otherwise successful run. |
|
||||
| 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
|
||||
backend capacity is exhausted`. The HTTP capacity response is defined in the
|
||||
[HTTP API reference](api.md).
|
||||
Native finalization handles presentation errors: success/usage become operational;
|
||||
an already nonzero domain outcome retains its classification/status. A report-file
|
||||
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
|
||||
|
||||
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.
|
||||
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||
|
||||
293
docs/config.md
293
docs/config.md
@@ -1,207 +1,158 @@
|
||||
# Configuration Reference
|
||||
|
||||
This is the canonical reference for Scriptorium application settings. Prompt,
|
||||
profile, schema, execution-setting, built-in profile, and framework credential
|
||||
semantics are defined by the
|
||||
[Promptkit v0.11.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
||||
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
|
||||
outcomes, see the [HTTP API reference](api.md).
|
||||
This document owns Scriptorium's application settings, discovery, and source
|
||||
selection. [CLI syntax](cli.md) and the [HTTP API](api.md) have separate owners.
|
||||
Framework definitions and execution semantics belong to the pinned
|
||||
[PromptKit v0.23.3 formats][formats]; ConfigKit v1.2.1 owns
|
||||
[native composition and inspection][configkit].
|
||||
|
||||
## 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;
|
||||
2. a configuration file; then
|
||||
3. CLI overrides.
|
||||
| Preset | Directories in order | Filename groups |
|
||||
| --- | --- | --- |
|
||||
| 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
|
||||
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
|
||||
If neither exists, it uses built-in defaults. An explicit `--config` path must
|
||||
exist and decode successfully.
|
||||
Named means `scriptorium.yml`, then `scriptorium.yaml`. Generic means
|
||||
`config.yml`, `config.yaml`, `main.yml`, then `main.yaml`.
|
||||
ConfigKit uses native Go directory resolution (including its user-config/home
|
||||
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),
|
||||
[complete configuration](../examples/config.full.yml), and
|
||||
[composed configuration](../examples/config.composed.yml) are copyable examples.
|
||||
ConfigKit assembles the main, enabled imports, and selected overlay, applies its
|
||||
inheritance/composition rules, creates typed defaults and strictly decodes, applies
|
||||
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,
|
||||
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
|
||||
An explicit empty string is a value: it clears a file-provided optional path
|
||||
or, for required `prompt_dir`, fails the command's prerequisite. A scalar
|
||||
`null` is not an empty string and is rejected for scalar fields; nullable
|
||||
fields such as `transient_retries` retain their documented meaning. Raw
|
||||
API-key fields are not accepted.
|
||||
Complete copyable configurations are maintained under
|
||||
[examples](../examples/config.yml), including [full settings](../examples/config.full.yml),
|
||||
[application imports](../examples/config.composed.yml),
|
||||
[framework fragment composition](../examples/config.collections.yml),
|
||||
[collection checkout discovery](../examples/config.discovery.yml), and
|
||||
[framework inheritance](../examples/config.inheritance.yml).
|
||||
|
||||
ConfigKit applies defaults, the selected file, then only explicitly supplied
|
||||
application CLI flags before validating the result. Paths in the application
|
||||
document remain relative to the process working directory, not to the file's
|
||||
directory. Load diagnostics are printed safely on stderr; invalid application
|
||||
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
|
||||
```yaml
|
||||
promptkit:
|
||||
configuration: ./examples/promptkit.yml
|
||||
schema_dir: ./examples/schemas
|
||||
```
|
||||
|
||||
Import and overlay file locations are constrained by ConfigKit;
|
||||
*application path values* such as `prompt_dir` remain relative
|
||||
to the process working directory even when authored in a fragment or overlay.
|
||||
These source constraints are separate from HTTP artifact containment.
|
||||
The `promptkit` section contains acquisition settings, not embedded framework
|
||||
definitions. Profiles, prompts, backends, and collections belong in the separate
|
||||
framework document. The retired `promptkit_sources`, top-level `schema_dir`,
|
||||
and `defaults.render_format` fields have no compatibility conversion and are
|
||||
rejected by strict decoding, as are unknown/raw credential fields.
|
||||
|
||||
| Field | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. |
|
||||
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
|
||||
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
|
||||
| `server.addr` | `:8080` | Address used by `serve`. |
|
||||
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
|
||||
| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
||||
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
||||
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
||||
| `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. |
|
||||
| `promptkit.configuration` | empty | One external framework file; omission/empty selects no external main. |
|
||||
| `promptkit.schema_dir` | `.` | Schema base directory passed to PromptKit. |
|
||||
| `transient_retries` | upstream default | Optional nonnegative engine retry count. Omitted/null delegates upstream; zero disables additional transient attempts. |
|
||||
| `server.addr` | `:8080` | HTTP listen address. |
|
||||
| `server.artifact_root` | empty | Root enabling HTTP file-artifact references. |
|
||||
| `server.max_request_bytes` | `16777216` | Encoded HTTP request limit; zero is unlimited. |
|
||||
| `server.max_artifact_bytes` | `16777216` | HTTP file-artifact limit; zero is unlimited. |
|
||||
| `server.max_response_bytes` | `16777216` | Encoded HTTP response limit; zero is unlimited. |
|
||||
|
||||
The size fields must be zero or greater. The [HTTP API](api.md) defines how
|
||||
each limit is enforced and reported. `server.artifact_root` configures an HTTP
|
||||
deployment boundary; see [operations](operations.md) for deployment handling.
|
||||
Size fields are nonnegative signed 64-bit values. [HTTP behavior](api.md) defines
|
||||
their enforcement; [operations](operations.md) covers safe deployment choices.
|
||||
|
||||
The `config validate`, `config show`, `config sources`, and `config explain`
|
||||
commands inspect this
|
||||
application configuration without creating a Promptkit engine. `show` is a
|
||||
resolved inspection snapshot, not necessarily a reloadable file. Application
|
||||
validation does not check framework sources, backend connectivity, or credential
|
||||
availability. `api_key_env` is an environment-variable *name* and remains
|
||||
visible in inspection; its environment value is never read by ConfigKit.
|
||||
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.
|
||||
ConfigKit strictly decodes application YAML: empty files, unknown fields,
|
||||
multiple documents, aliases/anchors, and incompatible/null values fail under its
|
||||
schema rules. Explicit empty strings and numeric zeros remain values. The
|
||||
nullable retry field preserves null. Application paths are trimmed/cleaned and
|
||||
the server address is trimmed within ConfigKit's resolver, with native
|
||||
normalization evidence. Paths remain relative to process cwd, not the application
|
||||
file's directory. No general environment-variable override layer is installed.
|
||||
|
||||
## 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
|
||||
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
|
||||
```
|
||||
`--overlay NAME` passes the name unchanged to ConfigKit. At the selected release,
|
||||
empty and exact lowercase `default` select none; other names use letters,
|
||||
digits, underscores, or hyphens and select `overlays/NAME.yml` beneath the main
|
||||
source root. A missing selected overlay fails. It is not a filesystem-path flag,
|
||||
inherited stack, or fallback-root mechanism. An active overlay after absent-main
|
||||
search exhaustion has no independent filesystem root in this application.
|
||||
|
||||
Each mapping key is the case-sensitive backend ID. `endpoint` is required;
|
||||
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are
|
||||
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting
|
||||
`queue_capacity` lets Promptkit use its default for a limited backend, while
|
||||
an explicit `queue_capacity: 0` disables queueing.
|
||||
|
||||
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.
|
||||
Only `serve` has named application override flags, for its HTTP settings.
|
||||
Native application-scope `--set` records are passed directly to ConfigKit.
|
||||
Nonconflicting records are supported; duplicate and ancestor/descendant paths
|
||||
are rejected rather than resolved by order. Configuration commands have no
|
||||
application-defined source/schema/HTTP selectors or comparison counterparts.
|
||||
Native comparison selections and supported overrides are independent on each side.
|
||||
|
||||
## Framework Source Mapping
|
||||
|
||||
Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit
|
||||
when constructing its engine. Scriptorium does not redefine or independently
|
||||
parse those framework file formats.
|
||||
A nonempty resolved `promptkit.configuration` becomes an import-enabled
|
||||
`configkit.File` main input to PromptKit. An empty value leaves its main absent.
|
||||
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
|
||||
session IDs are Promptkit contracts.
|
||||
- Profile fields, numeric ranges, execution defaults, overlay precedence,
|
||||
built-in profiles, and credential rules are Promptkit contracts.
|
||||
- Schema path behavior and generated-content validation are Promptkit
|
||||
contracts.
|
||||
Imports in that external document compose framework definitions using PromptKit's
|
||||
schema and ConfigKit's native rules. The [maintained entry file](../examples/promptkit.yml)
|
||||
imports the application's maintained prompt/profile fragments and backend
|
||||
definitions. Peer conflicts are errors, not filename-order precedence.
|
||||
Native whole-record replacement and inheritance remain framework-owned.
|
||||
Application settings do not embed or re-decode framework definitions.
|
||||
|
||||
See the
|
||||
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
||||
for all of those definitions. The files under
|
||||
[`examples/prompts`](../examples/prompts/),
|
||||
[`examples/profiles`](../examples/profiles/), and
|
||||
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium
|
||||
application inputs using that tagged format.
|
||||
PromptKit captures message-file resources with their defining source context
|
||||
when constructing the engine. Schema/artifact reads, credential resolution, and
|
||||
provider work retain native preparation/runtime lifecycles. The server keeps one
|
||||
engine until restarted; later CLI invocations perform fresh loads.
|
||||
|
||||
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and
|
||||
`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.
|
||||
### Collection Checkout Discovery
|
||||
|
||||
## 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
|
||||
request overrides. Keep secret values in environment variables and store only
|
||||
their names in configuration or framework source files. Do not place raw keys
|
||||
in configuration, prompts, profiles, CLI arguments, examples, or HTTP
|
||||
payloads.
|
||||
```yaml
|
||||
config:
|
||||
imports:
|
||||
- glob: collections/*/collection.yml
|
||||
- glob: collections/*/collection.yaml
|
||||
```
|
||||
|
||||
An optional `api_key_env` whose environment value is absent or empty can result
|
||||
in an unauthenticated provider request. A profile that declares credentials
|
||||
required still fails as an invalid request when no credential source is
|
||||
selected, and fails with `ErrAPIKeyEnvMissing` when its selected environment
|
||||
source is absent or empty. Scriptorium never reads or emits the environment
|
||||
value itself.
|
||||
Each independently maintained checkout declares its namespace and explicitly
|
||||
imports its own definitions relative to its entry file. Checkout names do not
|
||||
determine resource IDs. The [support example](../examples/discovery/collections/support-repo/collection.yml)
|
||||
imports multiple profiles/prompts and a source-relative message; the
|
||||
[review example](../examples/discovery/collections/review-repo/collection.yaml)
|
||||
uses the other spelling. Arbitrary checkout YAML is not loaded implicitly.
|
||||
|
||||
Unset optional provider controls are omitted from compatible provider requests.
|
||||
A positive Promptkit `repair_attempts` budget can add provider calls, latency,
|
||||
token use, and cost; see the tagged format reference for its permitted values
|
||||
and validation-mode requirements.
|
||||
Either glob may have no matches. New checkouts become visible on a later
|
||||
invocation, not through server hot reload. Entries in one discovery document are
|
||||
peers: conflicting qualified IDs fail instead of relying on glob order.
|
||||
|
||||
Promptkit's built-in client makes up to two additional attempts for eligible
|
||||
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.
|
||||
## Inspection And Credentials
|
||||
|
||||
Promptkit's
|
||||
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
|
||||
defines outbound authentication, provider request mapping, transport limits,
|
||||
and timeout layering.
|
||||
The native `app` scope exposes the actual application result without acquiring
|
||||
framework definitions or credentials. The `promptkit` scope exposes the captured
|
||||
framework result selected by the application config/overlay. They are not merged
|
||||
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)
|
||||
- [HTTP API reference](api.md)
|
||||
- [Operations guide](operations.md)
|
||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
||||
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md
|
||||
[configkit]: https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md
|
||||
|
||||
@@ -11,10 +11,11 @@ and the HTTP service according to the boundary your application needs.
|
||||
- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
|
||||
- HTTP service: [HTTP API reference](../api.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
|
||||
Promptkit directly. The tagged
|
||||
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
||||
`go.maximumdirect.net/promptkit` directly. The tagged
|
||||
[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.
|
||||
Consumers arriving from the former Scriptorium Go API should follow the
|
||||
[migration guide](migrating-to-promptkit.md).
|
||||
@@ -27,7 +28,7 @@ Consumers are responsible for:
|
||||
- supplying required inputs and template variables;
|
||||
- supplying credentials through the chosen interface;
|
||||
- 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
|
||||
- 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
|
||||
[CLI reference](../cli.md), HTTP status behavior belongs to the
|
||||
[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).
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# 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
|
||||
|
||||
Scriptorium `v0.11.1` at
|
||||
|
||||
95
docs/consumers/upgrading-cli.md
Normal file
95
docs/consumers/upgrading-cli.md
Normal 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.
|
||||
100
docs/consumers/upgrading-promptkit.md
Normal file
100
docs/consumers/upgrading-promptkit.md
Normal 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.
|
||||
@@ -2,9 +2,13 @@
|
||||
|
||||
This is the contributor entry point for Scriptorium. Scriptorium is an
|
||||
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
|
||||
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
|
||||
|
||||
@@ -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) |
|
||||
| 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 |
|
||||
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| 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 |
|
||||
|
||||
Cross-project changes land and release in Promptkit before Scriptorium adopts
|
||||
the tagged version. Do not commit a Go workspace, local replacement, vendored
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -1,63 +1,67 @@
|
||||
# Subprocess Integration
|
||||
|
||||
This document covers process-boundary behavior for callers that invoke
|
||||
Scriptorium as a child process. Command syntax, flags, output, and exit codes
|
||||
are defined by the [CLI reference](../cli.md). Interface selection belongs in
|
||||
the [consumer integration overview](../consumers/api.md).
|
||||
Use the executable when a local process boundary is appropriate.
|
||||
The [CLI contract](../cli.md) owns exact command/flag/status syntax; the
|
||||
[consumer overview](../consumers/api.md) compares subprocess and HTTP use.
|
||||
|
||||
## Process Contract
|
||||
## Artifact-First Execution And Inspection
|
||||
|
||||
Use `scriptorium render` when the caller needs prepared output without a model
|
||||
call, and `scriptorium run` for generation. Pass an explicit `--config` or
|
||||
make the configuration search paths available to the child process; configuration
|
||||
discovery, fields, profile selection, and credential mechanisms are defined in
|
||||
the [configuration reference](../config.md).
|
||||
Select a stored prompt and capture its generated artifact from stdout. Use native
|
||||
requirements discovery before generated input files exist, concrete validation
|
||||
once bindings exist, and prepared preview to render without a model call.
|
||||
The [CLI migration guide](../consumers/upgrading-cli.md) explains replacements
|
||||
for older command and file-output conventions.
|
||||
|
||||
Pass required API-key environment variables through the child environment. Do
|
||||
not place raw API keys in arguments. Keep the environment limited to the values
|
||||
needed for the selected profile.
|
||||
Pass an explicit application configuration or deliberately arrange the child's
|
||||
[configuration discovery](../config.md). Supply only the environment needed for
|
||||
selected credentials; never put raw keys in arguments.
|
||||
|
||||
For application-only preflight, invoke `scriptorium config validate`; it exits
|
||||
0 with empty stdout when the application configuration loads, but does not
|
||||
prove that Promptkit sources or credentials are usable. `config show` emits
|
||||
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.
|
||||
Discovery completeness is distinct from binding satisfaction and execution
|
||||
readiness. Partial reports can succeed. Consumers own their binding graph and
|
||||
policy for incomplete findings; Scriptorium supplies no workflow state.
|
||||
|
||||
## Streams And Output Ownership
|
||||
## Streams, Reports, And Availability
|
||||
|
||||
Capture stdout and stderr separately. Stdout contains the requested artifact or
|
||||
prepared output unless the caller selects an output file; stderr contains
|
||||
summaries, diagnostics, and server messages. The exact destinations and status
|
||||
meanings are part of the [CLI reference](../cli.md), not a stable stderr data
|
||||
protocol.
|
||||
Capture stdout and stderr separately. Diagnostics are not a machine-readable
|
||||
error protocol, even when structured result output is selected. Prefer exit
|
||||
classification and native report fields; do not parse diagnostic prose.
|
||||
|
||||
When using `--out`, the caller owns the output path, its permissions, and
|
||||
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as
|
||||
potentially sensitive.
|
||||
The default generated result is artifact content. Native structured results and
|
||||
optional separate reports carry the full returned result, including content and
|
||||
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
|
||||
metadata separate from generated stdout or `--out`. The caller owns that
|
||||
path's permissions and retention. Output and report files are not a
|
||||
transaction: one may be written when the other fails, and a preexisting report
|
||||
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.
|
||||
To save main output, supply a file as the subprocess stdout destination or use
|
||||
shell redirection. Omit quiet when that main result is needed: quiet suppresses
|
||||
it even for redirected stdout. A separately requested report remains an
|
||||
application file effect independent of quiet and main format selection.
|
||||
|
||||
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
|
||||
|
||||
A CLI invocation performs one synchronous request and creates no durable run
|
||||
state. A supervising process that needs cancellation must terminate the child
|
||||
process according to its own process-management policy. A later invocation is a
|
||||
new request and can make another model call; there is no resume or checkpoint
|
||||
protocol.
|
||||
Interrupt/SIGTERM cancels the child's invocation context. Engine cancellation is
|
||||
cooperative. The [whole-operation budget](../cli.md#generation) is separate from
|
||||
per-attempt provider timeouts and excludes process/configuration setup and
|
||||
delivery. Supervisors still own forced process termination when required.
|
||||
|
||||
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
|
||||
engine invocation. It is separate from the per-attempt generation timeout and
|
||||
does not include child startup or output writing. A deadline failure exits 1;
|
||||
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).
|
||||
A new invocation is a new request that may incur another provider call/cost.
|
||||
There is no checkpoint, archive, conversation, or resume protocol. Deployment and
|
||||
sensitive-data handling belong to [operations](../operations.md).
|
||||
|
||||
@@ -1,136 +1,89 @@
|
||||
# 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
|
||||
and translate Promptkit results or errors back to CLI or HTTP behavior. They
|
||||
own IO and presentation mechanics, not framework decisions.
|
||||
## CLI Composition And Acquisition
|
||||
|
||||
External contracts are canonical in the [CLI reference](../cli.md) and
|
||||
[HTTP API reference](../api.md). Promptkit's public engine contract is
|
||||
described by its tagged
|
||||
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md).
|
||||
`app.go` composes application run/serve declarations with native configuration,
|
||||
PromptKit, completion, help, and version support. CommandKit owns parsing,
|
||||
declaration-input checks, reporting selection, presentation, and finalization.
|
||||
|
||||
## 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
|
||||
`internal/adapter/cli`.
|
||||
- `internal/adapter/cli` resolves settings through `internal/config`,
|
||||
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
||||
and owns output files, summaries, and exit codes.
|
||||
- `internal/config` delegates application YAML decoding, default resolution,
|
||||
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.
|
||||
`native_config.go` adapts the actual application result through
|
||||
`ckconfig.FromConfigKit` and framework inspection through `ckprompt.ConfigScope`.
|
||||
Native views own effective values, paths, metadata, sources, findings, explanations,
|
||||
redaction, and comparison. Application inspection does not construct an engine.
|
||||
Comparison loads each side from that side's selection; there is no config/engine
|
||||
cache or effective-document reconstruction.
|
||||
|
||||
## 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
|
||||
`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.
|
||||
## Generation And Delivery
|
||||
|
||||
`inspect prompt` maps the selected ID and optional version to
|
||||
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
|
||||
data. It constructs the same configuration-aware engine but does not perform
|
||||
preparation or generation.
|
||||
`native_run.go` binds the required operand and reusable resource/input/execution
|
||||
flags into a native RunRequest. Ordinary typed namespace flags feed
|
||||
`Engine.WithNamespaces`; stored references are not rewritten. One `Engine.Run`
|
||||
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
|
||||
formats a safe application-owned effective profile view. It intentionally does
|
||||
not require prompt, schema, or artifact sources.
|
||||
`outcomes.go` maps typed failures and native configuration evidence to native
|
||||
outcomes, preserving causes while keeping provider payloads out of terminal
|
||||
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
|
||||
its validation, effective-output, source, and explanation views directly. It
|
||||
does not construct a Promptkit engine. The CLI maps source records into a small
|
||||
JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
|
||||
`delivery.go` submits the actual RunResult to the invocation reporter with a
|
||||
reusable artifact-byte text template. The optional file renders that same value
|
||||
without the template through CommandKit's writer API, outside reporter callbacks
|
||||
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
|
||||
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
||||
adapter's consumer-owned `Runner` interface, and starts the server.
|
||||
## Server And HTTP
|
||||
|
||||
The command paths assemble the engine from the same resolved prompt, profile,
|
||||
and schema directories plus configured custom backends. Each backend is mapped
|
||||
to Promptkit's public `Backend` value and registered during engine construction,
|
||||
so one constructed server engine retains one immutable backend registry and its
|
||||
associated capacity state.
|
||||
`server.go` loads application settings, injects the restricted artifact reader
|
||||
into one engine, installs the existing HTTP handler/limits, and opens a listener.
|
||||
It retains the header timeout and engine retry defaults. Context cancellation
|
||||
calls Server.Close; callback coordination finishes connection/listener closing
|
||||
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
|
||||
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and
|
||||
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact,
|
||||
validation, model, usage, and metadata values directly.
|
||||
The optional HTTP retry count maps to `RunRequest.TransientRetries` without
|
||||
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.
|
||||
HTTP optional reports use one per-request `internal/report.Collector`, attached
|
||||
only for opted-in requests. It copies terminal aggregates, not event history,
|
||||
and is never the CLI result report. Success/error attachment and encoded-size
|
||||
handling retain the [HTTP contract](../api.md#execution-report). Reader sentinel
|
||||
identities survive PromptKit wrapping for status mapping.
|
||||
|
||||
## 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`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `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.
|
||||
When changing behavior, update its canonical external contract and focused
|
||||
integration protection. Required shared capabilities belong upstream before
|
||||
tagged adoption, not in a resurrected application framework facade.
|
||||
|
||||
@@ -1,19 +1,18 @@
|
||||
# Internal Component Overview
|
||||
|
||||
This is the complete inventory of Scriptorium's implemented Go components.
|
||||
The [architecture policy](../policy/architecture.md) owns normative boundaries;
|
||||
This inventory describes implemented Go components. The
|
||||
[architecture policy](../policy/architecture.md) owns normative boundaries;
|
||||
public behavior belongs in the linked contracts.
|
||||
|
||||
| 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) |
|
||||
| `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/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/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/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../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` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [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` | 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` | 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` | ConfigKit application schema, discovery/selection, defaults/resolution/validation callbacks, and completed-value conversion. | [Configuration](../config.md), [sources](sources.md) |
|
||||
| `internal/defaults` | Application and HTTP default constants. | [Configuration](../config.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) |
|
||||
|
||||
Framework implementation packages are provided by
|
||||
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
||||
and are not part of this repository.
|
||||
CommandKit, ckconfig, ckprompt, ConfigKit, and PromptKit are released upstream
|
||||
dependencies, not local framework packages. There is no custom CLI formatter
|
||||
package or compatibility dispatch surface.
|
||||
|
||||
@@ -1,101 +1,55 @@
|
||||
# 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
|
||||
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 Boundary And Engine Construction
|
||||
|
||||
## 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
|
||||
Scriptorium defaults, configuration files, and CLI overrides. It also resolves
|
||||
the application-owned `backends` mapping into sorted engine settings.
|
||||
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps
|
||||
each configured backend to Promptkit's public engine registration when
|
||||
constructing an engine shared by the command path.
|
||||
The typed application PromptKit section selects acquisition only. In
|
||||
`engine.go`, a nonempty resolved configuration path becomes an import-enabled
|
||||
main Input; an empty path leaves Main nil. The schema base and retry default are
|
||||
passed directly, retaining the bundled underlay. There is no source-list parser,
|
||||
directory classification/expansion, or one-underlay-per-selector algorithm.
|
||||
|
||||
Scriptorium does not search, parse, validate, or overlay framework source files
|
||||
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema
|
||||
resolution, ordinary file artifacts, and the related error identities.
|
||||
Framework imports resolve within the native source context. Message resources
|
||||
are captured from their defining contexts at engine construction. Schema and
|
||||
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
|
||||
fields and precedence. Maintained files under `examples/` are application
|
||||
inputs that use Promptkit's tagged formats.
|
||||
|
||||
## Application Configuration Boundary
|
||||
|
||||
`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.
|
||||
Application-only inspection uses its completed result without framework
|
||||
acquisition. Framework inspection exposes the native captured view separately.
|
||||
Diagnostic decoration in the [CLI adapter](adapters.md) carries application
|
||||
messages without combining evidence trees or effective documents. There is no
|
||||
per-invocation engine/config cache or cross-invocation snapshot guarantee.
|
||||
|
||||
## Restricted HTTP Artifact Reader
|
||||
|
||||
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP
|
||||
requests. The `serve` path injects it with
|
||||
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for
|
||||
inbound HTTP inputs.
|
||||
The HTTP adapter implements `promptkit.ArtifactReader`; server construction
|
||||
injects it through the public option. Ordinary CLI artifact loading remains
|
||||
upstream-owned.
|
||||
|
||||
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;
|
||||
- denies file references when no root is configured;
|
||||
- resolves relative paths below the configured root;
|
||||
- accepts absolute paths only when they are lexically within that root;
|
||||
- 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 does not resolve symlinks. The OS may follow a symlink inside the
|
||||
root to an outside target; this is not a filesystem sandbox or a defense against
|
||||
privileged concurrent filesystem modification. Reader errors retain identity
|
||||
through upstream artifact-load wrapping, enabling the existing HTTP mapping.
|
||||
|
||||
Containment is lexical and does not resolve symlinks. The operating system
|
||||
follows symlinks after the check. The [HTTP API](../api.md) owns observable
|
||||
request outcomes, and [operations](../operations.md) owns safe deployment
|
||||
permissions and root selection.
|
||||
|
||||
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.
|
||||
The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
|
||||
safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
|
||||
reader/handler tests own their respective boundaries; upstream owns exhaustive
|
||||
source traversal, format parsing, ordinary artifacts, and inspection semantics.
|
||||
|
||||
@@ -1,229 +1,120 @@
|
||||
# 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
|
||||
recovery for Scriptorium. It does not redefine invocation syntax, configuration
|
||||
fields, or HTTP wire behavior.
|
||||
## Deploy Sources And Process
|
||||
|
||||
- [CLI reference](cli.md): commands, output destinations, and exit codes.
|
||||
- [Configuration reference](config.md): application settings, source
|
||||
locations, defaults, and credential mapping.
|
||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md):
|
||||
prompt, profile, schema, execution-setting, and framework credential
|
||||
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.
|
||||
Provide readable application configuration, its selected framework entry file,
|
||||
and explicitly imported definitions/resources. Set cwd deliberately: application
|
||||
path values are cwd-relative, while framework imports and message resources keep
|
||||
their native source contexts. ConfigKit confines source imports/overlays to the
|
||||
selected main's canonical root; Scriptorium does not widen it.
|
||||
|
||||
## 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.
|
||||
It has no durable run store, archive, checkpoint, cache, or resume mechanism.
|
||||
A failed or interrupted request is recovered by correcting its inputs,
|
||||
configuration, or environment and submitting a new request.
|
||||
For independent collections, install checkouts beneath the layout selected by
|
||||
the [discovery entry](../examples/discovery/framework.yml). Each checkout declares
|
||||
its namespace and explicit fragment imports; arbitrary YAML is not a framework
|
||||
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
|
||||
caller-owned data. Retention, encryption, backup, and deletion are deployment
|
||||
responsibilities.
|
||||
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.
|
||||
Supply only needed credential environment variables through a supervisor or
|
||||
secret-management mechanism. Confirm presence without printing their values.
|
||||
Raw keys do not belong in arguments or checked-in configuration.
|
||||
|
||||
## Deploy The Filesystem And Process
|
||||
## Normal Operator Workflow
|
||||
|
||||
Provide the process with readable configured Promptkit prompt, profile, and
|
||||
schema sources that follow the tagged framework formats. For an HTTP deployment
|
||||
that accepts file artifacts, use a dedicated, narrow artifact directory rather
|
||||
than a general-purpose or sensitive filesystem tree.
|
||||
1. Validate application configuration through the native application scope.
|
||||
This does not acquire framework sources or prove provider readiness.
|
||||
2. Inspect framework configuration/resources and discover requirements for the
|
||||
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,
|
||||
deploy those files beneath the selected configuration file's canonical
|
||||
directory. ConfigKit keeps imported and overlay files within that root;
|
||||
Scriptorium does not widen it. Application path values inside those files still
|
||||
resolve from the process working directory, so set that directory deliberately
|
||||
in the service manager. This configuration-source boundary is distinct from
|
||||
the HTTP artifact root and does not constrain prompt or schema directories.
|
||||
Use the [maintained preview script](../examples/render-markdown-summary.sh)
|
||||
for a provider-free example, and the [CLI contract](cli.md) for commands.
|
||||
A complete discovery report can still list required inputs that are not bound;
|
||||
a partial report can still be useful. Consumers own their policy for incomplete
|
||||
findings and changed resources between invocations.
|
||||
|
||||
When upgrading existing definitions, review selected profile IDs.
|
||||
`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).
|
||||
## Sensitive Data And Retention
|
||||
|
||||
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
|
||||
needs;
|
||||
- read the required credential environment variables without writing them to
|
||||
files or logs; and
|
||||
- write only caller-selected output locations when CLI output files are used.
|
||||
Keep main output and report destinations separate. Delivery is nontransactional:
|
||||
one destination or partial bytes can remain after failure. An existing report
|
||||
can remain on a resultless error; check status and report identity, not just file
|
||||
existence. A shell can truncate a redirected destination before the child starts.
|
||||
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
|
||||
artifact containment behavior is lexical and the operating system follows
|
||||
symlinks; account for that when choosing ownership and mount boundaries. See
|
||||
the [HTTP API reference](api.md) for the externally observable behavior.
|
||||
HTTP's optional [execution report](api.md#execution-report) remains a distinct
|
||||
terminal-observation projection. Protect its identifiers and any response data.
|
||||
It increases encoded response size and remains subject to the configured limit.
|
||||
|
||||
## Supply Credentials And Protect Runtime Data
|
||||
## HTTP Deployment And Shutdown
|
||||
|
||||
Set secret values in the process environment and configure only their
|
||||
environment-variable names. Do not put raw keys in configuration, prompt or
|
||||
profile files, process arguments, HTTP payloads, captured command lines, or
|
||||
debug dumps.
|
||||
The service has no built-in authentication/authorization. Deploy on a trusted
|
||||
network or behind appropriate authenticated proxy/gateway controls. Use a narrow,
|
||||
dedicated artifact root with controlled ownership and permissions when accepting
|
||||
file inputs; this is lexical containment, not a symlink sandbox.
|
||||
|
||||
Treat stdout, stderr, prepared-run output, generated artifacts, and HTTP
|
||||
responses as potentially sensitive. Send service logs to a controlled collector
|
||||
and apply the same retention and access rules as for model input and output.
|
||||
Use a supervisor for cwd, environment, restart policy, and stream capture.
|
||||
Startup information uses native Info reporting, not stdout banners.
|
||||
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
|
||||
application configuration and its selected sources without constructing an
|
||||
engine; this does not verify prompt files, provider access, or credentials;
|
||||
2. confirm the deployed configuration selects the intended sources and model
|
||||
credentials;
|
||||
3. use [`render`](cli.md) with the same request inputs and variables to confirm
|
||||
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.
|
||||
Plan for input/output sizes, schema complexity, provider latency, retries, and
|
||||
repair costs. Native transient attempts and repair generations can add calls and
|
||||
waiting; engine defaults and per-request overrides belong to
|
||||
[configuration](config.md) and the [CLI](cli.md)/[HTTP](api.md) contracts.
|
||||
Whole-operation budgets are distinct from per-attempt generation timeouts.
|
||||
They remain cooperative and do not include configuration/setup or delivery.
|
||||
|
||||
Inspection output can include configuration paths, names, and ordinary backend
|
||||
parameters. `config explain --path` uses JSON Pointer paths and can show
|
||||
displaced historical values as well as the final value. Protect both the
|
||||
selected paths and the output, especially when backend parameters contain
|
||||
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.
|
||||
Before increasing HTTP byte limits, measure representative requests/artifacts/
|
||||
responses, confirm memory/network/provider capacity, retain authentication and
|
||||
upstream request controls, and test a representative workload. Do not widen the
|
||||
artifact root just to make an arbitrary host path accessible.
|
||||
|
||||
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
||||
copyable preflight example. The CLI reference owns its complete invocation and
|
||||
exit semantics.
|
||||
For failures, capture diagnostics without publishing sensitive data. Verify
|
||||
selected configuration, resource identity, readable inputs, profile/credentials,
|
||||
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
|
||||
|
||||
The HTTP service has no built-in authentication or authorization. Place it on a
|
||||
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.
|
||||
There is no durable run store, archive, checkpoint, or resume mechanism.
|
||||
Cleanup concerns caller-owned files/logs only. Rotate/delete them under the
|
||||
deployment's normal retention policy; recovery starts from a new request.
|
||||
|
||||
@@ -5,23 +5,22 @@
|
||||
Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
|
||||
`docs/policy/agents.md`, `docs/policy/documentation.md`,
|
||||
`docs/policy/architecture.md`, `docs/policy/testing.md`,
|
||||
`docs/policy/release.md`, `AGENTS.md`, and the
|
||||
Policy Reading Guide section of `docs/development.md`, adapted for this
|
||||
repository.
|
||||
`docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section
|
||||
of `docs/development.md`, adapted for this repository.
|
||||
|
||||
Copyright (C) 2026 Eric Rakestraw
|
||||
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
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) |
|
||||
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
|
||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
|
||||
[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
|
||||
|
||||
@@ -29,14 +28,14 @@ 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://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/COPYRIGHT) |
|
||||
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/LICENSE).
|
||||
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/COPYRIGHT) |
|
||||
[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
|
||||
|
||||
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
|
||||
|
||||
@@ -44,87 +43,125 @@ 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://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/COPYRIGHT) |
|
||||
[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/LICENSE).
|
||||
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
|
||||
[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
|
||||
|
||||
SPDX-License-Identifier: MIT
|
||||
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||
|
||||
License and notices: [MIT](licenses/MIT.txt) |
|
||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/COPYRIGHT) |
|
||||
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/LICENSE).
|
||||
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/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
|
||||
|
||||
SPDX-License-Identifier: MIT
|
||||
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||
|
||||
License and notices: [MIT](licenses/MIT.txt) |
|
||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/COPYRIGHT) |
|
||||
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/LICENSE).
|
||||
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/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
|
||||
|
||||
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
|
||||
|
||||
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
|
||||
[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE).
|
||||
License and notices: [BSD 3-Clause](licenses/pflag-BSD-3-Clause.txt) |
|
||||
[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) |
|
||||
[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).
|
||||
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
|
||||
|
||||
[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
|
||||
|
||||
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
|
||||
|
||||
@@ -136,7 +173,7 @@ SPDX-License-Identifier: MIT AND Apache-2.0
|
||||
|
||||
License and notices: [MIT](licenses/MIT.txt) |
|
||||
[Apache 2.0](licenses/Apache-2.0.txt) |
|
||||
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
|
||||
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
|
||||
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
|
||||
[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).
|
||||
|
||||
27
docs/oss/licenses/go-x-text-BSD-3-Clause.txt
Normal file
27
docs/oss/licenses/go-x-text-BSD-3-Clause.txt
Normal 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.
|
||||
28
docs/oss/licenses/pflag-BSD-3-Clause.txt
Normal file
28
docs/oss/licenses/pflag-BSD-3-Clause.txt
Normal 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.
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
**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
|
||||
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
**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
|
||||
|
||||
@@ -39,8 +39,8 @@ Do not promote incidental implementation choices into architectural invariants.
|
||||
|
||||
## Scriptorium's Purpose And System Shape
|
||||
|
||||
Scriptorium is an executable application with CLI `run`, `render`,
|
||||
`inspect`, and `config` command families and an HTTP service started by
|
||||
Scriptorium is an executable application with CLI `run`, native `promptkit`
|
||||
and `config` families, and an HTTP service started by
|
||||
`serve`. It offers simple, request-independent execution of predefined
|
||||
prompts, not a reusable Scriptorium root Go API or a workflow framework.
|
||||
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
|
||||
|
||||
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,
|
||||
preparation, prompt and profile formats, built-in profiles, model-client
|
||||
behavior, validation, and framework defaults. Scriptorium owns application
|
||||
configuration, executable CLI and HTTP adapters, prepared-run and
|
||||
definition-inspection presentation, process behavior, and HTTP deployment
|
||||
policy. The [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
||||
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
|
||||
behavior, validation, inspection semantics, and framework defaults. Scriptorium
|
||||
owns the application domain, executable CLI and HTTP adapters, process behavior,
|
||||
and HTTP deployment policy. It interprets resolved configuration and uses
|
||||
PromptKit's supported APIs and results to satisfy user requests. The [format
|
||||
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.
|
||||
|
||||
Scriptorium uses ConfigKit v0.4.2 for strict application YAML decoding,
|
||||
resolution, and validation flow. Scriptorium retains its application schema,
|
||||
defaults, normalization, validation rules, source selection, and CLI override
|
||||
mapping. ConfigKit does not own Promptkit framework sources or HTTP artifact
|
||||
containment. The [configuration contract](../config.md) owns externally
|
||||
observable configuration behavior.
|
||||
ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
|
||||
fully resolved configuration handoff. Scriptorium supplies application schema
|
||||
and domain callbacks through ConfigKit's supported extension points and consumes
|
||||
the completed result without redefining effective configuration. PromptKit's
|
||||
configuration is also resolved through ConfigKit, with PromptKit supplying its
|
||||
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
|
||||
`internal` packages or catalog modules. It must not recreate the removed
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# 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
|
||||
|
||||
@@ -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. |
|
||||
| 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. |
|
||||
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | 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. |
|
||||
| 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, 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. |
|
||||
| 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
|
||||
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
|
||||
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
**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
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# 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
|
||||
|
||||
@@ -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)
|
||||
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.
|
||||
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.
|
||||
For another selected license, adapt the grant, SPDX expression, disclaimer, and
|
||||
text references together to reflect the author's selected grant.
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# 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
|
||||
|
||||
@@ -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
|
||||
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
|
||||
summaries belong in `docs/releases/`. The procedure must agree with the adopted
|
||||
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`:
|
||||
|
||||
- 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.
|
||||
|
||||
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,
|
||||
configuration, data, integration, or compatibility contract when the release
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
identify:
|
||||
|
||||
1. prerequisites, primary branch, and authoritative remote;
|
||||
1. prerequisites, selected release toolchain, primary branch, and authoritative
|
||||
remote;
|
||||
2. version and release-note preparation;
|
||||
3. one publication command with its selected local checks and automated guards;
|
||||
4. declared deliverables, required build targets, and automation responsibilities;
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
**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
|
||||
|
||||
@@ -178,12 +178,15 @@ Give each layer its distinct responsibility and keep expectation updates localiz
|
||||
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
|
||||
import and overlay composition, provenance, and inspection renderers.
|
||||
- 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,
|
||||
restricted artifact reading, and representative server workflows.
|
||||
- Formatting tests own prepared-run and definition-inspection text and JSON
|
||||
presentation. Architecture guards own dependency direction and removed
|
||||
framework-package boundaries.
|
||||
- CommandKit and its integrations own standard parsing and presentation.
|
||||
Scriptorium's integration tests protect native adoption, byte-preserving main
|
||||
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
|
||||
model-client behavior. Scriptorium's definition and execution fixtures
|
||||
protect adoption through its public adapter boundary without duplicating
|
||||
|
||||
@@ -9,11 +9,31 @@ discoverability requirements.
|
||||
## Prepare The Candidate
|
||||
|
||||
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
|
||||
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
|
||||
validation; when dependencies are not cached:
|
||||
repository root. The [developer guide](development.md#baseline-validation)
|
||||
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
|
||||
GOWORK=off go mod download
|
||||
@@ -66,8 +86,9 @@ The source-boundary guards reject committed workspaces, vendor trees, and
|
||||
module replacements.
|
||||
|
||||
It then runs the complete suite once with the race detector and builds Linux
|
||||
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and
|
||||
`-ldflags '-s -w'`. The native test run uses the host platform and enables cgo.
|
||||
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and linker flags
|
||||
`-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
|
||||
and toolchain downloads. Missing dependencies must be provisioned separately;
|
||||
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
|
||||
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.
|
||||
Source-publication success does not attest to workflow success or asset
|
||||
availability.
|
||||
|
||||
@@ -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
27
docs/roadmap/future.md
Normal 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
6
examples/collection-gpu.yml
Normal file
6
examples/collection-gpu.yml
Normal 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
5
examples/collections.yml
Normal file
@@ -0,0 +1,5 @@
|
||||
config:
|
||||
imports:
|
||||
- dir: config-fragments/collections
|
||||
pattern: '*.yml'
|
||||
required: true
|
||||
@@ -1,4 +0,0 @@
|
||||
backends:
|
||||
local-gpu:
|
||||
endpoint: http://localhost:11434/v1
|
||||
api_key_env: LOCAL_GPU_API_KEY
|
||||
4
examples/config-fragments/collections/10-backends.yml
Normal file
4
examples/config-fragments/collections/10-backends.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
config:
|
||||
imports:
|
||||
- path: ../../framework/backends.yml
|
||||
required: true
|
||||
4
examples/config-fragments/collections/20-profile.yml
Normal file
4
examples/config-fragments/collections/20-profile.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
config:
|
||||
imports:
|
||||
- path: ../../profiles/local-fast.yaml
|
||||
required: true
|
||||
4
examples/config-fragments/collections/30-prompt.yml
Normal file
4
examples/config-fragments/collections/30-prompt.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
config:
|
||||
imports:
|
||||
- path: ../../prompts/generic.markdown_summary.yaml
|
||||
required: true
|
||||
@@ -1,3 +1,3 @@
|
||||
prompt_dir: ./examples/prompts
|
||||
profile_dir: ./examples/profiles
|
||||
schema_dir: ./examples/schemas
|
||||
promptkit:
|
||||
configuration: ./examples/promptkit.yml
|
||||
schema_dir: ./examples/schemas
|
||||
|
||||
3
examples/config.collections.yml
Normal file
3
examples/config.collections.yml
Normal file
@@ -0,0 +1,3 @@
|
||||
promptkit:
|
||||
configuration: ./examples/collections.yml
|
||||
schema_dir: ./examples/schemas
|
||||
@@ -1,8 +1,8 @@
|
||||
# Select from the repository root; application paths remain working-directory-relative.
|
||||
configkit:
|
||||
config:
|
||||
imports:
|
||||
- path: config-fragments/sources.yml
|
||||
- path: config-fragments/backend.yml
|
||||
required: true
|
||||
|
||||
server:
|
||||
addr: :8080
|
||||
|
||||
2
examples/config.discovery.yml
Normal file
2
examples/config.discovery.yml
Normal file
@@ -0,0 +1,2 @@
|
||||
promptkit:
|
||||
configuration: ./examples/discovery/framework.yml
|
||||
@@ -1,15 +1,6 @@
|
||||
prompt_dir: ./examples/prompts
|
||||
profile_dir: ./examples/profiles
|
||||
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
|
||||
promptkit:
|
||||
configuration: ./examples/promptkit.yml
|
||||
schema_dir: ./examples/schemas
|
||||
|
||||
server:
|
||||
addr: 127.0.0.1:8080
|
||||
@@ -17,6 +8,3 @@ server:
|
||||
max_request_bytes: 16777216
|
||||
max_artifact_bytes: 16777216
|
||||
max_response_bytes: 16777216
|
||||
|
||||
defaults:
|
||||
render_format: text
|
||||
|
||||
4
examples/config.inheritance.yml
Normal file
4
examples/config.inheritance.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
# Application paths are relative to the repository invocation directory.
|
||||
promptkit:
|
||||
configuration: ./examples/inheritance.yml
|
||||
schema_dir: ./examples/schemas
|
||||
@@ -1,10 +1,7 @@
|
||||
prompt_dir: ./examples/prompts
|
||||
profile_dir: ./examples/profiles
|
||||
schema_dir: ./examples/schemas
|
||||
promptkit:
|
||||
configuration: ./examples/promptkit.yml
|
||||
schema_dir: ./examples/schemas
|
||||
|
||||
server:
|
||||
addr: :8080
|
||||
artifact_root: .
|
||||
|
||||
defaults:
|
||||
render_format: text
|
||||
|
||||
8
examples/definitions.yml
Normal file
8
examples/definitions.yml
Normal file
@@ -0,0 +1,8 @@
|
||||
config:
|
||||
imports:
|
||||
- dir: prompts
|
||||
pattern: '*.yaml'
|
||||
required: true
|
||||
- dir: profiles
|
||||
pattern: '*.y*ml'
|
||||
required: true
|
||||
12
examples/discovery/collections/review-repo/collection.yaml
Normal file
12
examples/discovery/collections/review-repo/collection.yaml
Normal 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: {}
|
||||
@@ -0,0 +1,3 @@
|
||||
id: base
|
||||
endpoint: https://example.invalid/v1
|
||||
model: review-example
|
||||
@@ -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
|
||||
20
examples/discovery/collections/support-repo/collection.yml
Normal file
20
examples/discovery/collections/support-repo/collection.yml
Normal 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: {}
|
||||
2
examples/discovery/collections/support-repo/other.yml
Normal file
2
examples/discovery/collections/support-repo/other.yml
Normal file
@@ -0,0 +1,2 @@
|
||||
repository_metadata:
|
||||
purpose: This file is not a PromptKit framework input.
|
||||
@@ -0,0 +1,4 @@
|
||||
id: base
|
||||
endpoint: https://example.invalid/v1
|
||||
model: support-example
|
||||
temperature: 0.2
|
||||
@@ -0,0 +1,3 @@
|
||||
id: fast
|
||||
extends: {id: base}
|
||||
max_tokens: 256
|
||||
@@ -0,0 +1,3 @@
|
||||
Answer the support request using this transcript:
|
||||
|
||||
{{input "transcript"}}
|
||||
@@ -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
|
||||
@@ -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
|
||||
4
examples/discovery/framework.yml
Normal file
4
examples/discovery/framework.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
config:
|
||||
imports:
|
||||
- glob: collections/*/collection.yml
|
||||
- glob: collections/*/collection.yaml
|
||||
8
examples/framework/backends.yml
Normal file
8
examples/framework/backends.yml
Normal 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
|
||||
13
examples/framework/inheritance.yml
Normal file
13
examples/framework/inheritance.yml
Normal 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
|
||||
@@ -14,5 +14,6 @@
|
||||
"vars": {
|
||||
"session_date": "2026-05-04"
|
||||
},
|
||||
"include_raw_output": false
|
||||
"include_raw_output": false,
|
||||
"include_execution_report": false
|
||||
}
|
||||
|
||||
6
examples/inheritance.yml
Normal file
6
examples/inheritance.yml
Normal file
@@ -0,0 +1,6 @@
|
||||
config:
|
||||
imports:
|
||||
- path: definitions.yml
|
||||
required: true
|
||||
- path: framework/inheritance.yml
|
||||
required: true
|
||||
2
examples/overlays/collection.yml
Normal file
2
examples/overlays/collection.yml
Normal file
@@ -0,0 +1,2 @@
|
||||
promptkit:
|
||||
configuration: ./examples/collection-gpu.yml
|
||||
@@ -1,4 +1,2 @@
|
||||
defaults:
|
||||
render_format: json
|
||||
server:
|
||||
addr: 127.0.0.1:8080
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
id: local-fast
|
||||
endpoint: http://localhost:8000/v1
|
||||
model: gpt-4o-mini
|
||||
temperature: 0.2
|
||||
max_tokens: 500
|
||||
top_p: 1.0
|
||||
timeout_seconds: 90
|
||||
profiles:
|
||||
- id: local-fast
|
||||
endpoint: http://localhost:8000/v1
|
||||
model: gpt-4o-mini
|
||||
temperature: 0.2
|
||||
max_tokens: 500
|
||||
top_p: 1.0
|
||||
timeout_seconds: 90
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
id: local-gpu
|
||||
backend: local-gpu
|
||||
model: local-model
|
||||
reasoning_effort: low
|
||||
profiles:
|
||||
- id: local-gpu
|
||||
backend: local-gpu
|
||||
model: local-model
|
||||
reasoning_effort: low
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
id: local-quality
|
||||
endpoint: http://localhost:8000/v1
|
||||
model: gpt-4.1
|
||||
temperature: 0.0
|
||||
max_tokens: 1200
|
||||
top_p: 1.0
|
||||
timeout_seconds: 180
|
||||
api_key_env: SCRIPTORIUM_API_KEY
|
||||
profiles:
|
||||
- id: local-quality
|
||||
endpoint: http://localhost:8000/v1
|
||||
model: gpt-4.1
|
||||
temperature: 0.0
|
||||
max_tokens: 1200
|
||||
top_p: 1.0
|
||||
timeout_seconds: 180
|
||||
api_key_env: SCRIPTORIUM_API_KEY
|
||||
|
||||
6
examples/promptkit.yml
Normal file
6
examples/promptkit.yml
Normal file
@@ -0,0 +1,6 @@
|
||||
config:
|
||||
imports:
|
||||
- path: definitions.yml
|
||||
required: true
|
||||
- path: framework/backends.yml
|
||||
required: true
|
||||
@@ -1,22 +1,22 @@
|
||||
id: dnd.session_recap
|
||||
version: "1.0.0"
|
||||
default_profile: local-quality
|
||||
description: Example D&D session recap prompt definition for demonstration only.
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Session source content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./dnd.session_recap.system.md
|
||||
- role: user
|
||||
content_file: ./dnd.session_recap.user.md
|
||||
output:
|
||||
format: markdown
|
||||
validation_mode: basic
|
||||
repair_attempts: 0
|
||||
prompts:
|
||||
- id: dnd.session_recap
|
||||
default_profile: local-quality
|
||||
description: Example D&D session recap prompt definition for demonstration only.
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Session source content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./dnd.session_recap.system.md
|
||||
- role: user
|
||||
content_file: ./dnd.session_recap.user.md
|
||||
output:
|
||||
format: markdown
|
||||
validation_mode: basic
|
||||
repair_attempts: 0
|
||||
|
||||
@@ -1,22 +1,22 @@
|
||||
id: generic.markdown_summary
|
||||
version: "1.0.0"
|
||||
default_profile: local-fast
|
||||
description: Generic markdown summary from transcript and glossary.
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Source transcript content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./generic.markdown_summary.system.md
|
||||
- role: user
|
||||
content_file: ./generic.markdown_summary.user.md
|
||||
output:
|
||||
format: markdown
|
||||
validation_mode: basic
|
||||
repair_attempts: 0
|
||||
prompts:
|
||||
- id: generic.markdown_summary
|
||||
default_profile: local-fast
|
||||
description: Generic markdown summary from transcript and glossary.
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Source transcript content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./generic.markdown_summary.system.md
|
||||
- role: user
|
||||
content_file: ./generic.markdown_summary.user.md
|
||||
output:
|
||||
format: markdown
|
||||
validation_mode: basic
|
||||
repair_attempts: 0
|
||||
|
||||
@@ -1,23 +1,23 @@
|
||||
id: generic.structured_events
|
||||
version: "1.0.0"
|
||||
default_profile: local-quality
|
||||
description: Produce structured event JSON from a transcript.
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Source transcript content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./generic.structured_events.system.md
|
||||
- role: user
|
||||
content_file: ./generic.structured_events.user.md
|
||||
output:
|
||||
format: json
|
||||
validation_mode: json_schema
|
||||
schema_path: structured_events.schema.json
|
||||
repair_attempts: 0
|
||||
prompts:
|
||||
- id: generic.structured_events
|
||||
default_profile: local-quality
|
||||
description: Produce structured event JSON from a transcript.
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Source transcript content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./generic.structured_events.system.md
|
||||
- role: user
|
||||
content_file: ./generic.structured_events.user.md
|
||||
output:
|
||||
format: json
|
||||
validation_mode: json_schema
|
||||
schema_path: structured_events.schema.json
|
||||
repair_attempts: 0
|
||||
|
||||
@@ -5,9 +5,8 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
cd "$repo_root"
|
||||
|
||||
go run ./cmd/scriptorium render \
|
||||
go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
|
||||
--config ./examples/config.yml \
|
||||
--prompt generic.markdown_summary \
|
||||
--input transcript=./examples/fixtures/transcript.md \
|
||||
--input glossary=./examples/fixtures/glossary.yml \
|
||||
--input-file transcript=./examples/fixtures/transcript.md \
|
||||
--input-file glossary=./examples/fixtures/glossary.yml \
|
||||
--format text
|
||||
|
||||
@@ -4,22 +4,18 @@ set -euo pipefail
|
||||
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$repo_root"
|
||||
|
||||
go run ./cmd/scriptorium render \
|
||||
go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
|
||||
--config ./examples/config.full.yml \
|
||||
--prompt generic.markdown_summary \
|
||||
--prompt-version 1.0.0 \
|
||||
--profile local-gpu \
|
||||
--session-id example-session \
|
||||
--reasoning-effort= \
|
||||
--input transcript=./examples/fixtures/transcript.md \
|
||||
--input glossary=./examples/fixtures/glossary.yml
|
||||
--input-file transcript=./examples/fixtures/transcript.md \
|
||||
--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 \
|
||||
--prompt generic.markdown_summary \
|
||||
--format json
|
||||
|
||||
go run ./cmd/scriptorium inspect profile \
|
||||
go run ./cmd/scriptorium promptkit show profile local-gpu \
|
||||
--config ./examples/config.full.yml \
|
||||
--profile local-gpu \
|
||||
--format json
|
||||
|
||||
21
go.mod
21
go.mod
@@ -1,17 +1,20 @@
|
||||
module gitea.maximumdirect.net/eric/scriptorium
|
||||
|
||||
go 1.25.5
|
||||
go 1.27.0
|
||||
|
||||
require (
|
||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.2
|
||||
gitea.maximumdirect.net/eric/promptkit v0.11.2
|
||||
go.maximumdirect.net/ckconfig v0.9.0
|
||||
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 (
|
||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0 // indirect
|
||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0 // indirect
|
||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
|
||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
|
||||
golang.org/x/text v0.14.0 // indirect
|
||||
gopkg.in/yaml.v3 v3.0.1 // indirect
|
||||
github.com/inconshreveable/mousetrap v1.1.0 // indirect
|
||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
|
||||
github.com/spf13/cobra v1.10.2 // indirect
|
||||
github.com/spf13/pflag v1.1.0 // indirect
|
||||
golang.org/x/text v0.44.0 // indirect
|
||||
)
|
||||
|
||||
43
go.sum
43
go.sum
@@ -1,20 +1,29 @@
|
||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.2 h1:ZMxmv8pOnLtAx2hFTf8Z+pHKUbR89xErkBhwjr4yK24=
|
||||
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/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
|
||||
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/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
|
||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
|
||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
||||
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
||||
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
|
||||
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
|
||||
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
|
||||
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
|
||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
|
||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
|
||||
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
|
||||
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/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
|
||||
59
internal/adapter/cli/acquisition.go
Normal file
59
internal/adapter/cli/acquisition.go
Normal 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
|
||||
}
|
||||
42
internal/adapter/cli/app.go
Normal file
42
internal/adapter/cli/app.go
Normal 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 })...)
|
||||
}
|
||||
44
internal/adapter/cli/app_test.go
Normal file
44
internal/adapter/cli/app_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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")
|
||||
}
|
||||
@@ -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())
|
||||
}
|
||||
}
|
||||
73
internal/adapter/cli/delivery.go
Normal file
73
internal/adapter/cli/delivery.go
Normal 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
|
||||
}
|
||||
287
internal/adapter/cli/delivery_test.go
Normal file
287
internal/adapter/cli/delivery_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
196
internal/adapter/cli/discovery_test.go
Normal file
196
internal/adapter/cli/discovery_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
24
internal/adapter/cli/engine.go
Normal file
24
internal/adapter/cli/engine.go
Normal 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
|
||||
}
|
||||
42
internal/adapter/cli/examples_test.go
Normal file
42
internal/adapter/cli/examples_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
235
internal/adapter/cli/lifecycle_test.go
Normal file
235
internal/adapter/cli/lifecycle_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
41
internal/adapter/cli/native_config.go
Normal file
41
internal/adapter/cli/native_config.go
Normal 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
|
||||
}
|
||||
247
internal/adapter/cli/native_config_test.go
Normal file
247
internal/adapter/cli/native_config_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
40
internal/adapter/cli/native_prompt.go
Normal file
40
internal/adapter/cli/native_prompt.go
Normal 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)
|
||||
}
|
||||
}
|
||||
368
internal/adapter/cli/native_prompt_test.go
Normal file
368
internal/adapter/cli/native_prompt_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
102
internal/adapter/cli/native_run.go
Normal file
102
internal/adapter/cli/native_run.go
Normal 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)
|
||||
}
|
||||
237
internal/adapter/cli/native_run_test.go
Normal file
237
internal/adapter/cli/native_run_test.go
Normal 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())
|
||||
}
|
||||
}
|
||||
87
internal/adapter/cli/outcomes.go
Normal file
87
internal/adapter/cli/outcomes.go
Normal 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
Reference in New Issue
Block a user