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

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

@@ -8,11 +8,14 @@ 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 type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.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";
+import { helmDeployOverSshTarget, type HelmDeploySshTargetDef, type HelmTargetDeployInput } from "./helm-deploy.ts";
 
 export { shq } from "./ssh.ts";
 
@@ -31,30 +34,40 @@ export const DEFAULT_ROLLOUT_TIMEOUT_SECONDS = 120;
 
 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 type HelmDeployOverSshInput<
+  Im extends Record<string, string> = DefaultImages,
+  R extends boolean = false,
+  Rf extends Record<string, string> = {},
+> = Simplify<
+  { readonly source: typeof Source } & { readonly [K in keyof Im]: ImageModel<R> } & { readonly [K in keyof Rf]: typeof PushedImage }
 >;
 
-export interface HelmDeployOverSshDef<N extends string, K extends string, Im extends Record<string, string> = DefaultImages, R extends boolean = false> {
+export interface HelmDeployOverSshDef<
+  N extends string,
+  K extends string,
+  Im extends Record<string, string> = DefaultImages,
+  R extends boolean = false,
+  Rf extends Record<string, 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;
+  host: Configurable<string>;
   /** Private key for `host`. */
   sshKey: Secret<K>;
   /** Helm release name. */
-  release: string;
-  namespace: string;
+  release: Configurable<string>;
+  namespace: Configurable<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[];
+  values?: Configurable<readonly string[]>;
   /**
    * 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>>;
+  set?: Configurable<Readonly<Record<string, 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
@@ -67,12 +80,19 @@ export interface HelmDeployOverSshDef<N extends string, K extends string, Im ext
    * `pullPolicy=Never`.
    */
   fromRegistry?: R & (boolean extends R ? "❌ fromRegistry must be a literal true or false (use `as const` on a shared config object)" : unknown);
+  /**
+   * Registry images the chart only references (not run by the release's own pods, e.g. an image the
+   * app starts Jobs with): step input key → values prefix. Each input is a `PushedImage`; the step sets
+   * `<prefix>.repository`, `<prefix>.tag` and `<prefix>.digest` and does not pull it on the host. Works
+   * next to tarball `images`.
+   */
+  imageRefs?: Rf & { readonly source?: never };
   /** 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">);
+  healthUrl?: Configurable<string> | ({ url: Configurable<string> } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
   timeoutSeconds?: number;
 }
 
@@ -81,19 +101,30 @@ export interface HelmImageFlags {
   repository: string;
   tag: string;
   pullPolicy: "Never" | "IfNotPresent";
+  /** Pins the image: `<prefix>.digest` (the chart renders `repository:tag@digest`). */
+  digest?: string;
 }
 
-/** Remote `helm upgrade --install`, run from inside the copied chart directory. */
-export function helmUpgradeCommand(o: {
-  remoteChart: string;
-  release: string;
-  namespace: string;
+/** A registry image the chart only references (`imageRefs`). */
+export interface HelmImageRefFlags {
+  prefix: string;
+  repository: string;
+  tag: string;
+  digest: string;
+}
+
+export interface HelmFlagOptions {
   values: readonly string[];
   set: Readonly<Record<string, string>>;
   images: readonly HelmImageFlags[];
-}): string {
+  imageRefs?: readonly HelmImageRefFlags[];
+}
+
+/** `helm upgrade` flags: values files, `--set`, then the image flags (which win). */
+export function helmFlags(o: HelmFlagOptions): 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.
+  // --set-string: a tag like `2026.10` or `1e5` would otherwise be parsed as a number.
   const flags = [
     ...o.values.flatMap((v) => ["-f", v]),
     ...Object.entries(o.set).flatMap(([k, v]) => ["--set", `${k}=${v}`]),
@@ -101,8 +132,20 @@ export function helmUpgradeCommand(o: {
       "--set", `${i.prefix}.repository=${i.repository}`,
       "--set", `${i.prefix}.tag=${i.tag}`,
       "--set", `${i.prefix}.pullPolicy=${i.pullPolicy}`,
+      ...(i.digest ? ["--set-string", `${i.prefix}.digest=${i.digest}`] : []),
+    ]),
+    ...(o.imageRefs ?? []).flatMap((i) => [
+      "--set-string", `${i.prefix}.repository=${i.repository}`,
+      "--set-string", `${i.prefix}.tag=${i.tag}`,
+      "--set-string", `${i.prefix}.digest=${i.digest}`,
     ]),
   ];
+  return flags;
+}
+
+/** Remote `helm upgrade --install`, run from inside the copied chart directory. */
+export function helmUpgradeCommand(o: HelmFlagOptions & { remoteChart: string; release: string; namespace: string }): string {
+  const flags = helmFlags(o);
   return [
     `cd ${shq(o.remoteChart)}`,
     ["helm", "upgrade", "--install", o.release, ".", "-n", o.namespace, ...flags].map(shq).join(" "),
@@ -110,87 +153,152 @@ export function helmUpgradeCommand(o: {
   ].join(" && ");
 }
 
+/** One image to get onto the host before the upgrade. */
+export interface HostImage {
+  repository: string;
+  tag: string;
+  digest?: string;
+  /** An image tarball to stream in; without one the image is pulled from its registry. */
+  tar?: string;
+}
+
+/**
+ * Over SSH: get each image into the host's k3s containerd, copy the chart (with any generated values
+ * files in it), `helm upgrade --install`, then wait for each rollout.
+ */
+export async function deployOverSsh(
+  ctx: Ctx,
+  o: {
+    host: string;
+    key: string;
+    chartDir: string;
+    release: string;
+    namespace: string;
+    hostImages: readonly HostImage[];
+    flags: HelmFlagOptions;
+    deployments: readonly string[];
+    rolloutTimeoutSeconds: number;
+  },
+): Promise<void> {
+  const ssh = await sshSession(ctx, { host: o.host, key: o.key });
+  for (const image of o.hostImages) {
+    if (image.tar) {
+      ctx.log("importing image", { image: `${image.repository}:${image.tag}`, host: o.host });
+      // Streamed over ssh's stdin (ctx.exec has none, hence the shell redirect).
+      await ctx.sh(`${ssh.shell(K3S_IMAGE_IMPORT)} < ${shq(image.tar)}`);
+    } else {
+      const ref = image.digest ? `${image.repository}@${image.digest}` : `${image.repository}:${image.tag}`;
+      ctx.log("pulling image", { image: ref, host: o.host });
+      await ssh.run(`${K3S_IMAGE_PULL} ${shq(ref)}`);
+    }
+  }
+  const remoteChart = `/tmp/${o.release}-helm-${o.namespace}`;
+  ctx.log("helm upgrade", { release: o.release, namespace: o.namespace, host: o.host });
+  await ssh.run(`rm -rf ${shq(remoteChart)}`);
+  await ssh.copy(o.chartDir, remoteChart);
+  await ssh.run(helmUpgradeCommand({ ...o.flags, remoteChart, release: o.release, namespace: o.namespace }));
+  for (const d of o.deployments) {
+    const target = d.includes("/") ? d : `deploy/${d}`;
+    ctx.log("waiting for rollout", { deployment: target });
+    await ssh.run(`kubectl -n ${shq(o.namespace)} rollout status ${shq(target)} --timeout=${o.rolloutTimeoutSeconds}s`);
+  }
+}
+
+/** The chart directory inside a fetched source tree, or an error naming it. */
+export function chartDirectory(tree: string, chart: string): string {
+  const dir = join(tree, chart);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`chart directory '${chart}' not found in the source tree`);
+  return dir;
+}
+
 /**
  * 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,
+  const Im extends Record<string, string> = DefaultImages,
+  const Rf extends Record<string, string> = {},
+>(def: HelmDeploySshTargetDef<N, K, Im, Rf>): Step<N, HelmTargetDeployInput<Im, Rf>, 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 Rf extends Record<string, string> = {},
+>(def: HelmDeployOverSshDef<N, K, Im, R, Rf>): Step<N, HelmDeployOverSshInput<Im, R, Rf>, typeof HelmRelease, K> & LibraryStep;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function helmDeployOverSsh(def: any): Step & LibraryStep {
+  return "target" in def ? helmDeployOverSshTarget(def) : helmDeployOverSshLiteral(def);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function helmDeployOverSshLiteral(def: HelmDeployOverSshDef<string, string, any, boolean, any>): Step & LibraryStep {
   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`);
+  if (def.deployments?.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': deployments must not be empty`);
+  const imageRefs: Record<string, string> = def.imageRefs ?? {};
+  const refEntries = Object.entries(imageRefs);
+  if ("source" in imageRefs) throw new Error(`helmDeployOverSsh '${def.name}': 'source' can't be an image input`);
+  for (const [key] of refEntries) if (key in images) throw new Error(`helmDeployOverSsh '${def.name}': '${key}' is both in images and imageRefs`);
   const imageModel = fromRegistry ? PushedImage : BuiltImage;
-  const input = { source: Source, ...Object.fromEntries(imageEntries.map(([key]) => [key, imageModel])) };
+  const input = {
+    source: Source,
+    ...Object.fromEntries(imageEntries.map(([key]) => [key, imageModel])),
+    ...Object.fromEntries(refEntries.map(([key]) => [key, PushedImage])),
+  };
   const isDefaultImages = imageEntries.length === 1 && images.image === "image";
+  const configurable = { host: def.host, release: def.release, namespace: def.namespace, values: def.values ?? [], set: def.set ?? {}, healthUrl: def.healthUrl };
 
   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,
+        host: recordConfigRefs(def.host),
         sshKey: def.sshKey.name,
-        release: def.release,
-        namespace: def.namespace,
+        release: recordConfigRefs(def.release),
+        namespace: recordConfigRefs(def.namespace),
         chart: def.chart,
-        values: [...values],
-        set: { ...set },
+        values: recordConfigRefs(configurable.values),
+        set: recordConfigRefs(configurable.set),
         ...(isDefaultImages ? {} : { images: { ...images } }),
         ...(fromRegistry ? { fromRegistry: true } : {}),
+        ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
         ...(def.deployments ? { deployments: [...def.deployments] } : {}),
         ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
-        ...(def.healthUrl !== undefined ? { healthUrl: typeof def.healthUrl === "string" ? def.healthUrl : { ...def.healthUrl } } : {}),
+        ...(def.healthUrl !== undefined ? { healthUrl: recordConfigRefs(def.healthUrl) } : {}),
       }),
-      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 ssh = await sshSession(ctx, { host: def.host, key: ctx.secrets[def.sshKey.name]! });
+      async run(input: Record<string, { repository: string; tag: string; digest: string; tar?: FileRef }> & { source: { tree: FileRef } }, ctx: Ctx) {
+        const d = resolveConfigRefs(configurable, ctx.config ?? {}) as {
+          host: string; release: string; namespace: string; values: string[]; set: Record<string, string>;
+          healthUrl?: string | ({ url: string } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
+        };
+        const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
+        const hostImages: HostImage[] = [];
         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)}`);
-          }
+          hostImages.push({ repository: image.repository, tag: image.tag, ...(fromRegistry ? {} : { tar: await ctx.files.fetch(image.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, 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 }));
-
-        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`);
-        }
-
+        const refs: HelmImageRefFlags[] = refEntries.map(([key, prefix]) => ({ prefix, repository: input[key]!.repository, tag: input[key]!.tag, digest: input[key]!.digest }));
+        await deployOverSsh(ctx, {
+          host: d.host, key: ctx.secrets[def.sshKey.name]!, chartDir, release: d.release, namespace: d.namespace, hostImages,
+          flags: { values: d.values, set: d.set, images: flags, imageRefs: refs },
+          deployments: def.deployments ?? [d.release], rolloutTimeoutSeconds: rolloutTimeout,
+        });
+        const health = typeof d.healthUrl === "string" ? { url: d.healthUrl } : d.healthUrl;
         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}` };
+        return { release: d.release, namespace: d.namespace, image: `${flags[0]!.repository}:${flags[0]!.tag}` };
       },
     },
+    configurable,
   ) as never;
 }

package/src/library/helm-deploy.ts

@@ -0,0 +1,268 @@
+// Helm deploys to a target from config (`helmTarget()`): steps.helmDeployInCluster runs helm in the step
+// pod against its own cluster; steps.helmDeployOverSsh({ target, … }) runs it on a k3s host. Pick one
+// per target kind with `select`. Images come from a registry, pinned by digest.
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import type { Ctx } from "../ctx/types.ts";
+import type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
+import type { FileRef } from "../core/models.ts";
+import { optional } from "../core/models.ts";
+import type { Secret } from "../core/secrets.ts";
+import { secretRef } from "../core/config.ts";
+import { makeStep, type LibraryStep, type LiteralName, type Step, type StepKind } from "../core/steps.ts";
+import type { Simplify } from "../core/types.ts";
+import { serviceUrl } from "./checks.ts";
+import { chartDirectory, deployOverSsh, DEFAULT_ROLLOUT_TIMEOUT_SECONDS, HELM_DEPLOY_IMAGE, helmFlags, type HelmImageFlags, type HelmImageRefFlags } from "./helm-deploy-ssh.ts";
+import { httpHealthCheck } from "./http-health.ts";
+import { HelmRelease, PushedImage, Source } from "./models.ts";
+
+/** helm 3 on Alpine, for in-cluster deploys (the health check runs in the harness). */
+export const HELM_IMAGE = "alpine/helm:3.16.2";
+
+/** Where the step pod finds its ServiceAccount token (mounted only with the instance's step ServiceAccount). */
+export const SERVICE_ACCOUNT_TOKEN = "/var/run/secrets/kubernetes.io/serviceaccount/token";
+
+function targetVariants<const E extends z.ZodRawShape, const K extends string>(o: Omit<DeployTargetOptions<E, K>, "composeToken"> & { composeToken?: Secret<K> }) {
+  const name = (d: string | undefined) => (d === undefined ? z.string() : z.string().default(d));
+  const common = {
+    namespace: name(o.namespace).describe("Namespace the release is installed into."),
+    release: name(o.release).describe("Helm release name."),
+    values: z.array(z.string()).default([]).describe("Values files, relative to the chart directory (-f, in order)."),
+    set: z.record(z.string(), z.string()).default({}).describe("Extra --set flags."),
+    url: z.string().optional().describe("Base URL step pods reach the release at (health checks, smoke tests); default http://<release>.<namespace>.svc.cluster.local."),
+    ...(o.extend ?? ({} as E)),
+  };
+  const inCluster = z.object({ kind: z.literal("inCluster").describe("helm runs in the step pod against its own cluster (needs the instance's step ServiceAccount)."), ...common });
+  const ssh = z.object({ kind: z.literal("ssh").describe("helm runs on a k3s host over SSH."), host: z.string().describe("user@host"), ...common });
+  const compose = z.object({
+    kind: z.literal("compose").describe("A Docker Compose deployer recreates a service with the image."),
+    deployerUrl: z.string().describe("The deployer's base URL (POST <deployerUrl>/v1/deploy)."),
+    service: z.string().describe("The compose service to recreate."),
+    token: secretRef(o.composeToken ?? ({ kind: "secret", name: "DEPLOYER_TOKEN", description: "" } as Secret<K>)).describe("The deployer's bearer token."),
+    healthUrl: z.string().optional().describe("Checked by the step after the deployer's own health check, when the step can reach it."),
+    ...(o.extend ?? ({} as E)),
+  });
+  const none = z.object({ kind: z.literal("none").describe("Not deployed: the target's steps are left out.") });
+  return { inCluster, ssh, compose, none };
+}
+
+export interface DeployTargetOptions<E extends z.ZodRawShape, K extends string> {
+  /** Default namespace (helm targets). */
+  namespace?: string;
+  /** Default release name (helm targets). */
+  release?: string;
+  /** Fields added to every kind but `none` (e.g. per-target auth overrides). */
+  extend?: E;
+  /** The secret holding the compose deployer's token (`kind: compose`'s `token: { secret: … }`). */
+  composeToken: Secret<K>;
+  /** Adds `kind: none`, a target that isn't deployed (e.g. an optional beta). */
+  optional?: boolean;
+}
+
+/**
+ * The config schema of a deploy target, a union on `kind` to `select` on: `inCluster` and `ssh` (helm),
+ * `compose` (a Docker Compose deployer), and with `optional: true` also `none` (not deployed).
+ * `config("target", "…", z.object({ beta: deployTarget({ optional: true, composeToken: T }), prod: deployTarget({ composeToken: T }) }))`
+ */
+export function deployTarget<const K extends string, const E extends z.ZodRawShape = {}>(o: DeployTargetOptions<E, K> & { optional: true }): z.ZodDiscriminatedUnion<[
+  ReturnType<typeof targetVariants<E, K>>["inCluster"], ReturnType<typeof targetVariants<E, K>>["ssh"], ReturnType<typeof targetVariants<E, K>>["compose"], ReturnType<typeof targetVariants<E, K>>["none"],
+]>;
+export function deployTarget<const K extends string, const E extends z.ZodRawShape = {}>(o: DeployTargetOptions<E, K>): z.ZodDiscriminatedUnion<[
+  ReturnType<typeof targetVariants<E, K>>["inCluster"], ReturnType<typeof targetVariants<E, K>>["ssh"], ReturnType<typeof targetVariants<E, K>>["compose"],
+]>;
+export function deployTarget(o: DeployTargetOptions<z.ZodRawShape, string>): unknown {
+  const v = targetVariants(o);
+  return z.discriminatedUnion("kind", o.optional ? [v.inCluster, v.ssh, v.compose, v.none] : [v.inCluster, v.ssh, v.compose]);
+}
+
+/** A helm-only deploy target (`inCluster | ssh`). */
+export function helmTarget<const E extends z.ZodRawShape = {}>(defaults: { namespace?: string; release?: string } = {}, extend?: E) {
+  const v = targetVariants({ ...defaults, extend });
+  return z.discriminatedUnion("kind", [v.inCluster, v.ssh]);
+}
+
+interface TargetCommon {
+  namespace: string;
+  release: string;
+  values: readonly string[];
+  set: Readonly<Record<string, string>>;
+  url?: string | undefined;
+}
+/** A resolved `kind: inCluster` target. */
+export type InClusterTargetValue = TargetCommon & { kind: "inCluster" };
+/** A resolved `kind: ssh` target. */
+export type SshTargetValue = TargetCommon & { kind: "ssh"; host: string };
+/** A resolved deploy target (the output of `helmTarget()`). */
+export type HelmTargetValue = InClusterTargetValue | SshTargetValue;
+
+type DefaultImages = { readonly image: "image" };
+export type HelmTargetDeployInput<Im extends Record<string, string> = DefaultImages, Rf extends Record<string, string> = {}> = Simplify<
+  { readonly source: typeof Source } & { readonly [K in keyof Im]: typeof PushedImage } & { readonly [K in keyof Rf]: ReturnType<typeof optional<typeof PushedImage>> }
+>;
+
+/** What both target deploys take (besides `target`). */
+export interface HelmTargetDeployDef<N extends string, Im extends Record<string, string> = DefaultImages, Rf extends Record<string, string> = {}> {
+  name: LiteralName<N>;
+  /** What the step does, shown in the UI. Required; may be empty. */
+  description: string;
+  /** Chart directory inside the source tree, e.g. `helm`. */
+  chart: string;
+  /**
+   * Values written as files and passed after the target's values files (`-f`, in order). Config
+   * references are resolved first; undefined members are dropped, so `{ auth: target.auth }`
+   * overrides only when set.
+   */
+  inlineValues?: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * The images to deploy: step input key → the chart's values prefix. Each input is a `PushedImage`;
+   * the step sets `<prefix>.repository`, `.tag`, `.digest` and `.pullPolicy=IfNotPresent`.
+   */
+  images?: Im & { readonly source?: never };
+  /**
+   * Registry images the chart only references: input key → values prefix. Each input is an
+   * `optional(PushedImage)`; when its producer was skipped the values are left alone.
+   */
+  imageRefs?: Rf & { readonly source?: never };
+  /** Rollout wait: per rollout over SSH, `helm --wait --timeout` in-cluster. Default 120. */
+  rolloutTimeoutSeconds?: number;
+  /** After the rollout, GET `http://<release>.<namespace>.svc.cluster.local<healthPath>` until it returns 2xx. */
+  healthPath?: string;
+  timeoutSeconds?: number;
+}
+
+export interface HelmDeployInClusterDef<N extends string, Im extends Record<string, string> = DefaultImages, Rf extends Record<string, string> = {}>
+  extends HelmTargetDeployDef<N, Im, Rf> {
+  /** An in-cluster target, usually a `select` case's reference (`(p, prod) => … target: prod`). */
+  target: Configurable<InClusterTargetValue>;
+}
+
+export interface HelmDeploySshTargetDef<N extends string, K extends string, Im extends Record<string, string> = DefaultImages, Rf extends Record<string, string> = {}>
+  extends HelmTargetDeployDef<N, Im, Rf> {
+  /** An ssh target, usually a `select` case's reference. */
+  target: Configurable<SshTargetValue>;
+  /** Private key for the target's host. */
+  sshKey: Secret<K>;
+  /** Rollouts to wait for (`deploy/<name>` for a bare name). Default: the release name. */
+  deployments?: readonly string[];
+}
+
+/**
+ * Deploys registry images, pinned by digest, with the Helm chart at `<source>/<chart>` into the
+ * cluster the step runs in: `helm upgrade --install --wait` in the step pod, with the instance's step
+ * ServiceAccount token (`clusterAccess`). Then (with `healthPath`) polls the release's Service.
+ */
+export function helmDeployInCluster<
+  const N extends string,
+  const Im extends Record<string, string> = DefaultImages,
+  const Rf extends Record<string, string> = {},
+>(def: HelmDeployInClusterDef<N, Im, Rf>): Step<N, HelmTargetDeployInput<Im, Rf>, typeof HelmRelease, never> & LibraryStep {
+  return targetDeploy("helmDeployInCluster", def as unknown as AnyTargetDef, undefined) as never;
+}
+
+/** The `target` form of `steps.helmDeployOverSsh`: an ssh target from config, registry images by digest. */
+export function helmDeployOverSshTarget(def: HelmDeploySshTargetDef<string, string, Record<string, string>, Record<string, string>>): Step & LibraryStep {
+  return targetDeploy("helmDeployOverSsh", def as unknown as AnyTargetDef, def.sshKey, def.deployments) as never;
+}
+
+interface AnyTargetDef {
+  name: string;
+  description: string;
+  chart: string;
+  target: unknown;
+  inlineValues?: readonly Readonly<Record<string, unknown>>[];
+  images?: Readonly<Record<string, string>>;
+  imageRefs?: Readonly<Record<string, string>>;
+  rolloutTimeoutSeconds?: number;
+  healthPath?: string;
+  timeoutSeconds?: number;
+}
+
+function targetDeploy(kind: StepKind, def: AnyTargetDef, sshKey: Secret | undefined, deployments?: readonly string[]): Step & LibraryStep {
+  const images: Record<string, string> = { ...(def.images ?? { image: "image" }) };
+  const imageEntries = Object.entries(images);
+  const imageRefs: Record<string, string> = { ...(def.imageRefs ?? {}) };
+  const refEntries = Object.entries(imageRefs);
+  const rolloutTimeout = def.rolloutTimeoutSeconds ?? DEFAULT_ROLLOUT_TIMEOUT_SECONDS;
+  if (imageEntries.length === 0) throw new Error(`${kind} '${def.name}': images must not be empty`);
+  if ("source" in images || "source" in imageRefs) throw new Error(`${kind} '${def.name}': 'source' can't be an image input`);
+  for (const [key] of refEntries) if (key in images) throw new Error(`${kind} '${def.name}': '${key}' is both in images and imageRefs`);
+  if (deployments?.length === 0) throw new Error(`${kind} '${def.name}': deployments must not be empty`);
+  if (def.healthPath !== undefined && !def.healthPath.startsWith("/")) throw new Error(`${kind} '${def.name}': healthPath must start with '/'`);
+  const inCluster = kind === "helmDeployInCluster";
+  const input = {
+    source: Source,
+    ...Object.fromEntries(imageEntries.map(([key]) => [key, PushedImage])),
+    ...Object.fromEntries(refEntries.map(([key]) => [key, optional(PushedImage)])),
+  };
+  const configurable = { target: def.target, inlineValues: def.inlineValues ?? [] };
+
+  return makeStep(
+    kind,
+    {
+      name: def.name, description: def.description, image: inCluster ? HELM_IMAGE : HELM_DEPLOY_IMAGE, input, output: HelmRelease,
+      secrets: sshKey ? [sshKey] : [], timeoutSeconds: def.timeoutSeconds, ...(inCluster ? { clusterAccess: true } : {}),
+    },
+    {
+      manifestConfig: () => ({
+        target: recordConfigRefs(def.target),
+        ...(sshKey ? { sshKey: sshKey.name } : {}),
+        chart: def.chart,
+        ...(def.inlineValues?.length ? { inlineValues: recordConfigRefs(def.inlineValues) } : {}),
+        images: { ...images },
+        ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
+        ...(deployments ? { deployments: [...deployments] } : {}),
+        ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
+        ...(def.healthPath !== undefined ? { healthPath: def.healthPath } : {}),
+      }),
+      async run(input: Record<string, { repository: string; tag: string; digest: string } | undefined> & { source: { tree: FileRef } }, ctx: Ctx) {
+        const { target, inlineValues } = resolveConfigRefs(configurable, ctx.config ?? {}) as { target: HelmTargetValue; inlineValues: Record<string, unknown>[] };
+        const want = inCluster ? "inCluster" : "ssh";
+        if (target?.kind !== want) throw new Error(`${kind} '${def.name}': the target is kind '${String(target?.kind)}', not '${want}'`);
+        const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
+
+        const generated = inlineValues.map((values, i) => {
+          const file = `olve-values-${i}.json`;
+          writeFileSync(join(chartDir, file), JSON.stringify(values));
+          return file;
+        });
+        const flags: HelmImageFlags[] = imageEntries.map(([key, prefix]) => {
+          const image = input[key]!;
+          return { prefix, repository: image.repository, tag: image.tag, digest: image.digest, pullPolicy: "IfNotPresent" };
+        });
+        const refs: HelmImageRefFlags[] = refEntries.flatMap(([key, prefix]) => {
+          const image = input[key];
+          return image ? [{ prefix, repository: image.repository, tag: image.tag, digest: image.digest }] : [];
+        });
+        const helm = { values: [...target.values, ...generated], set: target.set, images: flags, imageRefs: refs };
+        const { release, namespace } = target;
+
+        if (target.kind === "ssh") {
+          const key = ctx.secrets[sshKey!.name];
+          if (!key) throw new Error(`secret ${sshKey!.name} (sshKey) is not set`);
+          await deployOverSsh(ctx, {
+            host: target.host, key, chartDir, release, namespace,
+            hostImages: flags.map((f) => ({ repository: f.repository, tag: f.tag, digest: f.digest })),
+            flags: helm, deployments: deployments ?? [release], rolloutTimeoutSeconds: rolloutTimeout,
+          });
+        } else {
+          if (!existsSync(SERVICE_ACCOUNT_TOKEN))
+            throw new Error(`no ServiceAccount token in the step pod: the instance grants no step ServiceAccount (Kubernetes:StepServiceAccount), so an inCluster target can't be deployed`);
+          const home = join(ctx.tmpDir, "helm-home");
+          ctx.log("helm upgrade", { release, namespace, images: flags.map((f) => `${f.repository}@${f.digest}`).join(" ") });
+          await ctx.exec(["helm", "upgrade", "--install", release, ".", "-n", namespace, ...helmFlags(helm), "--wait", `--timeout=${rolloutTimeout}s`], {
+            cwd: chartDir,
+            env: { HOME: home, HELM_CACHE_HOME: join(home, "cache"), HELM_CONFIG_HOME: join(home, "config"), HELM_DATA_HOME: join(home, "data") },
+          });
+        }
+
+        const url = (target.url ?? serviceUrl({ release, namespace })).replace(/\/+$/, "");
+        if (def.healthPath !== undefined) await httpHealthCheck(ctx, `${url}${def.healthPath}`, { attempts: 12, delaySeconds: 5 });
+        const main = flags[0]!;
+        return { release, namespace, image: `${main.repository}:${main.tag}@${main.digest}`, ...(target.url ? { url } : {}) };
+      },
+    },
+    configurable,
+  ) as never;
+}