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

package/src/library/image-build.ts

@@ -1,13 +1,18 @@
-// 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 { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
-import { BuiltImage, Source } from "./models.ts";
+import type { Secret } from "../core/secrets.ts";
+import { isConfigRef, type ConfigRef, type Configurable } from "../core/config.ts";
+import { isLiteral, resolveConfigRefs } from "../core/config-refs.ts";
+import { implement, type Implementation } from "../core/handlers.ts";
+import { step, type LiteralName, type Step } from "../core/steps.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,20 +27,35 @@ 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;
   /**
-   * 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.
+   * 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`.
    */
-  cacheRepo?: string;
-  /** kaniko `--registry-map` (registry → mirror prefix); kaniko falls back to the original registry if the mirror lacks the image. */
-  registryMap?: Record<string, string>;
+  repository: Configurable<string>;
+  /** Build context: a directory of the source tree with a `Dockerfile` (default: the root). */
+  context?: string;
+  /**
+   * 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?: Configurable<Record<string, string> | undefined>;
   timeoutSeconds?: number;
   /**
    * Kill kaniko when it writes no output for this long (default 300 s; 0 disables), failing the
@@ -50,6 +70,81 @@ export interface ImageBuildDef<N extends string> {
    * 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;
+}
+
+/**
+ * Default `registryMap`: pull-through caches for mcr.microsoft.com and Docker Hub. kaniko under gVisor
+ * can stall forever pulling from mcr.microsoft.com directly.
+ */
+export const DEFAULT_REGISTRY_MAP: Readonly<Record<string, string>> = {
+  "mcr.microsoft.com": "mcr-cache.ovea.pro",
+  "index.docker.io": "hub-cache.ovea.pro",
+};
+
+/** How long a cache registry gets to answer `GET /v2/` before the build goes without it. */
+export const CACHE_PROBE_TIMEOUT_MS = 5000;
+
+/** The registry host of an image reference or mirror prefix (`registry.ovea.pro/a/b` → `registry.ovea.pro`). */
+export function registryHost(ref: string): string {
+  return ref.split("/")[0]!;
+}
+
+/** 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, insecure = false): Promise<boolean> {
+  try {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    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 {
+    return false;
+  }
+}
+
+/** The registry map without the mirrors that don't answer, so a mirror outage (GC, maintenance) never blocks a build. */
+export async function reachableMirrors(
+  ctx: Pick<Ctx, "http" | "log" | "signal">,
+  registryMap: Record<string, string>,
+  insecureHosts: readonly string[] = [],
+): Promise<Record<string, string>> {
+  const hosts = new Set(Object.values(registryMap).map(registryHost));
+  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 reachable: Record<string, string> = {};
+  for (const [from, to] of Object.entries(registryMap)) {
+    if (up.get(registryHost(to))) reachable[from] = to;
+    else ctx.log(`${registryHost(to)} unreachable; pulling from ${from} directly`);
+  }
+  return reachable;
 }
 
 /** Default `retries`: a stalled or flaky build gets two fresh attempts before the run fails. */
@@ -77,58 +172,247 @@ 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 {
-  return makeStep(
-    "imageBuild",
-    { name: def.name, description: def.description, image: KANIKO_IMAGE, input, output: BuiltImage, secrets: [], timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
-    {
-      manifestConfig: () => ({
-        repository: def.repository,
-        ...(def.cacheRepo ? { cacheRepo: def.cacheRepo } : {}),
-        ...(def.registryMap ? { registryMap: def.registryMap } : {}),
-      }),
-      async run({ source }: { source: { tree: FileRef } }, ctx: Ctx) {
-        const tag = imageTag(ctx.run);
-        const tree = await ctx.files.fetch(source.tree);
-        await ctx.exec(["mkdir", "-p", KANIKO_CONTEXT]);
-        await ctx.exec(["cp", "-r", `${tree}/.`, 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.
-        mkdirSync(ctx.tmpDir, { recursive: true });
-        const out = mkdtempSync(join(ctx.tmpDir, "image-build-"));
-        const tarPath = join(out, "image.tar");
-        const digestPath = join(out, "digest");
-        // No --single-snapshot: it is incompatible with multi-stage Dockerfiles whose later stages need
-        // the build context intact.
-        await ctx.exec([
-          "/kaniko/executor",
-          `--context=${KANIKO_CONTEXT}`,
-          `--dockerfile=${KANIKO_CONTEXT}/Dockerfile`,
-          "--no-push",
-          `--tar-path=${tarPath}`,
-          `--digest-file=${digestPath}`,
-          `--destination=${def.repository}:${tag}`,
-          ...(def.cacheRepo ? ["--cache=true", `--cache-repo=${def.cacheRepo}`] : []),
-          ...Object.entries(def.registryMap ?? {}).map(([from, to]) => `--registry-map=${from}=${to}`),
-        ], { idleTimeoutSeconds: def.stallTimeoutSeconds ?? DEFAULT_STALL_TIMEOUT_SECONDS });
-
-        let digest: string;
-        try {
-          digest = readFileSync(digestPath, "utf8").trim();
-        } catch {
-          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}'`);
-        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 };
-      },
+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: 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>): Implementation<Step<N, ImageBuildInput, typeof BuiltImage, K>>;
+export function imageBuild<const N extends string, const K extends string = never>(def: ImageBuildPushDef<N, K>): Implementation<Step<N, ImageBuildInput, typeof PushedImage, K>>;
+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 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);
+  const registryMap = def.registryMap ?? DEFAULT_REGISTRY_MAP;
+  const mapped = isConfigRef(registryMap) || Object.keys(registryMap).length > 0;
+  const contract = step({
+    name: def.name,
+    description: def.description,
+    kind: "imageBuild",
+    image: KANIKO_IMAGE,
+    input,
+    output: push ? PushedImage : BuiltImage,
+    secrets,
+    timeoutSeconds: def.timeoutSeconds,
+    retries: def.retries ?? DEFAULT_RETRIES,
+    settings: {
+      repository: def.repository,
+      ...(context ? { context } : {}),
+      ...(push ? { push: true } : {}),
+      ...(contentTag ? { contentTag: true } : {}),
+      ...(mapped ? { registryMap } : {}),
+      ...(authSecret ? { registryAuth: { username: authSecret.username, password: authSecret.password.name } } : {}),
+      ...(def.registryAuth && isConfigRef(def.registryAuth) ? { registryAuth: def.registryAuth } : {}),
+      ...(def.insecureRegistry !== undefined && def.insecureRegistry !== false ? { insecureRegistry: def.insecureRegistry } : {}),
+      ...(def.enabled !== undefined ? { enabled: def.enabled } : {}),
     },
-  ) as never;
+  });
+  return implement(contract, async ({ source }, ctx: Ctx) => {
+    const d = resolveConfigRefs({
+      repository: def.repository, 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 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 mirrors = await reachableMirrors(ctx, (d.registryMap as Record<string, string> | undefined) ?? DEFAULT_REGISTRY_MAP, 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.
+    mkdirSync(ctx.tmpDir, { recursive: true });
+    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.
+    await ctx.exec([
+      "/kaniko/executor",
+      `--context=${kanikoContext}`,
+      `--dockerfile=${kanikoContext}/Dockerfile`,
+      ...output,
+      `--digest-file=${digestPath}`,
+      `--destination=${repository}:${tag}`,
+      ...(insecure ? ["--insecure", `--insecure-registry=${host}`] : []),
+      "--snapshot-mode=redo",
+      "--use-new-run",
+      "--compressed-caching=false",
+      ...Object.entries(mirrors).map(([from, to]) => `--registry-map=${from}=${to}`),
+    ], { idleTimeoutSeconds: def.stallTimeoutSeconds ?? DEFAULT_STALL_TIMEOUT_SECONDS });
+
+    let digest: string;
+    try {
+      digest = readFileSync(digestPath, "utf8").trim();
+    } catch {
+      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: `${repository}:${tag}`, digest });
+    return { repository: qualifyRepository(repository), tag, digest, tar };
+  }) 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 };
+}
+
+type AnyImageBuild = Implementation<Step<string, ImageBuildInput, typeof BuiltImage | typeof PushedImage, any>>;

package/src/library/index.ts

@@ -1,14 +1,18 @@
 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 { inputEnvName, type RunValue, type ScriptDef } from "./script.ts";
+export { Source, BuiltImage, PushedImage, HelmRelease, FailureContext } from "./models.ts";
 export type { GitHubSourceDef } from "./github-source.ts";
-export type { ImageBuildDef } from "./image-build.ts";
+export type { ImageBuildDef, ImageBuildTarballDef, ImageBuildPushDef, RegistryAuth, RegistryAuthConfig } from "./image-build.ts";
 export type { HelmDeployOverSshDef } from "./helm-deploy-ssh.ts";
-export { httpHealthCheck, HTTP_HEALTH_DEFAULTS, type HttpHealthCheckOptions } from "./http-health.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, type SshSession } from "./ssh.ts";
+export { serviceUrl, checkSpa } from "./checks.ts";
+export { httpHealthCheck, type HttpHealthCheckOptions } from "./http-health.ts";
 
-/** SDK-provided steps (step + handler pairs with typed config). */
-export const steps = { script, gitHubSource, imageBuild, helmDeployOverSsh };
+/** SDK-provided steps: each is `implement(step(…), …)` with typed settings, staged directly. */
+export const steps = { gitHubSource, imageBuild, helmDeployOverSsh, helmDeployInCluster, composeDeploy };

package/src/library/models.ts

@@ -14,10 +14,26 @@ 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(),
+    /** The release's main image; absent for a chart deployed without images. */
+    image: z.string().optional(),
+    /** 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/ssh.ts

@@ -0,0 +1,50 @@
+// sshSession — run commands on a host over SSH from a handler (installs openssh-client when the image lacks ssh).
+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, `'\\''`)}'`;
+}
+
+/** Installs the ssh client unless the image has one: apk (Alpine) or apt-get (Debian, Ubuntu). */
+export const SSH_CLIENT_INSTALL =
+  "command -v ssh >/dev/null 2>&1 || if command -v apk >/dev/null 2>&1; then apk add --no-cache openssh-client; " +
+  "else apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends openssh-client; fi";
+
+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 if needed,
+ * 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.sh(SSH_CLIENT_INSTALL);
+  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 type { AnyStep, ConfigOf, OutputValue, SecretsOf, 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">>;
@@ -36,24 +38,18 @@ export type TestResult<S extends AnyStep> = {
 );
 
 /**
- * Runs a handler (the default export of `handlers/<step>.ts`) or a library step with `input`.
+ * Runs an implementation (a handler module's default export, or a step that carries its own) with `input`.
  * Input is validated like `input.json`, the result like a real run: an invalid output gives
  * `{ status: "failed", error: { kind: "output" } }`, a throwing handler `kind: "handler"`.
  */
 export async function testHandler<S extends AnyStep>(
-  target: Implementation<S> | (S & LibraryStep),
+  target: Implementation<S>,
   input: StepInput<S["input"]>,
   opts: TestHandlerOptions<S> = {},
 ): Promise<TestResult<S>> {
-  let step: AnyStep;
-  let fn: StepFunction;
-  if (isImplementation(target)) {
-    step = target.step;
-    fn = target.handler as unknown as StepFunction;
-  } else if (isStep(target) && target.builtin) {
-    step = target;
-    fn = target.builtin.run as StepFunction;
-  } else throw new TypeError("testHandler expects implement(...) (a handler module's default export) or a library step");
+  if (!isImplementation(target)) throw new TypeError("testHandler expects implement(…): a handler module's default export or a step that carries its implementation");
+  const step: AnyStep = target.step;
+  const fn = target.handler as unknown as StepFunction;
 
   const dir = opts.dir ?? mkdtempSync(join(tmpdir(), `olve-test-${step.name}-`));
   const filesDir = join(dir, "work", "files");
@@ -69,7 +65,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>;
 }