@olivervea/pipelines 2.0.0-beta.1 → 2.0.0-beta.3

package/src/describe/describe.ts

@@ -20,7 +20,7 @@ export class DescribeError extends Error {
 }
 
 export interface DescribeOptions {
-  /** Step names that have a handler file (`handlers/<name>.ts`). */
+  /** Step names that have a handler (a `handlers/*.ts` default-exporting `implement(step, …)`). */
   handlerNames: Iterable<string>;
   /** Step name → handler hash (from the build; includes the harness identity). */
   handlerHashes: Readonly<Record<string, string>>;
@@ -198,7 +198,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     let handlerHash: string;
     let config: Record<string, unknown> | undefined;
     if (s.kind === "custom") {
-      if (!handlerNames.has(s.name)) problems.push(`${at} has no handler (expected handlers/${s.name}.ts default-exporting implement(${camel(s.name)}, …))`);
+      if (!handlerNames.has(s.name)) problems.push(`${at} has no handler (add a handlers/*.ts default-exporting implement(${camel(s.name)}, …))`);
       handlerHash = opts.handlerHashes[s.name] ?? "";
       if (handlerNames.has(s.name) && !handlerHash) problems.push(`${at}: no handler hash was computed`);
     } else if (s.builtin) {
@@ -329,19 +329,26 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     return { step: describeStep({ step: fh.step }, new Map(), true), steps: scope };
   }).filter((x) => x !== undefined);
 
-  // ── handler files without a step ──
+  // ── handlers without a step ──
   for (const h of handlerNames) {
     const s = steps.get(h);
-    if (!s) problems.push(`handlers/${h}.ts does not match any step of the pipeline`);
-    else if (s.kind !== "custom") problems.push(`handlers/${h}.ts: '${h}' is a library step (${s.kind}) and must not have a handler file`);
+    if (!s) problems.push(`a handler implements step '${h}', which is not in the pipeline`);
+    else if (s.kind !== "custom") problems.push(`a handler implements '${h}', a library step (${s.kind}) that carries its own implementation`);
   }
 
   // ── triggers ──
   const triggerNames = new Set<string>();
   const triggers: TriggerT[] = data.triggers.map((t) => {
-    if (triggerNames.has(t.name)) problems.push(`duplicate trigger '${t.name}'${t.kind === "push" ? " (onPush may be used once)" : " (give each onPoll a distinct name)"}`);
+    if (triggerNames.has(t.name)) problems.push(`duplicate trigger '${t.name}'${t.kind === "push" ? " (onPush may be used once)" : " (give each onPoll and onWebhook a distinct name)"}`);
     triggerNames.add(t.name);
     if (t.kind === "push") return { kind: "push", name: "push" };
+    if (t.kind === "webhook") {
+      if (!STEP_NAME.test(t.name)) problems.push(`webhook trigger name '${t.name}' must be lower-case kebab`);
+      const secret = useSecret(t.verify.secret, `webhook '${t.name}'`);
+      if (t.verify.scheme === "bearer") return { kind: "webhook", name: t.name, verify: { scheme: "bearer", secret } };
+      if (!t.verify.header) problems.push(`webhook '${t.name}': the signature header must not be empty`);
+      return { kind: "webhook", name: t.name, verify: { scheme: "hmac-sha256", secret, header: t.verify.header, prefix: t.verify.prefix } };
+    }
     if (!STEP_NAME.test(t.name)) problems.push(`poll trigger name '${t.name}' must be lower-case kebab`);
     if (!(Number.isInteger(t.intervalSeconds) && t.intervalSeconds > 0)) problems.push(`poll '${t.name}': intervalSeconds must be a positive integer`);
     const declared = new Set(t.secrets.map((s) => useSecret(s, `poll '${t.name}'`)));

package/src/describe/manifest-schema.ts

@@ -90,6 +90,21 @@ export const Trigger = z
         intervalSeconds: z.number().int().positive(),
       })
       .describe("Background poller."),
+    z
+      .strictObject({
+        kind: z.literal("webhook"),
+        name: z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/),
+        verify: z.discriminatedUnion("scheme", [
+          z.strictObject({
+            scheme: z.literal("hmac-sha256"),
+            secret: secretName,
+            header: z.string().min(1),
+            prefix: z.string().describe("Text before the hex digest in the header, e.g. 'sha256='."),
+          }),
+          z.strictObject({ scheme: z.literal("bearer"), secret: secretName }),
+        ]),
+      })
+      .describe("Inbound HTTP delivery to /api/hooks/<pipeline id>/<name>. Event = {headers, body}; a null mapping ignores it."),
   ])
   .meta({ id: "Trigger" });
 
@@ -102,7 +117,7 @@ export const Manifest = z
     harness: z
       .strictObject({
         bun: z.string().describe("Bun runtime version compiled into the binary."),
-        sdk: z.string().describe("@olve/pipelines package version."),
+        sdk: z.string().describe("@olivervea/pipelines package version."),
         sdkHash: hash.describe("Hash of the SDK runtime sources + zod version."),
       })
       .describe("Harness identity. Already folded into every handlerHash."),

package/src/dev/cli.ts

@@ -17,7 +17,7 @@ const USAGE = `usage: olve-dev describe <dir> [--sentinels]
        olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]`;
 
 export async function devConfig(dir: string, withHashes: boolean): Promise<HarnessConfig> {
-  const project = loadProject(dir);
+  const project = await loadProject(dir);
   const mod = (await import(project.pipelineFile)) as { default?: unknown };
   if (!mod.default) throw new ProjectError(`${project.pipelineFile} has no default export (export default pipeline({...})...)`);
   const harness = harnessInfo();

package/src/harness/index.ts

@@ -1,4 +1,4 @@
-// @olve/pipelines/harness — the runtime the build tool compiles into the step binary.
+// @olivervea/pipelines/harness — the runtime the build tool compiles into the step binary.
 export { runHarness, defaultIO, allSteps, resolveStepFunction, type HarnessConfig, type HandlerRegistry, type HarnessIO } from "./main.ts";
 export { EXIT } from "./exit.ts";
 export { ENV, paths, runInfoFromEnv } from "./env.ts";

package/src/harness/main.ts

@@ -6,6 +6,7 @@ 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";
@@ -76,17 +77,17 @@ export async function resolveStepFunction(step: AnyStep, handlers: HandlerRegist
     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)`;
+  if (!load) return `step '${step.name}' has no handler`;
   let mod: { default: unknown };
   try {
     mod = await load();
   } catch (e) {
-    return `handlers/${step.name}.ts failed to load: ${(e as Error)?.stack ?? String(e)}`;
+    return `the handler of step '${step.name}' 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 (!isImplementation(impl)) return `the handler of step '${step.name}' 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 `the handler of step '${step.name}' implements a different step object (it must be implement(<the '${step.name}' step from pipeline.ts>, …))`;
   return impl.handler as unknown as StepFunction;
 }
 
@@ -162,6 +163,12 @@ async function runMode(cfg: HarnessConfig, name: string | undefined, io: Harness
   }
 }
 
+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);
@@ -181,15 +188,21 @@ async function mapTriggerMode(cfg: HarnessConfig, name: string | undefined, io:
     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) : await trigger.map(raw.value);
+      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

package/src/index.ts

@@ -1,11 +1,12 @@
 /// <reference path="./assets.d.ts" />
-// @olve/pipelines — authoring API (contracts, handlers, pipeline builder).
+// @olivervea/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";
+export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type HelmDeployOverSshDef, httpHealthCheck, type HttpHealthCheckOptions, sshSession, shq, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";

package/src/library/checks.ts

@@ -0,0 +1,23 @@
+// Checks for deployed apps, used from custom test handlers.
+import type { Ctx } from "../ctx/types.ts";
+
+/** The in-cluster URL of a release's Service, assuming the chart names it after the release. */
+export function serviceUrl(release: { release: string; namespace: string }): string {
+  return `http://${release.release}.${release.namespace}.svc.cluster.local`;
+}
+
+/**
+ * Checks `url` serves a single-page app: `GET <url>/` references a `/assets/*.js` bundle (Vite's
+ * layout), and the bundle is served as JavaScript. Returns the page, for app-specific checks.
+ */
+export async function checkSpa(ctx: Pick<Ctx, "http" | "log">, url: string): Promise<{ html: string; bundle: string }> {
+  const base = url.replace(/\/$/, "");
+  const html = await (await ctx.http.expectOk(`${base}/`)).text();
+  const bundle = html.match(/src="(\/assets\/[^"]+\.js)"/)?.[1];
+  if (bundle === undefined) throw new Error(`${base}/ does not reference an /assets/*.js bundle`);
+  const js = await ctx.http.expectOk(`${base}${bundle}`);
+  await js.body?.cancel().catch(() => {});
+  if (!(js.headers.get("content-type")?.includes("javascript") ?? false)) throw new Error(`${base}${bundle} is not served as JavaScript`);
+  ctx.log("SPA served", { url: base, bundle });
+  return { html, bundle };
+}

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

@@ -1,16 +1,20 @@
-// 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.
+// steps.helmDeployOverSsh — get built images onto a k3s host 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 { existsSync, statSync } 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";
+import type { Simplify } from "../core/types.ts";
+import { httpHealthCheck, type HttpHealthCheckOptions } from "./http-health.ts";
+import { BuiltImage, HelmRelease, PushedImage, Source } from "./models.ts";
+import { shq, sshSession } from "./ssh.ts";
+
+export { shq } from "./ssh.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";
@@ -20,13 +24,18 @@ export const HELM_DEPLOY_IMAGE = "alpine:3.22";
  * 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";
+/** Registry images are pulled the same way before the rollout, so the rollout doesn't wait on the pull. */
+export const K3S_IMAGE_PULL = "sudo nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io pull -q";
 
-const ROLLOUT_TIMEOUT = "120s";
+export const DEFAULT_ROLLOUT_TIMEOUT_SECONDS = 120;
 
-const input = { source: Source, image: BuiltImage };
-export type HelmDeployOverSshInput = typeof input;
+type DefaultImages = { readonly image: "image" };
+type ImageModel<R extends boolean> = R extends true ? typeof PushedImage : typeof BuiltImage;
+export type HelmDeployOverSshInput<Im extends Record<string, string> = DefaultImages, R extends boolean = false> = Simplify<
+  { readonly source: typeof Source } & { readonly [K in keyof Im]: ImageModel<R> }
+>;
 
-export interface HelmDeployOverSshDef<N extends string, K extends string> {
+export interface HelmDeployOverSshDef<N extends string, K extends string, Im extends Record<string, string> = DefaultImages, R extends boolean = false> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
@@ -34,7 +43,7 @@ export interface HelmDeployOverSshDef<N extends string, K extends string> {
   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). */
+  /** Helm release name. */
   release: string;
   namespace: string;
   /** Chart directory inside the source tree, e.g. `helm`. */
@@ -42,19 +51,36 @@ export interface HelmDeployOverSshDef<N extends string, K extends 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`.
+   * Chart-specific `--set` flags (e.g. `{ "ingress.enabled": "false" }`). The image flags are added by
+   * the step and always win: `<prefix>.repository`, `<prefix>.tag`, `<prefix>.pullPolicy`.
    */
   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;
+  /**
+   * The images to deploy: step input key → the chart's values prefix for that image. Each input is a
+   * `BuiltImage` (or `PushedImage` with `fromRegistry`). Default `{ image: "image" }`; several images
+   * need a mapper, e.g. `{ server: "image", web: "web.image" }`.
+   */
+  images?: Im & { readonly source?: never };
+  /**
+   * The images are `PushedImage`s from a registry (`imageBuild` with `push`): pulled on the host
+   * first, then `pullPolicy=IfNotPresent`. Default: `BuiltImage` tarballs, imported on the host, then
+   * `pullPolicy=Never`.
+   */
+  fromRegistry?: R & (boolean extends R ? "❌ fromRegistry must be a literal true or false (use `as const` on a shared config object)" : unknown);
+  /** Rollouts to wait for, in order: `deploy/<name>` for a bare name. Default: the release name. */
+  deployments?: readonly string[];
+  /** Per rollout (`kubectl rollout status --timeout`). Default 120. */
+  rolloutTimeoutSeconds?: number;
+  /** After the rollouts, GET this URL until it returns 2xx (`httpHealthCheck`: 5 × 5 s unless given), or fail the step. */
+  healthUrl?: string | ({ url: string } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
   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, `'\\''`)}'`;
+export interface HelmImageFlags {
+  prefix: string;
+  repository: string;
+  tag: string;
+  pullPolicy: "Never" | "IfNotPresent";
 }
 
 /** Remote `helm upgrade --install`, run from inside the copied chart directory. */
@@ -64,18 +90,18 @@ export function helmUpgradeCommand(o: {
   namespace: string;
   values: readonly string[];
   set: Readonly<Record<string, string>>;
-  repository: string;
-  tag: string;
+  images: readonly HelmImageFlags[];
 }): 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.
+  // copied chart dir. Extra flags come before the image flags, so the image overrides win.
   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",
+    ...o.images.flatMap((i) => [
+      "--set", `${i.prefix}.repository=${i.repository}`,
+      "--set", `${i.prefix}.tag=${i.tag}`,
+      "--set", `${i.prefix}.pullPolicy=${i.pullPolicy}`,
+    ]),
   ];
   return [
     `cd ${shq(o.remoteChart)}`,
@@ -85,15 +111,31 @@ export function helmUpgradeCommand(o: {
 }
 
 /**
- * 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.
+ * Deploys images with the Helm chart at `<source>/<chart>` on a k3s host over SSH: get each image
+ * into the host's k3s containerd (stream a tarball in, or pull from the registry), copy the chart,
+ * `helm upgrade --install`, wait for each rollout, 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 {
+export function helmDeployOverSsh<
+  const N extends string,
+  const K extends string,
+  const Im extends Record<string, string> = DefaultImages,
+  const R extends boolean = false,
+>(def: HelmDeployOverSshDef<N, K, Im, R>): Step<N, HelmDeployOverSshInput<Im, R>, typeof HelmRelease, K> & LibraryStep {
   const values = def.values ?? [];
   const set = def.set ?? {};
+  const images: Record<string, string> = def.images ?? { image: "image" };
+  const imageEntries = Object.entries(images);
+  const fromRegistry = def.fromRegistry === true;
+  const deployments = def.deployments ?? [def.release];
+  const rolloutTimeout = def.rolloutTimeoutSeconds ?? DEFAULT_ROLLOUT_TIMEOUT_SECONDS;
+  const health = typeof def.healthUrl === "string" ? { url: def.healthUrl } : def.healthUrl;
+  if (imageEntries.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': images must not be empty`);
+  if ("source" in images) throw new Error(`helmDeployOverSsh '${def.name}': 'source' can't be an image input`);
+  if (deployments.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': deployments must not be empty`);
+  const imageModel = fromRegistry ? PushedImage : BuiltImage;
+  const input = { source: Source, ...Object.fromEntries(imageEntries.map(([key]) => [key, imageModel])) };
+  const isDefaultImages = imageEntries.length === 1 && images.image === "image";
+
   return makeStep(
     "helmDeployOverSsh",
     { name: def.name, description: def.description, image: HELM_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.sshKey], timeoutSeconds: def.timeoutSeconds },
@@ -106,45 +148,48 @@ export function helmDeployOverSsh<const N extends string, const K extends string
         chart: def.chart,
         values: [...values],
         set: { ...set },
-        ...(def.healthUrl ? { healthUrl: def.healthUrl } : {}),
+        ...(isDefaultImages ? {} : { images: { ...images } }),
+        ...(fromRegistry ? { fromRegistry: true } : {}),
+        ...(def.deployments ? { deployments: [...def.deployments] } : {}),
+        ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
+        ...(def.healthUrl !== undefined ? { healthUrl: typeof def.healthUrl === "string" ? def.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);
+      async run(input: Record<string, { repository: string; tag: string; tar?: FileRef }> & { source: { tree: FileRef } }, ctx: Ctx) {
+        const tree = await ctx.files.fetch(input.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 ssh = await sshSession(ctx, { host: def.host, key: ctx.secrets[def.sshKey.name]! });
+        const flags: HelmImageFlags[] = [];
+        for (const [key, prefix] of imageEntries) {
+          const image = input[key]!;
+          const ref = `${image.repository}:${image.tag}`;
+          if (fromRegistry) {
+            ctx.log("pulling image", { image: ref, host: def.host });
+            await ssh.run(`${K3S_IMAGE_PULL} ${shq(ref)}`);
+          } else {
+            const tar = await ctx.files.fetch(image.tar!);
+            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.shell(K3S_IMAGE_IMPORT)} < ${shq(tar)}`);
+          }
+          flags.push({ prefix, repository: image.repository, tag: image.tag, pullPolicy: fromRegistry ? "IfNotPresent" : "Never" });
+        }
 
         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("helm upgrade", { release: def.release, namespace: def.namespace, images: flags.map((f) => `${f.repository}:${f.tag}`).join(" ") });
+        await ssh.run(`rm -rf ${shq(remoteChart)}`);
+        await ssh.copy(chartDir, remoteChart);
+        await ssh.run(helmUpgradeCommand({ remoteChart, release: def.release, namespace: def.namespace, values, set, images: flags }));
 
-        ctx.log("waiting for rollout", { deployment: def.release });
-        await ssh(`kubectl -n ${shq(def.namespace)} rollout status ${shq(`deploy/${def.release}`)} --timeout=${ROLLOUT_TIMEOUT}`);
+        for (const d of deployments) {
+          const target = d.includes("/") ? d : `deploy/${d}`;
+          ctx.log("waiting for rollout", { deployment: target });
+          await ssh.run(`kubectl -n ${shq(def.namespace)} rollout status ${shq(target)} --timeout=${rolloutTimeout}s`);
+        }
 
-        if (def.healthUrl) await httpHealthCheck(ctx, def.healthUrl);
-        return { release: def.release, namespace: def.namespace, image: ref };
+        if (health) await httpHealthCheck(ctx, health.url, { attempts: health.attempts, delaySeconds: health.delaySeconds });
+        return { release: def.release, namespace: def.namespace, image: `${flags[0]!.repository}:${flags[0]!.tag}` };
       },
     },
   ) as never;