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

package/src/harness/main.ts

@@ -5,7 +5,9 @@
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isImplementation } from "../core/handlers.ts";
+import { configRefPath, isConfigRef, unionAt } from "../core/config.ts";
 import type { AnyStep } from "../core/steps.ts";
+import type { WebhookEvent } from "../core/webhooks.ts";
 import { pipelineData, type PipelineData, type StageNode } from "../builder/pipeline.ts";
 import { createCtx, formatLog } from "../ctx/index.ts";
 import { DescribeError, describePipeline, manifestText } from "../describe/describe.ts";
@@ -24,6 +26,8 @@ export interface HarnessConfig {
   pipeline: unknown;
   handlers: HandlerRegistry;
   handlerHashes: Readonly<Record<string, string>>;
+  /** Kind → hash of the code of the steps of that kind that carry their implementation. */
+  kindHashes?: Readonly<Record<string, string>>;
   harness: HarnessInfo;
 }
 
@@ -45,14 +49,43 @@ const USAGE = "usage: step describe [--sentinels] | step run <step> | step map-t
 
 export function allSteps(data: PipelineData): AnyStep[] {
   const out: AnyStep[] = [];
-  const walk = (nodes: readonly StageNode[]) => {
-    for (const n of nodes) n.kind === "stage" ? out.push(...n.steps.map((s) => s.step)) : walk(n.nodes);
+  for (const { step } of stepsWithCases(data)) if (!out.includes(step)) out.push(step);
+  return out;
+}
+
+/** Every step with the `select` case conditions (`<ref>.<discriminator>=<value>`) it sits in. */
+export function stepsWithCases(data: PipelineData): { step: AnyStep; cases: string[] }[] {
+  const out: { step: AnyStep; cases: string[] }[] = [];
+  const walk = (nodes: readonly StageNode[], cases: string[]) => {
+    for (const n of nodes) {
+      if (n.kind === "stage") out.push(...n.steps.map((s) => ({ step: s.step, cases })));
+      else if (n.kind === "when") walk(n.nodes, cases);
+      else {
+        const union = isConfigRef(n.on) ? unionAt(n.on) : undefined;
+        for (const [value, inner] of Object.entries(n.cases))
+          walk(inner, union ? [...cases, `${configRefPath(n.on)}.${union.discriminator}=${value}`] : cases);
+      }
+    }
   };
-  walk(data.nodes);
-  for (const fh of data.failureHandlers) if (!out.includes(fh.step)) out.push(fh.step);
+  walk(data.nodes, []);
+  for (const fh of data.failureHandlers) out.push({ step: fh.step, cases: [] });
   return out;
 }
 
+/** The step `run <name>` executes: the only one so named, or the one in the cases the service selected (`OLVE_CASES`). */
+export function findStep(data: PipelineData, name: string, selected: readonly string[]): AnyStep | string {
+  const candidates = stepsWithCases(data).filter((c) => c.step.name === name);
+  const distinct = candidates.filter((c, i) => candidates.findIndex((d) => d.step === c.step) === i);
+  if (distinct.length === 0) return `unknown step '${name}'`;
+  if (distinct.length === 1) return distinct[0]!.step;
+  const chosen = distinct.filter((c) => c.cases.every((k) => selected.includes(k)));
+  if (chosen.length === 1) return chosen[0]!.step;
+  return `step '${name}' is in several select cases; ${ENV_CASES} must name the selected one (got ${JSON.stringify(selected)})`;
+}
+
+/** The select case conditions of the step being run (JSON array), set by the service for steps inside a select. */
+export const ENV_CASES = "OLVE_CASES";
+
 /** Installs SIGTERM/SIGINT handlers that abort the returned signal (PID 1 ignores signals without them). */
 export function cancellation(): { signal: AbortSignal; dispose(): void } {
   const ac = new AbortController();
@@ -69,24 +102,21 @@ export function cancellation(): { signal: AbortSignal; dispose(): void } {
   };
 }
 
-/** Resolves the function that implements `step` (library or handler module). */
+/** Resolves the function that implements `step` (carried by the step, or a handler module). */
 export async function resolveStepFunction(step: AnyStep, handlers: HandlerRegistry): Promise<StepFunction | string> {
-  if (step.kind !== "custom") {
-    if (!step.builtin) return `library step '${step.name}' (${step.kind}) has no implementation`;
-    return step.builtin.run as StepFunction;
-  }
+  if (isImplementation(step)) return step.handler as unknown as StepFunction;
   const load = handlers[step.name];
-  if (!load) return `step '${step.name}' has no handler (expected handlers/${step.name}.ts)`;
+  if (!load) return `step '${step.name}' has no handler`;
   let mod: { default: unknown };
   try {
     mod = await load();
   } catch (e) {
-    return `handlers/${step.name}.ts failed to load: ${(e as Error)?.stack ?? String(e)}`;
+    return `the handler of step '${step.name}' failed to load: ${(e as Error)?.stack ?? String(e)}`;
   }
   const impl = mod.default;
-  if (!isImplementation(impl)) return `handlers/${step.name}.ts must default-export implement(<step '${step.name}'>, …)`;
+  if (!isImplementation(impl)) return `the handler of step '${step.name}' must default-export implement(<step '${step.name}'>, …)`;
   if (impl.step !== step)
-    return `handlers/${step.name}.ts implements step '${(impl.step as AnyStep)?.name}', not '${step.name}' (the default export must be implement(<the '${step.name}' step from pipeline.ts>, …))`;
+    return `the handler of step '${step.name}' implements a different step object (it must be implement(<the '${step.name}' step from pipeline.ts>, …))`;
   return impl.handler as unknown as StepFunction;
 }
 
@@ -120,7 +150,7 @@ function readJson(path: string): { ok: true; value: unknown } | { ok: false; mes
 async function describeMode(cfg: HarnessConfig, args: string[], io: HarnessIO): Promise<number> {
   const sentinels = args.includes("--sentinels");
   try {
-    const text = manifestText(describePipeline(cfg.pipeline, { handlerNames: Object.keys(cfg.handlers), handlerHashes: cfg.handlerHashes, harness: cfg.harness }));
+    const text = manifestText(describePipeline(cfg.pipeline, { handlerNames: Object.keys(cfg.handlers), handlerHashes: cfg.handlerHashes, kindHashes: cfg.kindHashes, harness: cfg.harness }));
     await io.stdout(sentinels ? `${MANIFEST_BEGIN}\n${text}${MANIFEST_END}\n` : text);
     return EXIT.ok;
   } catch (e) {
@@ -135,8 +165,8 @@ async function describeMode(cfg: HarnessConfig, args: string[], io: HarnessIO):
 async function runMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
   if (!name) return io.stderr(USAGE), EXIT.usage;
   const data = pipelineData(cfg.pipeline);
-  const step = allSteps(data).find((s) => s.name === name);
-  if (!step) return io.stderr(`unknown step '${name}'`), EXIT.usage;
+  const step = findStep(data, name, selectedCases());
+  if (typeof step === "string") return io.stderr(step), EXIT.usage;
   const fn = await resolveStepFunction(step, cfg.handlers);
   if (typeof fn === "string") return io.stderr(fn), EXIT.configInvalid;
 
@@ -162,6 +192,12 @@ async function runMode(cfg: HarnessConfig, name: string | undefined, io: Harness
   }
 }
 
+function isWebhookEvent(v: unknown): boolean {
+  if (typeof v !== "object" || v === null || Array.isArray(v) || !("body" in v)) return false;
+  const headers = (v as { headers?: unknown }).headers;
+  return typeof headers === "object" && headers !== null && !Array.isArray(headers);
+}
+
 async function mapTriggerMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
   if (!name) return io.stderr(USAGE), EXIT.usage;
   const data = pipelineData(cfg.pipeline);
@@ -181,15 +217,21 @@ async function mapTriggerMode(cfg: HarnessConfig, name: string | undefined, io:
     exec = fail("input", `poll trigger '${name}': the event must be {"value": "<string>"}`, EXIT.inputInvalid);
   else if (trigger.kind === "push" && (typeof raw.value !== "object" || raw.value === null || Array.isArray(raw.value)))
     exec = fail("input", `push trigger: the event must be the webhook payload object`, EXIT.inputInvalid);
+  else if (trigger.kind === "webhook" && !isWebhookEvent(raw.value))
+    exec = fail("input", `webhook trigger '${name}': the event must be {"headers": {...}, "body": ...}`, EXIT.inputInvalid);
   else {
     let mapped: unknown;
     let threw: unknown = undefined;
     try {
-      mapped = trigger.kind === "poll" ? await trigger.map((raw.value as { value: string }).value) : await trigger.map(raw.value);
+      mapped =
+        trigger.kind === "poll" ? await trigger.map((raw.value as { value: string }).value)
+        : trigger.kind === "webhook" ? await trigger.map(raw.value as WebhookEvent)
+        : await trigger.map(raw.value);
     } catch (e) {
       threw = e ?? new Error("undefined");
     }
     if (threw !== undefined) exec = fail("handler", `trigger '${name}' mapper threw: ${(threw as Error)?.message ?? String(threw)}`, EXIT.handlerFailed);
+    else if (mapped === null && trigger.kind === "webhook") exec = { envelope: { status: "skipped", reason: `trigger '${name}' ignored the delivery` }, exitCode: EXIT.ok };
     else {
       const r = parseStrict(data.input.schema, mapped, "input");
       exec = r.ok
@@ -217,3 +259,12 @@ export async function runHarness(cfg: HarnessConfig, argv: readonly string[], io
 }
 
 export { formatIssues, formatLog };
+
+function selectedCases(): string[] {
+  try {
+    const v = JSON.parse(process.env[ENV_CASES] ?? "[]") as unknown;
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/src/harness/validate.ts

@@ -44,13 +44,31 @@ function entrySchema(e: unknown): z.ZodType {
   return e as z.ZodType;
 }
 
+/** Reserved input.json key holding the step's config entries (written by the service). */
+export const CONFIG_KEY = "$config";
+
+/** Parses `$config` with each declared entry's schema (defaults applied). Undeclared entries are ignored. */
+export function validateConfig(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
+  const given = isPlainObject(raw) ? raw[CONFIG_KEY] : undefined;
+  if (given !== undefined && !isPlainObject(given)) return { ok: false, issues: [`input.${CONFIG_KEY} must be an object keyed by config entry names`] };
+  const issues: string[] = [];
+  const out: Record<string, unknown> = {};
+  for (const e of step.config ?? []) {
+    const value = given?.[e.name];
+    const r = e.schema.safeParse(value);
+    if (!r.success) issues.push(...formatIssues(r.error, `config.${e.name}`).map((i) => (value === undefined ? `${i} (config entry '${e.name}' is not set)` : i)));
+    else if (r.data !== undefined) out[e.name] = r.data;
+  }
+  return issues.length ? { ok: false, issues } : { ok: true, value: out };
+}
+
 /** Validates input.json against the step's input entries. Unknown top-level keys are rejected; nested values are parsed (unknown nested keys stripped). */
 export function validateInput(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
   if (!isPlainObject(raw)) return { ok: false, issues: ["input.json must be a JSON object keyed by the step's input names"] };
   const issues: string[] = [];
   const out: Record<string, unknown> = {};
   const declared = step.input as Record<string, unknown>;
-  for (const k of Object.keys(raw)) if (!Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
+  for (const k of Object.keys(raw)) if (k !== CONFIG_KEY && !Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
   for (const [k, e] of Object.entries(declared)) {
     if (!Object.hasOwn(raw, k)) {
       if (isOptional(e)) continue;

package/src/index.ts

@@ -1,11 +1,15 @@
 /// <reference path="./assets.d.ts" />
-// @olve/pipelines — authoring API (contracts, handlers, pipeline builder).
+// @olivervea/pipelines — authoring API (contracts, handlers, pipeline builder).
 export { z } from "zod";
 export { model, fileRef, optional, type Model, type AnyModel, type Infer, type InferInput, type Plain, type FileRef, type Optional } from "./core/models.ts";
 export { secret, type Secret, type DeclaredSecrets } from "./core/secrets.ts";
-export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
+export { config, secretRef, isConfigRef, type ConfigEntry, type AnyConfigEntry, type ConfigValues, type ConfigRef, type ConfigNode, type Configurable, type DiscriminatorOf, type VariantOf } from "./core/config.ts";
+export { hmacSha256, githubSignature, bearer, type WebhookVerify, type WebhookEvent } from "./core/webhooks.ts";
+export { resolveConfigRefs, isLiteral, type Resolved } from "./core/config-refs.ts";
+export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type ConfigOf, type InputEntry, type InputSpec, type LiteralName, type OutputValue } from "./core/steps.ts";
+export type { Simplify } from "./core/types.ts";
 export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";
 export type { Ctx, RunInfo, Sh, ShOptions, ExecOptions, Http, HttpInit, RetryOptions, OutputFileOptions } from "./ctx/types.ts";
 export type { Ref, Mappable, MapperResult } from "./builder/refs.ts";
 export { pipeline, Pipeline, type PipelineDef, type InRefs, type InitialAvail, type WhenCond, type PushEvent, type StageEntry, type CheckStage, type MapperFn } from "./builder/pipeline.ts";
-export { steps, Source, BuiltImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type HelmDeployOverSshDef, httpHealthCheck, type HttpHealthCheckOptions } from "./library/index.ts";
+export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type RegistryAuthConfig, type HelmDeployOverSshDef, helmTarget, deployTarget, type DeployTargetOptions, type ComposeDeployDef, type ComposeTargetValue, type HelmDeployInClusterDef, type HelmDeploySshTargetDef, type HelmTargetDeployDef, type HelmTargetValue, type InClusterTargetValue, type SshTargetValue, httpHealthCheck, type HttpHealthCheckOptions, sshSession, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";

package/src/library/checks.ts

@@ -0,0 +1,23 @@
+// Checks for deployed apps, used from custom test handlers.
+import type { Ctx } from "../ctx/types.ts";
+
+/** The in-cluster URL of a release's Service, assuming the chart names it after the release. */
+export function serviceUrl(release: { release: string; namespace: string }): string {
+  return `http://${release.release}.${release.namespace}.svc.cluster.local`;
+}
+
+/**
+ * Checks `url` serves a single-page app: `GET <url>/` references a `/assets/*.js` bundle (Vite's
+ * layout), and the bundle is served as JavaScript. Returns the page, for app-specific checks.
+ */
+export async function checkSpa(ctx: Pick<Ctx, "http" | "log">, url: string): Promise<{ html: string; bundle: string }> {
+  const base = url.replace(/\/$/, "");
+  const html = await (await ctx.http.expectOk(`${base}/`)).text();
+  const bundle = html.match(/src="(\/assets\/[^"]+\.js)"/)?.[1];
+  if (bundle === undefined) throw new Error(`${base}/ does not reference an /assets/*.js bundle`);
+  const js = await ctx.http.expectOk(`${base}${bundle}`);
+  await js.body?.cancel().catch(() => {});
+  if (!(js.headers.get("content-type")?.includes("javascript") ?? false)) throw new Error(`${base}${bundle} is not served as JavaScript`);
+  ctx.log("SPA served", { url: base, bundle });
+  return { html, bundle };
+}

package/src/library/compose-deploy.ts

@@ -0,0 +1,96 @@
+// steps.composeDeploy — ask a Docker Compose deployer to recreate a service with an image. The step is
+// thin on purpose: the deployer (pull, recreate, health, rollback) lives beside the compose project
+// and is fixed there, behind a versioned HTTP API, without editing pipelines.
+import type { Ctx } from "../ctx/types.ts";
+import type { Configurable } from "../core/config.ts";
+import { resolveConfigRefs } from "../core/config-refs.ts";
+import { implement, type Implementation } from "../core/handlers.ts";
+import type { Secret } from "../core/secrets.ts";
+import { step, type LiteralName, type Step } from "../core/steps.ts";
+import { httpHealthCheck } from "./http-health.ts";
+import { HelmRelease, PushedImage } from "./models.ts";
+
+/** The step's own image: the work is one HTTP call from the harness. */
+export const COMPOSE_DEPLOY_IMAGE = "alpine:3.22";
+
+/** A resolved `kind: compose` target. */
+export interface ComposeTargetValue {
+  kind: "compose";
+  deployerUrl: string;
+  service: string;
+  token: { secret: string };
+  healthUrl?: string | undefined;
+}
+
+/** What the deployer answers to `POST /v1/deploy`. */
+export interface ComposeDeployResult {
+  status: "deployed" | "rolled-back" | "failed";
+  service: string;
+  image: string;
+  previousImage?: string;
+  message?: string;
+  log?: string[];
+}
+
+export interface ComposeDeployDef<N extends string, K extends string> {
+  name: LiteralName<N>;
+  /** What the step does, shown in the UI. Required; may be empty. */
+  description: string;
+  /** A compose target, usually a `select` case's reference. */
+  target: Configurable<ComposeTargetValue>;
+  /** The secret the target's `token` names (declared by the step). */
+  token: Secret<K>;
+  timeoutSeconds?: number;
+}
+
+const input = { image: PushedImage };
+
+/**
+ * Deploys a registry image (by digest) to a compose service: `POST <deployerUrl>/v1/deploy
+ * { service, image: <repository>@<digest> }` with the target's bearer token. The deployer pulls the
+ * image, recreates the service, waits for its health and rolls back on failure; the step reports its
+ * answer, then (with the target's `healthUrl`) checks health itself. Output: a `HelmRelease` with the
+ * service as `release` and `compose` as `namespace`, so it can share a step name with the helm deploys.
+ */
+export function composeDeploy<const N extends string, const K extends string>(
+  def: ComposeDeployDef<N, K>,
+): Implementation<Step<N, typeof input, typeof HelmRelease, K>> {
+  const contract = step({
+    name: def.name,
+    description: def.description,
+    kind: "composeDeploy",
+    image: COMPOSE_DEPLOY_IMAGE,
+    input,
+    output: HelmRelease,
+    secrets: [def.token],
+    timeoutSeconds: def.timeoutSeconds,
+    settings: { target: def.target, token: def.token.name },
+  });
+  return implement(contract, async ({ image }, ctx: Ctx) => {
+    const target = resolveConfigRefs(def.target, ctx.config ?? {}) as ComposeTargetValue;
+    if (target?.kind !== "compose") throw new Error(`composeDeploy '${def.name}': the target is kind '${String(target?.kind)}', not 'compose'`);
+    if (target.token.secret !== def.token.name) throw new Error(`composeDeploy '${def.name}': the target's token names secret ${target.token.secret}, but the step declares ${def.token.name}`);
+    const token = (ctx.secrets as Record<string, string>)[def.token.name];
+    const ref = `${image.repository}@${image.digest}`;
+    const url = `${target.deployerUrl.replace(/\/+$/, "")}/v1/deploy`;
+    ctx.log("deploying", { service: target.service, image: ref, deployer: target.deployerUrl });
+    const res = await ctx.http.fetch(url, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ service: target.service, image: ref }),
+    });
+    const text = await res.text();
+    let result: ComposeDeployResult | undefined;
+    try {
+      result = JSON.parse(text) as ComposeDeployResult;
+    } catch {
+      // reported below
+    }
+    for (const line of result?.log ?? []) ctx.log(`deployer: ${line}`);
+    if (!res.ok || result?.status !== "deployed")
+      throw new Error(`the deployer answered HTTP ${res.status}: ${result ? `${result.status}${result.message ? `: ${result.message}` : ""}` : text.slice(0, 300)}`);
+    if (target.healthUrl) await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
+    ctx.log("deployed", { service: target.service, image: ref, previous: result.previousImage ?? "-" });
+    return { release: target.service, namespace: "compose", image: ref };
+  }) as never;
+}

package/src/library/github-source.ts

@@ -7,7 +7,10 @@ import { join } from "node:path";
 import { z } from "zod";
 import type { Ctx } from "../ctx/types.ts";
 import type { Secret } from "../core/secrets.ts";
-import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import type { Configurable } from "../core/config.ts";
+import { 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 { extractTar } from "../util/tar.ts";
 import { Source } from "./models.ts";
 
@@ -23,11 +26,25 @@ export interface GitHubSourceDef<N extends string, T extends string> {
   description: string;
   /** Token sent to the GitHub API (needed for private repositories; raises the rate limit). */
   token?: Secret<T>;
+  /** GitHub API base (default `https://api.github.com`; GitHub Enterprise: `https://<host>/api/v3`). */
+  apiUrl?: Configurable<string | undefined>;
   timeoutSeconds?: number;
 }
 
+export const GITHUB_API_URL = "https://api.github.com";
+
+/** A declared secret's value, or "" when it is not set. */
+function optionalSecret(ctx: Pick<Ctx, "secrets">, name: string): string {
+  try {
+    return ((ctx.secrets as Record<string, string>)[name] ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
 /** Tarball URL of `repo` at `sha` (the API redirects to codeload.github.com). */
-export const gitHubTarballUrl = (repo: string, sha: string): string => `https://api.github.com/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
+export const gitHubTarballUrl = (repo: string, sha: string, apiUrl = GITHUB_API_URL): string =>
+  `${apiUrl.replace(/\/+$/, "")}/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
 
 /**
  * Downloads `repo` at `sha` from GitHub as a tarball and outputs it as a `Source` whose `tree` is the
@@ -36,42 +53,48 @@ export const gitHubTarballUrl = (repo: string, sha: string): string => `https://
  */
 export function gitHubSource<const N extends string, const T extends string = never>(
   def: GitHubSourceDef<N, T>,
-): Step<N, GitHubSourceInput, typeof Source, T> & LibraryStep {
-  return makeStep(
-    "gitHubSource",
-    { name: def.name, description: def.description, image: GITHUB_SOURCE_IMAGE, input, output: Source, secrets: def.token ? [def.token] : [], timeoutSeconds: def.timeoutSeconds },
-    {
-      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}) }),
-      async run({ repo, sha }: { repo: string; sha: string }, ctx: Ctx) {
-        const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
-        if (def.token) headers.authorization = `Bearer ${ctx.secrets[def.token.name]}`;
-        const url = gitHubTarballUrl(repo, sha);
-        mkdirSync(ctx.tmpDir, { recursive: true });
-        const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
-        const archive = join(dir, "repo.tar.gz");
+): Implementation<Step<N, GitHubSourceInput, typeof Source, T>> {
+  const contract = step({
+    name: def.name,
+    description: def.description,
+    kind: "gitHubSource",
+    image: GITHUB_SOURCE_IMAGE,
+    input,
+    output: Source,
+    secrets: def.token ? [def.token] : [],
+    timeoutSeconds: def.timeoutSeconds,
+    settings: { ...(def.token ? { token: def.token.name } : {}), ...(def.apiUrl !== undefined ? { apiUrl: def.apiUrl } : {}) },
+  });
+  return implement(contract, async ({ repo, sha }, ctx: Ctx) => {
+    const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
+    const token = def.token ? optionalSecret(ctx, def.token.name) : "";
+    if (token) headers.authorization = `Bearer ${token}`;
+    else if (def.token) ctx.log(`${def.token.name} is not set: fetching anonymously (public repositories only)`);
+    const url = gitHubTarballUrl(repo, sha, resolveConfigRefs(def.apiUrl, ctx.config ?? {}) ?? GITHUB_API_URL);
+    mkdirSync(ctx.tmpDir, { recursive: true });
+    const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
+    const archive = join(dir, "repo.tar.gz");
 
-        ctx.log("fetching source", { repo, sha });
-        // Retries network errors and 5xx; a 4xx (bad sha, no access) fails at once.
-        const status = await ctx.retry({ attempts: 4, delaySeconds: 2, backoff: 2 }, async () => {
-          const res = await ctx.http.fetch(url, { headers });
-          if (res.status >= 500) throw new Error(`HTTP ${res.status} from ${url}`);
-          if (res.ok) await Bun.write(archive, res);
-          return res.status;
-        });
-        if (status < 200 || status >= 300) {
-          throw new Error(`cannot fetch ${repo}@${sha}: HTTP ${status} from ${url}${def.token ? "" : " (no token configured: a private repository needs one)"}`);
-        }
+    ctx.log("fetching source", { repo, sha });
+    // Retries network errors and 5xx; a 4xx (bad sha, no access) fails at once.
+    const status = await ctx.retry({ attempts: 4, delaySeconds: 2, backoff: 2 }, async () => {
+      const res = await ctx.http.fetch(url, { headers });
+      if (res.status >= 500) throw new Error(`HTTP ${res.status} from ${url}`);
+      if (res.ok) await Bun.write(archive, res);
+      return res.status;
+    });
+    if (status < 200 || status >= 300) {
+      throw new Error(`cannot fetch ${repo}@${sha}: HTTP ${status} from ${url}${def.token ? "" : " (no token configured: a private repository needs one)"}`);
+    }
 
-        const extracted = join(dir, "x");
-        mkdirSync(extracted);
-        await extractTar(archive, extracted);
-        // GitHub tarballs hold one top-level directory, plus a pax_global_header entry (the commit id)
-        // that some extractors materialise as a file.
-        const roots = readdirSync(extracted).filter((e) => e !== "pax_global_header" && statSync(join(extracted, e)).isDirectory());
-        if (roots.length !== 1) throw new Error(`unexpected tarball layout for ${repo}@${sha}: top-level entries ${JSON.stringify(readdirSync(extracted))}`);
-        const tree = await ctx.output.dir(join(extracted, roots[0]!), { name: "tree" });
-        return { repo, sha, tree };
-      },
-    },
-  ) as never;
+    const extracted = join(dir, "x");
+    mkdirSync(extracted);
+    await extractTar(archive, extracted);
+    // GitHub tarballs hold one top-level directory, plus a pax_global_header entry (the commit id)
+    // that some extractors materialise as a file.
+    const roots = readdirSync(extracted).filter((e) => e !== "pax_global_header" && statSync(join(extracted, e)).isDirectory());
+    if (roots.length !== 1) throw new Error(`unexpected tarball layout for ${repo}@${sha}: top-level entries ${JSON.stringify(readdirSync(extracted))}`);
+    const tree = await ctx.output.dir(join(extracted, roots[0]!), { name: "tree" });
+    return { repo, sha, tree };
+  }) as never;
 }