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

package/src/library/image-build.ts

@@ -1,10 +1,13 @@
 // 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 { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } 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 { sha256File } from "../util/hash.ts";
 import { dirEntries, writeTar } from "../util/tar.ts";
@@ -23,7 +26,19 @@ 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;
@@ -31,7 +46,7 @@ export interface ImageBuildDef<N extends 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: string;
+  repository: Configurable<string>;
   /** Build context: a directory of the source tree (default: the root). */
   context?: string;
   /** Dockerfile path, relative to the context (default `Dockerfile`). */
@@ -41,13 +56,13 @@ export interface ImageBuildDef<N extends string> {
    * 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
@@ -56,16 +71,36 @@ 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> extends ImageBuildDef<N> {
+export interface ImageBuildTarballDef<N extends string, K extends string = never> extends ImageBuildDef<N, K> {
   push?: false;
   contentTag?: never;
 }
@@ -74,7 +109,7 @@ export interface ImageBuildTarballDef<N extends string> extends ImageBuildDef<N>
  * 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> extends ImageBuildDef<N> {
+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
@@ -101,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 {
@@ -119,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;
@@ -134,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;
 
@@ -186,61 +225,164 @@ const MANIFEST_TYPES = [
   "application/vnd.docker.distribution.manifest.v2+json",
 ].join(", ");
 
-/** The digest of `repository:tag` in its registry (anonymous `HEAD …/manifests/<tag>`), or undefined if it has none. */
-export async function registryDigest(http: Ctx["http"], repository: string, tag: string): Promise<string | undefined> {
+/** 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 };
+}
+
+/**
+ * `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).
+ */
+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 http.fetch(`https://${host}/v2/${path.join("/")}/manifests/${tag}`, { method: "HEAD", headers: { Accept: MANIFEST_TYPES } });
+  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>(def: ImageBuildTarballDef<N>): Step<N, ImageBuildInput, typeof BuiltImage, never> & LibraryStep;
-export function imageBuild<const N extends string>(def: ImageBuildPushDef<N>): Step<N, ImageBuildInput, typeof PushedImage, never> & LibraryStep;
-export function imageBuild<const N extends string>(def: ImageBuildTarballDef<N> | ImageBuildPushDef<N>): AnyImageBuild {
-  const registryMap = def.registryMap ?? DEFAULT_REGISTRY_MAP;
-  const mapped = Object.keys(registryMap).length > 0;
+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");
-  if (push && !/[.:]|^localhost$/.test(def.repository.split("/")[0]!)) throw new Error(`imageBuild '${def.name}': push needs a repository with a registry host, got '${def.repository}'`);
+  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: push ? PushedImage : 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,
-        ...(context ? { context } : {}),
-        ...(dockerfile !== "Dockerfile" ? { dockerfile } : {}),
-        ...(push ? { push: true } : {}),
-        ...(contentTag ? { contentTag: true } : {}),
-        ...(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 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, def.repository, tag);
+          const digest = await registryDigest(ctx.http, repository, tag, access);
           if (digest) {
-            ctx.log("image already in the registry", { image: `${def.repository}:${tag}`, digest });
-            return { repository: def.repository, tag, digest };
+            ctx.log("image already in the registry", { image: `${repository}:${tag}`, digest });
+            return { repository, tag, digest };
           }
         }
 
-        const caches = await reachableCaches(ctx, { registryMap, cacheRepo: def.cacheRepo });
+        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;
@@ -262,7 +404,11 @@ export function imageBuild<const N extends string>(def: ImageBuildTarballDef<N>
           `--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 });
@@ -275,16 +421,54 @@ export function imageBuild<const N extends string>(def: ImageBuildTarballDef<N>
         }
         if (!/^sha256:[0-9a-f]{64}$/.test(digest)) throw new Error(`kaniko wrote an unexpected digest: '${digest}'`);
         if (push) {
-          ctx.log("image pushed", { image: `${def.repository}:${tag}`, digest });
-          return { repository: def.repository, tag, digest };
+          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;
 }
 
-type AnyImageBuild = Step<string, ImageBuildInput, typeof BuiltImage | typeof PushedImage, never> & LibraryStep;
+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,4 +1,6 @@
 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";
@@ -6,11 +8,14 @@ import { script } from "./script.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, ImageBuildTarballDef, ImageBuildPushDef } 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

@@ -26,7 +26,13 @@ export const PushedImage = model(
 /** 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/testing/index.ts

@@ -5,7 +5,7 @@ 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>;
 }