@olivervea/pipelines 2.0.0-beta.33 → 2.0.0-beta.35

package/README.md

@@ -98,6 +98,7 @@ Rules:
 - **`optional(M)`** means "maybe skipped": `M` must still have an earlier producer.
 - **`cells(M)`** reads every cell of a matrix step whose output is `M` (see "Matrix steps").
 - **`external(M, { title, description?, from? })`** is answered from outside the run; `from` lists `callback()` (another system POSTs to the URL an earlier step gets from `ctx.inputUrl(step, input)`), `poll({ url, valuePath, intervalSeconds? })` and `person()` (the default). It needs no producer and no mapper entry; the step waits until it is answered, then the value (validated against `M`) is in its input like any other. Failure handlers can't have one. `link: { input, path?, label? }` is the link shown on the step while it waits: `input` is one of the same step's regular (non-external) inputs (typed to their names), `path` a dot path inside its value (`url` → `input.review.url`; none = the value itself is the URL), `label` defaults to `title`. A value that is not an absolute http(s) URL sets no link; the step waits all the same.
+- **`implement(step, handler, { preflight: async (input, ctx) => … })`** runs before a step with an external input waits: it hands the work and `ctx.inputUrl(step, input)` to whatever answers, and its `ctx.link` links join the waiting links. It gets the step's regular inputs only, and the handler's `ctx` without `output` and `skip`. Throwing fails the attempt without waiting. Only a step with an external input takes one (a type error, and a describe problem otherwise).
 
 ### Config
 
@@ -241,7 +242,7 @@ export const deployBeta = implement(step({ name: "deploy-beta", /* … */ }), as
 | `ctx.` | |
 |---|---|
 | `sh(cmd \| script, { env, cwd, args })`, `sh.text(…)` | Runs a command string, or an embedded script, through the image's shell. The script is copied to `$OLVE_DIR/tmp/scripts/` first. The shell is the first of `/bin/sh`, `/busybox/sh`, `/bin/bash` that exists; a shell-less image gets a clear `ShellNotFoundError`. A script's shebang is honoured when its interpreter exists. A string counts as an embedded script when it is a `/$bunfs/…` path, or an absolute path to an existing `*.sh` or `*.bash` file. Pass `{ script }` to force script mode. `args` are the script's arguments, or `$1`, `$2`… of a command string. A non-zero exit throws a `CommandError` that carries `exitCode`. |
-| `exec([argv…], { env, cwd, idleTimeoutSeconds })` | Runs a binary directly, with no shell (works on distroless). `idleTimeoutSeconds` (also on `sh`) is an inactivity watchdog: no stdout/stderr output for that long → SIGTERM, SIGKILL 10 s later, and a `CommandStalledError`. |
+| `exec([argv…], { env, cwd, idleTimeoutSeconds })` | Runs a binary directly, with no shell (works on distroless). `idleTimeoutSeconds` (also on `sh`) is an inactivity watchdog: no stdout/stderr output for that long → SIGTERM, SIGKILL 10 s later, and a `CommandStalledError`. Once a command exits, its output is read for at most 5 s more, so a leftover background child holding the pipes doesn't hang the step. |
 | `readText(path)`, `readJson(path)` | Paths are relative to the cwd. |
 | `files.fetch(ref)` | Downloads a file reference and verifies its sha256. Directory refs are extracted. Returns a local path. |
 | `output.write(name, content)`, `output.file(path, { name })`, `output.dir(path, { name })` | Adds a file to the step's output and returns its `FileRef`. A directory becomes a deterministic tar. |
@@ -308,9 +309,10 @@ This section is everything the C# side needs in order to run the binary.
 |---|---|---|---|
 | `describe [--sentinels]` | the binary itself | stdout: the manifest (canonical JSON) | With `--sentinels`, stdout gets the manifest between `---OLVE-MANIFEST-BEGIN---` and `---OLVE-MANIFEST-END---`. Needs no env and no files. |
 | `run <step>` | `$OLVE_DIR/input.json` | `$OLVE_DIR/work/output.json`, `$OLVE_DIR/work/files/…` | Steps in stages and failure-handler steps. A matrix step's cell runs as `run <step>` (the step's own name) with `OLVE_CELL`. |
+| `preflight <step>` | `$OLVE_DIR/input.json` | `$OLVE_DIR/work/output.json` | A step's preflight (manifest `preflight: true`). Validates only the step's regular inputs (external values already in the input are ignored) and writes `{"status":"succeeded","output":null}` with the preflight's `links`, or a failed envelope whose message names the preflight. Keeps no files; the service sets no `OLVE_RESULT_URL` and reads the envelope from the log. |
 | `map-trigger <trigger>` | `$OLVE_DIR/input.json` (the event) | `$OLVE_DIR/work/output.json` | `<trigger>` is the trigger's `name` from the manifest. |
 
-`run` and `map-trigger` also print the envelope on stdout, as one compact JSON line between `---OLVE-RESULT-BEGIN---` and `---OLVE-RESULT-END---`. The block always comes last. Use it as a fallback channel from the pod log. User output and stderr logs also go to the pod log, so never parse anything outside the sentinels.
+`run`, `preflight` and `map-trigger` also print the envelope on stdout, as one compact JSON line between `---OLVE-RESULT-BEGIN---` and `---OLVE-RESULT-END---`. The block always comes last. Use it as a fallback channel from the pod log. User output and stderr logs also go to the pod log, so never parse anything outside the sentinels.
 
 ### Files (`$OLVE_DIR`, default `/olve`)
 
@@ -343,7 +345,7 @@ This section is everything the C# side needs in order to run the binary.
 | `OLVE_FILES_BASE_URL` (+ `OLVE_FILES_TOKEN`) | optional | Fallback: `GET <base>/<run>/<step>/<attempt>/<object path>` with an optional `Authorization: Bearer <token>`. |
 | `OLVE_FILES_DIR` | dev | Local pool laid out as `<run>/<step>/<attempt>/files/<object path>`. |
 
-`OLVE_RESULT_URL`, `OLVE_FILE_URLS`, `OLVE_FILES_TOKEN` and `OLVE_CALLBACK_URLS` are removed from the environment of child processes. URLs are never logged past `?`.
+The variables in this table (the `OLVE_*` contract, credentials included) are removed from the environment of child processes `ctx.sh` and `ctx.exec` start; declared secrets are not. URLs are never logged past `?`.
 
 **Secret masking** (`run`): with `OLVE_SECRETS` set, the binary runs the step as its own child and replaces every value of those secrets with `***` in the child's stdout and stderr, a line at a time, from the pipeline's first import to its exit. That covers every way of printing: logs, `console`, direct writes, commands and the processes they start. The envelope's failure message, skip reason and links are masked too; outputs and files are data and aren't. A multi-line value is masked line by line, and values (or lines) shorter than 4 characters are left alone. Not masked: a value the step transforms before printing (escaped, encoded, cut short) and a process writing to the pod's stdout directly (`/proc/1/fd/1`).
 
@@ -423,6 +425,7 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
 
   An object whose only key is `ref` (with a string value) or `const` is a tag. Describe never emits a nested object with exactly that key set. Model-matched inputs are emitted already resolved (`{"ref": "build"}`).
 - **Step `externalInputs`** (when present) maps each external input key to `{model, title, description, from, link?}`, `from` being `{kind: "person"}`, `{kind: "callback"}` or `{kind: "poll", url, valuePath, intervalSeconds}`, and `link` `{input, path?, label?}` (omitted when not set, as are its `path` and `label`). Those keys are not in `input` or `inputTypes`; the service merges the answers into `input.json`.
+- **Step `preflight: true`** (omitted otherwise): the step runs `preflight <step>` before it waits for its external inputs.
 - **`inputTypes`** declares each input key: `{model, optional}`, `{model, optional: false, cells: true}` for a `cells` input (mapped with a whole-step ref to a matrix step whose output is that model), or `{schema: {output, input?}}` for a plain schema.
 - **Step `matrix`** (matrix steps only, never a failure handler) is `{axes: [{name, values}…], exclude?: [{axis: value…}…], failure: {kind: "keepRunning" | "cascadeFailure"}, maxParallel?}`. `axes` is a list because canonical JSON sorts keys; `exclude` is omitted when empty; `failure.kind` is always written. All of it is part of what the step declares.
 - **`codeHash`** is the build's identity: `sha256(canonical {bundle, harness})`. `bundle` hashes the entry point bundled with everything it imports, with `@olivervea/pipelines` external. It is tree-shaken and includes embedded scripts and dependencies, so any change to code in use changes it, and with it the manifest, which makes a new pipeline version. A step version covers what the step declares: image, `inputTypes`/model versions, `output` model version, `secrets`, `configEntries` (and those entries' schemas), `input` mappings and `config`.
@@ -446,6 +449,7 @@ Describe runs these checks; reconcile should re-run the manifest-level ones:
 - mapper source analysis and recording, unknown fields in refs, mapper keys that are missing or extra;
 - `when` on an unknown or non-literal field, or with an invalid value;
 - an external input's `link` naming anything but one of the step's regular inputs, an empty path segment, a label that is empty or over 100 characters;
+- a preflight on a step without an external input;
 - a poll header referencing an undeclared secret, duplicate triggers;
 - conflicting secret descriptions;
 - config names, one description and schema per config name, a step receiving a `secretRef` without declaring its secret, and input keys starting with `$` (reserved);
@@ -490,6 +494,7 @@ The manifest is the text between the sentinels in the pod log. The manifest text
 ```
 olve-dev describe <dir> [--sentinels]                     # same bytes as the compiled binary's describe
 olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
+olve-dev preflight <dir> <step> [same options as run]
 olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
 ```
 

package/manifest.schema.json

@@ -687,6 +687,11 @@
           ],
           "description": "Output model, or null if the step produces no output."
         },
+        "preflight": {
+          "const": true,
+          "description": "The step runs its preflight (the harness's 'preflight <step>' mode, on the step's non-external inputs) before it waits for its external inputs; only a step with external inputs has one. Omitted = none.",
+          "type": "boolean"
+        },
         "retries": {
           "maximum": 9007199254740991,
           "minimum": 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olivervea/pipelines",
-  "version": "2.0.0-beta.33",
+  "version": "2.0.0-beta.35",
   "description": "Olve.Pipelines v2 SDK: typed pipeline authoring, the step harness, and the build tool.",
   "type": "module",
   "license": "MIT",

package/src/core/handlers.ts

@@ -5,11 +5,13 @@ import {
   type SkippedBrand,
 } from './brands.ts';
 import type { StepCtx } from '../ctx/types.ts';
+import { isExternal, type External } from './external.ts';
 import type {
   AnyStep,
   CellOf,
   ConfigOf,
   OutputValue,
+  RegularInputKey,
   SecretsOf,
   StepInput,
 } from './steps.ts';
@@ -39,12 +41,40 @@ export type Handler<S extends AnyStep> = (
   ctx: CtxOf<S>,
 ) => Awaitable<HandlerResult<S>>;
 
+/** What a preflight receives: the step's non-external inputs (the external values don't exist yet). */
+export type PreflightInput<S extends AnyStep> = StepInput<
+  Pick<S['input'], RegularInputKey<S['input']>>
+>;
+/** The ctx a preflight of `S` gets: the handler's, without output files and `skip` (the step still waits). */
+export type PreflightCtxOf<S extends AnyStep> = Omit<CtxOf<S>, 'output' | 'skip'>;
+export type Preflight<S extends AnyStep> = (
+  input: PreflightInput<S>,
+  ctx: PreflightCtxOf<S>,
+) => Awaitable<void>;
+
+/** True when some input of the step is `external(...)`. */
+type HasExternalInput<I> = true extends {
+  [K in keyof I]-?: I[K] extends External ? true : false;
+}[keyof I]
+  ? true
+  : false;
+
+export interface ImplementOptions<S extends AnyStep> {
+  /**
+   * Runs before the step starts waiting for its external inputs, e.g. to hand work and
+   * `ctx.inputUrl(...)` to the system that will answer. Throwing fails the attempt without waiting.
+   */
+  preflight?: Preflight<S>;
+}
+
 /** A step with its handler. It is itself a step: stage it like any value. */
 export type Implementation<S extends AnyStep = AnyStep> = S & {
   readonly [ImplementationBrand]: true;
   /** The step as defined. */
   readonly step: S;
   readonly handler: Handler<S>;
+  /** Runs before the step waits for its external inputs; absent when none. */
+  readonly preflight?: Preflight<S>;
 };
 
 /** Block-bodied/async returns get no excess-property check; this restores it for handler outputs. */
@@ -69,16 +99,29 @@ export function implement<S extends AnyStep, R extends HandlerResult<S>>(
     input: StepInput<S['input']>,
     ctx: CtxOf<S>,
   ) => Awaitable<R & NoExtraFields<R, OutputValue<S>>>,
+  options?: HasExternalInput<S['input']> extends true
+    ? ImplementOptions<S>
+    : '❌ a preflight needs a step with an external(...) input',
 ): Implementation<S> {
   if (isImplementation(step))
     throw new TypeError(
       `step '${(step as AnyStep).name}' already carries its implementation`,
     );
+  const preflight =
+    typeof options === 'object' ? (options as ImplementOptions<S>).preflight : undefined;
+  if (
+    preflight !== undefined &&
+    !Object.values((step as AnyStep).input as Record<string, unknown>).some(isExternal)
+  )
+    throw new TypeError(
+      `step '${(step as AnyStep).name}': a preflight needs a step with an external(...) input`,
+    );
   return Object.freeze({
     ...step,
     [IMPLEMENTATION]: true,
     step,
     handler: handler as unknown as Handler<S>,
+    ...(preflight !== undefined ? { preflight } : {}),
   }) as unknown as Implementation<S>;
 }
 

package/src/ctx/sh.ts

@@ -52,6 +52,9 @@ export class CommandStalledError extends CommandError {
 /** Grace between the watchdog's SIGTERM and SIGKILL (a process blocked in a socket read may ignore TERM). */
 export const STALL_KILL_GRACE_MS = 10_000;
 
+/** How long output is still read after a command exits; a leftover child (an MSBuild node) may hold the pipes. */
+export const PIPE_GRACE_MS = 5_000;
+
 export function detectShell(candidates: readonly string[] = SHELL_CANDIDATES): string {
   for (const c of candidates) if (existsSync(c)) return c;
   throw new ShellNotFoundError();
@@ -80,6 +83,7 @@ export interface ShDeps {
   tmpDir: string;
   signal: AbortSignal;
   shellCandidates?: readonly string[];
+  pipeGraceMs?: number;
 }
 
 export function createSh(deps: ShDeps): {
@@ -208,9 +212,16 @@ export function createSh(deps: ShDeps): {
 
     try {
       const code = await proc.exited;
-      // A killed command's children may still hold the pipes open: don't wait for them after a stall.
-      if (stalled) await Promise.all(readers.map((r) => r.cancel().catch(() => {})));
-      else await Promise.all(pumps);
+      // A command's leftover children may still hold the pipes open: don't wait for them long.
+      if (!stalled) {
+        let grace: ReturnType<typeof setTimeout> | undefined;
+        await Promise.race([
+          Promise.all(pumps),
+          new Promise((r) => (grace = setTimeout(r, deps.pipeGraceMs ?? PIPE_GRACE_MS))),
+        ]);
+        clearTimeout(grace);
+      }
+      await Promise.all(readers.map((r) => r.cancel().catch(() => {})));
       if (stalled)
         throw new CommandStalledError(
           what,

package/src/describe/manifest-schema.ts

@@ -180,6 +180,12 @@ export const StepDescriptor = z
       .describe(
         "The step pod gets the instance's step ServiceAccount token (Kubernetes:StepServiceAccount), if the instance grants one. Omitted = no token.",
       ),
+    preflight: z
+      .literal(true)
+      .optional()
+      .describe(
+        "The step runs its preflight (the harness's 'preflight <step>' mode, on the step's non-external inputs) before it waits for its external inputs; only a step with external inputs has one. Omitted = none.",
+      ),
     externalInputs: z
       .record(
         z.string(),

package/src/describe/step.ts

@@ -68,6 +68,7 @@ export function describeStep(
     ),
   ].sort();
   const carried = isImplementation(s);
+  const preflight = carried && typeof s.preflight === 'function';
   const { settings, settingsProblem } = recordSettings(s, carried);
   const refs = settings ? recordedConfigRefs(settings) : [];
   checkConfigSecrets(ctx, at, configNames, refs, secretNames);
@@ -109,7 +110,10 @@ export function describeStep(
     ...(configNames.length ? { configEntries: configNames } : {}),
     ...(s.clusterAccess === true ? { clusterAccess: true as const } : {}),
     ...(Object.keys(externalInputs).length ? { externalInputs } : {}),
+    ...(preflight ? { preflight: true as const } : {}),
   };
+  if (preflight && Object.keys(externalInputs).length === 0)
+    problems.push(`${at}: a preflight needs at least one external input`);
   if (s.clusterAccess !== undefined && typeof s.clusterAccess !== 'boolean')
     problems.push(`${at}: clusterAccess must be a boolean`);
   if (s.output && !isModel(s.output)) problems.push(`${at}: output must be a model`);

package/src/dev/cli.ts

@@ -2,6 +2,7 @@
 // olve-dev — run a pipeline from source through the same harness path as the compiled binary.
 //   olve-dev describe <dir> [--sentinels]
 //   olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
+//   olve-dev preflight <dir> <step> [same options as run]
 //   olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
 // $OLVE_DIR defaults to <dir>/.olve; outputs land in <dir>/.olve/work/.
 import {
@@ -25,6 +26,7 @@ import {
 
 const USAGE = `usage: olve-dev describe <dir> [--sentinels]
        olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
+       olve-dev preflight <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
        olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]`;
 
 export async function devConfig(
@@ -71,10 +73,10 @@ export async function devMain(argv: string[]): Promise<number> {
         'describe',
         ...(values.sentinels ? ['--sentinels'] : []),
       ]);
-    if (mode !== 'run' && mode !== 'map-trigger')
+    if (mode !== 'run' && mode !== 'preflight' && mode !== 'map-trigger')
       return (console.error(USAGE), EXIT.usage);
     if (!name) return (console.error(USAGE), EXIT.usage);
-    const file = mode === 'run' ? values['input-file'] : values['event-file'];
+    const file = mode === 'map-trigger' ? values['event-file'] : values['input-file'];
     if (mode === 'map-trigger' && !file)
       return (console.error('--event-file is required'), EXIT.usage);
     const olveDir = resolve(values['olve-dir'] ?? join(dir, '.olve'));
@@ -88,7 +90,7 @@ export async function devMain(argv: string[]): Promise<number> {
       process.env[s.slice(0, i)] = s.slice(i + 1);
     }
     if (file) copyFileSync(resolve(file), join(olveDir, 'input.json'));
-    if (mode === 'run' && values['config-file']) {
+    if (mode !== 'map-trigger' && values['config-file']) {
       const inputFile = join(olveDir, 'input.json');
       const input = (
         existsSync(inputFile) ? JSON.parse(readFileSync(inputFile, 'utf8')) : {}

package/src/harness/env.ts

@@ -25,12 +25,12 @@ export const ENV = {
   filesDir: 'OLVE_FILES_DIR',
 } as const;
 
-/** Env vars never passed to child processes (they carry credentials for the harness only). */
+/** Env vars never passed to child processes: the harness's own contract, credentials included. */
 export const PRIVATE_ENV: readonly string[] = [
-  ENV.resultUrl,
-  ENV.fileUrls,
-  ENV.filesToken,
-  ENV.callbackUrls,
+  ...Object.values(ENV),
+  'OLVE_CASES',
+  'OLVE_SECRETS',
+  'OLVE_SUPERVISED',
 ];
 
 /** `OLVE_CALLBACK_URLS`, parsed; empty when unset or malformed. */

package/src/harness/execute.ts

@@ -3,13 +3,14 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { isSkipped } from '../core/handlers.ts';
+import { isExternal } from '../core/external.ts';
 import type { AnyStep } from '../core/steps.ts';
 import type { Ctx, RunInfo } from '../ctx/types.ts';
 import { objectPath } from '../ctx/files.ts';
 import { createLinks, type StepLink } from '../ctx/links.ts';
 import { sha256File } from '../util/hash.ts';
 import { EXIT } from './exit.ts';
-import { validateConfig, validateInput, validateOutput } from './validate.ts';
+import { CONFIG_KEY, validateConfig, validateInput, validateOutput } from './validate.ts';
 
 export type FailureKind = 'handler' | 'input' | 'output';
 export type Envelope = (
@@ -136,3 +137,78 @@ export async function executeStep(args: {
     exitCode: EXIT.ok,
   };
 }
+
+/**
+ * A step's preflight: validates the step's non-external inputs (external values already given are
+ * ignored), runs the preflight and reports its links. Succeeds with `output: null`; nothing is validated
+ * as output and no files are kept.
+ */
+export async function executePreflight(args: {
+  step: AnyStep;
+  fn: StepFunction;
+  rawInput: unknown;
+  ctx: Ctx;
+  workFiles: string;
+  log: (line: string) => void;
+}): Promise<Execution> {
+  const { step, log } = args;
+  const entries = Object.entries(step.input as Record<string, unknown>);
+  const external = new Set(entries.filter(([, e]) => isExternal(e)).map(([k]) => k));
+  const regular = {
+    ...step,
+    input: Object.fromEntries(entries.filter(([k]) => !external.has(k))),
+  };
+  const raw =
+    typeof args.rawInput === 'object' &&
+    args.rawInput !== null &&
+    !Array.isArray(args.rawInput)
+      ? Object.fromEntries(
+          Object.entries(args.rawInput).filter(
+            ([k]) => k === CONFIG_KEY || !external.has(k),
+          ),
+        )
+      : args.rawInput;
+  const input = validateInput(regular, raw);
+  const config = validateConfig(step, raw);
+  if (!input.ok || !config.ok) {
+    const issues = [
+      ...(input.ok ? [] : input.issues),
+      ...(config.ok ? [] : config.issues),
+    ];
+    const message = `step '${step.name}' preflight: input does not match the step's inputs:\n  ${issues.join('\n  ')}`;
+    log(message);
+    return {
+      envelope: { status: 'failed', error: { kind: 'input', message } },
+      exitCode: EXIT.inputInvalid,
+    };
+  }
+  const collected = createLinks();
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { output: _output, skip: _skip, ...rest } = args.ctx;
+  const ctx = {
+    ...rest,
+    config: Object.freeze(config.value) as Ctx['config'],
+    link: collected.link,
+  };
+  const withLinks = (e: Envelope): Envelope =>
+    collected.links.length ? { ...e, links: [...collected.links] } : e;
+  try {
+    await args.fn(input.value, ctx as Ctx);
+  } catch (e) {
+    const cancelled = cancelExitCode(ctx.signal);
+    const message = cancelled
+      ? `step '${step.name}' preflight was cancelled (${String(ctx.signal.reason)}): ${errorMessage(e)}`
+      : `step '${step.name}' preflight failed: ${errorMessage(e)}`;
+    log(message);
+    if (e instanceof Error && e.stack && !cancelled) log(e.stack);
+    return {
+      envelope: withLinks({ status: 'failed', error: { kind: 'handler', message } }),
+      exitCode: cancelled ?? EXIT.handlerFailed,
+    };
+  }
+  log(`step '${step.name}' preflight succeeded`);
+  return {
+    envelope: withLinks({ status: 'succeeded', output: null }),
+    exitCode: EXIT.ok,
+  };
+}

package/src/harness/main.ts

@@ -1,6 +1,7 @@
 // The harness: one executable, three modes.
 //   describe [--sentinels]   → manifest (canonical JSON) on stdout
 //   run <step>               → $OLVE_DIR/input.json → handler → $OLVE_DIR/work/output.json (+ result upload)
+//   preflight <step>         → the step's non-external inputs → preflight → envelope (links only, no output)
 //   map-trigger <trigger>    → $OLVE_DIR/input.json (event) → pipeline input → $OLVE_DIR/work/output.json
 import { mkdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -17,6 +18,7 @@ import type { HarnessInfo } from '../util/code-hash.ts';
 import { callbackUrlsFromEnv, ENV, paths, runInfoFromEnv } from './env.ts';
 import { EXIT } from './exit.ts';
 import {
+  executePreflight,
   executeStep,
   type Envelope,
   type Execution,
@@ -56,7 +58,7 @@ export const defaultIO: HarnessIO = {
 };
 
 const USAGE =
-  'usage: step describe [--sentinels] | step run <step> | step map-trigger <trigger>';
+  'usage: step describe [--sentinels] | step run <step> | step preflight <step> | step map-trigger <trigger>';
 
 /** Every step with the `select` case conditions (`<ref>.<discriminator>=<value>`) it sits in. */
 export function stepsWithCases(data: PipelineData): { step: AnyStep; cases: string[] }[] {
@@ -125,6 +127,13 @@ export function resolveStepFunction(step: AnyStep): StepFunction | string {
   return `step '${step.name}' has no implementation (stage implement(step({...}), fn))`;
 }
 
+/** The preflight `step` carries, or what is wrong. */
+export function resolvePreflight(step: AnyStep): StepFunction | string {
+  if (isImplementation(step) && step.preflight)
+    return step.preflight as unknown as StepFunction;
+  return `step '${step.name}' has no preflight (implement(step, fn, { preflight }))`;
+}
+
 /** Writes output.json, prints the sentinel block and uploads result.tar.gz when OLVE_RESULT_URL is set. */
 export async function finish(exec: Execution, io: HarnessIO): Promise<number> {
   const p = paths();
@@ -182,12 +191,13 @@ async function runMode(
   cfg: HarnessConfig,
   name: string | undefined,
   io: HarnessIO,
+  mode: 'run' | 'preflight' = 'run',
 ): Promise<number> {
   if (!name) return (io.stderr(USAGE), EXIT.usage);
   const data = pipelineData(cfg.pipeline);
   const step = findStep(data, name, selectedCases());
   if (typeof step === 'string') return (io.stderr(step), EXIT.usage);
-  const fn = resolveStepFunction(step);
+  const fn = mode === 'run' ? resolveStepFunction(step) : resolvePreflight(step);
   if (typeof fn === 'string') return (io.stderr(fn), EXIT.configInvalid);
 
   const p = paths();
@@ -225,17 +235,18 @@ async function runMode(
         callbackUrls: callbackUrlsFromEnv(),
         ...(cell?.ok ? { cell: cell.cell } : {}),
       });
-      exec = await executeStep({
+      const args = {
         step,
         fn,
         rawInput: raw.value,
         ctx,
         workFiles: p.files,
         log: io.stderr,
-      });
+      };
+      exec = await (mode === 'run' ? executeStep(args) : executePreflight(args));
     }
     if (uncaught !== undefined && exec.envelope.status !== 'failed') {
-      const message = `step '${step.name}' failed: an error nothing caught: ${uncaught instanceof Error ? uncaught.message : String(uncaught)}`;
+      const message = `step '${step.name}'${mode === 'preflight' ? ' preflight' : ''} failed: an error nothing caught: ${uncaught instanceof Error ? uncaught.message : String(uncaught)}`;
       io.stderr(message);
       exec = {
         envelope: { status: 'failed', error: { kind: 'handler', message } },
@@ -365,6 +376,8 @@ export async function runHarness(
       return describeMode(cfg, rest, io);
     case 'run':
       return runMode(cfg, rest[0], io);
+    case 'preflight':
+      return runMode(cfg, rest[0], io, 'preflight');
     case 'map-trigger':
       return mapTriggerMode(cfg, rest[0], io);
     default:

package/src/harness/supervise.ts

@@ -30,10 +30,11 @@ function ownArgv(): string[] {
 
 /**
  * Runs the step as a masked child and answers its exit code, or undefined when this process should
- * run the step itself: it is the child, the mode isn't `run`, or there is nothing to mask.
+ * run the step itself: it is the child, the mode isn't `run` or `preflight`, or there is nothing to mask.
  */
 export async function supervise(argv: readonly string[]): Promise<number | undefined> {
-  if (argv[0] !== 'run' || process.env[SUPERVISED]) return undefined;
+  if ((argv[0] !== 'run' && argv[0] !== 'preflight') || process.env[SUPERVISED])
+    return undefined;
   const patterns = secretPatterns();
   if (patterns.length === 0) return undefined;
 

package/src/index.ts

@@ -79,6 +79,10 @@ export {
   type CtxOf,
   type Handler,
   type HandlerResult,
+  type ImplementOptions,
+  type Preflight,
+  type PreflightCtxOf,
+  type PreflightInput,
   type Skipped,
 } from './core/handlers.ts';
 export type {