Refresh internal state and adapter documentation
This commit is contained in:
@@ -1,110 +1,51 @@
|
||||
# Scriptorium Adapter Internals
|
||||
|
||||
This document describes the subprocess adapter in
|
||||
`internal/adapters/scriptorium`.
|
||||
`internal/adapters/scriptorium` translates Weather Reporter render requests to
|
||||
Scriptorium process arguments and translates process results back to local
|
||||
types. The external CLI and output contract belongs to the
|
||||
[Scriptorium integration guide](../integrations/scriptorium.md); prompts,
|
||||
template inputs, and report ownership remain outside this adapter.
|
||||
|
||||
## Purpose
|
||||
## Request-to-command translation
|
||||
|
||||
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.
|
||||
`Runner` accepts a binary, config path, profile, timeout, extra arguments, and
|
||||
an injectable command executor. Its defaults are the `scriptorium` binary and
|
||||
the real `ExecRunner`. Optional configuration flags are placed before the
|
||||
operation-specific arguments, and extra arguments are appended last.
|
||||
|
||||
## Inputs And Outputs
|
||||
| Local operation | Required values | Translated arguments |
|
||||
| --- | --- | --- |
|
||||
| `Render` | prompt ID, data-package path | `render [--config …] [--profile …] --prompt <id> --input data_package=<path> --format json [extra …]` |
|
||||
| `Run` | prompt ID, data-package path, output path | `run [--config …] [--profile …] --prompt <id> --input data_package=<path> --out <path> [extra …]` |
|
||||
| `StructuredRun` | prompt ID, data-package path, output path | Same translation as `Run` |
|
||||
|
||||
Inputs:
|
||||
Blank required values fail before a command starts. The adapter does not add
|
||||
schema flags or interpret a prompt's payload; it only gives Scriptorium the
|
||||
named `data_package` input.
|
||||
|
||||
- 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
|
||||
## Command execution and result translation
|
||||
|
||||
Outputs:
|
||||
`ExecRunner` uses `exec.CommandContext`, never a shell. A positive configured
|
||||
timeout creates a child context. Standard output and standard error are
|
||||
captured independently, each with a 1 MiB limit, and the executed command is
|
||||
retained for diagnostics.
|
||||
|
||||
- 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`
|
||||
`RenderResult`, `RunResult`, and `StructuredRunResult` expose the command,
|
||||
captured output, truncation markers, and exit code. Run results also retain the
|
||||
requested output path. Exit status zero is successful. A nonzero process exit
|
||||
returns its result and an error, while a start failure, cancellation, or
|
||||
deadline failure returns no result and the execution error.
|
||||
|
||||
## Boundaries
|
||||
The adapter does not parse rendered JSON, validate a generated report, write
|
||||
state, or upload a report. Those responsibilities sit with
|
||||
[application orchestration](app-orchestration.md), [state internals](state.md), and the
|
||||
relevant delivery adapter.
|
||||
|
||||
`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.
|
||||
## Verification
|
||||
|
||||
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.
|
||||
Focused tests cover argument order, validation, bounded capture, timeout and
|
||||
cancellation handling, and exit-status translation:
|
||||
|
||||
## 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
|
||||
```sh
|
||||
go test ./internal/adapters/scriptorium
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user