@olivervea/pipelines 2.0.0-beta.7 → 2.0.0-beta.8

package/src/library/helm-deploy.ts

@@ -6,12 +6,13 @@ import { join } from "node:path";
 import { z } from "zod";
 import type { Ctx } from "../ctx/types.ts";
 import type { Configurable } from "../core/config.ts";
-import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
+import { resolveConfigRefs } from "../core/config-refs.ts";
+import { implement, type Implementation } from "../core/handlers.ts";
 import type { FileRef } from "../core/models.ts";
 import { optional } from "../core/models.ts";
 import type { Secret } from "../core/secrets.ts";
 import { secretRef } from "../core/config.ts";
-import { makeStep, type LibraryStep, type LiteralName, type Step, type StepKind } from "../core/steps.ts";
+import { step, type AnyStep, type LiteralName, type Step } from "../core/steps.ts";
 import type { Simplify } from "../core/types.ts";
 import { serviceUrl } from "./checks.ts";
 import { chartDirectory, deployOverSsh, DEFAULT_ROLLOUT_TIMEOUT_SECONDS, HELM_DEPLOY_IMAGE, helmFlags, type HelmImageFlags, type HelmImageRefFlags } from "./helm-deploy-ssh.ts";
@@ -117,7 +118,8 @@ export interface HelmTargetDeployDef<N extends string, Im extends Record<string,
   inlineValues?: readonly Readonly<Record<string, unknown>>[];
   /**
    * The images to deploy: step input key → the chart's values prefix. Each input is a `PushedImage`;
-   * the step sets `<prefix>.repository`, `.tag`, `.digest` and `.pullPolicy=IfNotPresent`.
+   * the step sets `<prefix>.repository`, `.tag`, `.digest` and `.pullPolicy=IfNotPresent`. `{}` deploys
+   * the chart alone.
    */
   images?: Im & { readonly source?: never };
   /**
@@ -144,7 +146,7 @@ export interface HelmDeploySshTargetDef<N extends string, K extends string, Im e
   target: Configurable<SshTargetValue>;
   /** Private key for the target's host. */
   sshKey: Secret<K>;
-  /** Rollouts to wait for (`deploy/<name>` for a bare name). Default: the release name. */
+  /** Rollouts to wait for (`deploy/<name>` for a bare name). Default: the release name, or none without images. */
   deployments?: readonly string[];
 }
 
@@ -157,12 +159,12 @@ export function helmDeployInCluster<
   const N extends string,
   const Im extends Record<string, string> = DefaultImages,
   const Rf extends Record<string, string> = {},
->(def: HelmDeployInClusterDef<N, Im, Rf>): Step<N, HelmTargetDeployInput<Im, Rf>, typeof HelmRelease, never> & LibraryStep {
+>(def: HelmDeployInClusterDef<N, Im, Rf>): Implementation<Step<N, HelmTargetDeployInput<Im, Rf>, typeof HelmRelease, never>> {
   return targetDeploy("helmDeployInCluster", def as unknown as AnyTargetDef, undefined) as never;
 }
 
 /** The `target` form of `steps.helmDeployOverSsh`: an ssh target from config, registry images by digest. */
-export function helmDeployOverSshTarget(def: HelmDeploySshTargetDef<string, string, Record<string, string>, Record<string, string>>): Step & LibraryStep {
+export function helmDeployOverSshTarget(def: HelmDeploySshTargetDef<string, string, Record<string, string>, Record<string, string>>): Implementation {
   return targetDeploy("helmDeployOverSsh", def as unknown as AnyTargetDef, def.sshKey, def.deployments) as never;
 }
 
@@ -179,13 +181,12 @@ interface AnyTargetDef {
   timeoutSeconds?: number;
 }
 
-function targetDeploy(kind: StepKind, def: AnyTargetDef, sshKey: Secret | undefined, deployments?: readonly string[]): Step & LibraryStep {
+function targetDeploy(kind: "helmDeployInCluster" | "helmDeployOverSsh", def: AnyTargetDef, sshKey: Secret | undefined, deployments?: readonly string[]): Implementation {
   const images: Record<string, string> = { ...(def.images ?? { image: "image" }) };
   const imageEntries = Object.entries(images);
   const imageRefs: Record<string, string> = { ...(def.imageRefs ?? {}) };
   const refEntries = Object.entries(imageRefs);
   const rolloutTimeout = def.rolloutTimeoutSeconds ?? DEFAULT_ROLLOUT_TIMEOUT_SECONDS;
-  if (imageEntries.length === 0) throw new Error(`${kind} '${def.name}': images must not be empty`);
   if ("source" in images || "source" in imageRefs) throw new Error(`${kind} '${def.name}': 'source' can't be an image input`);
   for (const [key] of refEntries) if (key in images) throw new Error(`${kind} '${def.name}': '${key}' is both in images and imageRefs`);
   if (deployments?.length === 0) throw new Error(`${kind} '${def.name}': deployments must not be empty`);
@@ -198,71 +199,73 @@ function targetDeploy(kind: StepKind, def: AnyTargetDef, sshKey: Secret | undefi
   };
   const configurable = { target: def.target, inlineValues: def.inlineValues ?? [] };
 
-  return makeStep(
+  const contract = step({
+    name: def.name,
+    description: def.description,
     kind,
-    {
-      name: def.name, description: def.description, image: inCluster ? HELM_IMAGE : HELM_DEPLOY_IMAGE, input, output: HelmRelease,
-      secrets: sshKey ? [sshKey] : [], timeoutSeconds: def.timeoutSeconds, ...(inCluster ? { clusterAccess: true } : {}),
+    image: inCluster ? HELM_IMAGE : HELM_DEPLOY_IMAGE,
+    input,
+    output: HelmRelease,
+    secrets: sshKey ? [sshKey] : [],
+    timeoutSeconds: def.timeoutSeconds,
+    ...(inCluster ? { clusterAccess: true } : {}),
+    settings: {
+      target: def.target,
+      ...(sshKey ? { sshKey: sshKey.name } : {}),
+      chart: def.chart,
+      ...(def.inlineValues?.length ? { inlineValues: def.inlineValues } : {}),
+      images: { ...images },
+      ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
+      ...(deployments ? { deployments: [...deployments] } : {}),
+      ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
+      ...(def.healthPath !== undefined ? { healthPath: def.healthPath } : {}),
     },
-    {
-      manifestConfig: () => ({
-        target: recordConfigRefs(def.target),
-        ...(sshKey ? { sshKey: sshKey.name } : {}),
-        chart: def.chart,
-        ...(def.inlineValues?.length ? { inlineValues: recordConfigRefs(def.inlineValues) } : {}),
-        images: { ...images },
-        ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
-        ...(deployments ? { deployments: [...deployments] } : {}),
-        ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
-        ...(def.healthPath !== undefined ? { healthPath: def.healthPath } : {}),
-      }),
-      async run(input: Record<string, { repository: string; tag: string; digest: string } | undefined> & { source: { tree: FileRef } }, ctx: Ctx) {
-        const { target, inlineValues } = resolveConfigRefs(configurable, ctx.config ?? {}) as { target: HelmTargetValue; inlineValues: Record<string, unknown>[] };
-        const want = inCluster ? "inCluster" : "ssh";
-        if (target?.kind !== want) throw new Error(`${kind} '${def.name}': the target is kind '${String(target?.kind)}', not '${want}'`);
-        const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
+  } as never) as AnyStep;
+  return implement(contract, async (stepInput, ctx: Ctx) => {
+    const input = stepInput as unknown as Record<string, { repository: string; tag: string; digest: string } | undefined> & { source: { tree: FileRef } };
+    const { target, inlineValues } = resolveConfigRefs(configurable, ctx.config ?? {}) as { target: HelmTargetValue; inlineValues: Record<string, unknown>[] };
+    const want = inCluster ? "inCluster" : "ssh";
+    if (target?.kind !== want) throw new Error(`${kind} '${def.name}': the target is kind '${String(target?.kind)}', not '${want}'`);
+    const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
 
-        const generated = inlineValues.map((values, i) => {
-          const file = `olve-values-${i}.json`;
-          writeFileSync(join(chartDir, file), JSON.stringify(values));
-          return file;
-        });
-        const flags: HelmImageFlags[] = imageEntries.map(([key, prefix]) => {
-          const image = input[key]!;
-          return { prefix, repository: image.repository, tag: image.tag, digest: image.digest, pullPolicy: "IfNotPresent" };
-        });
-        const refs: HelmImageRefFlags[] = refEntries.flatMap(([key, prefix]) => {
-          const image = input[key];
-          return image ? [{ prefix, repository: image.repository, tag: image.tag, digest: image.digest }] : [];
-        });
-        const helm = { values: [...target.values, ...generated], set: target.set, images: flags, imageRefs: refs };
-        const { release, namespace } = target;
+    const generated = inlineValues.map((values, i) => {
+      const file = `olve-values-${i}.json`;
+      writeFileSync(join(chartDir, file), JSON.stringify(values));
+      return file;
+    });
+    const flags: HelmImageFlags[] = imageEntries.map(([key, prefix]) => {
+      const image = input[key]!;
+      return { prefix, repository: image.repository, tag: image.tag, digest: image.digest, pullPolicy: "IfNotPresent" };
+    });
+    const refs: HelmImageRefFlags[] = refEntries.flatMap(([key, prefix]) => {
+      const image = input[key];
+      return image ? [{ prefix, repository: image.repository, tag: image.tag, digest: image.digest }] : [];
+    });
+    const helm = { values: [...target.values, ...generated], set: target.set, images: flags, imageRefs: refs };
+    const { release, namespace } = target;
 
-        if (target.kind === "ssh") {
-          const key = ctx.secrets[sshKey!.name];
-          if (!key) throw new Error(`secret ${sshKey!.name} (sshKey) is not set`);
-          await deployOverSsh(ctx, {
-            host: target.host, key, chartDir, release, namespace,
-            hostImages: flags.map((f) => ({ repository: f.repository, tag: f.tag, digest: f.digest })),
-            flags: helm, deployments: deployments ?? [release], rolloutTimeoutSeconds: rolloutTimeout,
-          });
-        } else {
-          if (!existsSync(SERVICE_ACCOUNT_TOKEN))
-            throw new Error(`no ServiceAccount token in the step pod: the instance grants no step ServiceAccount (Kubernetes:StepServiceAccount), so an inCluster target can't be deployed`);
-          const home = join(ctx.tmpDir, "helm-home");
-          ctx.log("helm upgrade", { release, namespace, images: flags.map((f) => `${f.repository}@${f.digest}`).join(" ") });
-          await ctx.exec(["helm", "upgrade", "--install", release, ".", "-n", namespace, ...helmFlags(helm), "--wait", `--timeout=${rolloutTimeout}s`], {
-            cwd: chartDir,
-            env: { HOME: home, HELM_CACHE_HOME: join(home, "cache"), HELM_CONFIG_HOME: join(home, "config"), HELM_DATA_HOME: join(home, "data") },
-          });
-        }
+    if (target.kind === "ssh") {
+      const key = ctx.secrets[sshKey!.name];
+      if (!key) throw new Error(`secret ${sshKey!.name} (sshKey) is not set`);
+      await deployOverSsh(ctx, {
+        host: target.host, key, chartDir, release, namespace,
+        hostImages: flags.map((f) => ({ repository: f.repository, tag: f.tag, digest: f.digest })),
+        flags: helm, deployments: deployments ?? (imageEntries.length ? [release] : []), rolloutTimeoutSeconds: rolloutTimeout,
+      });
+    } else {
+      if (!existsSync(SERVICE_ACCOUNT_TOKEN))
+        throw new Error(`no ServiceAccount token in the step pod: the instance grants no step ServiceAccount (Kubernetes:StepServiceAccount), so an inCluster target can't be deployed`);
+      const home = join(ctx.tmpDir, "helm-home");
+      ctx.log("helm upgrade", { release, namespace, images: flags.map((f) => `${f.repository}@${f.digest}`).join(" ") });
+      await ctx.exec(["helm", "upgrade", "--install", release, ".", "-n", namespace, ...helmFlags(helm), "--wait", `--timeout=${rolloutTimeout}s`], {
+        cwd: chartDir,
+        env: { HOME: home, HELM_CACHE_HOME: join(home, "cache"), HELM_CONFIG_HOME: join(home, "config"), HELM_DATA_HOME: join(home, "data") },
+      });
+    }
 
-        const url = (target.url ?? serviceUrl({ release, namespace })).replace(/\/+$/, "");
-        if (def.healthPath !== undefined) await httpHealthCheck(ctx, `${url}${def.healthPath}`, { attempts: 12, delaySeconds: 5 });
-        const main = flags[0]!;
-        return { release, namespace, image: `${main.repository}:${main.tag}@${main.digest}`, ...(target.url ? { url } : {}) };
-      },
-    },
-    configurable,
-  ) as never;
+    const url = (target.url ?? serviceUrl({ release, namespace })).replace(/\/+$/, "");
+    if (def.healthPath !== undefined) await httpHealthCheck(ctx, `${url}${def.healthPath}`, { attempts: 12, delaySeconds: 5 });
+    const main = flags[0];
+    return { release, namespace, ...(main ? { image: `${main.repository}:${main.tag}@${main.digest}` } : {}), ...(target.url ? { url } : {}) } as never;
+  }) as never;
 }

package/src/library/image-build.ts

@@ -7,8 +7,9 @@ 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 { 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";
@@ -47,16 +48,8 @@ export interface ImageBuildDef<N extends string, K extends string = never> {
    * (`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). */
+  /** Build context: a directory of the source tree with a `Dockerfile` (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?: 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`);
@@ -71,15 +64,6 @@ export interface ImageBuildDef<N extends string, K extends string = never> {
    * 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).
@@ -147,32 +131,22 @@ export async function registryUp(http: Ctx["http"], host: string, signal?: Abort
   }
 }
 
-/**
- * Drops the caches that don't answer, so a cache outage (GC, maintenance) never blocks a build: an
- * unreachable mirror is left out of the registry map, an unreachable `cacheRepo` means no layer cache.
- */
-export async function reachableCaches(
+/** 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">,
-  caches: { registryMap: Record<string, string>; cacheRepo?: string },
+  registryMap: Record<string, 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));
+): 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 registryMap: Record<string, string> = {};
-  for (const [from, to] of Object.entries(caches.registryMap)) {
-    if (up.get(registryHost(to))) registryMap[from] = to;
+  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`);
   }
-  if (caches.cacheRepo && !up.get(registryHost(caches.cacheRepo))) {
-    ctx.log(`${registryHost(caches.cacheRepo)} unreachable; building without the layer cache`);
-    return { registryMap };
-  }
-  return { registryMap, ...(caches.cacheRepo ? { cacheRepo: caches.cacheRepo } : {}) };
+  return reachable;
 }
 
-/** 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;
 
@@ -314,124 +288,115 @@ export function writeDockerConfig(dir: string, host: string, username: string, p
 }
 
 /**
- * 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 }`.
+ * 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>): 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>): 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 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: push ? PushedImage : BuiltImage, secrets, timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
-    {
-      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, 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.
-        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. --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=${kanikoContext}`,
-          `--dockerfile=${kanikoContext}/${dockerfile}`,
-          ...output,
-          `--digest-file=${digestPath}`,
-          `--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 });
-
-        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 };
-      },
+  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 } : {}),
     },
-    def,
-  ) 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 {
@@ -450,25 +415,4 @@ function registryLogin(auth: RegistryAuth<string> | RegistryAuthConfig | undefin
   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;
+type AnyImageBuild = Implementation<Step<string, ImageBuildInput, typeof BuiltImage | typeof PushedImage, any>>;

package/src/library/index.ts

@@ -3,19 +3,16 @@ 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, PushedImage, HelmRelease, FailureContext } from "./models.ts";
-export { inputEnvName, type RunValue, type ScriptDef } from "./script.ts";
 export type { GitHubSourceDef } from "./github-source.ts";
-export { registryTag, registryDigest, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type RegistryAuthConfig, type RegistryAccess } from "./image-build.ts";
+export type { ImageBuildDef, ImageBuildTarballDef, ImageBuildPushDef, RegistryAuth, RegistryAuthConfig } 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 { sshSession, 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";
+export { httpHealthCheck, type HttpHealthCheckOptions } from "./http-health.ts";
 
-/** SDK-provided steps (step + handler pairs with typed config). */
-export const steps = { script, gitHubSource, imageBuild, helmDeployOverSsh, helmDeployInCluster, composeDeploy };
+/** 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

@@ -29,7 +29,8 @@ export const HelmRelease = model(
   z.object({
     release: z.string(),
     namespace: z.string(),
-    image: 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(),
   }),

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 ConfigOf, 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";
@@ -38,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");

package/src/util/handler-hash.ts

@@ -16,7 +16,7 @@ export function composeHandlerHash(bundleHash: string, harness: HarnessInfo): st
   return "sha256:" + sha256Hex(canonicalJson({ bundle: bundleHash, harness }));
 }
 
-/** Library step: kind + canonical config + harness. */
-export function libraryHandlerHash(kind: string, config: unknown, harness: HarnessInfo): string {
-  return "sha256:" + sha256Hex(canonicalJson({ library: kind, config, harness }));
+/** A step that carries its implementation: kind + canonical settings + harness, and the hash of the code that implements the kind. */
+export function libraryHandlerHash(kind: string, config: unknown, harness: HarnessInfo, code?: string): string {
+  return "sha256:" + sha256Hex(canonicalJson({ library: kind, config, harness, ...(code ? { code } : {}) }));
 }