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
|
.env
|
||||||
|
|
||||||
# Ignore local test directory and complied binary
|
# Ignore local test directory and complied binary
|
||||||
scriptorium
|
/scriptorium
|
||||||
local-test/
|
local-test/
|
||||||
|
|
||||||
# ---> VisualStudio
|
# ---> VisualStudio
|
||||||
|
|||||||
@@ -3,12 +3,15 @@ when:
|
|||||||
|
|
||||||
steps:
|
steps:
|
||||||
- name: build-release-assets
|
- name: build-release-assets
|
||||||
image: golang:1.25
|
image: golang:1.27.4
|
||||||
commands:
|
commands:
|
||||||
- |
|
- |
|
||||||
set -eu
|
set -eu
|
||||||
|
|
||||||
|
export GOTOOLCHAIN=local
|
||||||
|
|
||||||
version="$CI_COMMIT_TAG"
|
version="$CI_COMMIT_TAG"
|
||||||
|
revision="$CI_COMMIT_SHA"
|
||||||
dist="dist"
|
dist="dist"
|
||||||
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
|
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
|
||||||
notes="docs/releases/$version.md"
|
notes="docs/releases/$version.md"
|
||||||
@@ -29,7 +32,7 @@ steps:
|
|||||||
output="$dist/scriptorium-$version-$goos-$goarch$suffix"
|
output="$dist/scriptorium-$version-$goos-$goarch$suffix"
|
||||||
|
|
||||||
CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
|
CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
|
||||||
go build -trimpath -ldflags "-s -w" \
|
go build -trimpath -ldflags "-s -w -X main.version=$version -X main.revision=$revision" \
|
||||||
-o "$output" "$pkg"
|
-o "$output" "$pkg"
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
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
|
OpenAI-compatible model endpoints, and returns generated output with validation
|
||||||
metadata.
|
metadata.
|
||||||
|
|
||||||
|
CommandKit supplies native configuration, resource discovery, preview, reporting,
|
||||||
|
and completion interfaces alongside application generation and HTTP startup.
|
||||||
|
|
||||||
The application uses
|
The application uses
|
||||||
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/)
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/)
|
||||||
for prompt, profile, schema, preparation, generation, and validation behavior.
|
for prompt, profile, schema, preparation, generation, and validation behavior.
|
||||||
Scriptorium owns executable configuration, CLI and HTTP mapping, process
|
Scriptorium owns executable configuration, CLI and HTTP mapping, process
|
||||||
behavior, output presentation, and HTTP artifact-containment policy.
|
behavior, output presentation, and HTTP artifact-containment policy.
|
||||||
@@ -16,11 +19,10 @@ behavior, output presentation, and HTTP artifact-containment policy.
|
|||||||
From the repository root:
|
From the repository root:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go run ./cmd/scriptorium render \
|
go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
|
||||||
--config ./examples/config.yml \
|
--config ./examples/config.yml \
|
||||||
--prompt generic.markdown_summary \
|
--input-file transcript=./examples/fixtures/transcript.md \
|
||||||
--input transcript=./examples/fixtures/transcript.md \
|
--input-file glossary=./examples/fixtures/glossary.yml \
|
||||||
--input glossary=./examples/fixtures/glossary.yml \
|
|
||||||
--format json
|
--format json
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -33,20 +35,26 @@ a model. For complete invocation and output behavior, see the
|
|||||||
- [CLI reference](docs/cli.md)
|
- [CLI reference](docs/cli.md)
|
||||||
- [Configuration reference](docs/config.md)
|
- [Configuration reference](docs/config.md)
|
||||||
- [Application configuration inspection](docs/cli.md#application-configuration-inspection)
|
- [Application configuration inspection](docs/cli.md#application-configuration-inspection)
|
||||||
|
- [Framework configuration inspection](docs/cli.md#framework-configuration-inspection)
|
||||||
- [HTTP API reference](docs/api.md)
|
- [HTTP API reference](docs/api.md)
|
||||||
- [Operations guide](docs/operations.md)
|
- [Operations guide](docs/operations.md)
|
||||||
- [Consumer integration overview](docs/consumers/api.md)
|
- [Consumer integration overview](docs/consumers/api.md)
|
||||||
- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
|
- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
|
||||||
|
- [Native CLI migration](docs/consumers/upgrading-cli.md)
|
||||||
|
- [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md)
|
||||||
- [Subprocess integration](docs/integrations/subprocess.md)
|
- [Subprocess integration](docs/integrations/subprocess.md)
|
||||||
- [Architecture policy](docs/policy/architecture.md)
|
- [Architecture policy](docs/policy/architecture.md)
|
||||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
- [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
- [Minimal configuration](examples/config.yml) and
|
- [Minimal configuration](examples/config.yml) and
|
||||||
[complete configuration](examples/config.full.yml), plus a
|
[complete configuration](examples/config.full.yml), plus a
|
||||||
[composed import/overlay example](examples/config.composed.yml)
|
[composed import/overlay example](examples/config.composed.yml), a
|
||||||
|
[collection composition example](examples/config.collections.yml), a
|
||||||
|
[collection checkout discovery example](examples/config.discovery.yml), and a
|
||||||
|
[backend inheritance example](examples/config.inheritance.yml)
|
||||||
- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/),
|
- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/),
|
||||||
[schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
|
[schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
|
||||||
- [Render script](examples/render-markdown-summary.sh)
|
- [Render script](examples/render-markdown-summary.sh)
|
||||||
|
|||||||
@@ -1,11 +1,29 @@
|
|||||||
package main
|
package main
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
"context"
|
||||||
|
"io"
|
||||||
"os"
|
"os"
|
||||||
|
"os/signal"
|
||||||
|
"syscall"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/scriptorium/internal/adapter/cli"
|
"gitea.maximumdirect.net/eric/scriptorium/internal/adapter/cli"
|
||||||
|
"go.maximumdirect.net/commandkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
var version = "dev"
|
||||||
|
var revision = ""
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
os.Exit(cli.Run(os.Args[1:], os.Stdout, os.Stderr))
|
os.Exit(runWithSignals(os.Args[1:], os.Stdout, os.Stderr))
|
||||||
|
}
|
||||||
|
|
||||||
|
func runWithSignals(args []string, stdout, stderr io.Writer) int {
|
||||||
|
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||||
|
defer stop()
|
||||||
|
return run(ctx, args, stdout, stderr)
|
||||||
|
}
|
||||||
|
|
||||||
|
func run(ctx context.Context, args []string, stdout, stderr io.Writer) int {
|
||||||
|
return cli.Execute(ctx, commandkit.Identity{Name: "scriptorium", Version: version, Revision: revision}, args, stdout, stderr).Status
|
||||||
}
|
}
|
||||||
|
|||||||
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 |
|
| Field | Required | Meaning |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `prompt_id` | yes | Non-blank prompt ID. |
|
| `prompt_id` | yes | Non-blank prompt ID. |
|
||||||
| `prompt_version` | no | Prompt version filter. |
|
|
||||||
| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
|
| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
|
||||||
| `session_id` | no | Optional direct, non-secret session identifier. |
|
| `session_id` | no | Optional direct, non-secret session identifier. |
|
||||||
| `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
|
| `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
|
||||||
@@ -52,7 +51,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
|
|||||||
| `include_raw_output` | no | Include `raw_model_output` when true. |
|
| `include_raw_output` | no | Include `raw_model_output` when true. |
|
||||||
| `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. |
|
| `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. |
|
||||||
| `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. |
|
| `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. |
|
||||||
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second limit for engine execution. Omitted, `null`, or `0` adds no deadline; positive values shorten the caller context deadline. |
|
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second engine operation budget. Omitted, `null`, or `0` adds no deadline. |
|
||||||
|
|
||||||
An input reference has a required `type` of `file` or `inline`. A `file`
|
An input reference has a required `type` of `file` or `inline`. A `file`
|
||||||
reference requires `uri`; an `inline` reference requires `body`.
|
reference requires `uri`; an `inline` reference requires `body`.
|
||||||
@@ -68,16 +67,17 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`,
|
|||||||
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
|
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
|
||||||
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
|
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
|
||||||
framework credential semantics are defined by the
|
framework credential semantics are defined by the
|
||||||
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||||
Explicit zero values for the numeric fields are overrides; zero
|
Explicit zero values for the numeric fields are overrides; zero
|
||||||
`timeout_seconds` disables the per-attempt generation deadline only, retaining the
|
`timeout_seconds` disables the per-attempt generation deadline only, retaining the
|
||||||
request context and configured transport cap. The timeout layers are defined in
|
request context and configured transport cap. The timeout layers are defined in
|
||||||
the [Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
the [PromptKit v0.23.3 outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||||
Each built-in transient retry gets a fresh generation timeout; the caller's
|
Each built-in transient retry gets a fresh generation timeout; the caller's
|
||||||
request context remains the outer cancellation boundary.
|
request context remains the outer cancellation boundary.
|
||||||
|
|
||||||
Raw API-key values are not accepted. `api_key` and any other unknown model
|
Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
|
||||||
field cause `400 invalid_json`.
|
and any other unknown field cause `400 invalid_json`. Prompt and profile IDs
|
||||||
|
are passed unchanged, including qualified collection IDs.
|
||||||
|
|
||||||
`model.reasoning_effort` is an optional JSON string with three states: omission
|
`model.reasoning_effort` is an optional JSON string with three states: omission
|
||||||
inherits the selected profile, a non-empty string replaces its value, and an
|
inherits the selected profile, a non-empty string replaces its value, and an
|
||||||
@@ -116,14 +116,14 @@ validation contract. The response contains:
|
|||||||
optional `uri`;
|
optional `uri`;
|
||||||
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
|
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
|
||||||
optional `errors` and `schema_path`;
|
optional `errors` and `schema_path`;
|
||||||
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage,
|
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
|
||||||
timing, validation, and repair-attempt metadata; and
|
model parameters, input hashes, usage, and timing; and
|
||||||
- optional `raw_model_output` when requested.
|
- optional `raw_model_output` when requested.
|
||||||
- optional `execution` when requested and a terminal observation exists.
|
- optional `execution` when requested and a terminal observation exists.
|
||||||
|
|
||||||
`metadata.model_params` has `endpoint`, `model`, `temperature`,
|
`metadata.model_params` has `endpoint`, `model`, `temperature`,
|
||||||
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional
|
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional
|
||||||
`backend_id`, `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
|
`service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
|
||||||
`metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
|
`metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
|
||||||
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
|
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
|
||||||
cache usage is reported as zero.
|
cache usage is reported as zero.
|
||||||
@@ -132,10 +132,11 @@ When Promptkit resolves a direct or definition-rendered session ID,
|
|||||||
`metadata.session_id` contains that effective result value. It is omitted when
|
`metadata.session_id` contains that effective result value. It is omitted when
|
||||||
no effective session ID exists.
|
no effective session ID exists.
|
||||||
|
|
||||||
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report
|
`metadata.selected_backend_id` is omitted for an endpoint-only profile;
|
||||||
the corresponding Promptkit result fields independently when present. Both are
|
Scriptorium does not infer backend identity from an endpoint. The redundant
|
||||||
omitted for an endpoint-only profile; Scriptorium does not infer backend
|
`prompt_version`, `model_name`, `endpoint`, `validation_mode`,
|
||||||
identity from an endpoint.
|
`validation_status`, `repair_attempts_used`, and `model_params.backend_id`
|
||||||
|
metadata members are not returned: use `model_params` and `validation`.
|
||||||
|
|
||||||
A validation failure has `validation.status: "failed"`, `is_valid: false`,
|
A validation failure has `validation.status: "failed"`, `is_valid: false`,
|
||||||
and any available diagnostic errors, while still returning the artifact and
|
and any available diagnostic errors, while still returning the artifact and
|
||||||
@@ -150,7 +151,7 @@ call was dispatched; if there is no terminal event, `execution` is omitted.
|
|||||||
|
|
||||||
| Field | Meaning |
|
| Field | Meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `run_id`, `prompt_id`, `prompt_version`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
|
| `run_id`, `prompt_id`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
|
||||||
| `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. |
|
| `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. |
|
||||||
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
|
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
|
||||||
| `status_code` | Provider status, omitted when unavailable. |
|
| `status_code` | Provider status, omitted when unavailable. |
|
||||||
@@ -201,7 +202,7 @@ exceed it, the response is the compact `413 response_too_large` error without
|
|||||||
| `400` | `prompt_render_failed` | Prompt template rendering failed. |
|
| `400` | `prompt_render_failed` | Prompt template rendering failed. |
|
||||||
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
|
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
|
||||||
| `404` | `not_found` | Route does not exist. |
|
| `404` | `not_found` | Route does not exist. |
|
||||||
| `404` | `prompt_not_found` | Prompt ID or version does not exist. |
|
| `404` | `prompt_not_found` | Prompt ID does not exist. |
|
||||||
| `404` | `profile_not_found` | Profile ID does not exist. |
|
| `404` | `profile_not_found` | Profile ID does not exist. |
|
||||||
| `405` | `method_not_allowed` | The route does not accept the method. |
|
| `405` | `method_not_allowed` | The route does not accept the method. |
|
||||||
| `408` | `request_canceled` | The caller context was canceled during a failed run. |
|
| `408` | `request_canceled` | The caller context was canceled during a failed run. |
|
||||||
@@ -212,10 +213,11 @@ exceed it, the response is the compact `413 response_too_large` error without
|
|||||||
| `500` | `internal_error` | Unclassified server failure. |
|
| `500` | `internal_error` | Unclassified server failure. |
|
||||||
| `502` | `llm_failed` | Outbound model request failed. |
|
| `502` | `llm_failed` | Outbound model request failed. |
|
||||||
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. |
|
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. |
|
||||||
| `504` | `deadline_exceeded` | The execution context's deadline expired during a failed run. |
|
| `504` | `deadline_exceeded` | PromptKit reports an operation timeout, or the parent deadline expired and the failed run wraps that deadline. |
|
||||||
|
|
||||||
These context outcomes require the execution context to have ended. A provider
|
An operation timeout is checked before parent cancellation; a failed run
|
||||||
attempt timeout while it remains live retains `502 llm_failed`. A successful
|
wrapping cancellation returns `408` when the parent is canceled. A provider
|
||||||
|
attempt timeout while the parent remains live retains `502 llm_failed`. A successful
|
||||||
run remains successful even if cancellation races with response formatting;
|
run remains successful even if cancellation races with response formatting;
|
||||||
delivery after a client disconnect cannot be guaranteed.
|
delivery after a client disconnect cannot be guaranteed.
|
||||||
|
|
||||||
|
|||||||
418
docs/cli.md
418
docs/cli.md
@@ -1,304 +1,186 @@
|
|||||||
# CLI Reference
|
# CLI Reference
|
||||||
|
|
||||||
This is the canonical contract for invoking Scriptorium. Configuration discovery,
|
Scriptorium uses CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0.
|
||||||
precedence, application source locations, and server settings are defined in the
|
This document owns application invocation and delivery behavior. The pinned
|
||||||
[configuration reference](config.md). The [HTTP API reference](api.md) owns
|
[upstream CLI contract][native-cli] owns standard family grammar and reports.
|
||||||
service request and response behavior.
|
[Configuration](config.md) owns discovery, settings, and source composition;
|
||||||
|
the [HTTP API](api.md) owns the service contract.
|
||||||
## Shortest Useful Command
|
Existing callers should read the [CLI migration guide](consumers/upgrading-cli.md).
|
||||||
|
|
||||||
```bash
|
|
||||||
go run ./cmd/scriptorium render \
|
|
||||||
--config ./examples/config.yml \
|
|
||||||
--prompt generic.markdown_summary \
|
|
||||||
--input transcript=./examples/fixtures/transcript.md \
|
|
||||||
--input glossary=./examples/fixtures/glossary.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
`render` prepares a request without calling an LLM.
|
|
||||||
|
|
||||||
## Commands
|
## Commands
|
||||||
|
|
||||||
- `scriptorium run`: prepare a prompt, call the configured LLM, and write the
|
|
||||||
generated artifact.
|
|
||||||
- `scriptorium render`: prepare a prompt and write prepared-run output.
|
|
||||||
- `scriptorium serve`: start the HTTP server.
|
|
||||||
- `scriptorium inspect prompt`: inspect one prompt definition without model execution.
|
|
||||||
- `scriptorium inspect profile`: inspect one effective profile without model execution.
|
|
||||||
- `scriptorium config validate`: validate application configuration without building an engine.
|
|
||||||
- `scriptorium config show`: show the resolved application configuration.
|
|
||||||
- `scriptorium config sources`: show the ordered configuration sources.
|
|
||||||
- `scriptorium config explain`: explain one effective or historical configuration path.
|
|
||||||
|
|
||||||
All commands accept `--config <path>` and `--config-overlay <name>` and reject
|
|
||||||
positional arguments. `--config-overlay` selects one application configuration
|
|
||||||
overlay; it is separate from `--profile`, which selects a Promptkit execution
|
|
||||||
profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
|
||||||
for name, root, and no-base behavior. `run`,
|
|
||||||
`render`, `serve`, and `inspect prompt` require an effective `prompt_dir`;
|
|
||||||
`inspect profile` does not. Supply the directory through the configuration
|
|
||||||
contract or a supported `--prompt-dir` flag. Explicit application flags,
|
|
||||||
including empty values, override file settings. Configuration load diagnostics
|
|
||||||
go to stderr and exit with status 1; successful load warnings are printed once
|
|
||||||
before command work.
|
|
||||||
|
|
||||||
## `scriptorium run`
|
|
||||||
|
|
||||||
```text
|
|
||||||
scriptorium run [flags]
|
|
||||||
```
|
|
||||||
|
|
||||||
Required flags:
|
|
||||||
|
|
||||||
| Flag | Meaning |
|
|
||||||
| --- | --- |
|
|
||||||
| `--prompt <id>` | Prompt ID to execute. |
|
|
||||||
|
|
||||||
Optional flags:
|
|
||||||
|
|
||||||
| Flag | Meaning |
|
|
||||||
| --- | --- |
|
|
||||||
| `--config <path>` | Application configuration file. |
|
|
||||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
|
||||||
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
|
||||||
| `--profile-dir <dir>` | Custom profile-directory override. |
|
|
||||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
|
||||||
| `--prompt-version <version>` | Optional prompt-definition version selector. |
|
|
||||||
| `--profile <id>` | Execution-profile override. |
|
|
||||||
| `--session-id <id>` | Optional direct session identifier. |
|
|
||||||
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
|
|
||||||
| `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
|
|
||||||
| `--out <path>` | Write generated content to this file instead of stdout. |
|
|
||||||
| `--execution-report <path>` | Write an opt-in terminal execution report as newline-terminated JSON to a separate file. |
|
|
||||||
| `--llm-base-url <url>` | Runtime endpoint override. |
|
|
||||||
| `--model <name>` | Runtime model override. |
|
|
||||||
| `--api-key-env <name>` | Runtime API-key environment-variable name override. |
|
|
||||||
| `--temperature <float>` | Runtime temperature override. |
|
|
||||||
| `--max-tokens <int>` | Runtime maximum-token override. |
|
|
||||||
| `--top-p <float>` | Runtime top-p override. |
|
|
||||||
| `--reasoning-effort <value>` | Runtime reasoning-effort override. |
|
|
||||||
| `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
|
|
||||||
| `--run-timeout <duration>` | Optional whole-run engine deadline using Go duration syntax; zero or omission adds no deadline, negative values are invalid. |
|
|
||||||
| `--transient-retries <integer>` | Nonnegative additional transient attempt count for this request; `0` disables additional attempts. |
|
|
||||||
|
|
||||||
Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
|
|
||||||
`--profile`.
|
|
||||||
|
|
||||||
Omitted numeric runtime flags preserve the selected effective value; explicit
|
|
||||||
zero values override it. `--timeout 0s` disables the per-attempt generation deadline
|
|
||||||
only; the caller context and configured transport cap remain active. CLI
|
|
||||||
durations are converted to whole seconds by truncation toward zero, so any
|
|
||||||
duration whose absolute value is below one second becomes an explicit
|
|
||||||
zero-second override. The timeout layers are defined in the
|
|
||||||
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
|
||||||
With the built-in client, each transient retry gets a fresh generation timeout;
|
|
||||||
this flag does not limit the complete run.
|
|
||||||
`--run-timeout` keeps subsecond precision and starts immediately before engine
|
|
||||||
execution. It bounds preparation, capacity waits, retry waits, generation, and
|
|
||||||
repairs where they honor context. Parsing, engine construction, and output
|
|
||||||
writes are outside that interval. A failed run whose execution context reaches
|
|
||||||
this deadline exits 1 with a safe deadline diagnostic; a completed invalid
|
|
||||||
output still exits 2. It does not promise immediate interruption of synchronous
|
|
||||||
work.
|
|
||||||
Omitting `--transient-retries` inherits the application setting or Promptkit's
|
|
||||||
current default of two additional attempts. The flag overrides only this
|
|
||||||
request; it does not alter the configured engine. Structural repair generations
|
|
||||||
have separate transient retry budgets.
|
|
||||||
|
|
||||||
There is no raw API-key flag. Use `--api-key-env`.
|
|
||||||
|
|
||||||
`--prompt-version` is passed directly to Promptkit. When it is omitted, the
|
|
||||||
selected prompt ID must have exactly one available version. `--input` is
|
|
||||||
optional at the CLI boundary: Promptkit decides whether the selected definition
|
|
||||||
requires declared inputs or template-referenced values.
|
|
||||||
|
|
||||||
`--session-id` supplies a direct, non-secret session identifier. A nonblank
|
|
||||||
value replaces a definition-rendered session ID; an omitted or blank value lets
|
|
||||||
the definition supply one. Promptkit trims direct values and limits them to 256
|
|
||||||
Unicode code points. Use stable, non-sensitive identifiers because effective
|
|
||||||
session IDs may appear in prepared output, run metadata, and provider-facing
|
|
||||||
requests.
|
|
||||||
|
|
||||||
`--reasoning-effort` is presence-aware: omitting it inherits the selected
|
|
||||||
profile value, a nonblank value replaces that value, and
|
|
||||||
`--reasoning-effort=` explicitly clears inherited reasoning. Promptkit treats
|
|
||||||
nonblank values as provider-specific opaque strings.
|
|
||||||
|
|
||||||
### Execution report file
|
|
||||||
|
|
||||||
`--execution-report` requires a nonempty path. It is available only for `run`;
|
|
||||||
`-` is an ordinary filename. Parent directories are not created. An existing
|
|
||||||
file is replaced through ordinary file writing, without rollback or an atomic
|
|
||||||
replacement guarantee. Generated content still goes to stdout or `--out`.
|
|
||||||
Equal output/report paths, including existing paths that refer to the same
|
|
||||||
file, are rejected before execution.
|
|
||||||
|
|
||||||
The file is written after engine execution when Promptkit supplies a terminal
|
|
||||||
event, including for a failed run or invalid generated output. A failure before
|
|
||||||
invocation leaves the report path untouched. If no terminal event is supplied,
|
|
||||||
Scriptorium leaves the path untouched and emits a diagnostic; an existing file
|
|
||||||
may therefore contain an older report. Artifact output is attempted first on a
|
|
||||||
successful run, and report writing is attempted even if artifact writing fails.
|
|
||||||
Any output or report write failure exits 1; already-written output is not
|
|
||||||
undone. Without a write failure, the actual run keeps its usual exit status.
|
|
||||||
|
|
||||||
The [HTTP API reference](api.md#execution-report) defines the shared report
|
|
||||||
fields and usage-presence semantics. The file contains that JSON object followed
|
|
||||||
by a newline.
|
|
||||||
|
|
||||||
The report excludes content, credentials, URLs, headers, and raw errors, but
|
|
||||||
its identifiers can still be sensitive. The caller owns file retention and
|
|
||||||
access.
|
|
||||||
|
|
||||||
## `scriptorium render`
|
|
||||||
|
|
||||||
```text
|
|
||||||
scriptorium render [flags]
|
|
||||||
```
|
|
||||||
|
|
||||||
`--prompt <id>` is required. The following optional flags are supported:
|
|
||||||
`--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, `--schema-dir`, `--prompt-version`, `--profile`,
|
|
||||||
`--input`, `--var`, `--out`, `--llm-base-url`,
|
|
||||||
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
|
|
||||||
`--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, and `--format text|json`. Their meanings match the corresponding
|
|
||||||
`run` flags; `--format` selects prepared-run output and otherwise uses
|
|
||||||
`defaults.render_format`.
|
|
||||||
|
|
||||||
The same deprecated aliases and numeric/timeout behavior as `run` apply.
|
|
||||||
The same session and reasoning inheritance, replacement, and clearing behavior
|
|
||||||
also applies.
|
|
||||||
`render` validates the retry override but does not generate model output or
|
|
||||||
include a retry field in prepared output.
|
|
||||||
`render` resolves profiles and schemas as part of preparation but
|
|
||||||
does not call an LLM.
|
|
||||||
|
|
||||||
## `scriptorium serve`
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
|
scriptorium run PROMPT_ID [flags]
|
||||||
scriptorium serve [flags]
|
scriptorium serve [flags]
|
||||||
|
scriptorium config scopes
|
||||||
|
scriptorium config validate|show|sources|explain|diff [flags]
|
||||||
|
scriptorium promptkit list prompts|profiles|backends|namespaces|collections [flags]
|
||||||
|
scriptorium promptkit show prompt|profile|backend ID [flags]
|
||||||
|
scriptorium promptkit requirements show|validate PROMPT_ID [flags]
|
||||||
|
scriptorium promptkit show prepared PROMPT_ID [flags]
|
||||||
|
scriptorium promptkit test KIND [flags]
|
||||||
|
scriptorium help [COMMAND ...]
|
||||||
|
scriptorium version
|
||||||
|
scriptorium completion bash|zsh|fish
|
||||||
```
|
```
|
||||||
|
|
||||||
Optional flags:
|
Native help is also available with `--help`. Help, version, scope discovery,
|
||||||
|
and static completion do not load configuration or contact a provider.
|
||||||
|
Version/revision metadata is supplied by the build; ordinary builds identify
|
||||||
|
themselves as `dev` with no revision. Release build mechanics belong to the
|
||||||
|
[release procedure](release.md).
|
||||||
|
|
||||||
|
Commands that consume configuration accept `--config PATH` and `--overlay NAME`.
|
||||||
|
An explicitly empty config value remains explicit; overlay names follow
|
||||||
|
[ConfigKit selection](config.md#explicit-imports-and-selected-overlays).
|
||||||
|
There are no source/schema convenience flags or legacy command aliases.
|
||||||
|
Native shared `--format`, `--quiet`, `--verbose`, `--debug`, and progress
|
||||||
|
controls retain their upstream meanings. Diagnostics use stderr, not stdout.
|
||||||
|
Verbose exposes emitted Info and Warning messages without changing result bytes.
|
||||||
|
|
||||||
|
## Generation
|
||||||
|
|
||||||
|
`run` requires exactly one positional prompt ID. It has no duplicate prompt
|
||||||
|
flag or direct backend-selection flag; choose a profile for backend routing.
|
||||||
|
It uses these native bindings, with the preferred aliases below. Canonical
|
||||||
|
spellings prepend `llm-` (for example, `--llm-profile`).
|
||||||
|
|
||||||
|
| Preferred flags | Meaning |
|
||||||
|
| --- | --- |
|
||||||
|
| `--profile ID`, `--session-id ID` | Profile selection and optional non-secret session context. |
|
||||||
|
| `--var KEY=VALUE` | Repeatable caller-variable mappings. |
|
||||||
|
| `--input-text NAME=TEXT`, `--input NAME=TEXT` | Repeatable literal input mappings; `--llm-input` is also a literal-text alias. |
|
||||||
|
| `--input-file NAME=PATH` | Repeatable file references. |
|
||||||
|
| `--endpoint URL`, `--model NAME` | Native endpoint/model overrides. |
|
||||||
|
| `--temperature N`, `--max-tokens N`, `--top-p N` | Presence-aware numeric overrides, including zero. |
|
||||||
|
| `--timeout-seconds N` | Integer per-attempt generation timeout; zero disables that deadline, not caller cancellation or the transport cap. |
|
||||||
|
| `--reasoning-effort VALUE`, `--service-tier VALUE` | Native provider controls; an explicit empty reasoning value is preserved. |
|
||||||
|
| `--api-key-env NAME` | Credential environment-variable name, never raw key bytes. |
|
||||||
|
| `--extra-params JSON` | Native JSON-object provider parameters. |
|
||||||
|
| `--transient-retries N` | Request retry override; omission leaves the engine default. |
|
||||||
|
| `--prompt-namespace NAME`, `--profile-namespace NAME`, `--backend-namespace NAME` | Independent native namespace views. Qualified resource IDs remain exact; stored references are not rewritten. |
|
||||||
|
|
||||||
|
Mappings split at the first `=`; commas and subsequent equals signs are literal.
|
||||||
|
Repeat flags for multiple mappings. The last text/file occurrence for the same
|
||||||
|
input wins in command-line order. PromptKit validates selected definitions,
|
||||||
|
inputs, namespaces, provider settings, and credential requirements; Scriptorium
|
||||||
|
does not add an execution-readiness preflight or configurable default namespace.
|
||||||
|
Native string/pointer override semantics remain upstream-owned.
|
||||||
|
|
||||||
|
Application-owned generation controls:
|
||||||
|
|
||||||
| Flag | Meaning |
|
| Flag | Meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `--config <path>` | Application configuration file. |
|
| `--run-timeout DURATION` | Go duration passed unchanged to PromptKit's operation budget. Positive values cover engine preparation/execution, including cooperative waits and repairs. Zero, omission, and negative values add no budget. Parsing, configuration/engine setup, and delivery are outside it. |
|
||||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
| `--report PATH` | Additionally write the returned native result to a separate file. |
|
||||||
| `--addr <listen-address>` | HTTP listen-address override. |
|
| `--report-format text\|yaml\|json` | Explicit separate-report format; omission leaves native automatic rendering selected. |
|
||||||
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
|
||||||
| `--profile-dir <dir>` | Custom profile-directory override. |
|
|
||||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
|
||||||
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
|
|
||||||
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
|
||||||
| `--max-artifact-bytes <n>` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
|
||||||
| `--max-response-bytes <n>` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
|
||||||
|
|
||||||
`serve` accepts no runtime model override flags. HTTP request fields, response
|
The operation budget is independent of the integer per-attempt timeout.
|
||||||
schemas, and error codes are defined in the [HTTP API reference](api.md).
|
Earlier parent cancellation/deadlines still apply. Cancellation is cooperative;
|
||||||
|
synchronous work that ignores context cannot be forcibly interrupted.
|
||||||
|
|
||||||
## `scriptorium inspect prompt`
|
### Results And Separate Reports
|
||||||
|
|
||||||
```text
|
The main report goes through the invocation reporter to stdout. Automatic/text
|
||||||
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
output is exactly `Artifact.Body`, with no added newline, header, escaping, or
|
||||||
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH]
|
summary. JSON/YAML output is the full native PromptKit `RunResult`, without a
|
||||||
```
|
Scriptorium envelope. In native structured serialization, artifact bytes use
|
||||||
|
the upstream representation (JSON base64), not an application text projection.
|
||||||
|
|
||||||
`--prompt` is required. Inspection uses normal configuration discovery and a
|
Save main output with shell redirection or the subprocess stdout destination.
|
||||||
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`,
|
There is no `--output` or `--out` flag. Omit `--quiet` when capturing the main
|
||||||
and writes to stdout unless `--out` is supplied. It loads and normalizes the
|
result: native quiet suppresses it even when stdout is redirected.
|
||||||
selected definition but does not resolve a profile, load a schema, render a
|
|
||||||
template, reserve backend capacity, or call a model.
|
|
||||||
|
|
||||||
## `scriptorium inspect profile`
|
`--report` renders the same result through CommandKit without the artifact-only
|
||||||
|
text template. Its format is independent of stdout's `--format` and the filename
|
||||||
|
extension. Omission passes an unset format to the upstream renderer; it currently
|
||||||
|
renders structured values as YAML in automatic/text mode. Choose an explicit
|
||||||
|
format when required rather than relying on that upstream default.
|
||||||
|
|
||||||
```text
|
The requested file is written even in quiet mode. Omission creates no separate
|
||||||
scriptorium inspect profile --profile ID
|
report. An explicitly empty path is a usage error before generation; `-` is an
|
||||||
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH]
|
ordinary filename. New files use mode 0644 subject to umask, existing files use
|
||||||
```
|
normal OS replacement behavior, and parent directories are not created.
|
||||||
|
Render, write, and close failures are reported.
|
||||||
|
|
||||||
`--profile` is required; built-in profiles need no prompt directory. Inspection
|
Only a returned result is eligible for delivery. A resultless failure leaves an
|
||||||
resolves profile inheritance and backend defaults, but never reads a credential
|
existing report untouched; it does not synthesize an invocation-error result.
|
||||||
value, loads a prompt, reserves capacity, or calls a model. Unset provider
|
Main delivery is attempted first, then the requested report even if main
|
||||||
controls are shown as zero values when Promptkit leaves them unspecified.
|
delivery fails. Writes are nontransactional; bytes already written remain.
|
||||||
|
Callers own redirected paths, retention, and keeping main and report destinations
|
||||||
|
separate. A shell may truncate its redirected file before the process starts.
|
||||||
|
|
||||||
## Application configuration inspection
|
## Application Configuration Inspection
|
||||||
|
|
||||||
```text
|
The native `config` family defaults to `app`; select `--scope promptkit` for
|
||||||
scriptorium config validate [flags]
|
captured framework configuration or use native scope discovery/all-scope modes.
|
||||||
scriptorium config show [flags]
|
`app` uses the actual completed ConfigKit result and does not construct an engine.
|
||||||
scriptorium config sources [flags]
|
|
||||||
scriptorium config explain --path JSON_POINTER [flags]
|
|
||||||
```
|
|
||||||
|
|
||||||
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
|
Native `--set POINTER=JSON` is enabled only for `app`. Records go directly to
|
||||||
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`,
|
ConfigKit: duplicate and ancestor/descendant-overlapping paths are rejected,
|
||||||
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
not resolved by flag order. No application-specific configuration flags or
|
||||||
configuration selectors and overrides; request, credential, backend-editing,
|
custom `--against-*` counterparts are installed.
|
||||||
output-format, and output-file flags are not accepted. Positional arguments
|
|
||||||
are rejected.
|
|
||||||
|
|
||||||
`validate` writes no success output; status 0 means the application configuration
|
Native diff uses independent `--against-config`, `--against-overlay`, and
|
||||||
loaded and passed its own validation. It does not establish that a prompt
|
supported `--against-set` selections. Omitted right-side values do not inherit
|
||||||
directory exists, credentials are present, or Promptkit can construct an
|
the left side. See the [upstream contract][native-cli] for focused paths,
|
||||||
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources`
|
metadata discovery, source IDs, findings, explanations, and detailed comparisons.
|
||||||
writes one newline-terminated JSON array of source records in load order. Each
|
|
||||||
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
|
|
||||||
overrides appear as synthetic sources. Defaults-only input without overrides
|
|
||||||
produces `[]` for `sources`.
|
|
||||||
|
|
||||||
`explain` requires an explicitly supplied `--path` in JSON Pointer syntax.
|
## Framework Configuration Inspection
|
||||||
The empty string selects the root; `/server/addr` selects a field; `~1` and
|
|
||||||
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
|
||||||
according to the containing mapping or sequence. Dotted paths, file paths,
|
|
||||||
and URL fragments are not accepted. ConfigKit writes a human-readable account
|
|
||||||
of the effective value and its chronological default, base, overlay, CLI,
|
|
||||||
and normalization history, including removed historical values. This is not a
|
|
||||||
JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths
|
|
||||||
exit 1 without successful explanation output.
|
|
||||||
|
|
||||||
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
The `promptkit` config scope loads application settings selected by `--config`
|
||||||
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
and `--overlay`, constructs an engine, and exposes its captured native view.
|
||||||
leave partial data on failure. The inspection output can contain paths,
|
It does not accept temporary overrides; native capability checks also apply
|
||||||
identifiers, `api_key_env` reference names, and ordinary `extra_params` values,
|
when an all-scope operation requests them.
|
||||||
including displaced historical values in explanations;
|
|
||||||
protect it accordingly. Raw API-key values are not read or emitted by these
|
|
||||||
commands.
|
|
||||||
|
|
||||||
## Input And Variable Syntax
|
Framework effective/explanation views retain native classified-field redaction,
|
||||||
|
including history. Environment-reference names and ordinary values remain
|
||||||
|
visible. This is not arbitrary secret detection and does not redact all prompt,
|
||||||
|
prepared, application, or generated content. Protect reports accordingly.
|
||||||
|
|
||||||
`--input name=path` maps an input name to a local file; `--var name=value`
|
## Discovery, Preview, And Explicit Smoke Testing
|
||||||
maps a template variable to a string. Both flags can be repeated or contain
|
|
||||||
comma-separated mappings. Values may contain `=` after the first separator.
|
|
||||||
Empty names and values are rejected.
|
|
||||||
|
|
||||||
CLI inputs are file references. HTTP inline inputs are defined by the
|
Inventories retain native defaults and `--namespace`/`--all-namespaces` filters.
|
||||||
[HTTP API reference](api.md).
|
Named inspections expose native prompt messages and profile/backend values;
|
||||||
|
prepared preview exposes rendered content, not a summary projection.
|
||||||
|
|
||||||
## Output And Exit Behavior
|
Requirements discovery works before input artifacts exist and without schema
|
||||||
|
loading, credential resolution, message rendering, or provider access. It still
|
||||||
|
loads configuration and captured message resources. Reports preserve exact names,
|
||||||
|
metadata, variable presence (including empty values), completeness, and issue
|
||||||
|
codes. Partial discovery may succeed with status zero; completeness is not
|
||||||
|
binding satisfaction or execution readiness. Concrete validation and preview
|
||||||
|
keep their native preparation-time prerequisites and make no generation call.
|
||||||
|
|
||||||
- `run` writes generated content to stdout, or to `--out` when supplied, and
|
Smoke-test kinds are `reachability`, `authentication`, `text_inference`,
|
||||||
writes a concise summary to stderr. The summary includes `backend=<id>` when
|
`structured_output`, or `all`, with native aliases as documented upstream.
|
||||||
Promptkit selected a backend; endpoint-only profiles omit it.
|
These explicit commands may contact providers and incur cost. Their presence
|
||||||
- `render` writes prepared-run output to stdout, or to `--out` when supplied,
|
does not add a startup/provider probe. Read the native findings: unsuccessful or
|
||||||
without a success summary. Text output includes `selected_backend_id` after
|
unsupported checks are not automatically invocation failures.
|
||||||
`selected_profile_id` when Promptkit selected one; endpoint-only profiles
|
|
||||||
omit it.
|
|
||||||
- `serve` writes startup and server errors to stderr.
|
|
||||||
|
|
||||||
Exit statuses:
|
## Server And Statuses
|
||||||
|
|
||||||
|
`serve` accepts configuration selection and presence-aware HTTP controls:
|
||||||
|
`--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`,
|
||||||
|
and `--max-response-bytes`. It has no generation request controls. Values and
|
||||||
|
defaults belong to [configuration](config.md).
|
||||||
|
|
||||||
|
Interrupt/SIGTERM cancels the invocation context. The server closes its listener
|
||||||
|
and active connections; canceled shutdown returns operational status, with no
|
||||||
|
graceful-drain deadline or guarantee that context-ignoring work has finished.
|
||||||
|
|
||||||
| Status | Meaning |
|
| Status | Meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `0` | Success. |
|
| 0 | Native success, subject to successful presentation/delivery. |
|
||||||
| `1` | Parse, configuration, loading, rendering, generation, output-write, or other runtime error. |
|
| 1 | Operational failure, including lookup/preparation/generation/capacity, cancellation/timeouts, unclassified load errors, and delivery failure for an otherwise successful run. |
|
||||||
| `2` | `run` generated and wrote output, but validation failed. |
|
| 2 | Native usage/declaration-input errors, or configuration errors classified as invalid input by native diagnostic evidence. |
|
||||||
|
| 3 | Native `config diff --check` found differences. |
|
||||||
|
| 4 | Completed generation returned `ValidationFailed`; artifact and native result remain deliverable. |
|
||||||
|
|
||||||
A backend admission rejection is a runtime error and prints `run error: model
|
Native finalization handles presentation errors: success/usage become operational;
|
||||||
backend capacity is exhausted`. The HTTP capacity response is defined in the
|
an already nonzero domain outcome retains its classification/status. A report-file
|
||||||
[HTTP API reference](api.md).
|
failure preserves completed-validation status 4 while adding its explanation and
|
||||||
|
cause. An operational failure to perform validation is status 1, not status 4.
|
||||||
|
JSON selection does not turn failures into a separate JSON error envelope.
|
||||||
|
|
||||||
## Workflows And Examples
|
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||||
|
|
||||||
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
|
||||||
copyable render workflow. The [HTTP request example](../examples/http-run.json)
|
|
||||||
is for a running `serve` process.
|
|
||||||
|
|||||||
293
docs/config.md
293
docs/config.md
@@ -1,207 +1,158 @@
|
|||||||
# Configuration Reference
|
# Configuration Reference
|
||||||
|
|
||||||
This is the canonical reference for Scriptorium application settings. Prompt,
|
This document owns Scriptorium's application settings, discovery, and source
|
||||||
profile, schema, execution-setting, built-in profile, and framework credential
|
selection. [CLI syntax](cli.md) and the [HTTP API](api.md) have separate owners.
|
||||||
semantics are defined by the
|
Framework definitions and execution semantics belong to the pinned
|
||||||
[Promptkit v0.11.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
[PromptKit v0.23.3 formats][formats]; ConfigKit v1.2.1 owns
|
||||||
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
|
[native composition and inspection][configkit].
|
||||||
outcomes, see the [HTTP API reference](api.md).
|
|
||||||
|
|
||||||
## Discovery And Precedence
|
## Discovery And Precedence
|
||||||
|
|
||||||
Application settings are resolved in this order:
|
An explicit `--config` selects that file, including an explicitly empty value
|
||||||
|
(which fails rather than falling back). With no selection, ConfigKit searches
|
||||||
|
these native presets in order, selecting one main file:
|
||||||
|
|
||||||
1. built-in Scriptorium defaults;
|
| Preset | Directories in order | Filename groups |
|
||||||
2. a configuration file; then
|
| --- | --- | --- |
|
||||||
3. CLI overrides.
|
| WorkingDirectory | Current working directory | Named only |
|
||||||
|
| UserConfigDirectory | Go user-config directory / `scriptorium`, then the user-config directory | Named then Generic in the application directory; Named only in the base |
|
||||||
|
| HomeDirectory | Go home directory / `.scriptorium`, then the home directory | Named then Generic in the application directory; Named only in the base |
|
||||||
|
| UnixSystemDirectories | `/usr/local/etc/scriptorium`, `/etc/scriptorium`, then `/etc` | Named then Generic in application directories; Named only in `/etc` |
|
||||||
|
|
||||||
When `--config` is omitted, Scriptorium searches
|
Named means `scriptorium.yml`, then `scriptorium.yaml`. Generic means
|
||||||
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
|
`config.yml`, `config.yaml`, `main.yml`, then `main.yaml`.
|
||||||
If neither exists, it uses built-in defaults. An explicit `--config` path must
|
ConfigKit uses native Go directory resolution (including its user-config/home
|
||||||
exist and decode successfully.
|
environment behavior) and checks every filename in one directory before the next.
|
||||||
|
Candidates are not configuration layers. Optional exhaustion uses application
|
||||||
|
defaults; a selected-file acquisition/decoding error is terminal.
|
||||||
|
|
||||||
The maintained [minimal configuration](../examples/config.yml),
|
ConfigKit assembles the main, enabled imports, and selected overlay, applies its
|
||||||
[complete configuration](../examples/config.full.yml), and
|
inheritance/composition rules, creates typed defaults and strictly decodes, applies
|
||||||
[composed configuration](../examples/config.composed.yml) are copyable examples.
|
explicit override records, then runs application normalization and validation.
|
||||||
|
An override can correct a decoded value before validation, but cannot repair
|
||||||
|
source/composition/decoding errors. The completed result is authoritative:
|
||||||
|
runtime settings conversion does not merge, default, or normalize again.
|
||||||
|
|
||||||
## Application Configuration File
|
## Application Settings
|
||||||
|
|
||||||
Configuration is decoded by ConfigKit v0.4.2 as strict YAML. Unknown fields,
|
Complete copyable configurations are maintained under
|
||||||
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
|
[examples](../examples/config.yml), including [full settings](../examples/config.full.yml),
|
||||||
An explicit empty string is a value: it clears a file-provided optional path
|
[application imports](../examples/config.composed.yml),
|
||||||
or, for required `prompt_dir`, fails the command's prerequisite. A scalar
|
[framework fragment composition](../examples/config.collections.yml),
|
||||||
`null` is not an empty string and is rejected for scalar fields; nullable
|
[collection checkout discovery](../examples/config.discovery.yml), and
|
||||||
fields such as `transient_retries` retain their documented meaning. Raw
|
[framework inheritance](../examples/config.inheritance.yml).
|
||||||
API-key fields are not accepted.
|
|
||||||
|
|
||||||
ConfigKit applies defaults, the selected file, then only explicitly supplied
|
```yaml
|
||||||
application CLI flags before validating the result. Paths in the application
|
promptkit:
|
||||||
document remain relative to the process working directory, not to the file's
|
configuration: ./examples/promptkit.yml
|
||||||
directory. Load diagnostics are printed safely on stderr; invalid application
|
schema_dir: ./examples/schemas
|
||||||
configuration exits with status 1.
|
|
||||||
|
|
||||||
### Explicit imports and selected overlays
|
|
||||||
|
|
||||||
A file-backed configuration may declare `configkit.imports` with relative
|
|
||||||
`path` or `glob` entries. Each entry is explicit; Scriptorium does not scan
|
|
||||||
for fragments on its own. ConfigKit composes the selected file and imports by
|
|
||||||
conflict, so two fragments cannot define the same field merely to establish
|
|
||||||
precedence. A required missing import fails; an entry may use
|
|
||||||
`optional: true` to suppress target nonexistence. Imports are resolved from
|
|
||||||
the declaring file's canonical directory and remain within the selected
|
|
||||||
file's canonical directory by default. Scriptorium does not widen that root.
|
|
||||||
|
|
||||||
`--config-overlay NAME` selects one file at `overlays/NAME.yml` below that
|
|
||||||
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
|
|
||||||
and exact lowercase `default` select no overlay. There is no fallback,
|
|
||||||
case folding, inherited stack, or automatic selection; a missing selected
|
|
||||||
overlay fails. ConfigKit merges mapping fields and replaces other values,
|
|
||||||
including sequences and explicit nulls, before applying explicit CLI flags.
|
|
||||||
An active overlay needs a selected base file. No-source defaults-only loads
|
|
||||||
cannot use imports or an active overlay.
|
|
||||||
|
|
||||||
The [composed example](../examples/config.composed.yml) imports two fragments
|
|
||||||
and has a selectable [local overlay](../examples/overlays/local.yml). From the
|
|
||||||
repository root:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
go run ./cmd/scriptorium render \
|
|
||||||
--config ./examples/config.composed.yml --config-overlay local \
|
|
||||||
--prompt generic.markdown_summary \
|
|
||||||
--input transcript=./examples/fixtures/transcript.md \
|
|
||||||
--input glossary=./examples/fixtures/glossary.yml
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Import and overlay file locations are constrained by ConfigKit;
|
The `promptkit` section contains acquisition settings, not embedded framework
|
||||||
*application path values* such as `prompt_dir` remain relative
|
definitions. Profiles, prompts, backends, and collections belong in the separate
|
||||||
to the process working directory even when authored in a fragment or overlay.
|
framework document. The retired `promptkit_sources`, top-level `schema_dir`,
|
||||||
These source constraints are separate from HTTP artifact containment.
|
and `defaults.render_format` fields have no compatibility conversion and are
|
||||||
|
rejected by strict decoding, as are unknown/raw credential fields.
|
||||||
|
|
||||||
| Field | Default | Meaning |
|
| Field | Default | Meaning |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. |
|
| `promptkit.configuration` | empty | One external framework file; omission/empty selects no external main. |
|
||||||
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
|
| `promptkit.schema_dir` | `.` | Schema base directory passed to PromptKit. |
|
||||||
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
|
| `transient_retries` | upstream default | Optional nonnegative engine retry count. Omitted/null delegates upstream; zero disables additional transient attempts. |
|
||||||
| `server.addr` | `:8080` | Address used by `serve`. |
|
| `server.addr` | `:8080` | HTTP listen address. |
|
||||||
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
|
| `server.artifact_root` | empty | Root enabling HTTP file-artifact references. |
|
||||||
| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
| `server.max_request_bytes` | `16777216` | Encoded HTTP request limit; zero is unlimited. |
|
||||||
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
| `server.max_artifact_bytes` | `16777216` | HTTP file-artifact limit; zero is unlimited. |
|
||||||
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
| `server.max_response_bytes` | `16777216` | Encoded HTTP response limit; zero is unlimited. |
|
||||||
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
|
|
||||||
| `backends` | unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. |
|
|
||||||
| `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. |
|
|
||||||
|
|
||||||
The size fields must be zero or greater. The [HTTP API](api.md) defines how
|
Size fields are nonnegative signed 64-bit values. [HTTP behavior](api.md) defines
|
||||||
each limit is enforced and reported. `server.artifact_root` configures an HTTP
|
their enforcement; [operations](operations.md) covers safe deployment choices.
|
||||||
deployment boundary; see [operations](operations.md) for deployment handling.
|
|
||||||
|
|
||||||
The `config validate`, `config show`, `config sources`, and `config explain`
|
ConfigKit strictly decodes application YAML: empty files, unknown fields,
|
||||||
commands inspect this
|
multiple documents, aliases/anchors, and incompatible/null values fail under its
|
||||||
application configuration without creating a Promptkit engine. `show` is a
|
schema rules. Explicit empty strings and numeric zeros remain values. The
|
||||||
resolved inspection snapshot, not necessarily a reloadable file. Application
|
nullable retry field preserves null. Application paths are trimmed/cleaned and
|
||||||
validation does not check framework sources, backend connectivity, or credential
|
the server address is trimmed within ConfigKit's resolver, with native
|
||||||
availability. `api_key_env` is an environment-variable *name* and remains
|
normalization evidence. Paths remain relative to process cwd, not the application
|
||||||
visible in inspection; its environment value is never read by ConfigKit.
|
file's directory. No general environment-variable override layer is installed.
|
||||||
Ordinary backend `extra_params` values also remain visible, so keep secrets out
|
|
||||||
of those fields and protect inspection output as potentially sensitive.
|
|
||||||
`config explain --path /server/addr` uses JSON Pointer syntax to show the
|
|
||||||
selected field's current value and history from defaults, files, overlays,
|
|
||||||
explicit CLI overrides, and normalization. `--path ''` selects the root.
|
|
||||||
History includes replaced and removed values; `show` presents the final
|
|
||||||
resolved snapshot. Neither renderer looks up credential bytes, and neither
|
|
||||||
claims to identify arbitrary secrets in unclassified parameter values.
|
|
||||||
|
|
||||||
## Custom Backends
|
## Explicit Imports And Selected Overlays
|
||||||
|
|
||||||
Use `backends` when a profile selects an application-defined backend ID:
|
Application imports use native root `config.imports` and are enabled during
|
||||||
|
loading. ConfigKit owns paths/directories/globs, requiredness, destination/item
|
||||||
|
placement, inheritance, sequence policy, and source-root confinement; consult its
|
||||||
|
[pinned contract][configkit]. Scriptorium does not widen the selected file's
|
||||||
|
canonical source root or implement another traversal/merge policy.
|
||||||
|
|
||||||
```yaml
|
`--overlay NAME` passes the name unchanged to ConfigKit. At the selected release,
|
||||||
backends:
|
empty and exact lowercase `default` select none; other names use letters,
|
||||||
local-gpu:
|
digits, underscores, or hyphens and select `overlays/NAME.yml` beneath the main
|
||||||
endpoint: http://localhost:11434/v1
|
source root. A missing selected overlay fails. It is not a filesystem-path flag,
|
||||||
api_key_env: LOCAL_GPU_API_KEY
|
inherited stack, or fallback-root mechanism. An active overlay after absent-main
|
||||||
extra_params:
|
search exhaustion has no independent filesystem root in this application.
|
||||||
provider_option: enabled
|
|
||||||
concurrency_limit: 2
|
|
||||||
queue_capacity: 0
|
|
||||||
```
|
|
||||||
|
|
||||||
Each mapping key is the case-sensitive backend ID. `endpoint` is required;
|
Only `serve` has named application override flags, for its HTTP settings.
|
||||||
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are
|
Native application-scope `--set` records are passed directly to ConfigKit.
|
||||||
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting
|
Nonconflicting records are supported; duplicate and ancestor/descendant paths
|
||||||
`queue_capacity` lets Promptkit use its default for a limited backend, while
|
are rejected rather than resolved by order. Configuration commands have no
|
||||||
an explicit `queue_capacity: 0` disables queueing.
|
application-defined source/schema/HTTP selectors or comparison counterparts.
|
||||||
|
Native comparison selections and supported overrides are independent on each side.
|
||||||
Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
|
|
||||||
validates backend IDs, endpoints, environment-variable names, extra parameters,
|
|
||||||
and capacity relationships when Scriptorium constructs its engine. There are no
|
|
||||||
backend command-line overrides. Store only an environment-variable name in
|
|
||||||
`api_key_env`; raw API-key fields are not accepted.
|
|
||||||
|
|
||||||
## Framework Source Mapping
|
## Framework Source Mapping
|
||||||
|
|
||||||
Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit
|
A nonempty resolved `promptkit.configuration` becomes an import-enabled
|
||||||
when constructing its engine. Scriptorium does not redefine or independently
|
`configkit.File` main input to PromptKit. An empty value leaves its main absent.
|
||||||
parse those framework file formats.
|
The native bundled OpenRouter underlay remains enabled; no application source
|
||||||
|
list, directory expansion, or local precedence interpreter is installed.
|
||||||
|
|
||||||
- Prompt selection, versions, message templates, inputs, output contracts, and
|
Imports in that external document compose framework definitions using PromptKit's
|
||||||
session IDs are Promptkit contracts.
|
schema and ConfigKit's native rules. The [maintained entry file](../examples/promptkit.yml)
|
||||||
- Profile fields, numeric ranges, execution defaults, overlay precedence,
|
imports the application's maintained prompt/profile fragments and backend
|
||||||
built-in profiles, and credential rules are Promptkit contracts.
|
definitions. Peer conflicts are errors, not filename-order precedence.
|
||||||
- Schema path behavior and generated-content validation are Promptkit
|
Native whole-record replacement and inheritance remain framework-owned.
|
||||||
contracts.
|
Application settings do not embed or re-decode framework definitions.
|
||||||
|
|
||||||
See the
|
PromptKit captures message-file resources with their defining source context
|
||||||
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
when constructing the engine. Schema/artifact reads, credential resolution, and
|
||||||
for all of those definitions. The files under
|
provider work retain native preparation/runtime lifecycles. The server keeps one
|
||||||
[`examples/prompts`](../examples/prompts/),
|
engine until restarted; later CLI invocations perform fresh loads.
|
||||||
[`examples/profiles`](../examples/profiles/), and
|
|
||||||
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium
|
|
||||||
application inputs using that tagged format.
|
|
||||||
|
|
||||||
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and
|
### Collection Checkout Discovery
|
||||||
`promptkit-openrouter-auto`. They can be selected as a prompt default or request
|
|
||||||
profile, and custom profile sources retain precedence. Their effective model
|
|
||||||
settings may change with a catalog upgrade; use a complete application-owned
|
|
||||||
profile when fixed settings are required. See the tagged format reference for
|
|
||||||
the maintained-profile contract.
|
|
||||||
|
|
||||||
## Credentials And Outbound Behavior
|
The [discovery configuration](../examples/config.discovery.yml) selects
|
||||||
|
[one framework entry](../examples/discovery/framework.yml) with two optional imports:
|
||||||
|
|
||||||
Scriptorium maps `--api-key-env` and HTTP `model.api_key_env` into Promptkit
|
```yaml
|
||||||
request overrides. Keep secret values in environment variables and store only
|
config:
|
||||||
their names in configuration or framework source files. Do not place raw keys
|
imports:
|
||||||
in configuration, prompts, profiles, CLI arguments, examples, or HTTP
|
- glob: collections/*/collection.yml
|
||||||
payloads.
|
- glob: collections/*/collection.yaml
|
||||||
|
```
|
||||||
|
|
||||||
An optional `api_key_env` whose environment value is absent or empty can result
|
Each independently maintained checkout declares its namespace and explicitly
|
||||||
in an unauthenticated provider request. A profile that declares credentials
|
imports its own definitions relative to its entry file. Checkout names do not
|
||||||
required still fails as an invalid request when no credential source is
|
determine resource IDs. The [support example](../examples/discovery/collections/support-repo/collection.yml)
|
||||||
selected, and fails with `ErrAPIKeyEnvMissing` when its selected environment
|
imports multiple profiles/prompts and a source-relative message; the
|
||||||
source is absent or empty. Scriptorium never reads or emits the environment
|
[review example](../examples/discovery/collections/review-repo/collection.yaml)
|
||||||
value itself.
|
uses the other spelling. Arbitrary checkout YAML is not loaded implicitly.
|
||||||
|
|
||||||
Unset optional provider controls are omitted from compatible provider requests.
|
Either glob may have no matches. New checkouts become visible on a later
|
||||||
A positive Promptkit `repair_attempts` budget can add provider calls, latency,
|
invocation, not through server hot reload. Entries in one discovery document are
|
||||||
token use, and cost; see the tagged format reference for its permitted values
|
peers: conflicting qualified IDs fail instead of relying on glob order.
|
||||||
and validation-mode requirements.
|
|
||||||
|
|
||||||
Promptkit's built-in client makes up to two additional attempts for eligible
|
## Inspection And Credentials
|
||||||
transient HTTP statuses by default. The application `transient_retries` setting
|
|
||||||
changes that budget for its constructed engine; an explicit `run` request
|
|
||||||
override takes precedence. This can increase latency, request count, and cost.
|
|
||||||
Each initial or repair generation has its own transient budget; an injected
|
|
||||||
client retains its own retry behavior. The tagged integration contract owns
|
|
||||||
eligibility and timing.
|
|
||||||
|
|
||||||
Promptkit's
|
The native `app` scope exposes the actual application result without acquiring
|
||||||
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
|
framework definitions or credentials. The `promptkit` scope exposes the captured
|
||||||
defines outbound authentication, provider request mapping, transport limits,
|
framework result selected by the application config/overlay. They are not merged
|
||||||
and timeout layering.
|
into one synthetic document. See [CLI inspection](cli.md#application-configuration-inspection)
|
||||||
|
for operations and independent comparison.
|
||||||
|
|
||||||
## Related References
|
PromptKit owns profiles, namespaces, provider controls, repairs, retries, and
|
||||||
|
credential resolution. Store credential environment-variable names, not raw
|
||||||
|
values; supply the selected environment to the process. Native framework
|
||||||
|
redaction is limited to classified fields and history, not arbitrary sensitive
|
||||||
|
content. Protect application, prompt, prepared, and generated reports as data.
|
||||||
|
|
||||||
- [CLI reference](cli.md)
|
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md
|
||||||
- [HTTP API reference](api.md)
|
[configkit]: https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md
|
||||||
- [Operations guide](operations.md)
|
|
||||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
|
||||||
|
|||||||
@@ -11,10 +11,11 @@ and the HTTP service according to the boundary your application needs.
|
|||||||
- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
|
- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
|
||||||
- HTTP service: [HTTP API reference](../api.md)
|
- HTTP service: [HTTP API reference](../api.md)
|
||||||
- Application configuration: [configuration reference](../config.md)
|
- Application configuration: [configuration reference](../config.md)
|
||||||
|
- Existing CLI callers: [native CLI migration](upgrading-cli.md)
|
||||||
|
|
||||||
Go applications that need an in-process prompt framework should import
|
Go applications that need an in-process prompt framework should import
|
||||||
Promptkit directly. The tagged
|
`go.maximumdirect.net/promptkit` directly. The tagged
|
||||||
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
[Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||||
owns that interface; Scriptorium does not provide a Go library package.
|
owns that interface; Scriptorium does not provide a Go library package.
|
||||||
Consumers arriving from the former Scriptorium Go API should follow the
|
Consumers arriving from the former Scriptorium Go API should follow the
|
||||||
[migration guide](migrating-to-promptkit.md).
|
[migration guide](migrating-to-promptkit.md).
|
||||||
@@ -27,7 +28,7 @@ Consumers are responsible for:
|
|||||||
- supplying required inputs and template variables;
|
- supplying required inputs and template variables;
|
||||||
- supplying credentials through the chosen interface;
|
- supplying credentials through the chosen interface;
|
||||||
- protecting rendered prompts and generated artifacts as potentially
|
- protecting rendered prompts and generated artifacts as potentially
|
||||||
sensitive;
|
sensitive, including native inspection and full result reports;
|
||||||
- deciding whether validation-failed output is usable; and
|
- deciding whether validation-failed output is usable; and
|
||||||
- retrying only when another model call is acceptable.
|
- retrying only when another model call is acceptable.
|
||||||
|
|
||||||
@@ -35,4 +36,4 @@ Scriptorium does not persist run state. A retry can produce different output
|
|||||||
and can incur another provider request. CLI exits belong to the
|
and can incur another provider request. CLI exits belong to the
|
||||||
[CLI reference](../cli.md), HTTP status behavior belongs to the
|
[CLI reference](../cli.md), HTTP status behavior belongs to the
|
||||||
[HTTP API reference](../api.md), and framework semantics belong to
|
[HTTP API reference](../api.md), and framework semantics belong to
|
||||||
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||||
|
|||||||
@@ -1,5 +1,11 @@
|
|||||||
# Migrate From Scriptorium To Promptkit
|
# Migrate From Scriptorium To Promptkit
|
||||||
|
|
||||||
|
This historical first hop targets Promptkit v0.11.1 and its former module
|
||||||
|
path. For the current public module `go.maximumdirect.net/promptkit` and the
|
||||||
|
ID-only configuration cutover, follow the
|
||||||
|
[current upgrade guide](upgrading-promptkit.md) afterward and consult the
|
||||||
|
[current Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
|
||||||
|
|
||||||
## Supported Migration Boundary
|
## Supported Migration Boundary
|
||||||
|
|
||||||
Scriptorium `v0.11.1` at
|
Scriptorium `v0.11.1` at
|
||||||
|
|||||||
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
|
This is the contributor entry point for Scriptorium. Scriptorium is an
|
||||||
application that consumes the public
|
application that consumes the public
|
||||||
[Promptkit v0.11.2 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md);
|
[PromptKit v0.23.3 package](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md);
|
||||||
framework implementation work belongs in Promptkit. Application configuration
|
framework implementation work belongs in Promptkit. Application configuration
|
||||||
uses ConfigKit v0.4.2; keep Scriptorium's schema and source selection local.
|
uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local.
|
||||||
|
Operator interfaces use CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0;
|
||||||
|
standard command families and presentation remain upstream-owned.
|
||||||
|
PromptKit uses the same ConfigKit release to load framework sources under its
|
||||||
|
own separate schema and format contract.
|
||||||
|
|
||||||
## Initial Orientation
|
## Initial Orientation
|
||||||
|
|
||||||
@@ -44,22 +48,32 @@ Before recommending, planning, or implementing work:
|
|||||||
| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) |
|
| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) |
|
||||||
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
||||||
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
|
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
|
||||||
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` |
|
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and the [native CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md) |
|
||||||
| Prompt, profile, schema, generation, or validation semantics | [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) |
|
| Promptkit source selection or captured framework inspection | [Configuration contract](config.md#framework-source-mapping), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) |
|
||||||
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) |
|
| Prompt, profile, schema, generation, or validation semantics | [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md) and the [Promptkit consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md) |
|
||||||
|
| OpenAI-compatible outbound behavior or timeout layering | [PromptKit v0.23.3 integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md) |
|
||||||
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
|
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
|
||||||
| Runtime operation or recovery | [Operations](operations.md) |
|
| Runtime operation or recovery | [Operations](operations.md) |
|
||||||
| Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) |
|
| Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) |
|
||||||
| Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) |
|
| Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) |
|
||||||
| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md), and the related files under `examples/` |
|
| Examples or copyable assets | The owning Scriptorium contract, the relevant [PromptKit v0.23.3 format contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md), and the related files under `examples/` |
|
||||||
| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents |
|
| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents |
|
||||||
|
|
||||||
Cross-project changes land and release in Promptkit before Scriptorium adopts
|
Cross-project changes land and release in Promptkit before Scriptorium adopts
|
||||||
the tagged version. Do not commit a Go workspace, local replacement, vendored
|
the tagged version. Do not commit a Go workspace, local replacement, vendored
|
||||||
Promptkit source, or an import of a Promptkit `internal` package.
|
Promptkit source, or an import of a Promptkit `internal` package.
|
||||||
|
The module graph can include upstream maintainer tools such as ReleaseKit and
|
||||||
|
their dependencies even though those graph-only packages are not linked into
|
||||||
|
the Scriptorium runtime; use `go list -deps ./cmd/scriptorium` to distinguish
|
||||||
|
the linked packages.
|
||||||
|
|
||||||
## Baseline Validation
|
## Baseline Validation
|
||||||
|
|
||||||
|
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0,
|
||||||
|
required by application ConfigKit v1.2.1. Running a published binary does not
|
||||||
|
require a Go installation. Release validation and builds use
|
||||||
|
the separately selected toolchain in the [release procedure](release.md).
|
||||||
|
|
||||||
For code changes, run:
|
For code changes, run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -1,63 +1,67 @@
|
|||||||
# Subprocess Integration
|
# Subprocess Integration
|
||||||
|
|
||||||
This document covers process-boundary behavior for callers that invoke
|
Use the executable when a local process boundary is appropriate.
|
||||||
Scriptorium as a child process. Command syntax, flags, output, and exit codes
|
The [CLI contract](../cli.md) owns exact command/flag/status syntax; the
|
||||||
are defined by the [CLI reference](../cli.md). Interface selection belongs in
|
[consumer overview](../consumers/api.md) compares subprocess and HTTP use.
|
||||||
the [consumer integration overview](../consumers/api.md).
|
|
||||||
|
|
||||||
## Process Contract
|
## Artifact-First Execution And Inspection
|
||||||
|
|
||||||
Use `scriptorium render` when the caller needs prepared output without a model
|
Select a stored prompt and capture its generated artifact from stdout. Use native
|
||||||
call, and `scriptorium run` for generation. Pass an explicit `--config` or
|
requirements discovery before generated input files exist, concrete validation
|
||||||
make the configuration search paths available to the child process; configuration
|
once bindings exist, and prepared preview to render without a model call.
|
||||||
discovery, fields, profile selection, and credential mechanisms are defined in
|
The [CLI migration guide](../consumers/upgrading-cli.md) explains replacements
|
||||||
the [configuration reference](../config.md).
|
for older command and file-output conventions.
|
||||||
|
|
||||||
Pass required API-key environment variables through the child environment. Do
|
Pass an explicit application configuration or deliberately arrange the child's
|
||||||
not place raw API keys in arguments. Keep the environment limited to the values
|
[configuration discovery](../config.md). Supply only the environment needed for
|
||||||
needed for the selected profile.
|
selected credentials; never put raw keys in arguments.
|
||||||
|
|
||||||
For application-only preflight, invoke `scriptorium config validate`; it exits
|
Discovery completeness is distinct from binding satisfaction and execution
|
||||||
0 with empty stdout when the application configuration loads, but does not
|
readiness. Partial reports can succeed. Consumers own their binding graph and
|
||||||
prove that Promptkit sources or credentials are usable. `config show` emits
|
policy for incomplete findings; Scriptorium supplies no workflow state.
|
||||||
resolved YAML and `config sources` emits newline-terminated JSON provenance.
|
|
||||||
All three use the same source selection and explicit overrides as execution
|
|
||||||
commands and require separate stderr capture for diagnostics. Their output can
|
|
||||||
include source paths, identifiers, credential reference names, and ordinary
|
|
||||||
backend parameters; treat it as potentially sensitive.
|
|
||||||
|
|
||||||
## Streams And Output Ownership
|
## Streams, Reports, And Availability
|
||||||
|
|
||||||
Capture stdout and stderr separately. Stdout contains the requested artifact or
|
Capture stdout and stderr separately. Diagnostics are not a machine-readable
|
||||||
prepared output unless the caller selects an output file; stderr contains
|
error protocol, even when structured result output is selected. Prefer exit
|
||||||
summaries, diagnostics, and server messages. The exact destinations and status
|
classification and native report fields; do not parse diagnostic prose.
|
||||||
meanings are part of the [CLI reference](../cli.md), not a stable stderr data
|
|
||||||
protocol.
|
|
||||||
|
|
||||||
When using `--out`, the caller owns the output path, its permissions, and
|
The default generated result is artifact content. Native structured results and
|
||||||
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as
|
optional separate reports carry the full returned result, including content and
|
||||||
potentially sensitive.
|
metadata. They are not the former metadata-only CLI observation report. Native
|
||||||
|
prompt/prepared inspection also carries content. Treat all captured streams and
|
||||||
|
reports as potentially sensitive.
|
||||||
|
|
||||||
For `run`, an optional [execution report file](../cli.md) contains terminal
|
To save main output, supply a file as the subprocess stdout destination or use
|
||||||
metadata separate from generated stdout or `--out`. The caller owns that
|
shell redirection. Omit quiet when that main result is needed: quiet suppresses
|
||||||
path's permissions and retention. Output and report files are not a
|
it even for redirected stdout. A separately requested report remains an
|
||||||
transaction: one may be written when the other fails, and a preexisting report
|
application file effect independent of quiet and main format selection.
|
||||||
may remain when the invocation has no terminal event. Check the exit status
|
|
||||||
and diagnostics rather than assuming a report path contains this run's data.
|
A completed content-validation failure can still deliver an artifact/result;
|
||||||
|
consumers decide whether it is usable. An operational failure with no result
|
||||||
|
produces diagnostics and a nonzero status, not a synthesized result/error
|
||||||
|
envelope. An existing separate report may then describe an older invocation.
|
||||||
|
|
||||||
|
## Partial Delivery And Caller Responsibility
|
||||||
|
|
||||||
|
Main output is attempted before a requested report, and report delivery is
|
||||||
|
attempted even after main presentation failure. Either destination may contain
|
||||||
|
partial data after an error. File delivery is not transactional and has no
|
||||||
|
rollback or atomic-replacement promise.
|
||||||
|
|
||||||
|
Callers own redirected file creation/truncation, permissions, retention, and
|
||||||
|
keeping destinations separate. A shell may truncate its file before the process
|
||||||
|
starts, unlike a separate report that is opened only after a result exists.
|
||||||
|
Check the finalized exit status and diagnostic stream; do not infer success or
|
||||||
|
freshness from a file's existence.
|
||||||
|
|
||||||
## Cancellation And Recovery
|
## Cancellation And Recovery
|
||||||
|
|
||||||
A CLI invocation performs one synchronous request and creates no durable run
|
Interrupt/SIGTERM cancels the child's invocation context. Engine cancellation is
|
||||||
state. A supervising process that needs cancellation must terminate the child
|
cooperative. The [whole-operation budget](../cli.md#generation) is separate from
|
||||||
process according to its own process-management policy. A later invocation is a
|
per-attempt provider timeouts and excludes process/configuration setup and
|
||||||
new request and can make another model call; there is no resume or checkpoint
|
delivery. Supervisors still own forced process termination when required.
|
||||||
protocol.
|
|
||||||
|
|
||||||
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
|
A new invocation is a new request that may incur another provider call/cost.
|
||||||
engine invocation. It is separate from the per-attempt generation timeout and
|
There is no checkpoint, archive, conversation, or resume protocol. Deployment and
|
||||||
does not include child startup or output writing. A deadline failure exits 1;
|
sensitive-data handling belong to [operations](../operations.md).
|
||||||
supervisors still own process termination when they need to stop the child
|
|
||||||
outside that engine interval.
|
|
||||||
|
|
||||||
For deployment, filesystem permissions, and sensitive-artifact handling, see
|
|
||||||
the [operations guide](../operations.md).
|
|
||||||
|
|||||||
@@ -1,136 +1,89 @@
|
|||||||
# Adapter Internals
|
# Adapter Internals
|
||||||
|
|
||||||
## Purpose
|
Adapters map executable inputs and effects through public upstream values.
|
||||||
|
The [CLI](../cli.md), [HTTP API](../api.md), and [architecture policy](../policy/architecture.md)
|
||||||
|
own their external contracts and boundaries.
|
||||||
|
|
||||||
Scriptorium adapters translate executable inputs into Promptkit public requests
|
## CLI Composition And Acquisition
|
||||||
and translate Promptkit results or errors back to CLI or HTTP behavior. They
|
|
||||||
own IO and presentation mechanics, not framework decisions.
|
|
||||||
|
|
||||||
External contracts are canonical in the [CLI reference](../cli.md) and
|
`app.go` composes application run/serve declarations with native configuration,
|
||||||
[HTTP API reference](../api.md). Promptkit's public engine contract is
|
PromptKit, completion, help, and version support. CommandKit owns parsing,
|
||||||
described by its tagged
|
declaration-input checks, reporting selection, presentation, and finalization.
|
||||||
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md).
|
|
||||||
|
|
||||||
## Components And Collaborators
|
`selection.go` maps explicit native config/overlay choices and server-only HTTP
|
||||||
|
bindings into `internal/config.Load`. It preserves supplied empty/zero values.
|
||||||
|
Native application `--set` records remain upstream records with native conflict
|
||||||
|
handling. No application selectors are installed under configuration commands.
|
||||||
|
|
||||||
- `cmd/scriptorium` passes process arguments and streams to
|
`native_config.go` adapts the actual application result through
|
||||||
`internal/adapter/cli`.
|
`ckconfig.FromConfigKit` and framework inspection through `ckprompt.ConfigScope`.
|
||||||
- `internal/adapter/cli` resolves settings through `internal/config`,
|
Native views own effective values, paths, metadata, sources, findings, explanations,
|
||||||
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
redaction, and comparison. Application inspection does not construct an engine.
|
||||||
and owns output files, summaries, and exit codes.
|
Comparison loads each side from that side's selection; there is no config/engine
|
||||||
- `internal/config` delegates application YAML decoding, default resolution,
|
cache or effective-document reconstruction.
|
||||||
overrides, and validation ordering to ConfigKit. The CLI supplies only
|
|
||||||
explicitly visited application flags as overrides and renders safe structured
|
|
||||||
load diagnostics on stderr.
|
|
||||||
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
|
|
||||||
public values, calls its adapter-owned `Runner` interface, and maps results
|
|
||||||
and errors to HTTP DTOs.
|
|
||||||
- `internal/format` renders `promptkit.PreparedRun` values as deterministic text
|
|
||||||
or JSON.
|
|
||||||
- `internal/report` maps Promptkit's terminal execution event to a small
|
|
||||||
application-owned value without invoking the engine or writing output.
|
|
||||||
|
|
||||||
## Wiring Flows
|
`acquisitionState` contains application diagnostic evidence only, never loaded
|
||||||
|
configuration or engines. Callback decorators forward it through native
|
||||||
|
`Acquired` channels. An application LoadError is transported separately while
|
||||||
|
the framework adapter runs, then its original typed cause is restored before
|
||||||
|
native outcome classification. This prevents app findings from becoming
|
||||||
|
framework findings. Native framework evidence remains unchanged; comparison
|
||||||
|
application messages identify left/right context. Callback marks prevent replay
|
||||||
|
when operations share invocation state.
|
||||||
|
|
||||||
### CLI
|
`native_prompt.go` installs all twelve ckprompt callbacks, nil request builders,
|
||||||
|
and empty-default native namespace views. Inventories, named resources,
|
||||||
|
requirements, validation, preparation, and smoke testing retain their upstream
|
||||||
|
lifecycles and reports.
|
||||||
|
|
||||||
`run` calls `promptkit.Engine.Run`; `render` calls
|
## Generation And Delivery
|
||||||
`promptkit.Engine.Prepare`. Both share request mapping for prompt ID/version
|
|
||||||
and profile selection, optional file inputs, variables, and presence-aware
|
|
||||||
execution overrides. Omitted framework settings remain zero values so Promptkit
|
|
||||||
resolves its own defaults and definition-required inputs.
|
|
||||||
The application retry setting enters shared engine construction, while a
|
|
||||||
run/render flag enters only the mapped request. The server uses the same engine
|
|
||||||
setting and retains one backend admission state. Render prepares without
|
|
||||||
generation.
|
|
||||||
|
|
||||||
`inspect prompt` maps the selected ID and optional version to
|
`native_run.go` binds the required operand and reusable resource/input/execution
|
||||||
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
|
flags into a native RunRequest. Ordinary typed namespace flags feed
|
||||||
data. It constructs the same configuration-aware engine but does not perform
|
`Engine.WithNamespaces`; stored references are not rewritten. One `Engine.Run`
|
||||||
preparation or generation.
|
call receives the invocation context and unchanged operation duration. PromptKit
|
||||||
|
owns preparation, credentials, admission, retries, repairs, and content validation.
|
||||||
|
|
||||||
`inspect profile` maps an explicit profile ID to `Engine.InspectProfile` and
|
`outcomes.go` maps typed failures and native configuration evidence to native
|
||||||
formats a safe application-owned effective profile view. It intentionally does
|
outcomes, preserving causes while keeping provider payloads out of terminal
|
||||||
not require prompt, schema, or artifact sources.
|
explanations. A returned completed validation failure remains a domain outcome;
|
||||||
|
an unexpected nil successful result is an integration failure.
|
||||||
|
|
||||||
The `config` family loads the same application ConfigKit result once and uses
|
`delivery.go` submits the actual RunResult to the invocation reporter with a
|
||||||
its validation, effective-output, source, and explanation views directly. It
|
reusable artifact-byte text template. The optional file renders that same value
|
||||||
does not construct a Promptkit engine. The CLI maps source records into a small
|
without the template through CommandKit's writer API, outside reporter callbacks
|
||||||
JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
|
to avoid reentrancy. File failures add explanations/causes while reporter
|
||||||
|
presentation failures remain native. See [delivery semantics](../cli.md#results-and-separate-reports).
|
||||||
|
|
||||||
`serve` constructs Scriptorium's restricted HTTP artifact reader, injects it
|
## Server And HTTP
|
||||||
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
|
||||||
adapter's consumer-owned `Runner` interface, and starts the server.
|
|
||||||
|
|
||||||
The command paths assemble the engine from the same resolved prompt, profile,
|
`server.go` loads application settings, injects the restricted artifact reader
|
||||||
and schema directories plus configured custom backends. Each backend is mapped
|
into one engine, installs the existing HTTP handler/limits, and opens a listener.
|
||||||
to Promptkit's public `Backend` value and registered during engine construction,
|
It retains the header timeout and engine retry defaults. Context cancellation
|
||||||
so one constructed server engine retains one immutable backend registry and its
|
calls Server.Close; callback coordination finishes connection/listener closing
|
||||||
associated capacity state.
|
before return, without waiting for arbitrary context-ignoring application work.
|
||||||
|
|
||||||
### HTTP
|
The HTTP handler strictly decodes DTOs and applies transport policy before
|
||||||
|
mapping to PromptKit requests. Its Runner interface is a consumer-side external
|
||||||
|
boundary using native values. Request controls do not mutate shared engine
|
||||||
|
defaults; shared backend capacity accounting remains in that engine.
|
||||||
|
|
||||||
The handler enforces transport limits and strict JSON decoding before mapping
|
HTTP optional reports use one per-request `internal/report.Collector`, attached
|
||||||
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and
|
only for opted-in requests. It copies terminal aggregates, not event history,
|
||||||
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact,
|
and is never the CLI result report. Success/error attachment and encoded-size
|
||||||
validation, model, usage, and metadata values directly.
|
handling retain the [HTTP contract](../api.md#execution-report). Reader sentinel
|
||||||
The optional HTTP retry count maps to `RunRequest.TransientRetries` without
|
identities survive PromptKit wrapping for status mapping.
|
||||||
mutating the shared engine. Negative values are rejected before invocation;
|
|
||||||
Promptkit controls retries and backend admission for concurrent requests.
|
|
||||||
|
|
||||||
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
|
|
||||||
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader
|
|
||||||
errors preserve their identity through Promptkit's artifact-load boundary.
|
|
||||||
|
|
||||||
The report collector is per invocation. It ignores nonterminal events and
|
|
||||||
copies terminal aggregates once, including usage presence and completeness.
|
|
||||||
It retains no history or shared state; adapters decide whether to attach it and
|
|
||||||
how to present its snapshot.
|
|
||||||
CLI `run` attaches one only when a report path is selected, writes generated
|
|
||||||
output first on success, and then writes the terminal snapshot when present.
|
|
||||||
Its report path remains untouched for pre-invocation failures or absent
|
|
||||||
terminal observations; report and artifact writes are independent.
|
|
||||||
HTTP `POST /v1/runs` attaches a separate collector to each invocation only when
|
|
||||||
`include_execution_report` is true. Its optional top-level `execution` field
|
|
||||||
appears in success or error envelopes only when Promptkit emits a terminal
|
|
||||||
event. Pre-invocation adapter errors and absent terminal events leave it out.
|
|
||||||
The complete serialized success or report-bearing error response is subject to
|
|
||||||
the configured response-size limit; overflow returns the compact 413 error
|
|
||||||
without a report. Field meanings are owned by the [API contract](../api.md#execution-report).
|
|
||||||
|
|
||||||
## Package-Local Guarantees
|
|
||||||
|
|
||||||
- Adapters contain no copied framework types or orchestration.
|
|
||||||
- Configuration is resolved before Promptkit engine construction.
|
|
||||||
- Explicit numeric overrides preserve presence, including zero.
|
|
||||||
- HTTP DTO and error mapping remains stable and transport-owned.
|
|
||||||
- Resolved secrets are not serialized or printed.
|
|
||||||
- No adapter creates durable run state.
|
|
||||||
|
|
||||||
## Verification
|
## Verification
|
||||||
|
|
||||||
Inspect:
|
Native composition/configuration/prompt/run/delivery/lifecycle tests protect the
|
||||||
|
application's integration choices using real libraries and controlled local
|
||||||
|
providers. Checkout-discovery tests cover fresh invocations and entry-file
|
||||||
|
spellings. Entrypoint tests protect identity/status mapping; HTTP reader/DTO/
|
||||||
|
report/capacity regressions and the architecture guard remain their own owners.
|
||||||
|
Do not duplicate upstream parsers, analyzers, serializers, or exhaustive format
|
||||||
|
matrices to change an adapter.
|
||||||
|
|
||||||
- `internal/adapter/cli/run_test.go`
|
When changing behavior, update its canonical external contract and focused
|
||||||
- `internal/adapter/http/handler_test.go`
|
integration protection. Required shared capabilities belong upstream before
|
||||||
- `internal/adapter/http/artifact_reader_test.go`
|
tagged adoption, not in a resurrected application framework facade.
|
||||||
- `internal/format/prepared_run_test.go`
|
|
||||||
- `internal/adapter/dependency_test.go`
|
|
||||||
|
|
||||||
The adapter tests protect parsing, configuration mapping, output, status
|
|
||||||
mapping, restricted artifacts, and representative real Promptkit-engine
|
|
||||||
workflows. The dependency test protects the repository boundary.
|
|
||||||
|
|
||||||
## Change Recipes
|
|
||||||
|
|
||||||
For a CLI or HTTP change:
|
|
||||||
|
|
||||||
1. identify the Scriptorium-owned external contract;
|
|
||||||
2. map through Promptkit public values without copying framework semantics;
|
|
||||||
3. add or update the narrow application-owned test;
|
|
||||||
4. update the canonical Scriptorium contract; and
|
|
||||||
5. coordinate and tag Promptkit first if a required public capability is
|
|
||||||
genuinely absent.
|
|
||||||
|
|
||||||
Update [source internals](sources.md) when application source locations or HTTP
|
|
||||||
artifact containment changes.
|
|
||||||
|
|||||||
@@ -1,19 +1,18 @@
|
|||||||
# Internal Component Overview
|
# Internal Component Overview
|
||||||
|
|
||||||
This is the complete inventory of Scriptorium's implemented Go components.
|
This inventory describes implemented Go components. The
|
||||||
The [architecture policy](../policy/architecture.md) owns normative boundaries;
|
[architecture policy](../policy/architecture.md) owns normative boundaries;
|
||||||
public behavior belongs in the linked contracts.
|
public behavior belongs in the linked contracts.
|
||||||
|
|
||||||
| Component | Implemented responsibility | References |
|
| Component | Implemented responsibility | References |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
| `cmd/scriptorium` | Build identity, signal-aware context, native status-to-process exit. | [CLI](../cli.md), [adapters](adapters.md) |
|
||||||
| `internal/adapter/cli` | Parses execution and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
| `internal/adapter/cli` | CommandKit composition, ckconfig/ckprompt acquisition, application loading, native request mapping, run/report effects, and HTTP process lifecycle. | [CLI](../cli.md), [adapters](adapters.md), [sources](sources.md) |
|
||||||
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
| `internal/adapter/http` | Routes, strict DTO decoding, transport limits, public request/result/error mapping, and restricted artifact reader. | [HTTP API](../api.md), [adapters](adapters.md), [sources](sources.md) |
|
||||||
| `internal/config` | Selects application sources, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md) |
|
| `internal/config` | ConfigKit application schema, discovery/selection, defaults/resolution/validation callbacks, and completed-value conversion. | [Configuration](../config.md), [sources](sources.md) |
|
||||||
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
|
| `internal/defaults` | Application and HTTP default constants. | [Configuration](../config.md) |
|
||||||
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
| `internal/report` | HTTP terminal-observation metadata projection. It is not used for CLI native result reports. | [HTTP execution report](../api.md#execution-report), [adapters](adapters.md) |
|
||||||
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
|
|
||||||
|
|
||||||
Framework implementation packages are provided by
|
CommandKit, ckconfig, ckprompt, ConfigKit, and PromptKit are released upstream
|
||||||
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
dependencies, not local framework packages. There is no custom CLI formatter
|
||||||
and are not part of this repository.
|
package or compatibility dispatch surface.
|
||||||
|
|||||||
@@ -1,101 +1,55 @@
|
|||||||
# Source Internals
|
# Source Internals
|
||||||
|
|
||||||
## Purpose
|
This document covers application acquisition and the restricted HTTP artifact
|
||||||
|
reader. [Configuration](../config.md) owns field/discovery/composition contracts;
|
||||||
|
the [PromptKit formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
|
own framework resources and execution semantics.
|
||||||
|
|
||||||
This document covers Scriptorium-owned source locations and the restricted HTTP
|
## Application Boundary And Engine Construction
|
||||||
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
|
|
||||||
owned by the tagged
|
|
||||||
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
|
||||||
|
|
||||||
## Application Source Locations
|
`internal/config.Load` selects an explicit File or the ordered native SearchConfig
|
||||||
|
presets and performs one ConfigKit load with imports, overlay selection, and
|
||||||
|
explicit overrides. It returns the actual Result with native inspection evidence.
|
||||||
|
Definition callbacks supply application defaults, record actual path/address
|
||||||
|
normalizations through ConfigKit, and validate retry/HTTP-size domains. Settings
|
||||||
|
conversion consumes completed values without another merge or normalization pass.
|
||||||
|
|
||||||
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from
|
The typed application PromptKit section selects acquisition only. In
|
||||||
Scriptorium defaults, configuration files, and CLI overrides. It also resolves
|
`engine.go`, a nonempty resolved configuration path becomes an import-enabled
|
||||||
the application-owned `backends` mapping into sorted engine settings.
|
main Input; an empty path leaves Main nil. The schema base and retry default are
|
||||||
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps
|
passed directly, retaining the bundled underlay. There is no source-list parser,
|
||||||
each configured backend to Promptkit's public engine registration when
|
directory classification/expansion, or one-underlay-per-selector algorithm.
|
||||||
constructing an engine shared by the command path.
|
|
||||||
|
|
||||||
Scriptorium does not search, parse, validate, or overlay framework source files
|
Framework imports resolve within the native source context. Message resources
|
||||||
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema
|
are captured from their defining contexts at engine construction. Schema and
|
||||||
resolution, ordinary file artifacts, and the related error identities.
|
request-artifact acquisition retain their preparation-time behavior.
|
||||||
|
Independent collection checkouts are discovered by native file import globs,
|
||||||
|
not application traversal. New invocations reload normally; a server retains
|
||||||
|
its single engine until restart.
|
||||||
|
|
||||||
The [configuration reference](../config.md) owns Scriptorium's source-location
|
Application-only inspection uses its completed result without framework
|
||||||
fields and precedence. Maintained files under `examples/` are application
|
acquisition. Framework inspection exposes the native captured view separately.
|
||||||
inputs that use Promptkit's tagged formats.
|
Diagnostic decoration in the [CLI adapter](adapters.md) carries application
|
||||||
|
messages without combining evidence trees or effective documents. There is no
|
||||||
## Application Configuration Boundary
|
per-invocation engine/config cache or cross-invocation snapshot guarantee.
|
||||||
|
|
||||||
`internal/config` contains a ConfigKit-native `Document` definition. Its
|
|
||||||
fresh defaults come from Scriptorium's existing default constants; its resolver
|
|
||||||
records only actual trimming, path cleaning, and render-format normalization.
|
|
||||||
The validator reports application retry, size-limit, and format errors without
|
|
||||||
mutating the document or exposing rejected values. Application path values keep
|
|
||||||
working-directory-relative meaning. ConfigKit owns strict YAML decoding and
|
|
||||||
presence semantics, including dynamic integer values in backend parameters.
|
|
||||||
|
|
||||||
The `Load` boundary selects an explicit file, the first existing implicit
|
|
||||||
configuration file, or ConfigKit's defaults-only source. Only absence advances
|
|
||||||
implicit discovery. One ConfigKit load applies explicit application overrides
|
|
||||||
before validation and returns a result containing the resolved document and
|
|
||||||
its frozen inspection records. `Settings` converts that document into the
|
|
||||||
existing runtime settings with backend IDs sorted; it does not read files or
|
|
||||||
apply another merge. File-backed loads enable explicit ConfigKit imports and
|
|
||||||
select one named overlay when requested. ConfigKit uses the selected file's
|
|
||||||
canonical directory as the source root; the application does not widen it.
|
|
||||||
Application path values retain process-working-directory-relative meaning.
|
|
||||||
|
|
||||||
Every configuration-loading command uses this boundary. The CLI maps only
|
|
||||||
explicitly visited application flags to ConfigKit overrides and prints
|
|
||||||
structured load diagnostics before engine construction. The old application
|
|
||||||
YAML decoder and merge path have been removed.
|
|
||||||
Application `config` inspection reuses the result's frozen effective,
|
|
||||||
provenance, and history views without constructing an engine or reloading
|
|
||||||
sources. It does not resolve API-key environment values; ordinary backend
|
|
||||||
parameters remain visible by the selected inspection policy.
|
|
||||||
|
|
||||||
## Restricted HTTP Artifact Reader
|
## Restricted HTTP Artifact Reader
|
||||||
|
|
||||||
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP
|
The HTTP adapter implements `promptkit.ArtifactReader`; server construction
|
||||||
requests. The `serve` path injects it with
|
injects it through the public option. Ordinary CLI artifact loading remains
|
||||||
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for
|
upstream-owned.
|
||||||
inbound HTTP inputs.
|
|
||||||
|
|
||||||
The reader:
|
The reader accepts inline content without a root. File references need a root;
|
||||||
|
relative paths resolve below it and absolute paths must be lexically contained.
|
||||||
|
Traversal outside is rejected and the configured file byte limit applies, with
|
||||||
|
zero unlimited. Reads preserve native artifact metadata and honor cancellation.
|
||||||
|
|
||||||
- accepts inline references without an artifact root;
|
Containment does not resolve symlinks. The OS may follow a symlink inside the
|
||||||
- denies file references when no root is configured;
|
root to an outside target; this is not a filesystem sandbox or a defense against
|
||||||
- resolves relative paths below the configured root;
|
privileged concurrent filesystem modification. Reader errors retain identity
|
||||||
- accepts absolute paths only when they are lexically within that root;
|
through upstream artifact-load wrapping, enabling the existing HTTP mapping.
|
||||||
- rejects lexical traversal outside the root;
|
|
||||||
- applies the configured file byte limit, with zero meaning unlimited;
|
|
||||||
- preserves content type, body, size, hash, name, and URI metadata; and
|
|
||||||
- honors context cancellation.
|
|
||||||
|
|
||||||
Containment is lexical and does not resolve symlinks. The operating system
|
The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
|
||||||
follows symlinks after the check. The [HTTP API](../api.md) owns observable
|
safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
|
||||||
request outcomes, and [operations](../operations.md) owns safe deployment
|
reader/handler tests own their respective boundaries; upstream owns exhaustive
|
||||||
permissions and root selection.
|
source traversal, format parsing, ordinary artifacts, and inspection semantics.
|
||||||
|
|
||||||
Reader errors remain identifiable after Promptkit wraps them as artifact-load
|
|
||||||
failures, allowing the HTTP adapter to preserve Scriptorium status and error
|
|
||||||
codes.
|
|
||||||
|
|
||||||
## Verification And Change Recipe
|
|
||||||
|
|
||||||
Inspect:
|
|
||||||
|
|
||||||
- `internal/config/document_test.go`
|
|
||||||
- `internal/config/load_test.go`
|
|
||||||
- `internal/adapter/cli/run_test.go`
|
|
||||||
- `internal/adapter/http/artifact_reader_test.go`
|
|
||||||
- `internal/adapter/http/handler_test.go`
|
|
||||||
|
|
||||||
When changing an application source location or HTTP artifact policy:
|
|
||||||
|
|
||||||
1. preserve strict configuration precedence and the Promptkit public boundary;
|
|
||||||
2. keep containment and size policy in Scriptorium;
|
|
||||||
3. update focused configuration, reader, and handler tests;
|
|
||||||
4. update the [configuration](../config.md), [HTTP](../api.md), and
|
|
||||||
[operations](../operations.md) contracts as applicable; and
|
|
||||||
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.
|
|
||||||
|
|||||||
@@ -1,229 +1,120 @@
|
|||||||
# Operations Guide
|
# Operations Guide
|
||||||
|
|
||||||
## Scope And References
|
This runbook covers deployment, normal operation, capacity, sensitive data, and
|
||||||
|
recovery. Exact [CLI syntax/statuses](cli.md), [configuration](config.md), and
|
||||||
|
[HTTP wire behavior](api.md) remain in their canonical references.
|
||||||
|
See the [CLI migration guide](consumers/upgrading-cli.md) for changed jobs and
|
||||||
|
the [framework upgrade guide](consumers/upgrading-promptkit.md) for definitions.
|
||||||
|
|
||||||
This runbook covers deployment, normal operation, capacity planning, and safe
|
## Deploy Sources And Process
|
||||||
recovery for Scriptorium. It does not redefine invocation syntax, configuration
|
|
||||||
fields, or HTTP wire behavior.
|
|
||||||
|
|
||||||
- [CLI reference](cli.md): commands, output destinations, and exit codes.
|
Provide readable application configuration, its selected framework entry file,
|
||||||
- [Configuration reference](config.md): application settings, source
|
and explicitly imported definitions/resources. Set cwd deliberately: application
|
||||||
locations, defaults, and credential mapping.
|
path values are cwd-relative, while framework imports and message resources keep
|
||||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md):
|
their native source contexts. ConfigKit confines source imports/overlays to the
|
||||||
prompt, profile, schema, execution-setting, and framework credential
|
selected main's canonical root; Scriptorium does not widen it.
|
||||||
contracts.
|
|
||||||
- [HTTP API reference](api.md): route, request/response schema, status codes,
|
|
||||||
limits, and HTTP artifact access.
|
|
||||||
- [Consumer integration overview](consumers/api.md): caller responsibilities.
|
|
||||||
|
|
||||||
## Operational Model And State
|
Engine construction validates selected effective definitions and captures message
|
||||||
|
resources/template syntax, including definitions not used by a particular request.
|
||||||
|
Schema/artifact reads, credential resolution, and model work retain their native
|
||||||
|
preparation/runtime lifecycles. A server constructs one engine at startup and
|
||||||
|
does not hot-reload changed files; restart to capture updates. Separate CLI
|
||||||
|
invocations load afresh rather than sharing an immutable snapshot.
|
||||||
|
|
||||||
Scriptorium handles one prompt request for each CLI invocation or HTTP request.
|
For independent collections, install checkouts beneath the layout selected by
|
||||||
It has no durable run store, archive, checkpoint, cache, or resume mechanism.
|
the [discovery entry](../examples/discovery/framework.yml). Each checkout declares
|
||||||
A failed or interrupted request is recovered by correcting its inputs,
|
its namespace and explicit fragment imports; arbitrary YAML is not a framework
|
||||||
configuration, or environment and submitting a new request.
|
source. The maintained [discovery example](../examples/config.discovery.yml)
|
||||||
|
supports both entry-file spellings and multiple definitions. New checkouts or
|
||||||
|
updates become visible to later invocations or a restarted server.
|
||||||
|
|
||||||
Generated artifacts, rendered prompts, model output, and run metadata are
|
Supply only needed credential environment variables through a supervisor or
|
||||||
caller-owned data. Retention, encryption, backup, and deletion are deployment
|
secret-management mechanism. Confirm presence without printing their values.
|
||||||
responsibilities.
|
Raw keys do not belong in arguments or checked-in configuration.
|
||||||
Optional [CLI execution reports](cli.md) also belong to the caller. They can
|
|
||||||
contain sensitive identifiers even though they omit prompt and response bodies.
|
|
||||||
Keep report paths separate from generated output and apply the same access and
|
|
||||||
retention controls. Output and report writes are not transactional; an older
|
|
||||||
report may remain when no terminal observation was produced.
|
|
||||||
HTTP callers may also request a [terminal execution report](api.md#execution-report).
|
|
||||||
It shares the same identifier sensitivity and should receive response access
|
|
||||||
and retention controls. An opted-in report increases the encoded response size;
|
|
||||||
an oversized success or report-bearing error becomes the compact 413 response
|
|
||||||
without a report.
|
|
||||||
|
|
||||||
## Deploy The Filesystem And Process
|
## Normal Operator Workflow
|
||||||
|
|
||||||
Provide the process with readable configured Promptkit prompt, profile, and
|
1. Validate application configuration through the native application scope.
|
||||||
schema sources that follow the tagged framework formats. For an HTTP deployment
|
This does not acquire framework sources or prove provider readiness.
|
||||||
that accepts file artifacts, use a dedicated, narrow artifact directory rather
|
2. Inspect framework configuration/resources and discover requirements for the
|
||||||
than a general-purpose or sensitive filesystem tree.
|
selected prompt/profile/namespaces. Discovery can precede generated input
|
||||||
|
artifacts; completeness does not establish satisfied bindings.
|
||||||
|
3. Once artifacts exist, validate the concrete request or inspect prepared
|
||||||
|
content. These are provider-free preparation checks with native prerequisites.
|
||||||
|
4. Invoke a smoke test only when its provider effects are intended. Findings
|
||||||
|
can be unsupported or unsuccessful while the command itself succeeds.
|
||||||
|
Smoke tests are not an automatic startup or release prerequisite.
|
||||||
|
5. Generate with the same selections and bindings, then inspect the finalized
|
||||||
|
status and any returned validation result before accepting the output.
|
||||||
|
|
||||||
If application configuration uses explicit imports or a selected overlay,
|
Use the [maintained preview script](../examples/render-markdown-summary.sh)
|
||||||
deploy those files beneath the selected configuration file's canonical
|
for a provider-free example, and the [CLI contract](cli.md) for commands.
|
||||||
directory. ConfigKit keeps imported and overlay files within that root;
|
A complete discovery report can still list required inputs that are not bound;
|
||||||
Scriptorium does not widen it. Application path values inside those files still
|
a partial report can still be useful. Consumers own their policy for incomplete
|
||||||
resolve from the process working directory, so set that directory deliberately
|
findings and changed resources between invocations.
|
||||||
in the service manager. This configuration-source boundary is distinct from
|
|
||||||
the HTTP artifact root and does not constrain prompt or schema directories.
|
|
||||||
|
|
||||||
When upgrading existing definitions, review selected profile IDs.
|
## Sensitive Data And Retention
|
||||||
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro` were removed from the
|
|
||||||
selected catalog. Choose an available catalog profile, one of Promptkit's
|
|
||||||
maintained names, or a complete application-owned profile. New DeepSeek names
|
|
||||||
are not aliases for the removed ones; see the
|
|
||||||
[v0.10 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md).
|
|
||||||
|
|
||||||
Run Scriptorium under an identity that can:
|
Artifacts, prompt messages, prepared content, native run reports, metadata,
|
||||||
|
diagnostics, and redirected streams are caller-owned potentially sensitive data.
|
||||||
|
The separate CLI report contains the full returned result, not metadata alone.
|
||||||
|
Control access, retention, encryption, backup, and deletion accordingly.
|
||||||
|
Framework effective/explanation views apply native classified-field redaction,
|
||||||
|
including history, but do not detect arbitrary secrets. Other content-bearing
|
||||||
|
reports are not automatically made safe for publication.
|
||||||
|
|
||||||
- read only the prompt, profile, schema, and allowed input-artifact paths it
|
Keep main output and report destinations separate. Delivery is nontransactional:
|
||||||
needs;
|
one destination or partial bytes can remain after failure. An existing report
|
||||||
- read the required credential environment variables without writing them to
|
can remain on a resultless error; check status and report identity, not just file
|
||||||
files or logs; and
|
existence. A shell can truncate a redirected destination before the child starts.
|
||||||
- write only caller-selected output locations when CLI output files are used.
|
Omit quiet if main stdout must be captured; the separate report effect remains
|
||||||
|
independent. Exact delivery behavior belongs to [CLI results](cli.md#results-and-separate-reports).
|
||||||
|
|
||||||
Do not make the HTTP artifact directory writable by untrusted users. The HTTP
|
HTTP's optional [execution report](api.md#execution-report) remains a distinct
|
||||||
artifact containment behavior is lexical and the operating system follows
|
terminal-observation projection. Protect its identifiers and any response data.
|
||||||
symlinks; account for that when choosing ownership and mount boundaries. See
|
It increases encoded response size and remains subject to the configured limit.
|
||||||
the [HTTP API reference](api.md) for the externally observable behavior.
|
|
||||||
|
|
||||||
## Supply Credentials And Protect Runtime Data
|
## HTTP Deployment And Shutdown
|
||||||
|
|
||||||
Set secret values in the process environment and configure only their
|
The service has no built-in authentication/authorization. Deploy on a trusted
|
||||||
environment-variable names. Do not put raw keys in configuration, prompt or
|
network or behind appropriate authenticated proxy/gateway controls. Use a narrow,
|
||||||
profile files, process arguments, HTTP payloads, captured command lines, or
|
dedicated artifact root with controlled ownership and permissions when accepting
|
||||||
debug dumps.
|
file inputs; this is lexical containment, not a symlink sandbox.
|
||||||
|
|
||||||
Treat stdout, stderr, prepared-run output, generated artifacts, and HTTP
|
Use a supervisor for cwd, environment, restart policy, and stream capture.
|
||||||
responses as potentially sensitive. Send service logs to a controlled collector
|
Startup information uses native Info reporting, not stdout banners.
|
||||||
and apply the same retention and access rules as for model input and output.
|
Interrupt/SIGTERM cancels the invocation and closes the listener and active
|
||||||
|
connections. Canceled shutdown is nonzero operational termination. There is no
|
||||||
|
graceful-drain deadline or promise that context-ignoring work has finished;
|
||||||
|
supervisors own forced termination when necessary.
|
||||||
|
|
||||||
## Run A Normal Workflow
|
## Capacity, Limits, And Recovery
|
||||||
|
|
||||||
Before changing production inputs, profiles, or schemas:
|
One server engine shares backend admission/queue state across concurrent requests.
|
||||||
|
That state is transient operational coordination, not a durable workflow or
|
||||||
|
queue of resumable runs. HTTP capacity exhaustion retains its
|
||||||
|
[API outcome](api.md); callers decide whether another model call is safe.
|
||||||
|
|
||||||
1. use `config validate`, `config show`, or `config sources` to check the
|
Plan for input/output sizes, schema complexity, provider latency, retries, and
|
||||||
application configuration and its selected sources without constructing an
|
repair costs. Native transient attempts and repair generations can add calls and
|
||||||
engine; this does not verify prompt files, provider access, or credentials;
|
waiting; engine defaults and per-request overrides belong to
|
||||||
2. confirm the deployed configuration selects the intended sources and model
|
[configuration](config.md) and the [CLI](cli.md)/[HTTP](api.md) contracts.
|
||||||
credentials;
|
Whole-operation budgets are distinct from per-attempt generation timeouts.
|
||||||
3. use [`render`](cli.md) with the same request inputs and variables to confirm
|
They remain cooperative and do not include configuration/setup or delivery.
|
||||||
preparation without a model call;
|
|
||||||
4. use [`run`](cli.md) for generation; and
|
|
||||||
5. retain or discard validation-failed output according to the caller's
|
|
||||||
policy.
|
|
||||||
|
|
||||||
Inspection output can include configuration paths, names, and ordinary backend
|
Before increasing HTTP byte limits, measure representative requests/artifacts/
|
||||||
parameters. `config explain --path` uses JSON Pointer paths and can show
|
responses, confirm memory/network/provider capacity, retain authentication and
|
||||||
displaced historical values as well as the final value. Protect both the
|
upstream request controls, and test a representative workload. Do not widen the
|
||||||
selected paths and the output, especially when backend parameters contain
|
artifact root just to make an arbitrary host path accessible.
|
||||||
sensitive identifiers; ConfigKit does not infer arbitrary secrets in those
|
|
||||||
parameters. Apply
|
|
||||||
access and retention controls; the application stores only API-key environment
|
|
||||||
reference names, not the resolved credential bytes.
|
|
||||||
|
|
||||||
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
For failures, capture diagnostics without publishing sensitive data. Verify
|
||||||
copyable preflight example. The CLI reference owns its complete invocation and
|
selected configuration, resource identity, readable inputs, profile/credentials,
|
||||||
exit semantics.
|
and schema deployment. Use native prepared preview to isolate pre-generation
|
||||||
|
problems. A completed content-validation failure is distinct from an operational
|
||||||
|
failure to validate; consumers choose whether failed content is usable.
|
||||||
|
Correct the cause, then issue a new request only when another provider call and
|
||||||
|
its cost are acceptable.
|
||||||
|
|
||||||
## Expose The HTTP Service
|
There is no durable run store, archive, checkpoint, or resume mechanism.
|
||||||
|
Cleanup concerns caller-owned files/logs only. Rotate/delete them under the
|
||||||
The HTTP service has no built-in authentication or authorization. Place it on a
|
deployment's normal retention policy; recovery starts from a new request.
|
||||||
trusted network or behind an authenticated reverse proxy, API gateway, or
|
|
||||||
equivalent access control. Restrict who can reach it and who can read the
|
|
||||||
artifact root.
|
|
||||||
|
|
||||||
Use a service manager or supervisor appropriate to the deployment to manage
|
|
||||||
process lifetime, restart policy, log capture, and environment injection. The
|
|
||||||
[HTTP API reference](api.md) owns client request shapes, status behavior, and
|
|
||||||
artifact-access outcomes.
|
|
||||||
|
|
||||||
## Plan Capacity And Limits
|
|
||||||
|
|
||||||
Capacity is primarily determined by concurrent model calls, input and output
|
|
||||||
sizes, schema complexity, provider latency, and network behavior. Size limits
|
|
||||||
protect request bodies, HTTP file artifacts, and encoded responses; configure
|
|
||||||
them through the [configuration reference](config.md) and rely on the
|
|
||||||
[HTTP API reference](api.md) for their response effects.
|
|
||||||
|
|
||||||
Configured backend concurrency and queue capacity are enforced per constructed
|
|
||||||
Promptkit engine. A `serve` process constructs one engine for its handler, so
|
|
||||||
concurrent HTTP requests share that transient admission state. Scriptorium does
|
|
||||||
not retain workflow state: capacity is neither durable nor a queue of resumable
|
|
||||||
runs. When admission is exhausted, HTTP returns `503 capacity_exceeded` without
|
|
||||||
retry timing; callers choose any retry policy that is safe for another model
|
|
||||||
call.
|
|
||||||
|
|
||||||
Promptkit's built-in client now allows two additional attempts for eligible
|
|
||||||
transient provider statuses by default. Account for added calls, latency, and
|
|
||||||
cost when planning capacity. Each repair generation has its own transient
|
|
||||||
budget, separate from the structural repair count. Configure the engine budget
|
|
||||||
with [`transient_retries`](config.md); `run` and `render` accept a request
|
|
||||||
override described in the [CLI contract](cli.md), and HTTP callers can select
|
|
||||||
one through the [API contract](api.md). Omission inherits the engine
|
|
||||||
setting and then Promptkit's default, while explicit zero disables additional
|
|
||||||
attempts. Existing generation timeouts apply
|
|
||||||
per attempt, while the caller context covers the complete operation. Provider
|
|
||||||
`Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the
|
|
||||||
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
|
|
||||||
for details.
|
|
||||||
|
|
||||||
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must
|
|
||||||
be bounded. The existing generation timeout applies afresh to each attempt and
|
|
||||||
does not cap retry waits or the complete invocation. The whole-run interval
|
|
||||||
covers the engine call, including capacity waiting and repairs as supported by
|
|
||||||
context cancellation; it excludes parsing, engine setup, and output writes.
|
|
||||||
HTTP callers can use [`run_timeout_seconds`](api.md) to shorten their request
|
|
||||||
context for the same engine interval. The API distinguishes an expired
|
|
||||||
execution deadline from caller cancellation and from a provider-attempt
|
|
||||||
timeout. A canceled capacity waiter releases its Promptkit admission state.
|
|
||||||
|
|
||||||
Before increasing a limit:
|
|
||||||
|
|
||||||
1. measure representative input, generated-output, and optional raw-output
|
|
||||||
sizes;
|
|
||||||
2. confirm memory, network, and upstream-provider capacity;
|
|
||||||
3. retain an upstream request-size and authentication boundary; and
|
|
||||||
4. test the intended workload in a non-production environment.
|
|
||||||
|
|
||||||
For large local inputs, prefer a controlled file-artifact directory over
|
|
||||||
placing arbitrary paths on the service host. Avoid disabling a limit unless an
|
|
||||||
equivalent trusted control exists elsewhere.
|
|
||||||
|
|
||||||
## Diagnose And Recover
|
|
||||||
|
|
||||||
### Preparation Or Configuration Failure
|
|
||||||
|
|
||||||
Capture the CLI diagnostic or HTTP error response, then verify the selected
|
|
||||||
configuration, prompt ID, profile selection, source readability, and input
|
|
||||||
mapping. Use `render` with the same request when it is unclear whether failure
|
|
||||||
occurs before model execution. Consult the [CLI reference](cli.md), the
|
|
||||||
[configuration reference](config.md), and the [HTTP API reference](api.md) for
|
|
||||||
the exact interface contract.
|
|
||||||
|
|
||||||
### Credential Or Provider Failure
|
|
||||||
|
|
||||||
Confirm that the process environment contains the configured credential name
|
|
||||||
without printing the secret. Check endpoint reachability and provider health
|
|
||||||
from the process network. If preparation succeeds but generation fails, inspect
|
|
||||||
the selected model settings in prepared output and the service's controlled
|
|
||||||
logs. Correct the deployment or provider issue, then submit a new request.
|
|
||||||
|
|
||||||
### Artifact Or Permission Failure
|
|
||||||
|
|
||||||
Verify that the process can read the intended local input. For HTTP file
|
|
||||||
artifacts, verify the deployment's artifact root, ownership, path layout, and
|
|
||||||
file size. Do not widen filesystem permissions or the allowed root merely to
|
|
||||||
make an arbitrary path work; move or copy the required artifact into the
|
|
||||||
controlled location instead.
|
|
||||||
|
|
||||||
### Validation Failure
|
|
||||||
|
|
||||||
A generated-content validation failure is distinct from a runtime failure.
|
|
||||||
CLI `run` reports the validation result and error count in its success summary;
|
|
||||||
it does not print the individual validation messages. For HTTP, inspect the
|
|
||||||
validation object in the response according to the [HTTP API reference](api.md).
|
|
||||||
|
|
||||||
Use rendered input and generated output to determine whether prompt instructions,
|
|
||||||
the selected model, or the schema needs correction. If schema loading or
|
|
||||||
compilation itself fails, correct the source deployment or schema document
|
|
||||||
before rerunning.
|
|
||||||
|
|
||||||
### HTTP Limit Or Request Failure
|
|
||||||
|
|
||||||
Compare the request, artifact, or expected response size with the deployed
|
|
||||||
configuration, and validate the request against the [HTTP API reference](api.md).
|
|
||||||
Reduce the payload, use an appropriate controlled artifact source, omit
|
|
||||||
unneeded raw output, or adjust the deployment limit after capacity review.
|
|
||||||
|
|
||||||
## Cleanup And Reruns
|
|
||||||
|
|
||||||
Because no run state is retained, cleanup concerns caller-owned output files,
|
|
||||||
logs, and artifacts only. Remove or rotate them using the deployment's normal
|
|
||||||
retention policy. After a correction, rerun the request from the beginning;
|
|
||||||
there is no safe resume point.
|
|
||||||
|
|||||||
@@ -5,23 +5,22 @@
|
|||||||
Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
|
Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
|
||||||
`docs/policy/agents.md`, `docs/policy/documentation.md`,
|
`docs/policy/agents.md`, `docs/policy/documentation.md`,
|
||||||
`docs/policy/architecture.md`, `docs/policy/testing.md`,
|
`docs/policy/architecture.md`, `docs/policy/testing.md`,
|
||||||
`docs/policy/release.md`, `AGENTS.md`, and the
|
`docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section
|
||||||
Policy Reading Guide section of `docs/development.md`, adapted for this
|
of `docs/development.md`, adapted for this repository.
|
||||||
repository.
|
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||||
|
|
||||||
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
|
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
|
||||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
|
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
|
||||||
|
|
||||||
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
|
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
|
||||||
|
|
||||||
## Promptkit
|
## PromptKit
|
||||||
|
|
||||||
Selected module: `gitea.maximumdirect.net/eric/promptkit` at `v0.11.2`.
|
Selected module: `go.maximumdirect.net/promptkit` at `v0.23.3`.
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
@@ -29,14 +28,14 @@ SPDX-License-Identifier: LGPL-3.0-or-later
|
|||||||
|
|
||||||
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
||||||
[GPL 3.0](licenses/GPL-3.0.txt) |
|
[GPL 3.0](licenses/GPL-3.0.txt) |
|
||||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/COPYRIGHT) |
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/COPYRIGHT) |
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/LICENSE).
|
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/LICENSE).
|
||||||
|
|
||||||
[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2).
|
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f).
|
||||||
|
|
||||||
## ConfigKit
|
## ConfigKit
|
||||||
|
|
||||||
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.4.2`.
|
Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
@@ -44,87 +43,125 @@ SPDX-License-Identifier: LGPL-3.0-or-later
|
|||||||
|
|
||||||
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
||||||
[GPL 3.0](licenses/GPL-3.0.txt) |
|
[GPL 3.0](licenses/GPL-3.0.txt) |
|
||||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/COPYRIGHT) |
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/LICENSE).
|
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
|
||||||
|
|
||||||
[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f).
|
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
|
||||||
|
|
||||||
## Promptkit OpenRouter Catalog
|
## CommandKit
|
||||||
|
|
||||||
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2` at `v2.20260926.0`.
|
Selected module: `go.maximumdirect.net/commandkit` at `v0.7.0`.
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: MIT
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
License and notices: [MIT](licenses/MIT.txt) |
|
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
||||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/COPYRIGHT) |
|
[GPL 3.0](licenses/GPL-3.0.txt) |
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/LICENSE).
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/COPYRIGHT) |
|
||||||
|
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/LICENSE).
|
||||||
|
|
||||||
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3).
|
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4).
|
||||||
|
|
||||||
## Promptkit Rakestrawhome Catalog
|
## CommandKit ckconfig
|
||||||
|
|
||||||
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2` at `v2.20260926.0`.
|
Selected module: `go.maximumdirect.net/ckconfig` at `v0.9.0`.
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: MIT
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
License and notices: [MIT](licenses/MIT.txt) |
|
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
||||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/COPYRIGHT) |
|
[GPL 3.0](licenses/GPL-3.0.txt) |
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/LICENSE).
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/COPYRIGHT) |
|
||||||
|
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/LICENSE).
|
||||||
|
|
||||||
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596).
|
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig).
|
||||||
|
|
||||||
## jsonschema/v6
|
## CommandKit ckprompt
|
||||||
|
|
||||||
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2`.
|
Selected module: `go.maximumdirect.net/ckprompt` at `v0.10.0`.
|
||||||
|
|
||||||
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
|
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
||||||
|
[GPL 3.0](licenses/GPL-3.0.txt) |
|
||||||
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt/COPYRIGHT) |
|
||||||
|
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt/LICENSE).
|
||||||
|
|
||||||
|
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt).
|
||||||
|
|
||||||
|
## Cobra
|
||||||
|
|
||||||
|
Selected module: `github.com/spf13/cobra` at `v1.10.2` (transitive dependency).
|
||||||
|
|
||||||
|
Copyright 2013-2023 The Cobra Authors
|
||||||
|
|
||||||
SPDX-License-Identifier: Apache-2.0
|
SPDX-License-Identifier: Apache-2.0
|
||||||
|
|
||||||
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
|
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
|
||||||
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE).
|
[LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
|
||||||
|
|
||||||
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71).
|
[Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
|
||||||
|
|
||||||
## golang.org/x/text
|
## pflag
|
||||||
|
|
||||||
Selected module: `golang.org/x/text` at `v0.14.0`.
|
Selected module: `github.com/spf13/pflag` at `v1.1.0` (transitive dependency).
|
||||||
|
|
||||||
Copyright (c) 2009 The Go Authors. All rights reserved.
|
Copyright (c) 2012 Alex Ogier. All rights reserved.
|
||||||
|
|
||||||
|
Copyright (c) 2012 The Go Authors. All rights reserved.
|
||||||
|
|
||||||
SPDX-License-Identifier: BSD-3-Clause
|
SPDX-License-Identifier: BSD-3-Clause
|
||||||
|
|
||||||
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
|
License and notices: [BSD 3-Clause](licenses/pflag-BSD-3-Clause.txt) |
|
||||||
[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE).
|
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
|
||||||
|
|
||||||
[Source](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353).
|
[Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).
|
||||||
|
|
||||||
## gopkg.in/yaml.v3
|
## mousetrap
|
||||||
|
|
||||||
Selected module: `gopkg.in/yaml.v3` at `v3.0.1`.
|
Selected module: `github.com/inconshreveable/mousetrap` at `v1.1.0` (Windows transitive dependency).
|
||||||
|
|
||||||
Copyright (c) 2006-2010 Kirill Simonov
|
Copyright 2022 Alan Shreve (@inconshreveable)
|
||||||
|
|
||||||
Copyright (c) 2006-2011 Kirill Simonov
|
SPDX-License-Identifier: Apache-2.0
|
||||||
|
|
||||||
Copyright (c) 2011-2019 Canonical Ltd
|
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
|
||||||
|
[LICENSE](https://github.com/inconshreveable/mousetrap/blob/4e8053ee7ef85a6bd26368364a6d27f1641c1d21/LICENSE).
|
||||||
|
|
||||||
Copyright 2011-2016 Canonical Ltd.
|
[Source](https://github.com/inconshreveable/mousetrap/tree/4e8053ee7ef85a6bd26368364a6d27f1641c1d21).
|
||||||
|
|
||||||
SPDX-License-Identifier: MIT AND Apache-2.0
|
## jsonschema/v6
|
||||||
|
|
||||||
License and notices: [MIT](licenses/MIT.txt) |
|
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
|
||||||
[Apache 2.0](licenses/Apache-2.0.txt) |
|
|
||||||
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
|
|
||||||
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
|
|
||||||
|
|
||||||
[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
|
SPDX-License-Identifier: Apache-2.0
|
||||||
|
|
||||||
|
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
|
||||||
|
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
|
||||||
|
|
||||||
|
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
|
||||||
|
|
||||||
|
## golang.org/x/text
|
||||||
|
|
||||||
|
Selected module: `golang.org/x/text` at `v0.44.0`.
|
||||||
|
|
||||||
|
Copyright 2009 The Go Authors.
|
||||||
|
|
||||||
|
SPDX-License-Identifier: BSD-3-Clause
|
||||||
|
|
||||||
|
License and notices: [BSD 3-Clause](licenses/go-x-text-BSD-3-Clause.txt) |
|
||||||
|
[LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
|
||||||
|
[PATENTS](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
|
||||||
|
|
||||||
|
[Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
|
||||||
|
|
||||||
## go.yaml.in/yaml/v4
|
## go.yaml.in/yaml/v4
|
||||||
|
|
||||||
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
|
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
|
||||||
|
|
||||||
Copyright 2006-2010 Kirill Simonov
|
Copyright 2006-2010 Kirill Simonov
|
||||||
|
|
||||||
@@ -136,7 +173,7 @@ SPDX-License-Identifier: MIT AND Apache-2.0
|
|||||||
|
|
||||||
License and notices: [MIT](licenses/MIT.txt) |
|
License and notices: [MIT](licenses/MIT.txt) |
|
||||||
[Apache 2.0](licenses/Apache-2.0.txt) |
|
[Apache 2.0](licenses/Apache-2.0.txt) |
|
||||||
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
|
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
|
||||||
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
|
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
|
||||||
|
|
||||||
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
|
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
|
||||||
|
|||||||
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
|
**Base Policy Version:** 1.3
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
|
|||||||
@@ -2,9 +2,9 @@
|
|||||||
|
|
||||||
**Base Policy Version:** 1.3
|
**Base Policy Version:** 1.3
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-20
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md
|
||||||
|
|
||||||
## Purpose And Ownership
|
## Purpose And Ownership
|
||||||
|
|
||||||
@@ -39,8 +39,8 @@ Do not promote incidental implementation choices into architectural invariants.
|
|||||||
|
|
||||||
## Scriptorium's Purpose And System Shape
|
## Scriptorium's Purpose And System Shape
|
||||||
|
|
||||||
Scriptorium is an executable application with CLI `run`, `render`,
|
Scriptorium is an executable application with CLI `run`, native `promptkit`
|
||||||
`inspect`, and `config` command families and an HTTP service started by
|
and `config` families, and an HTTP service started by
|
||||||
`serve`. It offers simple, request-independent execution of predefined
|
`serve`. It offers simple, request-independent execution of predefined
|
||||||
prompts, not a reusable Scriptorium root Go API or a workflow framework.
|
prompts, not a reusable Scriptorium root Go API or a workflow framework.
|
||||||
The [internal overview](../internal/overview.md) owns the concrete package
|
The [internal overview](../internal/overview.md) owns the concrete package
|
||||||
@@ -50,22 +50,40 @@ inventory; [adapter internals](../internal/adapters.md) and
|
|||||||
## Framework And Application Boundaries
|
## Framework And Application Boundaries
|
||||||
|
|
||||||
Scriptorium consumes
|
Scriptorium consumes
|
||||||
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||||
through its supported public root package. Promptkit owns prompt execution,
|
through its supported public root package. Promptkit owns prompt execution,
|
||||||
preparation, prompt and profile formats, built-in profiles, model-client
|
preparation, prompt and profile formats, built-in profiles, model-client
|
||||||
behavior, validation, and framework defaults. Scriptorium owns application
|
behavior, validation, inspection semantics, and framework defaults. Scriptorium
|
||||||
configuration, executable CLI and HTTP adapters, prepared-run and
|
owns the application domain, executable CLI and HTTP adapters, process behavior,
|
||||||
definition-inspection presentation, process behavior, and HTTP deployment
|
and HTTP deployment policy. It interprets resolved configuration and uses
|
||||||
policy. The [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
PromptKit's supported APIs and results to satisfy user requests. The [format
|
||||||
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
|
reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
|
and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
|
||||||
remain Promptkit's contracts.
|
remain Promptkit's contracts.
|
||||||
|
|
||||||
Scriptorium uses ConfigKit v0.4.2 for strict application YAML decoding,
|
ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
|
||||||
resolution, and validation flow. Scriptorium retains its application schema,
|
fully resolved configuration handoff. Scriptorium supplies application schema
|
||||||
defaults, normalization, validation rules, source selection, and CLI override
|
and domain callbacks through ConfigKit's supported extension points and consumes
|
||||||
mapping. ConfigKit does not own Promptkit framework sources or HTTP artifact
|
the completed result without redefining effective configuration. PromptKit's
|
||||||
containment. The [configuration contract](../config.md) owns externally
|
configuration is also resolved through ConfigKit, with PromptKit supplying its
|
||||||
observable configuration behavior.
|
domain schema and rules. The [configuration contract](../config.md) owns
|
||||||
|
externally observable application behavior; PromptKit owns framework formats.
|
||||||
|
|
||||||
|
As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
|
||||||
|
Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to
|
||||||
|
neutrally expose upstream features and semantics. CommandKit owns shared command,
|
||||||
|
parsing, presentation, and outcome mechanics; application commands and effects
|
||||||
|
remain local. Standard configuration inspection uses native adapters without
|
||||||
|
custom effective documents or evidence reconciliation. This decision complements
|
||||||
|
ADRs 0004 and 0005; the completed
|
||||||
|
[adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md)
|
||||||
|
remains in Git history.
|
||||||
|
|
||||||
|
The CLI exposes Promptkit's captured framework configuration inspection. Its
|
||||||
|
`show` and `explain` reports use Promptkit's native redaction for classified
|
||||||
|
credential-shaped fields, including historical values. This scoped behavior is
|
||||||
|
not a general-purpose filter for arbitrary sensitive content and does not
|
||||||
|
extend to application configuration or existing prompt/profile inspection.
|
||||||
|
|
||||||
Application code may import Promptkit's public root package, but not its
|
Application code may import Promptkit's public root package, but not its
|
||||||
`internal` packages or catalog modules. It must not recreate the removed
|
`internal` packages or catalog modules. It must not recreate the removed
|
||||||
|
|||||||
@@ -1,10 +1,10 @@
|
|||||||
# Documentation Policy
|
# Documentation Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.11
|
**Base Policy Version:** 1.12
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
@@ -87,8 +87,8 @@ secret values.
|
|||||||
| Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
|
| Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
|
||||||
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
|
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
|
||||||
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
|
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
|
||||||
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
|
| Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
|
||||||
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
|
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
|
||||||
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
|
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
|
||||||
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
|
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
|
||||||
|
|
||||||
@@ -154,8 +154,15 @@ Use sequentially numbered ADR filenames such as
|
|||||||
|
|
||||||
Treat the decision content of an accepted ADR as immutable. When a decision
|
Treat the decision content of an accepted ADR as immutable. When a decision
|
||||||
changes, create a new ADR and update the earlier ADR's status to superseded.
|
changes, create a new ADR and update the earlier ADR's status to superseded.
|
||||||
Rejected architectural alternatives belong in the ADR; rejected product ideas
|
|
||||||
belong in the roadmap.
|
ADRs should be reserved for major architectural decisions, such as ownership
|
||||||
|
boundaries, large-scale architectural features, or invariants that rise to
|
||||||
|
the level of architectural significance. Routine choices, implementation
|
||||||
|
decisions, and rejected suggestions do not warrant an ADR unless they
|
||||||
|
otherwise represent a significant architectural decision.
|
||||||
|
|
||||||
|
Roadmaps should preserve plausible future work, not rejected product
|
||||||
|
ideas.
|
||||||
|
|
||||||
## Maintenance
|
## Maintenance
|
||||||
|
|
||||||
|
|||||||
@@ -2,9 +2,9 @@
|
|||||||
|
|
||||||
**Base Policy Version:** 1.0
|
**Base Policy Version:** 1.0
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md
|
||||||
|
|
||||||
## Origin And Local Authority
|
## Origin And Local Authority
|
||||||
|
|
||||||
|
|||||||
@@ -1,10 +1,10 @@
|
|||||||
# Open Source Licensing And Attribution Policy
|
# Open Source Licensing And Attribution Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.8
|
**Base Policy Version:** 1.9
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md
|
||||||
|
|
||||||
## Purpose And Scope
|
## Purpose And Scope
|
||||||
|
|
||||||
@@ -64,6 +64,9 @@ individual packages.
|
|||||||
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
|
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
|
||||||
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
|
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
|
||||||
to create the project’s root `COPYRIGHT` file.
|
to create the project’s root `COPYRIGHT` file.
|
||||||
|
Use the COPYRIGHT examples exactly as provided, except for placeholder
|
||||||
|
substitutions and changes expressly required or authorized by this policy or
|
||||||
|
the author.
|
||||||
Use verified project names, contribution years, and copyright holders.
|
Use verified project names, contribution years, and copyright holders.
|
||||||
For another selected license, adapt the grant, SPDX expression, disclaimer, and
|
For another selected license, adapt the grant, SPDX expression, disclaimer, and
|
||||||
text references together to reflect the author's selected grant.
|
text references together to reflect the author's selected grant.
|
||||||
|
|||||||
@@ -1,10 +1,10 @@
|
|||||||
# Release Policy
|
# Release Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.4
|
**Base Policy Version:** 1.7
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
@@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
|
|||||||
intended source revision under a fresh version. Releases should require little
|
intended source revision under a fresh version. Releases should require little
|
||||||
routine intervention, avoid repeated work, and preserve published contents.
|
routine intervention, avoid repeated work, and preserve published contents.
|
||||||
|
|
||||||
|
Adopt stronger verification or reproducibility requirements through an explicit
|
||||||
|
project-specific decision justified by the intended audience and support needs.
|
||||||
|
|
||||||
The repository-specific commands belong in `docs/release.md`. Historical release
|
The repository-specific commands belong in `docs/release.md`. Historical release
|
||||||
summaries belong in `docs/releases/`. The procedure must agree with the adopted
|
summaries belong in `docs/releases/`. The procedure must agree with the adopted
|
||||||
policy and link to it rather than introduce additional release requirements.
|
policy and link to it rather than introduce additional release requirements.
|
||||||
@@ -59,9 +62,14 @@ requires a deliberate update to the policy and procedure where needed.
|
|||||||
For releases at or after `v1.0.0`:
|
For releases at or after `v1.0.0`:
|
||||||
|
|
||||||
- a major release may make intentional incompatible changes;
|
- a major release may make intentional incompatible changes;
|
||||||
- a minor release may add backward-compatible behavior; and
|
- a minor release may add backward-compatible behavior or raise the Go consumer
|
||||||
|
minimum as described below; and
|
||||||
- a patch release may make backward-compatible fixes.
|
- a patch release may make backward-compatible fixes.
|
||||||
|
|
||||||
|
In this context, "backward-compatible" means only that pre-existing, valid
|
||||||
|
configurations will continue to work following the relase. Behavior need not
|
||||||
|
remain strictly identical.
|
||||||
|
|
||||||
Before `v1.0.0`, a minor release may change a documented public, operational,
|
Before `v1.0.0`, a minor release may change a documented public, operational,
|
||||||
configuration, data, integration, or compatibility contract when the release
|
configuration, data, integration, or compatibility contract when the release
|
||||||
note explains the impact and required consumer action. A patch release must
|
note explains the impact and required consumer action. A patch release must
|
||||||
@@ -71,6 +79,36 @@ Additional compatibility promises and deliberate exceptions belong in the
|
|||||||
adopted policy or canonical contract documentation. Release notes explain
|
adopted policy or canonical contract documentation. Release notes explain
|
||||||
changes; they do not redefine current compatibility contracts.
|
changes; they do not redefine current compatibility contracts.
|
||||||
|
|
||||||
|
## Consumer Minimum And Release Toolchain
|
||||||
|
|
||||||
|
Distinguish the minimum toolchain supported for consumers from the toolchain
|
||||||
|
maintainers use to build and validate a release. Record the consumer minimum in
|
||||||
|
the language's standard metadata and explain its support meaning in canonical
|
||||||
|
documentation. Define the selected release toolchain and its setup commands in
|
||||||
|
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
|
||||||
|
choices.
|
||||||
|
|
||||||
|
For Go repositories, normally declare the initial stable release of the selected
|
||||||
|
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
|
||||||
|
when a dependency or an identified correctness fix requires it, and document
|
||||||
|
the reason.
|
||||||
|
|
||||||
|
For release-policy purposes, successful build and release validation on the
|
||||||
|
selected Go patch release are sufficient to presume support across that Go
|
||||||
|
series, subject to the declared consumer minimum and concrete evidence of
|
||||||
|
incompatibility. Investigate specific compatibility concerns as they arise.
|
||||||
|
|
||||||
|
Use the selected release toolchain for candidate validation and release builds,
|
||||||
|
including CI jobs performing those tasks. A newer validation patch version alone
|
||||||
|
leaves the consumer minimum unchanged.
|
||||||
|
|
||||||
|
A minor release may raise the Go consumer minimum, including from one Go series
|
||||||
|
to the next, both before and after `v1.0.0`. This is an explicit exception to the
|
||||||
|
backward-compatibility requirement for minor releases. Patch releases preserve
|
||||||
|
the consumer minimum. Explain an increase's impact and required consumer action
|
||||||
|
in the release note. Other incompatible changes remain subject to the versioning
|
||||||
|
rules above.
|
||||||
|
|
||||||
## Release Documentation And Preparation
|
## Release Documentation And Preparation
|
||||||
|
|
||||||
Every new release must include `docs/releases/<version>.md` in the tagged
|
Every new release must include `docs/releases/<version>.md` in the tagged
|
||||||
@@ -186,7 +224,8 @@ release without replacing its contents or reusing its version.
|
|||||||
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
|
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
|
||||||
identify:
|
identify:
|
||||||
|
|
||||||
1. prerequisites, primary branch, and authoritative remote;
|
1. prerequisites, selected release toolchain, primary branch, and authoritative
|
||||||
|
remote;
|
||||||
2. version and release-note preparation;
|
2. version and release-note preparation;
|
||||||
3. one publication command with its selected local checks and automated guards;
|
3. one publication command with its selected local checks and automated guards;
|
||||||
4. declared deliverables, required build targets, and automation responsibilities;
|
4. declared deliverables, required build targets, and automation responsibilities;
|
||||||
|
|||||||
@@ -2,9 +2,9 @@
|
|||||||
|
|
||||||
**Base Policy Version:** 1.3
|
**Base Policy Version:** 1.3
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-19
|
||||||
|
|
||||||
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
@@ -178,12 +178,15 @@ Give each layer its distinct responsibility and keep expectation updates localiz
|
|||||||
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
|
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
|
||||||
import and overlay composition, provenance, and inspection renderers.
|
import and overlay composition, provenance, and inspection renderers.
|
||||||
- CLI tests own argument mapping, streams, output, exit behavior, and
|
- CLI tests own argument mapping, streams, output, exit behavior, and
|
||||||
representative run, render, inspect, serve, and config workflows.
|
representative native run, PromptKit resource/requirements/preview/smoke,
|
||||||
|
serve, and configuration comparison workflows.
|
||||||
- HTTP tests own DTO decoding, transport limits, status and error mapping,
|
- HTTP tests own DTO decoding, transport limits, status and error mapping,
|
||||||
restricted artifact reading, and representative server workflows.
|
restricted artifact reading, and representative server workflows.
|
||||||
- Formatting tests own prepared-run and definition-inspection text and JSON
|
- CommandKit and its integrations own standard parsing and presentation.
|
||||||
presentation. Architecture guards own dependency direction and removed
|
Scriptorium's integration tests protect native adoption, byte-preserving main
|
||||||
framework-package boundaries.
|
output, separate report effects, outcomes, and acquisition boundaries without
|
||||||
|
reproducing the upstream formatting matrix. Architecture guards own dependency
|
||||||
|
direction and removed framework-package boundaries.
|
||||||
- Promptkit owns framework parsing, orchestration, validation, profiles, and
|
- Promptkit owns framework parsing, orchestration, validation, profiles, and
|
||||||
model-client behavior. Scriptorium's definition and execution fixtures
|
model-client behavior. Scriptorium's definition and execution fixtures
|
||||||
protect adoption through its public adapter boundary without duplicating
|
protect adoption through its public adapter boundary without duplicating
|
||||||
|
|||||||
@@ -9,11 +9,31 @@ discoverability requirements.
|
|||||||
## Prepare The Candidate
|
## Prepare The Candidate
|
||||||
|
|
||||||
Use a POSIX shell, Git with a configured tagger identity and access to
|
Use a POSIX shell, Git with a configured tagger identity and access to
|
||||||
`origin`, and a Go toolchain compatible with `go.mod`. The native host must
|
`origin`, and the selected release toolchain, Go 1.27.4. The native host must
|
||||||
support Go's race detector and have its required C compiler. If Git is
|
support Go's race detector and have its required C compiler. If Git is
|
||||||
configured to sign tags, its signing tool and key must be available. Run from the
|
configured to sign tags, its signing tool and key must be available. Run from the
|
||||||
repository root. Provision the toolchain and module cache before offline
|
repository root. The [developer guide](development.md#baseline-validation)
|
||||||
validation; when dependencies are not cached:
|
explains the separate Go consumer minimum; selecting a release toolchain does
|
||||||
|
not raise that minimum.
|
||||||
|
|
||||||
|
Install Go 1.27.4 from the [official downloads](https://go.dev/dl/) or an
|
||||||
|
equivalent package source before validation. Set `release_go_root` to its
|
||||||
|
installation directory, replacing the illustrative path below, and select it
|
||||||
|
in the release shell:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
release_go_root=/path/to/go1.27.4
|
||||||
|
export PATH="$release_go_root/bin:$PATH"
|
||||||
|
export GOTOOLCHAIN=local
|
||||||
|
go version
|
||||||
|
```
|
||||||
|
|
||||||
|
The version output should identify `go1.27.4`. Keep this selection and the
|
||||||
|
hosted workflow's Go image in step when deliberately updating the release
|
||||||
|
toolchain. Ordinary contributor checks may use another compatible toolchain.
|
||||||
|
|
||||||
|
Provision the module cache before offline validation; when dependencies are
|
||||||
|
not cached:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
GOWORK=off go mod download
|
GOWORK=off go mod download
|
||||||
@@ -66,8 +86,9 @@ The source-boundary guards reject committed workspaces, vendor trees, and
|
|||||||
module replacements.
|
module replacements.
|
||||||
|
|
||||||
It then runs the complete suite once with the race detector and builds Linux
|
It then runs the complete suite once with the race detector and builds Linux
|
||||||
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and
|
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and linker flags
|
||||||
`-ldflags '-s -w'`. The native test run uses the host platform and enables cgo.
|
`-s -w -X main.version=<version> -X main.revision=<candidate-commit>`.
|
||||||
|
The native test run uses the host platform and enables cgo.
|
||||||
Validation disables workspaces, uses read-only module mode, and disables module
|
Validation disables workspaces, uses read-only module mode, and disables module
|
||||||
and toolchain downloads. Missing dependencies must be provisioned separately;
|
and toolchain downloads. Missing dependencies must be provisioned separately;
|
||||||
fix the environment and rerun the command. No persistent validation cache is
|
fix the environment and rerun the command. No persistent validation cache is
|
||||||
@@ -91,6 +112,8 @@ publishes:
|
|||||||
|
|
||||||
The matching checked-in note supplies the hosted release body. The workflow
|
The matching checked-in note supplies the hosted release body. The workflow
|
||||||
owns image selection, packaging, checksum generation, and upload configuration.
|
owns image selection, packaging, checksum generation, and upload configuration.
|
||||||
|
Its binaries receive the tag and source commit as the same version/revision
|
||||||
|
metadata used by local candidate builds.
|
||||||
Its upload step skips existing files and does not overwrite the release.
|
Its upload step skips existing files and does not overwrite the release.
|
||||||
Source-publication success does not attest to workflow success or asset
|
Source-publication success does not attest to workflow success or asset
|
||||||
availability.
|
availability.
|
||||||
|
|||||||
@@ -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
|
promptkit:
|
||||||
profile_dir: ./examples/profiles
|
configuration: ./examples/promptkit.yml
|
||||||
schema_dir: ./examples/schemas
|
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.
|
# Select from the repository root; application paths remain working-directory-relative.
|
||||||
configkit:
|
config:
|
||||||
imports:
|
imports:
|
||||||
- path: config-fragments/sources.yml
|
- path: config-fragments/sources.yml
|
||||||
- path: config-fragments/backend.yml
|
required: true
|
||||||
|
|
||||||
server:
|
server:
|
||||||
addr: :8080
|
addr: :8080
|
||||||
|
|||||||
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,22 +1,10 @@
|
|||||||
prompt_dir: ./examples/prompts
|
promptkit:
|
||||||
profile_dir: ./examples/profiles
|
configuration: ./examples/promptkit.yml
|
||||||
schema_dir: ./examples/schemas
|
schema_dir: ./examples/schemas
|
||||||
|
|
||||||
backends:
|
|
||||||
local-gpu:
|
|
||||||
endpoint: http://localhost:11434/v1
|
|
||||||
api_key_env: LOCAL_GPU_API_KEY
|
|
||||||
extra_params:
|
|
||||||
provider_option: enabled
|
|
||||||
concurrency_limit: 2
|
|
||||||
queue_capacity: 0
|
|
||||||
|
|
||||||
server:
|
server:
|
||||||
addr: 127.0.0.1:8080
|
addr: 127.0.0.1:8080
|
||||||
artifact_root: .
|
artifact_root: .
|
||||||
max_request_bytes: 16777216
|
max_request_bytes: 16777216
|
||||||
max_artifact_bytes: 16777216
|
max_artifact_bytes: 16777216
|
||||||
max_response_bytes: 16777216
|
max_response_bytes: 16777216
|
||||||
|
|
||||||
defaults:
|
|
||||||
render_format: text
|
|
||||||
|
|||||||
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
|
promptkit:
|
||||||
profile_dir: ./examples/profiles
|
configuration: ./examples/promptkit.yml
|
||||||
schema_dir: ./examples/schemas
|
schema_dir: ./examples/schemas
|
||||||
|
|
||||||
server:
|
server:
|
||||||
addr: :8080
|
addr: :8080
|
||||||
artifact_root: .
|
artifact_root: .
|
||||||
|
|
||||||
defaults:
|
|
||||||
render_format: text
|
|
||||||
|
|||||||
8
examples/definitions.yml
Normal file
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": {
|
"vars": {
|
||||||
"session_date": "2026-05-04"
|
"session_date": "2026-05-04"
|
||||||
},
|
},
|
||||||
"include_raw_output": false
|
"include_raw_output": false,
|
||||||
|
"include_execution_report": false
|
||||||
}
|
}
|
||||||
|
|||||||
6
examples/inheritance.yml
Normal file
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:
|
server:
|
||||||
addr: 127.0.0.1:8080
|
addr: 127.0.0.1:8080
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
id: local-fast
|
profiles:
|
||||||
|
- id: local-fast
|
||||||
endpoint: http://localhost:8000/v1
|
endpoint: http://localhost:8000/v1
|
||||||
model: gpt-4o-mini
|
model: gpt-4o-mini
|
||||||
temperature: 0.2
|
temperature: 0.2
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
id: local-gpu
|
profiles:
|
||||||
|
- id: local-gpu
|
||||||
backend: local-gpu
|
backend: local-gpu
|
||||||
model: local-model
|
model: local-model
|
||||||
reasoning_effort: low
|
reasoning_effort: low
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
id: local-quality
|
profiles:
|
||||||
|
- id: local-quality
|
||||||
endpoint: http://localhost:8000/v1
|
endpoint: http://localhost:8000/v1
|
||||||
model: gpt-4.1
|
model: gpt-4.1
|
||||||
temperature: 0.0
|
temperature: 0.0
|
||||||
|
|||||||
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,5 +1,5 @@
|
|||||||
id: dnd.session_recap
|
prompts:
|
||||||
version: "1.0.0"
|
- id: dnd.session_recap
|
||||||
default_profile: local-quality
|
default_profile: local-quality
|
||||||
description: Example D&D session recap prompt definition for demonstration only.
|
description: Example D&D session recap prompt definition for demonstration only.
|
||||||
inputs:
|
inputs:
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
id: generic.markdown_summary
|
prompts:
|
||||||
version: "1.0.0"
|
- id: generic.markdown_summary
|
||||||
default_profile: local-fast
|
default_profile: local-fast
|
||||||
description: Generic markdown summary from transcript and glossary.
|
description: Generic markdown summary from transcript and glossary.
|
||||||
inputs:
|
inputs:
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
id: generic.structured_events
|
prompts:
|
||||||
version: "1.0.0"
|
- id: generic.structured_events
|
||||||
default_profile: local-quality
|
default_profile: local-quality
|
||||||
description: Produce structured event JSON from a transcript.
|
description: Produce structured event JSON from a transcript.
|
||||||
inputs:
|
inputs:
|
||||||
|
|||||||
@@ -5,9 +5,8 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|||||||
|
|
||||||
cd "$repo_root"
|
cd "$repo_root"
|
||||||
|
|
||||||
go run ./cmd/scriptorium render \
|
go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
|
||||||
--config ./examples/config.yml \
|
--config ./examples/config.yml \
|
||||||
--prompt generic.markdown_summary \
|
--input-file transcript=./examples/fixtures/transcript.md \
|
||||||
--input transcript=./examples/fixtures/transcript.md \
|
--input-file glossary=./examples/fixtures/glossary.yml \
|
||||||
--input glossary=./examples/fixtures/glossary.yml \
|
|
||||||
--format text
|
--format text
|
||||||
|
|||||||
@@ -4,22 +4,18 @@ set -euo pipefail
|
|||||||
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||||
cd "$repo_root"
|
cd "$repo_root"
|
||||||
|
|
||||||
go run ./cmd/scriptorium render \
|
go run ./cmd/scriptorium promptkit show prepared generic.markdown_summary \
|
||||||
--config ./examples/config.full.yml \
|
--config ./examples/config.full.yml \
|
||||||
--prompt generic.markdown_summary \
|
|
||||||
--prompt-version 1.0.0 \
|
|
||||||
--profile local-gpu \
|
--profile local-gpu \
|
||||||
--session-id example-session \
|
--session-id example-session \
|
||||||
--reasoning-effort= \
|
--reasoning-effort= \
|
||||||
--input transcript=./examples/fixtures/transcript.md \
|
--input-file transcript=./examples/fixtures/transcript.md \
|
||||||
--input glossary=./examples/fixtures/glossary.yml
|
--input-file glossary=./examples/fixtures/glossary.yml
|
||||||
|
|
||||||
go run ./cmd/scriptorium inspect prompt \
|
go run ./cmd/scriptorium promptkit show prompt generic.markdown_summary \
|
||||||
--config ./examples/config.full.yml \
|
--config ./examples/config.full.yml \
|
||||||
--prompt generic.markdown_summary \
|
|
||||||
--format json
|
--format json
|
||||||
|
|
||||||
go run ./cmd/scriptorium inspect profile \
|
go run ./cmd/scriptorium promptkit show profile local-gpu \
|
||||||
--config ./examples/config.full.yml \
|
--config ./examples/config.full.yml \
|
||||||
--profile local-gpu \
|
|
||||||
--format json
|
--format json
|
||||||
|
|||||||
21
go.mod
21
go.mod
@@ -1,17 +1,20 @@
|
|||||||
module gitea.maximumdirect.net/eric/scriptorium
|
module gitea.maximumdirect.net/eric/scriptorium
|
||||||
|
|
||||||
go 1.25.5
|
go 1.27.0
|
||||||
|
|
||||||
require (
|
require (
|
||||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.2
|
go.maximumdirect.net/ckconfig v0.9.0
|
||||||
gitea.maximumdirect.net/eric/promptkit v0.11.2
|
go.maximumdirect.net/ckprompt v0.10.0
|
||||||
|
go.maximumdirect.net/commandkit v0.7.0
|
||||||
|
go.maximumdirect.net/configkit v1.2.1
|
||||||
|
go.maximumdirect.net/promptkit v0.23.3
|
||||||
|
go.yaml.in/yaml/v4 v4.0.0
|
||||||
)
|
)
|
||||||
|
|
||||||
require (
|
require (
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0 // indirect
|
github.com/inconshreveable/mousetrap v1.1.0 // indirect
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0 // indirect
|
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
|
||||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
|
github.com/spf13/cobra v1.10.2 // indirect
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
|
github.com/spf13/pflag v1.1.0 // indirect
|
||||||
golang.org/x/text v0.14.0 // indirect
|
golang.org/x/text v0.44.0 // indirect
|
||||||
gopkg.in/yaml.v3 v3.0.1 // indirect
|
|
||||||
)
|
)
|
||||||
|
|||||||
43
go.sum
43
go.sum
@@ -1,20 +1,29 @@
|
|||||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.2 h1:ZMxmv8pOnLtAx2hFTf8Z+pHKUbR89xErkBhwjr4yK24=
|
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
|
||||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.2/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit v0.11.2 h1:2RqI+KtflvSh7vLQaTAQCmMaFQscEA7EPwPazyvXRoY=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit v0.11.2/go.mod h1:onm/FBPUKQ8/NSPwTEk26Ut+dVX2iXcq8vEseB+g/0E=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0 h1:wdab+R+lgMZxzYwhbAuCrW7zdSQ1cW9ovBR6UzLmZR4=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260926.0/go.mod h1:a3VBbh9oaGXD6ruxhtwHj+AWW6DY/SSyby1QtMmYSUo=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0 h1:baCCIB6Ee5t0S4Zc++NTBIPcJEv5UPS6DlSrpZfykwg=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260926.0/go.mod h1:mtgD1E0SGm0e/I8Ffhz+AYX7GN7RKUWJXehNFIKHs4Y=
|
|
||||||
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
|
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
|
||||||
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
|
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
|
||||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
|
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
|
||||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
|
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
|
||||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
|
||||||
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
|
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
|
||||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
|
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
|
||||||
|
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
||||||
|
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
|
||||||
|
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
||||||
|
go.maximumdirect.net/ckconfig v0.9.0 h1:s9Ikga4wt4K1NpLCX9bLhm5vbcm1Fgqy9yk2lmO4Sss=
|
||||||
|
go.maximumdirect.net/ckconfig v0.9.0/go.mod h1:yGjFVr2UzjJjiwDdMwsKehuQfvvtv7rTEOIk5NQOY00=
|
||||||
|
go.maximumdirect.net/ckprompt v0.10.0 h1:t2UyWSke+bWH9aTDrw5/bteD+TO0y5LD0NWw0y2KniQ=
|
||||||
|
go.maximumdirect.net/ckprompt v0.10.0/go.mod h1:vx8lZnelASctQtyxY2yV4PuTZfLpE9EqDa+LPj3+SHM=
|
||||||
|
go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
|
||||||
|
go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
|
||||||
|
go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
|
||||||
|
go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
|
||||||
|
go.maximumdirect.net/promptkit v0.23.3 h1:bKbrkluwfgXUsm0e/mxz/TpV9b60yUtJLVUROLsM3VU=
|
||||||
|
go.maximumdirect.net/promptkit v0.23.3/go.mod h1:vPFg76VXcffP0JBFMS2WADCHwV5FYvO2O4bvIoiDlwc=
|
||||||
|
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
|
||||||
|
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
|
||||||
|
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
||||||
|
golang.org/x/text v0.44.0 h1:YItdp/mQNGnsmrgpcdA5yQ3bnRxCfo/Tj/iByGW9GGo=
|
||||||
|
golang.org/x/text v0.44.0/go.mod h1:S4FR1waQ9LbjQTls97SyRjDaUUVkaM+cXwwuG/G+MwY=
|
||||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
|
||||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
|
||||||
|
|||||||
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