From ff2e664c62bbc67e295905514866cc5fb8b56efe Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 31 Jul 2026 01:14:04 +0000 Subject: [PATCH] Refresh Scriptorium integration guide --- docs/integrations/scriptorium.md | 163 +++++++++++++------------------ 1 file changed, 68 insertions(+), 95 deletions(-) diff --git a/docs/integrations/scriptorium.md b/docs/integrations/scriptorium.md index 12aba57..78df078 100644 --- a/docs/integrations/scriptorium.md +++ b/docs/integrations/scriptorium.md @@ -1,118 +1,91 @@ # Scriptorium Integration -This document describes the external Scriptorium CLI contract used by -`weatherreporter`. +`weatherreporter` invokes the Scriptorium executable as a subprocess to +preflight prompt input and produce report artifacts. This is the limited CLI +contract Weatherreporter uses, not general Scriptorium documentation. -## Purpose +## Invocation -`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input -and generate report artifacts. This page documents the CLI surface the adapter -uses, not the full Scriptorium product. +The configured `scriptorium.binary` is the executable name or path. When it is +empty, the adapter invokes `scriptorium`. Arguments are passed directly to the +process, without a shell. -## Commands Used +For every command, arguments occur in this order: -Render preflight: +1. The subcommand. +2. `--config ` when `scriptorium.config_path` is set. +3. `--profile ` when `scriptorium.profile` is set. +4. The command-specific arguments below. +5. Each configured `scriptorium.extra_args` item. -```bash -scriptorium render \ - --prompt \ - --input data_package= \ - --format json +The adapter uses these exact command shapes: + +```text +scriptorium render [--config ] [--profile ] \ + --prompt --input data_package= --format json \ + [ ...] + +scriptorium run [--config ] [--profile ] \ + --prompt --input data_package= --out \ + [ ...] ``` -Report generation: +`render` is the preflight command. `run` writes either a Markdown report or a +raw generated-text artifact to the supplied `--out` path. The structured +generated-text use of `run` has the same argv as Markdown generation; it does +not add `--format`, `--schema`, `--schema-path`, or `--json-schema` flags. +Prompt configuration selected by `` controls that output. -```bash -scriptorium run \ - --prompt \ - --input data_package= \ - --out -``` +## Inputs and Outputs -Structured generated-text report generation uses the same command shape: +Weatherreporter always supplies exactly one prompt input: +`--input data_package=`. The path identifies the YAML data +package produced by the [prompt-input builder](../internal/prompt-input.md). +Its schema and the separate JSON module snapshots are internal artifacts, not +part of this CLI contract. -```bash -scriptorium run \ - --prompt \ - --input data_package= \ - --out -``` +The application supplies an already-managed output path to every `run` call. +For direct reports it is the Markdown artifact path. For generated-text +reports it is the raw JSON artifact path; subsequent validation and Markdown +rendering are owned by [generated-text processing](../internal/generatedtext.md). -`weatherreporter` always passes prompt input as -`--input data_package=`. The data package is structured YAML created by -`internal/promptinput`; module snapshots remain separate JSON artifacts for -inspection and Recent Changes. +`render` has no output-path argument. Its JSON-formatted stdout remains +captured output: the adapter records it and does not parse it into a separate +CLI result type. Likewise, the adapter records `run` output metadata without +decoding the artifact written at `--out`. -For generated-text reports, Scriptorium selects the structured output schema -from the prompt configuration associated with the prompt ID. `weatherreporter` -does not pass `--format`, schema path, or JSON Schema flags for structured -generation. +## Execution and Results -## Configured Arguments +`scriptorium.timeout`, when greater than zero, creates a timeout for each +subprocess invocation. Parent-context cancellation and that timeout stop the +command through the process context. -The adapter can prepend configured flags before prompt-specific arguments: +Stdout and stderr are captured independently, each up to 1 MiB. Every returned +result records the complete argv as `command`, the captured `stdout` and +`stderr`, `exitCode`, and `stdoutTruncated` and `stderrTruncated` when a stream +was capped. Results from both forms of `run` also record `outputPath`, the +requested `--out` value. -- `--config ` from `scriptorium.config_path` -- `--profile ` from `scriptorium.profile` - -It appends `scriptorium.extra_args` after the built-in arguments. Extra -arguments are passed directly as argv items. - -`scriptorium.binary` selects the executable name or path. If unset inside the -adapter, it falls back to `scriptorium`. - -## Execution Behavior - -The adapter runs Scriptorium without shell interpolation. Arguments are passed -through `exec.CommandContext`. - -`scriptorium.timeout` limits each subprocess call when configured. Context -cancellation or timeout returns an execution error. - -Stdout and stderr are captured separately. Each stream is capped at 1 MiB and -the result records whether truncation occurred. - -## Results - -Render results include: - -- full argv recorded as `command` -- stdout -- stderr -- exit code -- truncation flags when applicable - -Run results include the same fields plus the requested output path. Structured -generated-text run results use the same captured fields and output-path -recording, with the output path pointing at the raw generated-text JSON -artifact. - -`weatherreporter` persists render preflight JSON when orchestration reaches the -preflight save point. For direct Markdown reports, Scriptorium writes the -managed Markdown artifact to the `--out` path. For generated-text-template -reports, Scriptorium writes raw JSON to the `--out` path; later -weatherreporter workflow steps validate those bytes and render Markdown from an -embedded template. +The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process +execution and result capture. [Application orchestration](../internal/app-orchestration.md) +owns when preflight output, report artifacts, and generated-text artifacts are +persisted. ## Failure Behavior -The adapter validates required request fields before starting Scriptorium: +Before starting Scriptorium, the adapter requires a prompt ID and data-package +path for every command, plus an output path for `run`. Missing fields fail +without executing a subprocess. -- prompt ID -- data package path -- output path for `run` and structured generated-text `run` +A nonzero process exit returns the captured result and an error that includes +the exit code and stderr. An output file written before such an exit does not +make the request successful. Failures to start the command, context +cancellation, and timeout return an error rather than a successful result. -Nonzero exits return both the captured result and an error containing the exit -code and stderr. A `run` exit code such as `2` is still treated as an error by -the adapter, even if Scriptorium wrote output to the requested artifact path. +## Operational Notes -Subprocess start failures, context cancellation, and timeouts return errors -without fabricating a successful result. - -## Security Notes - -- The adapter does not invoke a shell. -- Generated artifacts, rendered prompt context, stdout, and stderr can contain - operationally sensitive data. -- API keys should be provided through the Scriptorium environment or - Scriptorium configuration, not through `weatherreporter` CLI arguments. +- Extra arguments are argv items; they are not shell-interpreted. +- Prompt input, generated artifacts, stdout, and stderr can contain + operationally sensitive weather data. +- Provide API keys through the Scriptorium environment or its configuration, + not through Weatherreporter CLI arguments.