111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# Scriptorium Adapter Internals
|
|
|
|
This document describes the subprocess adapter in
|
|
`internal/adapters/scriptorium`.
|
|
|
|
## Purpose
|
|
|
|
The adapter runs `scriptorium render` for prompt preflight and `scriptorium run`
|
|
for Markdown report generation or structured generated-text output. It isolates
|
|
subprocess execution, argv construction, timeout handling, output capture, and
|
|
exit-code interpretation from app and domain packages.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- prompt ID
|
|
- YAML prompt input data package path
|
|
- report output path for `run`
|
|
- raw generated-text output path for structured `run`
|
|
- configured binary, config path, profile, timeout, and extra arguments
|
|
- context for cancellation
|
|
|
|
Outputs:
|
|
|
|
- argv used for execution
|
|
- captured stdout and stderr
|
|
- truncation flags for captured output
|
|
- exit code
|
|
- report output path for `run`
|
|
- raw generated-text output path for structured `run`
|
|
|
|
## Boundaries
|
|
|
|
`internal/adapters/scriptorium` owns Scriptorium command construction and
|
|
subprocess execution. It does not choose report types, build prompt input,
|
|
collect weather data, decide workflow order, or persist workflow metadata.
|
|
|
|
The adapter exposes request and result structs for render, Markdown run, and
|
|
structured generated-text run operations. State persistence uses state-owned
|
|
artifact shapes; app orchestration converts adapter results before saving.
|
|
|
|
## Config Fields Used
|
|
|
|
- `scriptorium.binary`
|
|
- `scriptorium.config_path`
|
|
- `scriptorium.profile`
|
|
- `scriptorium.timeout`
|
|
- `scriptorium.extra_args`
|
|
|
|
## Commands
|
|
|
|
Render preflight argv starts with:
|
|
|
|
```text
|
|
scriptorium render --prompt <prompt_id> --input data_package=<path> --format json
|
|
```
|
|
|
|
Report generation argv starts with:
|
|
|
|
```text
|
|
scriptorium run --prompt <prompt_id> --input data_package=<path> --out <path>
|
|
```
|
|
|
|
Structured generated-text argv uses the same `scriptorium run` form, with the
|
|
`--out` value set to the raw generated-text JSON artifact path. The adapter
|
|
does not add `--format`, schema path, or JSON Schema flags for structured
|
|
generation; Scriptorium selects the structured output schema from prompt
|
|
configuration.
|
|
|
|
Configured `--config` and `--profile` flags are inserted after the subcommand
|
|
and before prompt-specific arguments. Extra arguments are appended after the
|
|
built-in arguments.
|
|
|
|
## Execution Behavior
|
|
|
|
The adapter runs commands without shell interpolation. The same private
|
|
execution path is used by render, Markdown run, and structured run after
|
|
command-specific request validation and argv construction.
|
|
|
|
When `scriptorium.timeout` is greater than zero, each subprocess call uses a
|
|
context with that timeout. Stdout and stderr are captured separately, capped at
|
|
1 MiB each, and marked as truncated when the cap is reached.
|
|
|
|
## Failure Behavior
|
|
|
|
- Missing prompt ID or data package path returns an error before subprocess
|
|
execution.
|
|
- Missing run output path returns an error before subprocess execution.
|
|
- Subprocess start errors, context cancellation, and timeouts are wrapped with
|
|
operation context by the caller-facing method.
|
|
- Nonzero render, Markdown run, and structured run exits return the captured
|
|
result plus an error containing the exit code and stderr.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/adapters/scriptorium/runner_test.go`
|
|
- `internal/app/app_test.go`
|
|
- `internal/cli/root_test.go`
|
|
|
|
## Invariants
|
|
|
|
- No shell interpolation is used.
|
|
- The Scriptorium input name is `data_package`.
|
|
- The file at the data package path is YAML produced by `internal/promptinput`.
|
|
- Render, Markdown run, and structured run preserve command-specific result
|
|
structs.
|
|
- Scriptorium-specific flags stay inside adapter and config boundaries.
|