prescript

package
v0.33.0 Latest Latest
Warning

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

Go to latest
Published: Jul 30, 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).

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