Retire the legacy CLI and document native operator workflows

This commit is contained in:
2026-11-20 05:08:40 +00:00
parent 10387d4aea
commit bd7136ceeb
52 changed files with 846 additions and 7067 deletions

View File

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

View File

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

View File

@@ -1,117 +1,55 @@
# Source Internals
## Purpose
This document covers application acquisition and the restricted HTTP artifact
reader. [Configuration](../config.md) owns field/discovery/composition contracts;
the [PromptKit formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
own framework resources and execution semantics.
This document covers Scriptorium-owned source locations and the restricted HTTP
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
## Application Boundary And Engine Construction
## Application Source Locations
`internal/config.Load` selects an explicit File or the ordered native SearchConfig
presets and performs one ConfigKit load with imports, overlay selection, and
explicit overrides. It returns the actual Result with native inspection evidence.
Definition callbacks supply application defaults, record actual path/address
normalizations through ConfigKit, and validate retry/HTTP-size domains. Settings
conversion consumes completed values without another merge or normalization pass.
`internal/config` resolves the ordered `promptkit_sources` sequence and
`schema_dir` from application configuration and explicit CLI overrides. It
owns selector-shape validation, not framework file parsing. During engine
construction, `internal/adapter/cli` turns file selections into import-enabled
ConfigKit inputs and expands directory selections with
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
configuration underlays, one per selector. Directory inputs retain the
helper's strict-composition grouping; no selected source becomes an implicit
framework main. The shared Promptkit engine receives the selected schema
directory and retry setting, and the default OpenRouter bundle remains enabled.
The typed application PromptKit section selects acquisition only. In
`engine.go`, a nonempty resolved configuration path becomes an import-enabled
main Input; an empty path leaves Main nil. The schema base and retry default are
passed directly, retaining the bundled underlay. There is no source-list parser,
directory classification/expansion, or one-underlay-per-selector algorithm.
Promptkit uses ConfigKit to load and compose those framework inputs according
to Promptkit's own schema and format. Scriptorium does not parse or validate
Promptkit definitions. Promptkit owns definition selection and validation,
profile built-ins and overlays, schema resolution, ordinary file artifacts,
captured framework configuration inspection, and related error identities.
Framework imports resolve within the native source context. Message resources
are captured from their defining contexts at engine construction. Schema and
request-artifact acquisition retain their preparation-time behavior.
Independent collection checkouts are discovered by native file import globs,
not application traversal. New invocations reload normally; a server retains
its single engine until restart.
The [configuration reference](../config.md) owns Scriptorium's source-location
fields and precedence. Maintained files under `examples/` are application
inputs that use Promptkit's tagged formats.
## Application Configuration Boundary
`internal/config` contains the application-owned ConfigKit-native `Document`
definition. Its fresh defaults come from Scriptorium's existing default
constants; its resolver records only actual leaf-level trimming, path cleaning, and
render-format normalization. The validator reports selector-shape, retry,
size-limit, and format errors without mutating the document or exposing
rejected values. Application path values keep working-directory-relative
meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by PromptKit using
the same ConfigKit release under PromptKit's own schema and source contract.
The `Load` boundary selects an explicit file or constructs a native ConfigKit
search over the ordered implicit paths. Discovery exhaustion uses defaults;
a selected-file error stops loading. One ConfigKit load enables imports,
applies explicitly supplied application overrides after decoding and before
resolution and validation, and returns the document and its frozen inspection
records. `Settings` copies selectors in their resolved order into runtime
settings; it does not read files or apply another merge. 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.
Runtime conversion consumes the resolved application values through the
existing `Settings` path. Promptkit receives selected framework sources only
after application configuration has loaded and validated; its source merge,
definition validation, and captured inspection view remain framework-owned.
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. Application and
framework load errors and warnings use their respective native writers. 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 credentials. `inspect configuration` separately
constructs an engine and exposes Promptkit's captured framework view; only its
framework `show` and `explain` reports receive Promptkit's native,
credential-shaped redaction. Neither inspection family is a general-purpose
filter for arbitrary sensitive values.
Application-only inspection uses its completed result without framework
acquisition. Framework inspection exposes the native captured view separately.
Diagnostic decoration in the [CLI adapter](adapters.md) carries application
messages without combining evidence trees or effective documents. There is no
per-invocation engine/config cache or cross-invocation snapshot guarantee.
## Restricted HTTP Artifact Reader
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP
requests. The `serve` path injects it with
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for
inbound HTTP inputs.
The HTTP adapter implements `promptkit.ArtifactReader`; server construction
injects it through the public option. Ordinary CLI artifact loading remains
upstream-owned.
The reader:
The reader accepts inline content without a root. File references need a root;
relative paths resolve below it and absolute paths must be lexically contained.
Traversal outside is rejected and the configured file byte limit applies, with
zero unlimited. Reads preserve native artifact metadata and honor cancellation.
- accepts inline references without an artifact root;
- denies file references when no root is configured;
- resolves relative paths below the configured root;
- accepts absolute paths only when they are lexically within that root;
- rejects lexical traversal outside the root;
- applies the configured file byte limit, with zero meaning unlimited;
- preserves content type, body, size, hash, name, and URI metadata; and
- honors context cancellation.
Containment does not resolve symlinks. The OS may follow a symlink inside the
root to an outside target; this is not a filesystem sandbox or a defense against
privileged concurrent filesystem modification. Reader errors retain identity
through upstream artifact-load wrapping, enabling the existing HTTP mapping.
Containment is lexical and does not resolve symlinks. The operating system
follows symlinks after the check. The [HTTP API](../api.md) owns observable
request outcomes, and [operations](../operations.md) owns safe deployment
permissions and root selection.
Reader errors remain identifiable after Promptkit wraps them as artifact-load
failures, allowing the HTTP adapter to preserve Scriptorium status and error
codes.
## Verification And Change Recipe
Inspect:
- `internal/config/document_test.go`
- `internal/config/load_test.go`
- `internal/adapter/cli/run_test.go`
- `internal/adapter/http/artifact_reader_test.go`
- `internal/adapter/http/handler_test.go`
When changing an application source location or HTTP artifact policy:
1. preserve strict configuration precedence and the Promptkit public boundary;
2. keep containment and size policy in Scriptorium;
3. update focused configuration, reader, and handler tests;
4. update the [configuration](../config.md), [HTTP](../api.md), and
[operations](../operations.md) contracts as applicable; and
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.
The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
reader/handler tests own their respective boundaries; upstream owns exhaustive
source traversal, format parsing, ordinary artifacts, and inspection semantics.