Adapter Internals

Purpose

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.

External contracts are canonical in the CLI reference and HTTP API reference. Promptkit's public engine contract is described by its tagged Go consumer guide.

Components And Collaborators

cmd/scriptorium passes process arguments and streams to internal/adapter/cli.
internal/adapter/cli resolves settings through internal/config, constructs promptkit.Engine, maps CLI values to promptkit.RunRequest, and owns output files, summaries, and exit codes.
internal/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.

Wiring Flows

CLI

run calls promptkit.Engine.Run; render calls promptkit.Engine.Prepare. Both share request mapping for prompt ID/version and profile selection, optional file inputs, variables, and presence-aware execution overrides. Omitted framework settings remain zero values so Promptkit resolves its own defaults and definition-required inputs.

inspect prompt maps the selected ID and optional version to promptkit.Engine.InspectPrompt, then formats Scriptorium-owned inspection data. It constructs the same configuration-aware engine but does not perform preparation or generation.

inspect profile maps an explicit profile ID to Engine.InspectProfile and formats a safe application-owned effective profile view. It intentionally does not require prompt, schema, or artifact sources.

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.

All three CLI paths assemble the engine from the same resolved prompt, profile, and schema directories plus configured custom backends. Each backend is mapped to Promptkit's public Backend value and registered during engine construction, so one constructed server engine retains one immutable backend registry and its associated capacity state.

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.

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.

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

Inspect:

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:

identify the Scriptorium-owned external contract;
map through Promptkit public values without copying framework semantics;
add or update the narrow application-owned test;
update the canonical Scriptorium contract; and
coordinate and tag Promptkit first if a required public capability is genuinely absent.

Update source internals when application source locations or HTTP artifact containment changes.

4.2 KiB Raw Blame History