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

package/src/library/image-build.ts

@@ -1,13 +1,17 @@
-// steps.imageBuild — build a container image from a `Source` with kaniko, to an image tarball.
-//
-// No registry push: the tarball travels as a file ref and a deploy step imports it on the host.
+// steps.imageBuild — build a container image from a `Source` with kaniko: to an image tarball that
+// travels as a file ref (a deploy imports it on the host), or pushed to a registry (`push: true`).
 // Ported from v1's olve-lib.sh (olve_kaniko_build + build.sh's layer cache); footguns kept below.
-import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Ctx, RunInfo } from "../ctx/types.ts";
 import type { FileRef } from "../core/models.ts";
+import type { Secret } from "../core/secrets.ts";
+import { isConfigRef, type ConfigRef, type Configurable } from "../core/config.ts";
+import { isLiteral, recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
-import { BuiltImage, Source } from "./models.ts";
+import { sha256File } from "../util/hash.ts";
+import { dirEntries, writeTar } from "../util/tar.ts";
+import { BuiltImage, PushedImage, Source } from "./models.ts";
 
 /** kaniko's debug image (it has a busybox shell for debugging; the executor itself needs none). */
 export const KANIKO_IMAGE = "gcr.io/kaniko-project/executor:debug";
@@ -22,24 +26,43 @@ export const KANIKO_CONTEXT = "/kaniko/build-context";
 const input = { source: Source };
 export type ImageBuildInput = typeof input;
 
-export interface ImageBuildDef<N extends string> {
+/** Credentials for the registry of `repository`: a user name and a secret holding the password or token. */
+export interface RegistryAuth<K extends string> {
+  username: string;
+  password: Secret<K>;
+}
+
+/** Registry credentials as config: the password is a `secretRef` (`{ secret: NAME }`) the step must declare in `secrets`. */
+export interface RegistryAuthConfig {
+  username: string;
+  password: { secret: string };
+}
+
+export interface ImageBuildDef<N extends string, K extends string = never> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
-  /** Image name, e.g. `olve-pipelines-v2`. The tag is the run's version (see `imageTag`). */
-  repository: string;
+  /**
+   * Image name, e.g. `olve-pipelines-v2`; with `push`, the registry repository to push to
+   * (`registry.ovea.pro/app/api`). The tag is the run's version (see `imageTag`) unless `contentTag`.
+   */
+  repository: Configurable<string>;
+  /** Build context: a directory of the source tree (default: the root). */
+  context?: string;
+  /** Dockerfile path, relative to the context (default `Dockerfile`). */
+  dockerfile?: string;
   /**
    * Registry repository for kaniko's layer cache (`--cache=true --cache-repo=…`), so unchanged
    * layers (restore, apt, npm, …) are reused. kaniko pushes cache layers even with `--no-push`.
    * A registry without GC grows with every changed layer — prune it when needed.
    */
-  cacheRepo?: string;
+  cacheRepo?: Configurable<string | undefined>;
   /**
    * kaniko `--registry-map` (registry → mirror prefix); kaniko falls back to the original registry if
    * the mirror lacks the image. Defaults to the homelab pull-through caches (`DEFAULT_REGISTRY_MAP`);
    * a map replaces the default entirely, `{}` turns mapping off.
    */
-  registryMap?: Record<string, string>;
+  registryMap?: Configurable<Record<string, string> | undefined>;
   timeoutSeconds?: number;
   /**
    * Kill kaniko when it writes no output for this long (default 300 s; 0 disables), failing the
@@ -48,12 +71,51 @@ export interface ImageBuildDef<N extends string> {
    * the longest silent build phase (an AOT "Generating native code" runs ~2 min with no output).
    */
   stallTimeoutSeconds?: number;
+  /**
+   * kaniko `--snapshot-mode`: `redo` (default) compares file metadata instead of hashing every file's
+   * content after each instruction; `full` hashes content (slower, and what kaniko defaults to).
+   */
+  snapshotMode?: "redo" | "full" | "time";
+  /** kaniko `--use-new-run`: snapshot only what a RUN changed (faster for big images). Default true. */
+  useNewRun?: boolean;
+  /** kaniko `--compressed-caching`: compress layers while caching (saves memory, costs time). Default false. */
+  compressedCaching?: boolean;
   /**
    * Automatic retries of a failed attempt (a fresh pod: kaniko unpacks the base image over the
    * container root and does not clean up when killed, so retrying inside the same pod is unsafe).
    * A `--no-push` build is idempotent, so the default is 2 (three tries).
    */
   retries?: number;
+  /**
+   * Log in to the registry of `repository` (e.g. `ghcr.io` with a token that may write packages).
+   * Used for kaniko's push, base image and cache pulls from that registry, and the `contentTag` lookup.
+   */
+  registryAuth?: RegistryAuth<K> | ConfigRef<RegistryAuthConfig | undefined>;
+  /** The registry of `repository` speaks plain HTTP (a local `registry:2`). */
+  insecureRegistry?: Configurable<boolean | undefined>;
+  /** Secrets a config-referenced `registryAuth` may name (the step declares them). */
+  secrets?: readonly Secret<K>[];
+  /** `false` skips the step (`ctx.skip`), e.g. `enabled: PUBLISH.harness.push`. Default true. */
+  enabled?: Configurable<boolean | undefined>;
+}
+
+/** Tarball mode (default): output `BuiltImage` with the image tar as a file. */
+export interface ImageBuildTarballDef<N extends string, K extends string = never> extends ImageBuildDef<N, K> {
+  push?: false;
+  contentTag?: never;
+}
+
+/**
+ * Registry mode: push to `repository` and output `PushedImage`, for images too big to travel as a
+ * tarball (the step's scratch space is ~1 GiB).
+ */
+export interface ImageBuildPushDef<N extends string, K extends string = never> extends ImageBuildDef<N, K> {
+  push: true;
+  /**
+   * Tag the image `src-<hash>`, the hash of the build context's content, and skip the build when the
+   * registry already has that tag: the image is rebuilt only when its context changes.
+   */
+  contentTag?: boolean;
 }
 
 /**
@@ -74,10 +136,10 @@ export function registryHost(ref: string): string {
 }
 
 /** Whether a registry answers its API root: 200, or 401 (it wants a token). Never throws. */
-export async function registryUp(http: Ctx["http"], host: string, signal?: AbortSignal, timeoutMs = CACHE_PROBE_TIMEOUT_MS): Promise<boolean> {
+export async function registryUp(http: Ctx["http"], host: string, signal?: AbortSignal, timeoutMs = CACHE_PROBE_TIMEOUT_MS, insecure = false): Promise<boolean> {
   try {
     const timeout = AbortSignal.timeout(timeoutMs);
-    const res = await http.fetch(`https://${host}/v2/`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+    const res = await http.fetch(`${insecure ? "http" : "https"}://${host}/v2/`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
     await res.body?.cancel().catch(() => {});
     return res.status === 200 || res.status === 401;
   } catch {
@@ -92,9 +154,10 @@ export async function registryUp(http: Ctx["http"], host: string, signal?: Abort
 export async function reachableCaches(
   ctx: Pick<Ctx, "http" | "log" | "signal">,
   caches: { registryMap: Record<string, string>; cacheRepo?: string },
+  insecureHosts: readonly string[] = [],
 ): Promise<{ registryMap: Record<string, string>; cacheRepo?: string }> {
   const hosts = new Set([...Object.values(caches.registryMap), ...(caches.cacheRepo ? [caches.cacheRepo] : [])].map(registryHost));
-  const up = new Map(await Promise.all([...hosts].map(async (h) => [h, await registryUp(ctx.http, h, ctx.signal)] as const)));
+  const up = new Map(await Promise.all([...hosts].map(async (h) => [h, await registryUp(ctx.http, h, ctx.signal, undefined, insecureHosts.includes(h))] as const)));
   const registryMap: Record<string, string> = {};
   for (const [from, to] of Object.entries(caches.registryMap)) {
     if (up.get(registryHost(to))) registryMap[from] = to;
@@ -107,6 +170,9 @@ export async function reachableCaches(
   return { registryMap, ...(caches.cacheRepo ? { cacheRepo: caches.cacheRepo } : {}) };
 }
 
+/** Default kaniko `--snapshot-mode`. */
+export const DEFAULT_SNAPSHOT_MODE = "redo";
+
 /** Default `retries`: a stalled or flaky build gets two fresh attempts before the run fails. */
 export const DEFAULT_RETRIES = 2;
 
@@ -132,28 +198,194 @@ export function qualifyRepository(repository: string): string {
   return `docker.io/${repository}`;
 }
 
+/** A relative path inside the source tree (no `..`, not absolute). */
+function checkRelative(what: string, path: string): string {
+  const clean = path.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  if (clean.startsWith("/") || clean.split("/").includes("..")) throw new Error(`imageBuild ${what} '${path}' must be a relative path inside the source tree`);
+  return clean === "." ? "" : clean;
+}
+
+/** The `src-<12 hex>` tag of a directory: the sha256 of its deterministic tar (as `ctx.output.dir` writes it). */
+export function contentTagOf(dir: string, tmpDir: string): string {
+  mkdirSync(tmpDir, { recursive: true });
+  const work = mkdtempSync(join(tmpDir, "content-tag-"));
+  try {
+    const tar = join(work, "context.tar");
+    writeTar(tar, dirEntries(dir));
+    return `src-${sha256File(tar).slice(0, 12)}`;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+const MANIFEST_TYPES = [
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.oci.image.manifest.v1+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+  "application/vnd.docker.distribution.manifest.v2+json",
+].join(", ");
+
+/** Options of a registry API call: login (`username`/`password`) and plain HTTP. */
+export interface RegistryAccess {
+  username?: string;
+  password?: string;
+  insecure?: boolean;
+}
+
+const basic = (username: string, password: string) => `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+
+/** `Bearer realm="…",service="…",scope="…"` → its parameters. */
+export function parseChallenge(header: string): { scheme: string; params: Record<string, string> } {
+  const scheme = header.trim().split(/\s+/, 1)[0]!.toLowerCase();
+  const params: Record<string, string> = {};
+  for (const m of header.slice(scheme.length).matchAll(/([A-Za-z]+)="([^"]*)"/g)) params[m[1]!.toLowerCase()] = m[2]!;
+  return { scheme, params };
+}
+
 /**
- * Builds `<source>/Dockerfile` with the source root as context, using kaniko, into an image tarball.
- * Output: `BuiltImage { repository, tag, digest, tar }`.
+ * `HEAD`/`GET` against a registry API path, answering its auth challenge: Basic (a `registry:2` with
+ * htpasswd) or a Bearer token from the realm (ghcr.io, Docker Hub; anonymous for public images).
  */
-export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<N, ImageBuildInput, typeof BuiltImage, never> & LibraryStep {
-  const registryMap = def.registryMap ?? DEFAULT_REGISTRY_MAP;
-  const mapped = Object.keys(registryMap).length > 0;
+async function registryFetch(http: Ctx["http"], host: string, path: string, init: RequestInit, access: RegistryAccess): Promise<Response> {
+  const url = `${access.insecure ? "http" : "https"}://${host}${path}`;
+  const res = await http.fetch(url, init);
+  if (res.status !== 401) return res;
+  await res.body?.cancel().catch(() => {});
+  const { scheme, params } = parseChallenge(res.headers.get("www-authenticate") ?? "");
+  const login = access.username !== undefined && access.password !== undefined ? basic(access.username, access.password) : undefined;
+  let authorization: string;
+  if (scheme === "basic") {
+    if (!login) return new Response(null, { status: 401 });
+    authorization = login;
+  } else if (scheme === "bearer" && params.realm) {
+    const q = new URLSearchParams();
+    if (params.service) q.set("service", params.service);
+    if (params.scope) q.set("scope", params.scope);
+    const tokenRes = await http.fetch(`${params.realm}?${q}`, { headers: login ? { Authorization: login } : {} });
+    if (!tokenRes.ok) {
+      await tokenRes.body?.cancel().catch(() => {});
+      return new Response(null, { status: tokenRes.status === 404 ? 401 : tokenRes.status });
+    }
+    const body = (await tokenRes.json()) as { token?: string; access_token?: string };
+    const token = body.token ?? body.access_token;
+    if (!token) throw new Error(`registry token endpoint ${params.realm} returned no token`);
+    authorization = `Bearer ${token}`;
+  } else {
+    return new Response(null, { status: 401 });
+  }
+  const headers = new Headers(init.headers);
+  headers.set("Authorization", authorization);
+  return http.fetch(url, { ...init, headers });
+}
+
+/** The digest of `repository:tag` in its registry (`HEAD …/manifests/<tag>`), or undefined if it has none. */
+export async function registryDigest(http: Ctx["http"], repository: string, tag: string, access: RegistryAccess = {}): Promise<string | undefined> {
+  const [host, ...path] = repository.split("/");
+  const res = await registryFetch(http, host!, `/v2/${path.join("/")}/manifests/${tag}`, { method: "HEAD", headers: { Accept: MANIFEST_TYPES } }, access);
+  await res.body?.cancel().catch(() => {});
+  if (res.status === 404) return undefined;
+  // An anonymous lookup of a repository that doesn't exist yet (or is private) is denied, not 404.
+  if ((res.status === 401 || res.status === 403) && access.password === undefined) return undefined;
+  if (!res.ok) throw new Error(`registry lookup of ${repository}:${tag} answered HTTP ${res.status}`);
+  const digest = res.headers.get("docker-content-digest") ?? "";
+  return /^sha256:[0-9a-f]{64}$/.test(digest) ? digest : undefined;
+}
+
+/** kaniko reads registry logins from `$DOCKER_CONFIG/config.json` (`/kaniko/.docker` in its image). */
+export const KANIKO_DOCKER_CONFIG = "/kaniko/.docker";
+
+/** A docker `config.json` that logs in to `host`. */
+export function dockerConfigJson(host: string, username: string, password: string): string {
+  return JSON.stringify({ auths: { [host]: { auth: Buffer.from(`${username}:${password}`).toString("base64") } } });
+}
+
+/** Adds the login for `host` to `<dir>/config.json` (owner-only), keeping what is there (kaniko's credHelpers). */
+export function writeDockerConfig(dir: string, host: string, username: string, password: string): void {
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, "config.json");
+  let config: { auths?: Record<string, unknown> } = {};
+  try {
+    config = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    // absent or unreadable: start fresh
+  }
+  const login = JSON.parse(dockerConfigJson(host, username, password)) as { auths: Record<string, unknown> };
+  writeFileSync(file, JSON.stringify({ ...config, auths: { ...config.auths, ...login.auths } }), { mode: 0o600 });
+}
+
+/**
+ * Builds an image with kaniko from `<context>/<dockerfile>` in the source tree (default: `Dockerfile`
+ * at the root). Default: into an image tarball, output `BuiltImage { repository, tag, digest, tar }`.
+ * With `push: true`: pushed to `repository`, output `PushedImage { repository, tag, digest }`.
+ */
+export function imageBuild<const N extends string, const K extends string = never>(def: ImageBuildTarballDef<N, K>): Step<N, ImageBuildInput, typeof BuiltImage, K> & LibraryStep;
+export function imageBuild<const N extends string, const K extends string = never>(def: ImageBuildPushDef<N, K>): Step<N, ImageBuildInput, typeof PushedImage, K> & LibraryStep;
+export function imageBuild<const N extends string, const K extends string = never>(def: ImageBuildTarballDef<N, K> | ImageBuildPushDef<N, K>): AnyImageBuild {
+  const push = def.push === true;
+  const contentTag = push && def.contentTag === true;
+  const context = checkRelative("context", def.context ?? "");
+  const dockerfile = checkRelative("dockerfile", def.dockerfile ?? "Dockerfile");
+  const authSecret = def.registryAuth && !isConfigRef(def.registryAuth) ? def.registryAuth : undefined;
+  if (isLiteral([def.repository, def.registryAuth, def.insecureRegistry])) checkRegistryHost(def.name, def.repository as string, push, def.registryAuth !== undefined, def.insecureRegistry === true);
+  const secrets = [...(authSecret ? [authSecret.password] : []), ...(def.secrets ?? [])].filter((s, i, all) => all.findIndex((x) => x.name === s.name) === i);
   return makeStep(
     "imageBuild",
-    { name: def.name, description: def.description, image: KANIKO_IMAGE, input, output: BuiltImage, secrets: [], timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
+    { name: def.name, description: def.description, image: KANIKO_IMAGE, input, output: push ? PushedImage : BuiltImage, secrets, timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
     {
-      manifestConfig: () => ({
-        repository: def.repository,
-        ...(def.cacheRepo ? { cacheRepo: def.cacheRepo } : {}),
-        ...(mapped ? { registryMap: { ...registryMap } } : {}),
-      }),
+      manifestConfig: () => {
+        const registryMap = def.registryMap ?? DEFAULT_REGISTRY_MAP;
+        const mapped = isConfigRef(registryMap) || Object.keys(registryMap).length > 0;
+        return {
+          repository: recordConfigRefs(def.repository),
+          ...(context ? { context } : {}),
+          ...(dockerfile !== "Dockerfile" ? { dockerfile } : {}),
+          ...(push ? { push: true } : {}),
+          ...(contentTag ? { contentTag: true } : {}),
+          ...(def.cacheRepo !== undefined ? { cacheRepo: recordConfigRefs(def.cacheRepo) } : {}),
+          ...(mapped ? { registryMap: recordConfigRefs(registryMap) } : {}),
+          ...(authSecret ? { registryAuth: { username: authSecret.username, password: authSecret.password.name } } : {}),
+          ...(def.registryAuth && isConfigRef(def.registryAuth) ? { registryAuth: recordConfigRefs(def.registryAuth) } : {}),
+          ...(def.insecureRegistry !== undefined && def.insecureRegistry !== false ? { insecureRegistry: recordConfigRefs(def.insecureRegistry) } : {}),
+          ...(def.enabled !== undefined ? { enabled: recordConfigRefs(def.enabled) } : {}),
+          ...(def.snapshotMode !== undefined && def.snapshotMode !== DEFAULT_SNAPSHOT_MODE ? { snapshotMode: def.snapshotMode } : {}),
+          ...(def.useNewRun === false ? { useNewRun: false } : {}),
+          ...(def.compressedCaching === true ? { compressedCaching: true } : {}),
+        };
+      },
       async run({ source }: { source: { tree: FileRef } }, ctx: Ctx) {
-        const tag = imageTag(ctx.run);
-        const caches = await reachableCaches(ctx, { registryMap, cacheRepo: def.cacheRepo });
+        const d = resolveConfigRefs({
+          repository: def.repository, cacheRepo: def.cacheRepo, registryMap: def.registryMap, insecureRegistry: def.insecureRegistry,
+          registryAuth: def.registryAuth, enabled: def.enabled,
+        }, ctx.config ?? {});
+        const repository = d.repository as string;
+        if (d.enabled === false) return ctx.skip(`publishing ${repository} is turned off`);
+        const registryMap = (d.registryMap as Record<string, string> | undefined) ?? DEFAULT_REGISTRY_MAP;
+        const insecure = d.insecureRegistry === true;
+        const auth = registryLogin(d.registryAuth as RegistryAuth<string> | RegistryAuthConfig | undefined, ctx, secrets.map((s) => s.name));
+        checkRegistryHost(def.name, repository, push, auth !== undefined, insecure);
+        const host = registryHost(repository);
+
         const tree = await ctx.files.fetch(source.tree);
+        const contextDir = context ? join(tree, context) : tree;
+        if (!existsSync(contextDir) || !statSync(contextDir).isDirectory()) throw new Error(`build context '${context}' not found in the source tree`);
+        if (!existsSync(join(contextDir, dockerfile))) throw new Error(`${dockerfile} not found in the build context${context ? ` '${context}'` : ""}`);
+
+        const access: RegistryAccess = { insecure, ...(auth ?? {}) };
+        if (auth) writeDockerConfig(process.env.DOCKER_CONFIG || KANIKO_DOCKER_CONFIG, host, auth.username, auth.password);
+
+        const tag = contentTag ? contentTagOf(contextDir, ctx.tmpDir) : imageTag(ctx.run);
+        if (contentTag) {
+          const digest = await registryDigest(ctx.http, repository, tag, access);
+          if (digest) {
+            ctx.log("image already in the registry", { image: `${repository}:${tag}`, digest });
+            return { repository, tag, digest };
+          }
+        }
+
+        const caches = await reachableCaches(ctx, { registryMap, cacheRepo: d.cacheRepo as string | undefined }, insecure ? [host] : []);
         await ctx.exec(["mkdir", "-p", KANIKO_CONTEXT]);
         await ctx.exec(["cp", "-r", `${tree}/.`, KANIKO_CONTEXT]);
+        const kanikoContext = context ? `${KANIKO_CONTEXT}/${context}` : KANIKO_CONTEXT;
 
         // Outputs go to the harness's scratch dir (/olve/tmp, an emptyDir mount kaniko leaves alone;
         // kaniko images have no /tmp), then into the step's files.
@@ -161,18 +393,22 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
         const out = mkdtempSync(join(ctx.tmpDir, "image-build-"));
         const tarPath = join(out, "image.tar");
         const digestPath = join(out, "digest");
+        const output = push ? [] : ["--no-push", `--tar-path=${tarPath}`];
         // No --single-snapshot: it is incompatible with multi-stage Dockerfiles whose later stages need
         // the build context intact. --skip-push-permission-check: with --no-push kaniko otherwise checks
         // the cache repo at startup and exits if it is down; later cache lookup and push errors are
         // only warnings.
         await ctx.exec([
           "/kaniko/executor",
-          `--context=${KANIKO_CONTEXT}`,
-          `--dockerfile=${KANIKO_CONTEXT}/Dockerfile`,
-          "--no-push",
-          `--tar-path=${tarPath}`,
+          `--context=${kanikoContext}`,
+          `--dockerfile=${kanikoContext}/${dockerfile}`,
+          ...output,
           `--digest-file=${digestPath}`,
-          `--destination=${def.repository}:${tag}`,
+          `--destination=${repository}:${tag}`,
+          ...(insecure ? ["--insecure", `--insecure-registry=${host}`] : []),
+          `--snapshot-mode=${def.snapshotMode ?? DEFAULT_SNAPSHOT_MODE}`,
+          ...((def.useNewRun ?? true) ? ["--use-new-run"] : []),
+          `--compressed-caching=${def.compressedCaching ?? false}`,
           ...(caches.cacheRepo ? ["--cache=true", `--cache-repo=${caches.cacheRepo}`, "--skip-push-permission-check"] : []),
           ...Object.entries(caches.registryMap).map(([from, to]) => `--registry-map=${from}=${to}`),
         ], { idleTimeoutSeconds: def.stallTimeoutSeconds ?? DEFAULT_STALL_TIMEOUT_SECONDS });
@@ -184,11 +420,55 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
           throw new Error(`kaniko did not write the image digest to ${digestPath}`);
         }
         if (!/^sha256:[0-9a-f]{64}$/.test(digest)) throw new Error(`kaniko wrote an unexpected digest: '${digest}'`);
+        if (push) {
+          ctx.log("image pushed", { image: `${repository}:${tag}`, digest });
+          return { repository, tag, digest };
+        }
         const tar = await ctx.output.file(tarPath, { name: "image.tar" });
         rmSync(tarPath); // the copy in the step's files is the one that counts; don't hold the image twice in /olve
-        ctx.log("image built", { image: `${def.repository}:${tag}`, digest });
-        return { repository: qualifyRepository(def.repository), tag, digest, tar };
+        ctx.log("image built", { image: `${repository}:${tag}`, digest });
+        return { repository: qualifyRepository(repository), tag, digest, tar };
       },
     },
+    def,
   ) as never;
 }
+
+function checkRegistryHost(name: string, repository: string, push: boolean, auth: boolean, insecure: boolean): void {
+  const host = registryHost(repository);
+  if (push && !/[.:]|^localhost$/.test(host)) throw new Error(`imageBuild '${name}': push needs a repository with a registry host, got '${repository}'`);
+  if ((auth || insecure) && !/[.:]|^localhost$/.test(host)) throw new Error(`imageBuild '${name}': registryAuth and insecureRegistry need a repository with a registry host, got '${repository}'`);
+}
+
+/** The login for `registryAuth` (a literal secret or a config `secretRef`), or undefined without one. */
+function registryLogin(auth: RegistryAuth<string> | RegistryAuthConfig | undefined, ctx: Pick<Ctx, "secrets">, declared: readonly string[]): { username: string; password: string } | undefined {
+  if (!auth) return undefined;
+  const name = "name" in auth.password ? auth.password.name : auth.password.secret;
+  if (!declared.includes(name)) throw new Error(`registryAuth names secret ${name}, which the step does not declare (add it to secrets)`);
+  const password = (ctx.secrets as Record<string, string | undefined>)[name];
+  if (!password) throw new Error(`secret ${name} (registryAuth) is not set`);
+  return { username: auth.username, password };
+}
+
+/**
+ * Adds `tag` to the image `repository@digest` without rebuilding it: the manifest is fetched by
+ * digest and PUT back under the tag byte for byte, so the digest stays the same.
+ */
+export async function registryTag(http: Ctx["http"], repository: string, digest: string, tag: string, access: RegistryAccess = {}): Promise<void> {
+  const [host, ...path] = repository.split("/");
+  const name = path.join("/");
+  const got = await registryFetch(http, host!, `/v2/${name}/manifests/${digest}`, { method: "GET", headers: { Accept: MANIFEST_TYPES } }, access);
+  if (!got.ok) {
+    await got.body?.cancel().catch(() => {});
+    throw new Error(`registry fetch of ${repository}@${digest} answered HTTP ${got.status}`);
+  }
+  const type = got.headers.get("content-type") ?? "application/vnd.oci.image.manifest.v1+json";
+  const body = new Uint8Array(await got.arrayBuffer());
+  const put = await registryFetch(http, host!, `/v2/${name}/manifests/${encodeURIComponent(tag)}`, { method: "PUT", headers: { "Content-Type": type }, body }, access);
+  await put.body?.cancel().catch(() => {});
+  if (!put.ok) throw new Error(`registry tag ${repository}:${tag} → ${digest} answered HTTP ${put.status}`);
+  const written = put.headers.get("docker-content-digest");
+  if (written && written !== digest) throw new Error(`registry stored ${repository}:${tag} as ${written}, not ${digest}`);
+}
+
+type AnyImageBuild = Step<string, ImageBuildInput, typeof BuiltImage | typeof PushedImage, any> & LibraryStep;

package/src/library/index.ts

@@ -1,14 +1,21 @@
 import { gitHubSource } from "./github-source.ts";
+import { composeDeploy } from "./compose-deploy.ts";
+import { helmDeployInCluster } from "./helm-deploy.ts";
 import { helmDeployOverSsh } from "./helm-deploy-ssh.ts";
 import { imageBuild } from "./image-build.ts";
 import { script } from "./script.ts";
 
-export { Source, BuiltImage, HelmRelease, FailureContext } from "./models.ts";
+export { Source, BuiltImage, PushedImage, HelmRelease, FailureContext } from "./models.ts";
 export { inputEnvName, type RunValue, type ScriptDef } from "./script.ts";
 export type { GitHubSourceDef } from "./github-source.ts";
-export type { ImageBuildDef } from "./image-build.ts";
+export { registryTag, registryDigest, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type RegistryAuthConfig, type RegistryAccess } from "./image-build.ts";
 export type { HelmDeployOverSshDef } from "./helm-deploy-ssh.ts";
+export { type ComposeDeployDef, type ComposeTargetValue, type ComposeDeployResult } from "./compose-deploy.ts";
+export { helmTarget, deployTarget, type DeployTargetOptions, type HelmDeployInClusterDef, type HelmDeploySshTargetDef, type HelmTargetDeployDef, type HelmTargetValue, type InClusterTargetValue, type SshTargetValue } from "./helm-deploy.ts";
+export { sshSession, shq, type SshSession } from "./ssh.ts";
+export { serviceUrl, checkSpa } from "./checks.ts";
 export { httpHealthCheck, HTTP_HEALTH_DEFAULTS, type HttpHealthCheckOptions } from "./http-health.ts";
+export { npmDistTag, npmHasVersion, NPM_REGISTRY } from "./npm.ts";
 
 /** SDK-provided steps (step + handler pairs with typed config). */
-export const steps = { script, gitHubSource, imageBuild, helmDeployOverSsh };
+export const steps = { script, gitHubSource, imageBuild, helmDeployOverSsh, helmDeployInCluster, composeDeploy };

package/src/library/models.ts

@@ -14,10 +14,25 @@ export const BuiltImage = model(
   z.object({ repository: z.string(), tag: z.string(), digest: z.string(), tar: fileRef() }),
 );
 
+/**
+ * A container image pushed to a registry by a step (`imageBuild` with `push: true`), pulled from there
+ * by the deploy. `repository` includes the registry host.
+ */
+export const PushedImage = model(
+  "PushedImage",
+  z.object({ repository: z.string(), tag: z.string(), digest: z.string() }),
+);
+
 /** A Helm release that was installed or upgraded. */
 export const HelmRelease = model(
   "HelmRelease",
-  z.object({ release: z.string(), namespace: z.string(), image: z.string() }),
+  z.object({
+    release: z.string(),
+    namespace: z.string(),
+    image: z.string(),
+    /** Where step pods reach the release (the target's `url`); absent = its in-cluster Service URL (`serviceUrl`). */
+    url: z.string().optional(),
+  }),
 );
 
 /** One failed step of a run, as seen by a failure handler. */

package/src/library/npm.ts

@@ -0,0 +1,33 @@
+// npm registry calls for release steps (no npm CLI needed in the image).
+import type { Ctx } from "../ctx/types.ts";
+
+export const NPM_REGISTRY = "https://registry.npmjs.org";
+
+const packagePath = (name: string) => name.replace("/", "%2f");
+
+/** Whether `name@version` is on the registry. */
+export async function npmHasVersion(ctx: Pick<Ctx, "http">, name: string, version: string, registry = NPM_REGISTRY): Promise<boolean> {
+  const res = await ctx.http.fetch(`${registry}/${packagePath(name)}`, { headers: { "cache-control": "no-cache" } });
+  if (res.status === 404) {
+    await res.body?.cancel().catch(() => {});
+    return false;
+  }
+  if (!res.ok) throw new Error(`npm registry lookup of ${name} failed: HTTP ${res.status}`);
+  return Boolean(((await res.json()) as { versions?: Record<string, unknown> }).versions?.[version]);
+}
+
+/** `npm dist-tag add <name>@<version> <tag>`: points the tag at an already published version. */
+export async function npmDistTag(
+  ctx: Pick<Ctx, "http" | "log">,
+  o: { name: string; version: string; tag: string; token: string; registry?: string },
+): Promise<void> {
+  const url = `${o.registry ?? NPM_REGISTRY}/-/package/${packagePath(o.name)}/dist-tags/${encodeURIComponent(o.tag)}`;
+  const res = await ctx.http.fetch(url, {
+    method: "PUT",
+    headers: { authorization: `Bearer ${o.token}`, "content-type": "application/json" },
+    body: JSON.stringify(o.version),
+  });
+  await res.body?.cancel().catch(() => {});
+  if (!res.ok) throw new Error(`npm dist-tag ${o.name}@${o.version} ${o.tag} failed: HTTP ${res.status}`);
+  ctx.log("npm dist-tag", { package: `${o.name}@${o.version}`, tag: o.tag });
+}

package/src/library/ssh.ts

@@ -0,0 +1,45 @@
+// sshSession — run commands on a host over SSH from a handler (alpine image: installs openssh-client).
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Ctx } from "../ctx/types.ts";
+
+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 SshSession {
+  readonly host: string;
+  /** Runs a remote command; a non-zero exit throws. */
+  run(remote: string): Promise<void>;
+  /** Runs a remote command and returns its stdout. */
+  text(remote: string): Promise<string>;
+  /** `scp -r` a local file or directory to a remote path. */
+  copy(local: string, remote: string): Promise<void>;
+  /** The ssh invocation as a shell command, for pipes and redirects: `ctx.sh(`${s.shell("cat > f")} < ${file}`)`. */
+  shell(remote: string): string;
+}
+
+/**
+ * Opens an SSH "session" to `host` (`user@host`) with a private key: installs openssh-client (apk),
+ * writes the key to `<tmpDir>/ssh/id`. The host key is not verified: hosts are reached over the tailnet.
+ */
+export async function sshSession(ctx: Pick<Ctx, "exec" | "sh" | "tmpDir">, opts: { host: string; key: string }): Promise<SshSession> {
+  await ctx.exec(["apk", "add", "--no-cache", "openssh-client"]);
+  const dir = join(ctx.tmpDir, "ssh");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const keyFile = join(dir, "id");
+  // OpenSSH rejects a key without a trailing newline.
+  writeFileSync(keyFile, opts.key.endsWith("\n") ? opts.key : opts.key + "\n", { mode: 0o600 });
+  chmodSync(keyFile, 0o600);
+  const sshOpts = ["-i", keyFile, "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR", "-o", "BatchMode=yes"];
+  const argv = (remote: string) => ["ssh", ...sshOpts, opts.host, remote];
+  return {
+    host: opts.host,
+    run: (remote) => ctx.exec(argv(remote)),
+    text: (remote) => ctx.sh.text(argv(remote).map(shq).join(" ")),
+    copy: (local, remote) => ctx.exec(["scp", ...sshOpts, "-r", local, `${opts.host}:${remote}`]),
+    shell: (remote) => argv(remote).map(shq).join(" "),
+  };
+}

package/src/testing/index.ts

@@ -1,11 +1,11 @@
-// @olve/pipelines/testing — run a handler under `bun test` through the real harness path
+// @olivervea/pipelines/testing — run a handler under `bun test` through the real harness path
 // (validate input → handler → strict output validation), with a real ctx you can override.
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { isImplementation, type Implementation } from "../core/handlers.ts";
 import type { FileRef } from "../core/models.ts";
-import { isStep, type AnyStep, type LibraryStep, type OutputValue, type SecretsOf, type StepInput } from "../core/steps.ts";
+import { isStep, type AnyStep, type ConfigOf, type LibraryStep, type OutputValue, type SecretsOf, type StepInput } from "../core/steps.ts";
 import { createCtx } from "../ctx/index.ts";
 import type { Ctx, RunInfo } from "../ctx/types.ts";
 import { executeStep, type FailureKind, type StepFunction } from "../harness/execute.ts";
@@ -13,7 +13,9 @@ import { sha256Hex } from "../util/hash.ts";
 
 export interface TestHandlerOptions<S extends AnyStep> {
   /** Replace parts of ctx (e.g. `sh`, `http`, `files`). The rest is the real implementation. */
-  ctx?: Partial<Ctx<SecretsOf<S>>>;
+  ctx?: Partial<Ctx<SecretsOf<S>, ConfigOf<S>>>;
+  /** The step's config entries (z.input view: defaults are applied), like `$config` in input.json. */
+  config?: Record<string, unknown>;
   /** Secret values (instead of reading the environment). */
   secrets?: Partial<Record<SecretsOf<S>, string>>;
   run?: Partial<Omit<RunInfo, "step">>;
@@ -69,7 +71,7 @@ export async function testHandler<S extends AnyStep>(
   });
   const ctx = { ...real, ...opts.ctx } as Ctx;
   // Round-trip through JSON like input.json does (drops undefined, rejects non-JSON values early).
-  const raw = JSON.parse(JSON.stringify(input ?? {}));
+  const raw = JSON.parse(JSON.stringify({ ...input, ...(opts.config ? { $config: opts.config } : {}) }));
   const exec = await executeStep({ step, fn, rawInput: raw, ctx, workFiles: filesDir, log: (l) => logs.push(l) });
   return { dir, filesDir, logs, exitCode: exec.exitCode, ...exec.envelope } as TestResult<S>;
 }

package/src/util/handler-hash.ts

@@ -5,7 +5,7 @@ import { sha256Hex } from "./hash.ts";
 export interface HarnessInfo {
   /** Bun version (runtime compiled into the binary). */
   bun: string;
-  /** @olve/pipelines package version. */
+  /** @olivervea/pipelines package version. */
   sdk: string;
   /** `sha256:` hash over the SDK runtime sources and the zod version. */
   sdkHash: string;