@olivervea/pipelines 0.0.0-stage → 2.0.0-beta.2

package/src/harness/main.ts

@@ -0,0 +1,232 @@
+// 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)
+//   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";
+import { isImplementation } from "../core/handlers.ts";
+import type { AnyStep } from "../core/steps.ts";
+import type { WebhookEvent } from "../core/webhooks.ts";
+import { pipelineData, type PipelineData, type StageNode } from "../builder/pipeline.ts";
+import { createCtx, formatLog } from "../ctx/index.ts";
+import { DescribeError, describePipeline, manifestText } from "../describe/describe.ts";
+import type { HarnessInfo } from "../util/handler-hash.ts";
+import { ENV, paths, runInfoFromEnv } from "./env.ts";
+import { EXIT } from "./exit.ts";
+import { executeStep, type Envelope, type Execution, type StepFunction } from "./execute.ts";
+import { MANIFEST_BEGIN, MANIFEST_END, packResult, removeStale, sentinelBlock, uploadFile, writeEnvelope } from "./result.ts";
+import { formatIssues, parseStrict } from "./validate.ts";
+
+/** step name → lazy import of `handlers/<name>.ts`. Literal import() paths so Bun bundles them. */
+export type HandlerRegistry = Readonly<Record<string, () => Promise<{ default: unknown }>>>;
+
+export interface HarnessConfig {
+  /** Default export of pipeline.ts. */
+  pipeline: unknown;
+  handlers: HandlerRegistry;
+  handlerHashes: Readonly<Record<string, string>>;
+  harness: HarnessInfo;
+}
+
+export interface HarnessIO {
+  stdout(text: string): Promise<void>;
+  stderr(line: string): void;
+}
+
+export const defaultIO: HarnessIO = {
+  stdout: async (text) => {
+    await Bun.write(Bun.stdout, text);
+  },
+  stderr: (line) => {
+    process.stderr.write(line.endsWith("\n") ? line : line + "\n");
+  },
+};
+
+const USAGE = "usage: step describe [--sentinels] | step run <step> | step map-trigger <trigger>";
+
+export function allSteps(data: PipelineData): AnyStep[] {
+  const out: AnyStep[] = [];
+  const walk = (nodes: readonly StageNode[]) => {
+    for (const n of nodes) n.kind === "stage" ? out.push(...n.steps.map((s) => s.step)) : walk(n.nodes);
+  };
+  walk(data.nodes);
+  for (const fh of data.failureHandlers) if (!out.includes(fh.step)) out.push(fh.step);
+  return out;
+}
+
+/** Installs SIGTERM/SIGINT handlers that abort the returned signal (PID 1 ignores signals without them). */
+export function cancellation(): { signal: AbortSignal; dispose(): void } {
+  const ac = new AbortController();
+  const onTerm = () => ac.abort("SIGTERM");
+  const onInt = () => (ac.signal.aborted ? process.exit(EXIT.sigint) : ac.abort("SIGINT"));
+  process.on("SIGTERM", onTerm);
+  process.on("SIGINT", onInt);
+  return {
+    signal: ac.signal,
+    dispose() {
+      process.off("SIGTERM", onTerm);
+      process.off("SIGINT", onInt);
+    },
+  };
+}
+
+/** Resolves the function that implements `step` (library or handler module). */
+export async function resolveStepFunction(step: AnyStep, handlers: HandlerRegistry): Promise<StepFunction | string> {
+  if (step.kind !== "custom") {
+    if (!step.builtin) return `library step '${step.name}' (${step.kind}) has no implementation`;
+    return step.builtin.run as StepFunction;
+  }
+  const load = handlers[step.name];
+  if (!load) return `step '${step.name}' has no handler (expected handlers/${step.name}.ts)`;
+  let mod: { default: unknown };
+  try {
+    mod = await load();
+  } catch (e) {
+    return `handlers/${step.name}.ts failed to load: ${(e as Error)?.stack ?? String(e)}`;
+  }
+  const impl = mod.default;
+  if (!isImplementation(impl)) return `handlers/${step.name}.ts must default-export implement(<step '${step.name}'>, …)`;
+  if (impl.step !== step)
+    return `handlers/${step.name}.ts implements step '${(impl.step as AnyStep)?.name}', not '${step.name}' (the default export must be implement(<the '${step.name}' step from pipeline.ts>, …))`;
+  return impl.handler as unknown as StepFunction;
+}
+
+/** 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();
+  writeEnvelope(p.work, exec.envelope);
+  await io.stdout(sentinelBlock(exec.envelope));
+  const url = process.env[ENV.resultUrl];
+  if (!url) return exec.exitCode;
+  try {
+    mkdirSync(p.tmp, { recursive: true });
+    const archive = join(p.tmp, "result.tar.gz");
+    await packResult(p.work, archive);
+    await uploadFile(url, archive, io.stderr);
+  } catch (e) {
+    io.stderr(`result upload failed: ${(e as Error).message}`);
+    return exec.exitCode === EXIT.ok ? EXIT.uploadFailed : exec.exitCode;
+  }
+  return exec.exitCode;
+}
+
+function readJson(path: string): { ok: true; value: unknown } | { ok: false; message: string } {
+  try {
+    return { ok: true, value: JSON.parse(readFileSync(path, "utf8")) };
+  } catch (e) {
+    return { ok: false, message: `cannot read ${path}: ${(e as Error).message}` };
+  }
+}
+
+async function describeMode(cfg: HarnessConfig, args: string[], io: HarnessIO): Promise<number> {
+  const sentinels = args.includes("--sentinels");
+  try {
+    const text = manifestText(describePipeline(cfg.pipeline, { handlerNames: Object.keys(cfg.handlers), handlerHashes: cfg.handlerHashes, harness: cfg.harness }));
+    await io.stdout(sentinels ? `${MANIFEST_BEGIN}\n${text}${MANIFEST_END}\n` : text);
+    return EXIT.ok;
+  } catch (e) {
+    if (e instanceof DescribeError) {
+      io.stderr(e.message);
+      return EXIT.configInvalid;
+    }
+    throw e;
+  }
+}
+
+async function runMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
+  if (!name) return io.stderr(USAGE), EXIT.usage;
+  const data = pipelineData(cfg.pipeline);
+  const step = allSteps(data).find((s) => s.name === name);
+  if (!step) return io.stderr(`unknown step '${name}'`), EXIT.usage;
+  const fn = await resolveStepFunction(step, cfg.handlers);
+  if (typeof fn === "string") return io.stderr(fn), EXIT.configInvalid;
+
+  const p = paths();
+  removeStale(p.work);
+  mkdirSync(p.files, { recursive: true });
+  mkdirSync(p.tmp, { recursive: true });
+  const raw = readJson(p.input);
+  const cancel = cancellation();
+  try {
+    let exec: Execution;
+    if (!raw.ok) {
+      io.stderr(raw.message);
+      exec = { envelope: { status: "failed", error: { kind: "input", message: raw.message } }, exitCode: EXIT.inputInvalid };
+    } else {
+      const run = runInfoFromEnv(step.name);
+      const ctx = createCtx({ run, secrets: step.secrets, paths: { root: p.root, workFiles: p.files, tmp: p.tmp }, signal: cancel.signal, logSink: io.stderr });
+      exec = await executeStep({ step, fn, rawInput: raw.value, ctx, workFiles: p.files, log: io.stderr });
+    }
+    return await finish(exec, io);
+  } finally {
+    cancel.dispose();
+  }
+}
+
+function isWebhookEvent(v: unknown): boolean {
+  if (typeof v !== "object" || v === null || Array.isArray(v) || !("body" in v)) return false;
+  const headers = (v as { headers?: unknown }).headers;
+  return typeof headers === "object" && headers !== null && !Array.isArray(headers);
+}
+
+async function mapTriggerMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
+  if (!name) return io.stderr(USAGE), EXIT.usage;
+  const data = pipelineData(cfg.pipeline);
+  const trigger = data.triggers.find((t) => t.name === name);
+  if (!trigger) return io.stderr(`unknown trigger '${name}' (known: ${data.triggers.map((t) => t.name).join(", ") || "none"})`), EXIT.usage;
+  const p = paths();
+  removeStale(p.work);
+  mkdirSync(p.work, { recursive: true });
+  const raw = readJson(p.input);
+  const fail = (kind: "input" | "output" | "handler", message: string, exitCode: number): Execution => {
+    io.stderr(message);
+    return { envelope: { status: "failed", error: { kind, message } }, exitCode };
+  };
+  let exec: Execution;
+  if (!raw.ok) exec = fail("input", raw.message, EXIT.inputInvalid);
+  else if (trigger.kind === "poll" && (typeof raw.value !== "object" || raw.value === null || typeof (raw.value as { value?: unknown }).value !== "string"))
+    exec = fail("input", `poll trigger '${name}': the event must be {"value": "<string>"}`, EXIT.inputInvalid);
+  else if (trigger.kind === "push" && (typeof raw.value !== "object" || raw.value === null || Array.isArray(raw.value)))
+    exec = fail("input", `push trigger: the event must be the webhook payload object`, EXIT.inputInvalid);
+  else if (trigger.kind === "webhook" && !isWebhookEvent(raw.value))
+    exec = fail("input", `webhook trigger '${name}': the event must be {"headers": {...}, "body": ...}`, EXIT.inputInvalid);
+  else {
+    let mapped: unknown;
+    let threw: unknown = undefined;
+    try {
+      mapped =
+        trigger.kind === "poll" ? await trigger.map((raw.value as { value: string }).value)
+        : trigger.kind === "webhook" ? await trigger.map(raw.value as WebhookEvent)
+        : await trigger.map(raw.value);
+    } catch (e) {
+      threw = e ?? new Error("undefined");
+    }
+    if (threw !== undefined) exec = fail("handler", `trigger '${name}' mapper threw: ${(threw as Error)?.message ?? String(threw)}`, EXIT.handlerFailed);
+    else if (mapped === null && trigger.kind === "webhook") exec = { envelope: { status: "skipped", reason: `trigger '${name}' ignored the delivery` }, exitCode: EXIT.ok };
+    else {
+      const r = parseStrict(data.input.schema, mapped, "input");
+      exec = r.ok
+        ? { envelope: { status: "succeeded", output: r.value } satisfies Envelope, exitCode: EXIT.ok }
+        : fail("output", `trigger '${name}': mapped input does not match ${data.input.name}:\n  ${r.issues.join("\n  ")}`, EXIT.outputInvalid);
+    }
+  }
+  return finish(exec, io);
+}
+
+/** Entry point of the compiled binary (and the dev runner). Returns the exit code. */
+export async function runHarness(cfg: HarnessConfig, argv: readonly string[], io: HarnessIO = defaultIO): Promise<number> {
+  const [mode, ...rest] = argv;
+  switch (mode) {
+    case "describe":
+      return describeMode(cfg, rest, io);
+    case "run":
+      return runMode(cfg, rest[0], io);
+    case "map-trigger":
+      return mapTriggerMode(cfg, rest[0], io);
+    default:
+      io.stderr(USAGE);
+      return EXIT.usage;
+  }
+}
+
+export { formatIssues, formatLog };

package/src/harness/result.ts

@@ -0,0 +1,75 @@
+// Writing, printing and uploading the result of `run` / `map-trigger`.
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalJson } from "../util/canonical.ts";
+import { dirEntries, writeTarGz, type TarEntry } from "../util/tar.ts";
+import { redactUrl } from "../ctx/files.ts";
+import type { Envelope } from "./execute.ts";
+
+export const RESULT_BEGIN = "---OLVE-RESULT-BEGIN---";
+export const RESULT_END = "---OLVE-RESULT-END---";
+export const MANIFEST_BEGIN = "---OLVE-MANIFEST-BEGIN---";
+export const MANIFEST_END = "---OLVE-MANIFEST-END---";
+
+/** Atomically writes the envelope to `<work>/output.json`. */
+export function writeEnvelope(work: string, envelope: Envelope): string {
+  mkdirSync(work, { recursive: true });
+  const path = join(work, "output.json");
+  writeFileSync(path + ".partial", canonicalJson(envelope));
+  renameSync(path + ".partial", path);
+  return path;
+}
+
+/** The envelope as one compact line between sentinels (fallback channel via pod logs). */
+export function sentinelBlock(envelope: Envelope): string {
+  return `${RESULT_BEGIN}\n${JSON.stringify(JSON.parse(canonicalJson(envelope)))}\n${RESULT_END}\n`;
+}
+
+/** Packs output.json + files/ into result.tar.gz (deterministic). */
+export async function packResult(work: string, out: string): Promise<void> {
+  const entries: TarEntry[] = [{ path: "output.json", type: "file", mode: 0o644, source: join(work, "output.json") }];
+  const files = join(work, "files");
+  if (existsSync(files)) entries.push({ path: "files", type: "dir", mode: 0o755 }, ...dirEntries(files, "files"));
+  await writeTarGz(out, entries);
+}
+
+const TRANSIENT = (status: number) => status >= 500 || status === 408 || status === 429;
+
+/** PUTs `file` to a pre-signed URL; retries network errors / 5xx / 408 / 429 with backoff, fails fast on other 4xx. */
+export async function uploadFile(
+  url: string,
+  file: string,
+  log: (line: string) => void,
+  opts: { attempts?: number; baseDelayMs?: number } = {},
+): Promise<void> {
+  const attempts = opts.attempts ?? 5;
+  const base = opts.baseDelayMs ?? 1000;
+  for (let i = 1; ; i++) {
+    let status = 0;
+    let detail: string;
+    try {
+      const res = await fetch(url, { method: "PUT", body: Bun.file(file) });
+      status = res.status;
+      if (res.ok) return;
+      detail = `HTTP ${res.status} ${res.statusText}`;
+      await res.body?.cancel();
+    } catch (e) {
+      detail = (e as Error).message;
+    }
+    const transient = status === 0 || TRANSIENT(status);
+    if (!transient || i >= attempts) throw new Error(`upload to ${redactUrl(url)} failed: ${detail}`);
+    log(`upload to ${redactUrl(url)} failed (${detail}); retry ${i}/${attempts - 1}`);
+    await Bun.sleep(base * 2 ** (i - 1));
+  }
+}
+
+/**
+ * Clears results of a previous run in the same $OLVE_DIR (dev loops reuse it): output.json and the
+ * *contents* of files/. The directories themselves are kept (olve-init creates them 1777).
+ */
+export function removeStale(work: string): void {
+  rmSync(join(work, "output.json"), { force: true });
+  rmSync(join(work, "output.json.partial"), { force: true });
+  const files = join(work, "files");
+  if (existsSync(files)) for (const e of readdirSync(files)) rmSync(join(files, e), { recursive: true, force: true });
+}

package/src/harness/validate.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { isModel, isOptional } from "../core/models.ts";
+import type { AnyStep } from "../core/steps.ts";
+
+export type Validation<T> = { ok: true; value: T } | { ok: false; issues: string[] };
+
+export function formatIssues(err: z.ZodError, prefix: string): string[] {
+  return err.issues.map((i) => `${prefix}${i.path.length ? "." + i.path.map(String).join(".") : ""}: ${i.message}`);
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+/**
+ * zod strips unknown keys silently (at every depth). Compares the raw value with the parsed one:
+ * any key present in a raw object but absent from the parsed object at the same place was stripped.
+ */
+export function strippedKeys(raw: unknown, parsed: unknown, path = ""): string[] {
+  if (Array.isArray(raw) && Array.isArray(parsed)) return raw.flatMap((x, i) => strippedKeys(x, parsed[i], `${path}[${i}]`));
+  if (isPlainObject(raw) && isPlainObject(parsed)) {
+    const out: string[] = [];
+    for (const k of Object.keys(raw)) {
+      const p = path ? `${path}.${k}` : k;
+      if (!Object.hasOwn(parsed, k)) out.push(p);
+      else out.push(...strippedKeys(raw[k], parsed[k], p));
+    }
+    return out;
+  }
+  return [];
+}
+
+/** Strict parse: zod validation plus rejection of unknown keys at any depth. */
+export function parseStrict(schema: z.ZodType, value: unknown, prefix: string): Validation<unknown> {
+  const r = schema.safeParse(value);
+  if (!r.success) return { ok: false, issues: formatIssues(r.error, prefix) };
+  const extra = strippedKeys(value, r.data);
+  if (extra.length) return { ok: false, issues: extra.map((k) => `${prefix}.${k}: unknown field (outputs are validated strictly)`) };
+  return { ok: true, value: r.data };
+}
+
+function entrySchema(e: unknown): z.ZodType {
+  if (isOptional(e)) return e.model.schema;
+  if (isModel(e)) return e.schema;
+  return e as z.ZodType;
+}
+
+/** Validates input.json against the step's input entries. Unknown top-level keys are rejected; nested values are parsed (unknown nested keys stripped). */
+export function validateInput(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
+  if (!isPlainObject(raw)) return { ok: false, issues: ["input.json must be a JSON object keyed by the step's input names"] };
+  const issues: string[] = [];
+  const out: Record<string, unknown> = {};
+  const declared = step.input as Record<string, unknown>;
+  for (const k of Object.keys(raw)) if (!Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
+  for (const [k, e] of Object.entries(declared)) {
+    if (!Object.hasOwn(raw, k)) {
+      if (isOptional(e)) continue;
+      issues.push(`input.${k}: missing`);
+      continue;
+    }
+    const r = entrySchema(e).safeParse(raw[k]);
+    if (r.success) out[k] = r.data;
+    else issues.push(...formatIssues(r.error, `input.${k}`));
+  }
+  return issues.length ? { ok: false, issues } : { ok: true, value: out };
+}
+
+/** Validates a handler's return value strictly against the step's output model. */
+export function validateOutput(step: AnyStep, value: unknown): Validation<unknown> {
+  if (!step.output) {
+    if (value === undefined || value === null) return { ok: true, value: null };
+    return { ok: false, issues: [`step '${step.name}' declares no output model but the handler returned a value`] };
+  }
+  return parseStrict(step.output.schema, value, "output");
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/// <reference path="./assets.d.ts" />
+// @olve/pipelines — authoring API (contracts, handlers, pipeline builder).
+export { z } from "zod";
+export { model, fileRef, optional, type Model, type AnyModel, type Infer, type InferInput, type Plain, type FileRef, type Optional } from "./core/models.ts";
+export { secret, type Secret, type DeclaredSecrets } from "./core/secrets.ts";
+export { hmacSha256, githubSignature, bearer, type WebhookVerify, type WebhookEvent } from "./core/webhooks.ts";
+export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
+export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";
+export type { Ctx, RunInfo, Sh, ShOptions, ExecOptions, Http, HttpInit, RetryOptions, OutputFileOptions } from "./ctx/types.ts";
+export type { Ref, Mappable, MapperResult } from "./builder/refs.ts";
+export { pipeline, Pipeline, type PipelineDef, type InRefs, type InitialAvail, type WhenCond, type PushEvent, type StageEntry, type CheckStage, type MapperFn } from "./builder/pipeline.ts";
+export { steps, Source, BuiltImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type HelmDeployOverSshDef, httpHealthCheck, type HttpHealthCheckOptions } from "./library/index.ts";

package/src/library/github-source.ts

@@ -0,0 +1,77 @@
+// steps.gitHubSource — a GitHub repository at a commit, as a `Source`.
+//
+// Runs entirely inside the harness (HTTP + tar extraction in Bun): no git, wget or tar is needed
+// in the image, so v1's busybox-wget TLS footgun (`--no-check-certificate`) is gone.
+import { mkdirSync, mkdtempSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import type { Ctx } from "../ctx/types.ts";
+import type { Secret } from "../core/secrets.ts";
+import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { extractTar } from "../util/tar.ts";
+import { Source } from "./models.ts";
+
+/** Image the step runs in. The work happens in the harness, so any image would do. */
+export const GITHUB_SOURCE_IMAGE = "alpine:3.22";
+
+const input = { repo: z.string().regex(/^[\w.-]+\/[\w.-]+$/, "expected owner/name"), sha: z.string().min(1) };
+export type GitHubSourceInput = typeof input;
+
+export interface GitHubSourceDef<N extends string, T extends string> {
+  name: LiteralName<N>;
+  /** What the step does, shown in the UI. Required; may be empty. */
+  description: string;
+  /** Token sent to the GitHub API (needed for private repositories; raises the rate limit). */
+  token?: Secret<T>;
+  timeoutSeconds?: number;
+}
+
+/** Tarball URL of `repo` at `sha` (the API redirects to codeload.github.com). */
+export const gitHubTarballUrl = (repo: string, sha: string): string => `https://api.github.com/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
+
+/**
+ * Downloads `repo` at `sha` from GitHub as a tarball and outputs it as a `Source` whose `tree` is the
+ * repository root (the tarball's single `<owner>-<repo>-<sha>/` directory, stripped).
+ * Input `{ repo: "owner/name", sha }` is a plain schema, so the stage needs a mapper.
+ */
+export function gitHubSource<const N extends string, const T extends string = never>(
+  def: GitHubSourceDef<N, T>,
+): Step<N, GitHubSourceInput, typeof Source, T> & LibraryStep {
+  return makeStep(
+    "gitHubSource",
+    { name: def.name, description: def.description, image: GITHUB_SOURCE_IMAGE, input, output: Source, secrets: def.token ? [def.token] : [], timeoutSeconds: def.timeoutSeconds },
+    {
+      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}) }),
+      async run({ repo, sha }: { repo: string; sha: string }, ctx: Ctx) {
+        const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
+        if (def.token) headers.authorization = `Bearer ${ctx.secrets[def.token.name]}`;
+        const url = gitHubTarballUrl(repo, sha);
+        mkdirSync(ctx.tmpDir, { recursive: true });
+        const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
+        const archive = join(dir, "repo.tar.gz");
+
+        ctx.log("fetching source", { repo, sha });
+        // Retries network errors and 5xx; a 4xx (bad sha, no access) fails at once.
+        const status = await ctx.retry({ attempts: 4, delaySeconds: 2, backoff: 2 }, async () => {
+          const res = await ctx.http.fetch(url, { headers });
+          if (res.status >= 500) throw new Error(`HTTP ${res.status} from ${url}`);
+          if (res.ok) await Bun.write(archive, res);
+          return res.status;
+        });
+        if (status < 200 || status >= 300) {
+          throw new Error(`cannot fetch ${repo}@${sha}: HTTP ${status} from ${url}${def.token ? "" : " (no token configured: a private repository needs one)"}`);
+        }
+
+        const extracted = join(dir, "x");
+        mkdirSync(extracted);
+        await extractTar(archive, extracted);
+        // GitHub tarballs hold one top-level directory, plus a pax_global_header entry (the commit id)
+        // that some extractors materialise as a file.
+        const roots = readdirSync(extracted).filter((e) => e !== "pax_global_header" && statSync(join(extracted, e)).isDirectory());
+        if (roots.length !== 1) throw new Error(`unexpected tarball layout for ${repo}@${sha}: top-level entries ${JSON.stringify(readdirSync(extracted))}`);
+        const tree = await ctx.output.dir(join(extracted, roots[0]!), { name: "tree" });
+        return { repo, sha, tree };
+      },
+    },
+  ) as never;
+}

package/src/library/helm-deploy-ssh.ts

@@ -0,0 +1,151 @@
+// steps.helmDeployOverSsh — import a built image into a k3s host's containerd and helm-upgrade a
+// release there, over SSH; optionally verify an HTTP health endpoint afterwards.
+//
+// Ported from v1's olve-lib.sh (olve_ssh_host, olve_image_import, olve_helm_deploy) and
+// deploy-beta.sh (rollout wait + health loop); the footguns are kept as comments below.
+import { chmodSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Ctx } from "../ctx/types.ts";
+import type { FileRef } from "../core/models.ts";
+import type { Secret } from "../core/secrets.ts";
+import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { httpHealthCheck } from "./http-health.ts";
+import { BuiltImage, HelmRelease, Source } from "./models.ts";
+
+/** Alpine: `apk add openssh-client` at run time gives ssh/scp (the health check runs in the harness). */
+export const HELM_DEPLOY_IMAGE = "alpine:3.22";
+
+/**
+ * Footgun: import via the k3s containerd socket, NOT the default one — kubelet only sees images in
+ * the k3s instance's `k8s.io` namespace (otherwise pods fail with ErrImageNeverPull).
+ */
+export const K3S_IMAGE_IMPORT = "sudo nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load";
+
+const ROLLOUT_TIMEOUT = "120s";
+
+const input = { source: Source, image: BuiltImage };
+export type HelmDeployOverSshInput = typeof input;
+
+export interface HelmDeployOverSshDef<N extends string, K extends string> {
+  name: LiteralName<N>;
+  /** What the step does, shown in the UI. Required; may be empty. */
+  description: string;
+  /** SSH target, `user@host`. The user needs passwordless sudo for nerdctl, and helm/kubectl with a kubeconfig. */
+  host: string;
+  /** Private key for `host`. */
+  sshKey: Secret<K>;
+  /** Helm release name; the chart's Deployment is expected to be named the same (rollout wait). */
+  release: string;
+  namespace: string;
+  /** Chart directory inside the source tree, e.g. `helm`. */
+  chart: string;
+  /** Values files, relative to the chart directory (`-f`, in order). */
+  values?: readonly string[];
+  /**
+   * Chart-specific `--set` flags (e.g. `{ "slo.enabled": "false" }`). The image flags are added by
+   * the step and always win: `image.repository`, `image.tag`, `image.pullPolicy=Never`.
+   */
+  set?: Readonly<Record<string, string>>;
+  /** After the rollout, GET this URL until it returns 2xx, 5 × 5 s (`httpHealthCheck`), or fail the step. */
+  healthUrl?: string;
+  timeoutSeconds?: number;
+}
+
+const SAFE = /^[A-Za-z0-9_\/.:=@%+,-]+$/;
+/** POSIX shell quoting (safe words are left bare, so logs stay readable). */
+export function shq(s: string): string {
+  return SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Remote `helm upgrade --install`, run from inside the copied chart directory. */
+export function helmUpgradeCommand(o: {
+  remoteChart: string;
+  release: string;
+  namespace: string;
+  values: readonly string[];
+  set: Readonly<Record<string, string>>;
+  repository: string;
+  tag: string;
+}): string {
+  // Chart-relative values paths (`-f values-beta.yaml`) resolve because helm runs from inside the
+  // copied chart dir. Extra flags come before the image flags, so the image overrides win. The image
+  // is local to the node (imported above), never pulled: pullPolicy=Never.
+  const flags = [
+    ...o.values.flatMap((v) => ["-f", v]),
+    ...Object.entries(o.set).flatMap(([k, v]) => ["--set", `${k}=${v}`]),
+    "--set", `image.repository=${o.repository}`,
+    "--set", `image.tag=${o.tag}`,
+    "--set", "image.pullPolicy=Never",
+  ];
+  return [
+    `cd ${shq(o.remoteChart)}`,
+    ["helm", "upgrade", "--install", o.release, ".", "-n", o.namespace, ...flags].map(shq).join(" "),
+    `cd / && rm -rf ${shq(o.remoteChart)}`,
+  ].join(" && ");
+}
+
+/**
+ * Deploys `image` with the Helm chart at `<source>/<chart>` on a k3s host over SSH:
+ * stream the image tar into the host's k3s containerd, copy the chart, `helm upgrade --install`,
+ * wait for `deploy/<release>` to roll out, then (with `healthUrl`) poll the health endpoint.
+ */
+export function helmDeployOverSsh<const N extends string, const K extends string>(
+  def: HelmDeployOverSshDef<N, K>,
+): Step<N, HelmDeployOverSshInput, typeof HelmRelease, K> & LibraryStep {
+  const values = def.values ?? [];
+  const set = def.set ?? {};
+  return makeStep(
+    "helmDeployOverSsh",
+    { name: def.name, description: def.description, image: HELM_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.sshKey], timeoutSeconds: def.timeoutSeconds },
+    {
+      manifestConfig: () => ({
+        host: def.host,
+        sshKey: def.sshKey.name,
+        release: def.release,
+        namespace: def.namespace,
+        chart: def.chart,
+        values: [...values],
+        set: { ...set },
+        ...(def.healthUrl ? { healthUrl: def.healthUrl } : {}),
+      }),
+      async run(
+        { source, image }: { source: { tree: FileRef }; image: { repository: string; tag: string; tar: FileRef } },
+        ctx: Ctx,
+      ) {
+        const tree = await ctx.files.fetch(source.tree);
+        const chartDir = join(tree, def.chart);
+        if (!existsSync(chartDir) || !statSync(chartDir).isDirectory()) throw new Error(`chart directory '${def.chart}' not found in the source tree`);
+        const imageTar = await ctx.files.fetch(image.tar);
+
+        // SSH setup. The key file needs a trailing newline (OpenSSH rejects the key otherwise) and
+        // mode 600. The host key is not verified (as in v1): the host is reached over the tailnet.
+        await ctx.exec(["apk", "add", "--no-cache", "openssh-client"]);
+        const sshDir = join(ctx.tmpDir, "ssh");
+        mkdirSync(sshDir, { recursive: true, mode: 0o700 });
+        const keyFile = join(sshDir, "id");
+        const key = ctx.secrets[def.sshKey.name]!;
+        writeFileSync(keyFile, key.endsWith("\n") ? key : key + "\n", { mode: 0o600 });
+        chmodSync(keyFile, 0o600);
+        const opts = ["-i", keyFile, "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR", "-o", "BatchMode=yes"];
+        const ssh = (remote: string) => ctx.exec(["ssh", ...opts, def.host, remote]);
+
+        const ref = `${image.repository}:${image.tag}`;
+        ctx.log("importing image", { image: ref, host: def.host });
+        // Streamed over ssh's stdin (ctx.exec has none, hence the shell redirect).
+        await ctx.sh(["ssh", ...opts, def.host, K3S_IMAGE_IMPORT].map(shq).join(" ") + ` < ${shq(imageTar)}`);
+
+        const remoteChart = `/tmp/${def.release}-helm-${def.namespace}`;
+        ctx.log("helm upgrade", { release: def.release, namespace: def.namespace, image: ref });
+        await ssh(`rm -rf ${shq(remoteChart)}`);
+        await ctx.exec(["scp", ...opts, "-r", chartDir, `${def.host}:${remoteChart}`]);
+        await ssh(helmUpgradeCommand({ remoteChart, release: def.release, namespace: def.namespace, values, set, repository: image.repository, tag: image.tag }));
+
+        ctx.log("waiting for rollout", { deployment: def.release });
+        await ssh(`kubectl -n ${shq(def.namespace)} rollout status ${shq(`deploy/${def.release}`)} --timeout=${ROLLOUT_TIMEOUT}`);
+
+        if (def.healthUrl) await httpHealthCheck(ctx, def.healthUrl);
+        return { release: def.release, namespace: def.namespace, image: ref };
+      },
+    },
+  ) as never;
+}

package/src/library/http-health.ts

@@ -0,0 +1,34 @@
+// httpHealthCheck — GET a URL until it answers 2xx, or fail.
+//
+// The general HTTP health check (ported from v1's deploy-beta.sh curl loop). Library steps use it
+// (helmDeployOverSsh's `healthUrl`), and it is exported for custom handlers, which get it with
+// their own retry policy. Runs in the harness (Bun fetch), so the image needs no curl.
+import type { Ctx } from "../ctx/types.ts";
+
+export interface HttpHealthCheckOptions {
+  /** Total attempts (v1: 5). */
+  attempts?: number;
+  /** Delay between attempts, in seconds (v1: 5). */
+  delaySeconds?: number;
+  /** Request headers (e.g. an Authorization header built from a secret). */
+  headers?: Record<string, string>;
+}
+
+/** Defaults match v1's deploy-beta.sh: 5 attempts, 5 s apart. */
+export const HTTP_HEALTH_DEFAULTS = { attempts: 5, delaySeconds: 5 } as const;
+
+/**
+ * GETs `url` until it returns a 2xx status (redirects are followed), retrying network errors and
+ * non-2xx statuses. Throws the last error (status + URL, query redacted) once the attempts run out.
+ */
+export async function httpHealthCheck(
+  ctx: Pick<Ctx, "http" | "retry" | "log">,
+  url: string,
+  opts: HttpHealthCheckOptions = {},
+): Promise<void> {
+  const attempts = opts.attempts ?? HTTP_HEALTH_DEFAULTS.attempts;
+  const delaySeconds = opts.delaySeconds ?? HTTP_HEALTH_DEFAULTS.delaySeconds;
+  ctx.log("checking health", { url: url.split("?")[0]!, attempts });
+  await ctx.retry({ attempts, delaySeconds }, () => ctx.http.expectOk(url, opts.headers ? { headers: opts.headers } : undefined));
+  ctx.log("health OK", { url: url.split("?")[0]! });
+}