prescript

package
v0.46.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package prescript implements the pre-script output protocol (issue #4718).

fullsend run hands the harness pre-script an output file path via the FULLSEND_PRESCRIPT_OUTPUT environment variable. The script may append key=value lines to that file — most notably "skipped=true" plus an optional "reason=..." — which fullsend run reads back after the script exits. When skipped=true, fullsend run reports a "skipped" status and exits successfully before creating the sandbox.

The protocol is specified normatively in docs/normative/prescript-output/v1; that document, not this comment, is what pre-script authors write against. The summary below is a convenience for readers of this package.

Version skew is the same class of concern as ADR 0062, and is handled asymmetrically — deliberately, because the two directions have different costs:

  • Old script, new CLI: the script never writes to the file, which parses to a Result with Skipped false and no outputs — exactly today's behavior.
  • New script, old CLI: FULLSEND_PRESCRIPT_OUTPUT is unset, so the script cannot signal a skip and the agent runs anyway (a duplicate run — this direction fails open). Scripts must guard on the variable being unset, the same pattern as the existing GITHUB_OUTPUT guard in the scaffold scripts.

Malformed content is a hard error, not a silent proceed: a typo like "skipped true" silently ignored would let a duplicate agent run start — the exact failure mode the pre-checks exist to prevent. Values that case-insensitively match a reserved key but differ in case (SKIPPED=true) are rejected for the same reason.

Supported syntax (line-based):

skipped=true
reason=an open PR already addresses this issue
# comments and blank lines are ignored

The format resembles GITHUB_OUTPUT but is not compatible with it: there is no quoting, and the "key<<DELIMITER" heredoc form for multiline values is not supported. Values are single-line and may not contain control characters. Surrounding whitespace around both key and value is not significant. Later assignments to the same key win.

Index

Constants

View Source
const EnvVar = "FULLSEND_PRESCRIPT_OUTPUT"

EnvVar is the environment variable through which fullsend run passes the output file path to the pre-script. Scripts must guard on it being unset (older CLI versions do not export it).

View Source
const ExitCodeNeutral = 78

ExitCodeNeutral is the exit code a pre-script uses to signal "nothing to do, skip cleanly" (issue #582). When fullsend run sees this exit code it treats the run as skipped/neutral — no sandbox is created, no LLM is invoked, and the run reports a skipped status. The code follows the CI convention for "neutral" (used by GitHub Actions and others).

Exit 78 is complementary to the file-based skip protocol (skipped=true). Either mechanism alone is sufficient to request a skip. When both are present, exit 78 wins — even if the output file says skipped=false.

Variables

This section is empty.

Functions

func LogLine

func LogLine(res Result) string

LogLine renders the outputs as a single stable, sorted line for the run log, so non-GitHub CIs (and local runs) can still see what the pre-script reported. Returns "" when there is nothing to show, or when an output would break the single-line rendering.

func Prepare

func Prepare(dir string) (path string, cleanup func(), err error)

Prepare creates the file the pre-script writes its outputs to, inside dir. Using the run directory rather than the system temp directory keeps the file out of reach of tmp reapers during a long pre-script. The cleanup func removes the file and never fails loudly.

func Relay

func Relay(res Result) (relayed bool, err error)

Relay surfaces the pre-script outputs to the surrounding CI system so remaining workflow-level gating (if any) can consume them. Today only GitHub Actions is detected; other CIs get the outputs in the run log only (fullsend run logs them on every path). Returns whether a relay target was found.

Callers must invoke Relay on both the skip and proceed paths: the skipped key is always written (normalized to "true"/"false") so consumers can gate on its value, and an absent key means the CLI predates this protocol rather than "not skipped".

Types

type Result

type Result struct {
	// Skipped is true when the pre-script wrote skipped=true, requesting
	// that fullsend run stop before sandbox creation.
	Skipped bool
	// Reason is the optional human-readable reason accompanying a skip.
	Reason string
	// Outputs holds every key=value pair the script wrote, including
	// skipped and reason, with later assignments overriding earlier ones.
	Outputs map[string]string
}

Result is the parsed pre-script output.

func ParseFile

func ParseFile(path string) (Result, error)

ParseFile reads a pre-script output file. An empty file yields a Result with Skipped false and no outputs (proceed). Malformed lines, invalid keys, values containing control characters, and skipped values other than "true"/"false" are hard errors.

A missing file is also a hard error: Prepare creates the file before the script runs, so its absence afterwards means something removed it, and treating that as "proceed" is the silent-proceed failure this protocol exists to prevent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL