scriptorium/docs/internal/adapters.md

Adapter Internals

Purpose

Adapters translate external inputs into public engine requests and translate public results or errors back to their interface. They own IO and presentation mechanics; use-case decisions remain behind the root scriptorium facade.

External contracts are canonical in the CLI reference, HTTP API reference, and Go package contract.

Components And Collaborators

• cmd/scriptorium passes process arguments and streams to internal/adapter/cli.
• internal/adapter/cli parses commands, resolves application settings through internal/config, constructs the public engine, and owns process output handling.
• internal/adapter/http decodes DTOs, maps them to public run requests, calls its local public Runner interface, and maps public errors and results to HTTP DTOs.
• The root scriptorium package maps its public types and options to internal collaborators and maps selected internal errors to public sentinels.
• internal/format formats public prepared runs for the CLI.

Wiring Flows

CLI

The CLI resolves configuration before constructing the public engine. run calls Engine.Run with a public request and render calls Engine.Prepare with the same request mapping. serve constructs the HTTP-owned restricted artifact reader, injects it with WithArtifactReader, passes the resulting engine directly to the HTTP handler, and starts the server.

Parser state records whether numeric runtime values were explicitly supplied. That presence is carried into scriptorium.ExecutionTargetOverride, allowing the engine to distinguish omitted values from explicit zero overrides.

HTTP

The handler first enforces transport limits, strict JSON decoding, and the minimal request shape. It maps DTO values to public types without deciding prompt selection, source behavior, or validation semantics. On success it maps the public result to the response DTO; on failure it uses errors.Is over public framework errors and HTTP-local artifact-policy errors to choose the public error mapping.

The HTTP API reference owns the route, DTO schema, status codes, and externally observable limit behavior.

Public Go Facade

NewEngine applies public options, selects filesystem, fs.FS, single-file, or in-memory dependencies, and constructs a runner. The conversion functions copy maps and slices across the boundary so callers do not receive internal domain values. The facade maps selected internal errors to the public sentinel set and keeps direct request API keys out of public results.

Package-Local Guarantees

• Adapters do not embed framework orchestration or source-loading decisions.
• Configuration is resolved before adapter dependency composition.
• CLI and HTTP consume the public engine without a repairer; a repairer remains available only through explicit internal runner construction.
• DTO conversion preserves explicit numeric-override presence.
• Error mapping matches error identities, not error text.
• No adapter creates durable run state; caller-selected output files are not application state.

Failure And Verification Boundaries

Keep external error payloads concise, preserve strict external decoding, and do not serialize resolved secret values. Validation content failures remain result state; runtime failures remain errors for the relevant adapter to map.

Inspect focused tests when changing this area:

• internal/adapter/cli/run_test.go
• internal/adapter/http/handler_test.go
• engine_test.go
• internal/format/prepared_run_test.go

Run the affected adapter package tests and recheck the relevant canonical contract. The testing policy owns global test sufficiency guidance.

Change Recipes

Application Configuration Fields

1. Add the field to the relevant internal/config shape and default handling.
2. Parse and validate it, then preserve configuration and CLI-override precedence while wiring it through its consuming adapter.
3. Add focused configuration and adapter tests for parsing, mapping, and effective behavior.
4. Update the configuration contract and any affected external contract.

CLI Flags

1. Add the flag to the relevant parser in internal/adapter/cli/run.go.
2. Keep command scope and application-configuration precedence intentional.
3. Add or update parser and command tests in internal/adapter/cli/run_test.go.
4. Update the CLI contract and affected maintained examples.

Adapter Capabilities

1. Define or reuse an adapter-local consumer interface with public facade types when a test seam is needed.
2. Implement translation and IO behavior without moving framework decisions out of the public engine.
3. Add focused mapping, parsing, and error-behavior tests.
4. Update this document and the affected public or integration contract. Update source internals when source-loading behavior changes.