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

package/src/ctx/sh.ts

@@ -1,32 +1,49 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, isAbsolute, join } from "node:path";
-import type { ExecOptions, Sh, ShOptions } from "./types.ts";
-import { PRIVATE_ENV } from "../harness/env.ts";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, isAbsolute, join } from 'node:path';
+import type { ExecOptions, Sh, ShOptions } from './types.ts';
+import { PRIVATE_ENV } from '../harness/env.ts';
 
 /** Shells looked for, in order. kaniko only has /busybox/sh; distroless has none. */
-export const SHELL_CANDIDATES = ["/bin/sh", "/busybox/sh", "/bin/bash"] as const;
+export const SHELL_CANDIDATES = ['/bin/sh', '/busybox/sh', '/bin/bash'] as const;
 
 export class ShellNotFoundError extends Error {
-  override name = "ShellNotFoundError";
+  override name = 'ShellNotFoundError';
   constructor() {
     super(
-      `no shell found in this image (looked for ${SHELL_CANDIDATES.join(", ")}). ` +
+      `no shell found in this image (looked for ${SHELL_CANDIDATES.join(', ')}). ` +
         `ctx.sh needs a shell: use an image that has one, or run binaries directly with ctx.exec([...]).`,
     );
   }
 }
 
 export class CommandError extends Error {
-  override name = "CommandError";
-  constructor(readonly what: string, readonly exitCode: number | null, readonly signalCode: string | null) {
-    super(`${what} failed with ${signalCode ? `signal ${signalCode}` : `exit code ${exitCode}`}`);
+  override name = 'CommandError';
+  constructor(
+    readonly what: string,
+    readonly exitCode: number | null,
+    readonly signalCode: string | null,
+  ) {
+    super(
+      `${what} failed with ${signalCode ? `signal ${signalCode}` : `exit code ${exitCode}`}`,
+    );
   }
 }
 
 /** The command went quiet for longer than its `idleTimeoutSeconds` and was killed. */
 export class CommandStalledError extends CommandError {
-  override name = "CommandStalledError";
-  constructor(what: string, readonly idleTimeoutSeconds: number, signalCode: string | null) {
+  override name = 'CommandStalledError';
+  constructor(
+    what: string,
+    readonly idleTimeoutSeconds: number,
+    signalCode: string | null,
+  ) {
     super(what, null, signalCode);
     this.message = `${what} produced no output for ${idleTimeoutSeconds} s and was killed`;
   }
@@ -42,7 +59,7 @@ export function detectShell(candidates: readonly string[] = SHELL_CANDIDATES): s
 
 /** True for the value of `import x from "./x.sh" with { type: "file" }` (compiled or from source). */
 export function isEmbeddedScript(s: string): boolean {
-  if (s.startsWith("/$bunfs/") || s.startsWith("B:/~BUN/")) return true;
+  if (s.startsWith('/$bunfs/') || s.startsWith('B:/~BUN/')) return true;
   if (!isAbsolute(s) || !/\.(sh|bash)$/.test(s) || /\s/.test(s)) return false;
   try {
     return statSync(s).isFile();
@@ -54,7 +71,8 @@ export function isEmbeddedScript(s: string): boolean {
 /** Environment for child processes: the harness env minus harness-only credentials, plus extras. */
 export function childEnv(extra?: Record<string, string>): Record<string, string> {
   const env: Record<string, string> = {};
-  for (const [k, v] of Object.entries(process.env)) if (v !== undefined && !PRIVATE_ENV.includes(k)) env[k] = v;
+  for (const [k, v] of Object.entries(process.env))
+    if (v !== undefined && !PRIVATE_ENV.includes(k)) env[k] = v;
   return { ...env, ...extra };
 }
 
@@ -64,7 +82,10 @@ export interface ShDeps {
   shellCandidates?: readonly string[];
 }
 
-export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[], opts?: ExecOptions) => Promise<void> } {
+export function createSh(deps: ShDeps): {
+  sh: Sh;
+  exec: (argv: readonly string[], opts?: ExecOptions) => Promise<void>;
+} {
   const copied = new Map<string, string>();
   let counter = 0;
 
@@ -72,7 +93,7 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
   const materialize = (script: string): string => {
     const hit = copied.get(script);
     if (hit) return hit;
-    const dir = join(deps.tmpDir, "scripts");
+    const dir = join(deps.tmpDir, 'scripts');
     mkdirSync(dir, { recursive: true });
     const dest = join(dir, `${++counter}-${basename(script)}`);
     writeFileSync(dest, readFileSync(script));
@@ -81,21 +102,34 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
     return dest;
   };
 
-  const argvFor = (cmd: string | { script: string }, args: readonly string[]): { argv: string[]; what: string } => {
-    const scriptPath = typeof cmd === "object" ? cmd.script : isEmbeddedScript(cmd) ? cmd : undefined;
+  const argvFor = (
+    cmd: string | { script: string },
+    args: readonly string[],
+  ): { argv: string[]; what: string } => {
+    const scriptPath =
+      typeof cmd === 'object' ? cmd.script : isEmbeddedScript(cmd) ? cmd : undefined;
     if (scriptPath === undefined) {
       const shell = detectShell(deps.shellCandidates);
       // `sh -c cmd sh a b`: the args are $1, $2… of the command.
-      return { argv: [shell, "-c", cmd as string, "sh", ...args], what: `command \`${truncate(cmd as string)}\`` };
+      return {
+        argv: [shell, '-c', cmd as string, 'sh', ...args],
+        what: `command \`${truncate(cmd as string)}\``,
+      };
     }
     const file = materialize(scriptPath);
-    const first = readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+    const first = readFileSync(file, 'utf8').split('\n', 1)[0] ?? '';
     const shebang = /^#!\s*(\S+)(?:\s+(.*))?$/.exec(first);
     if (shebang && existsSync(shebang[1]!)) {
       const interpArgs = shebang[2] ? [shebang[2].trim()] : [];
-      return { argv: [shebang[1]!, ...interpArgs, file, ...args], what: `script ${basename(scriptPath)}` };
+      return {
+        argv: [shebang[1]!, ...interpArgs, file, ...args],
+        what: `script ${basename(scriptPath)}`,
+      };
     }
-    return { argv: [detectShell(deps.shellCandidates), file, ...args], what: `script ${basename(scriptPath)}` };
+    return {
+      argv: [detectShell(deps.shellCandidates), file, ...args],
+      what: `script ${basename(scriptPath)}`,
+    };
   };
 
   const run = async (
@@ -104,22 +138,26 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
     opts: { env?: Record<string, string>; cwd?: string; idleTimeoutSeconds?: number },
     capture: boolean,
   ): Promise<string> => {
-    if (deps.signal.aborted) throw new Error(`${what} not started: the step was cancelled`);
-    const idleSeconds = opts.idleTimeoutSeconds !== undefined && opts.idleTimeoutSeconds > 0 ? opts.idleTimeoutSeconds : undefined;
-    let proc: Bun.Subprocess<"ignore", "pipe" | "inherit", "pipe" | "inherit">;
+    if (deps.signal.aborted)
+      throw new Error(`${what} not started: the step was cancelled`);
+    const idleSeconds =
+      opts.idleTimeoutSeconds !== undefined && opts.idleTimeoutSeconds > 0
+        ? opts.idleTimeoutSeconds
+        : undefined;
+    let proc: Bun.Subprocess<'ignore', 'pipe' | 'inherit', 'pipe' | 'inherit'>;
     try {
       proc = Bun.spawn(argv, {
         cwd: opts.cwd,
         env: childEnv(opts.env),
-        stdin: "ignore",
-        stdout: capture || idleSeconds ? "pipe" : "inherit",
-        stderr: idleSeconds ? "pipe" : "inherit",
+        stdin: 'ignore',
+        stdout: capture || idleSeconds ? 'pipe' : 'inherit',
+        stderr: idleSeconds ? 'pipe' : 'inherit',
       });
     } catch (e) {
       throw new Error(`cannot start ${what} (${argv[0]}): ${(e as Error).message}`);
     }
-    const onAbort = () => proc.kill("SIGTERM");
-    deps.signal.addEventListener("abort", onAbort, { once: true });
+    const onAbort = () => proc.kill('SIGTERM');
+    deps.signal.addEventListener('abort', onAbort, { once: true });
 
     // Watchdog: every chunk of output re-arms the timer; on expiry TERM, then KILL after a grace.
     let stalled = false;
@@ -130,13 +168,16 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
       clearTimeout(idleTimer);
       idleTimer = setTimeout(() => {
         stalled = true;
-        proc.kill("SIGTERM");
-        killTimer = setTimeout(() => proc.kill("SIGKILL"), STALL_KILL_GRACE_MS);
+        proc.kill('SIGTERM');
+        killTimer = setTimeout(() => proc.kill('SIGKILL'), STALL_KILL_GRACE_MS);
       }, idleSeconds * 1000);
     };
     const captured: Uint8Array[] = [];
     const readers: { cancel(): Promise<void> }[] = [];
-    const pump = async (stream: ReadableStream<Uint8Array>, sink: (chunk: Uint8Array) => void) => {
+    const pump = async (
+      stream: ReadableStream<Uint8Array>,
+      sink: (chunk: Uint8Array) => void,
+    ) => {
       const reader = stream.getReader();
       readers.push(reader);
       try {
@@ -151,9 +192,18 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
       }
     };
     const pumps: Promise<void>[] = [];
-    if (capture) pumps.push(pump(proc.stdout as ReadableStream<Uint8Array>, (c) => captured.push(c)));
-    else if (idleSeconds) pumps.push(pump(proc.stdout as ReadableStream<Uint8Array>, (c) => process.stdout.write(c)));
-    if (idleSeconds) pumps.push(pump(proc.stderr as ReadableStream<Uint8Array>, (c) => process.stderr.write(c)));
+    if (capture)
+      pumps.push(
+        pump(proc.stdout as ReadableStream<Uint8Array>, (c) => captured.push(c)),
+      );
+    else if (idleSeconds)
+      pumps.push(
+        pump(proc.stdout as ReadableStream<Uint8Array>, (c) => process.stdout.write(c)),
+      );
+    if (idleSeconds)
+      pumps.push(
+        pump(proc.stderr as ReadableStream<Uint8Array>, (c) => process.stderr.write(c)),
+      );
     arm();
 
     try {
@@ -161,13 +211,23 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
       // A killed command's children may still hold the pipes open: don't wait for them after a stall.
       if (stalled) await Promise.all(readers.map((r) => r.cancel().catch(() => {})));
       else await Promise.all(pumps);
-      if (stalled) throw new CommandStalledError(what, idleSeconds!, proc.signalCode ? String(proc.signalCode) : null);
-      if (code !== 0) throw new CommandError(what, proc.signalCode ? null : code, proc.signalCode ? String(proc.signalCode) : null);
-      return capture ? Buffer.concat(captured).toString("utf8") : "";
+      if (stalled)
+        throw new CommandStalledError(
+          what,
+          idleSeconds!,
+          proc.signalCode ? String(proc.signalCode) : null,
+        );
+      if (code !== 0)
+        throw new CommandError(
+          what,
+          proc.signalCode ? null : code,
+          proc.signalCode ? String(proc.signalCode) : null,
+        );
+      return capture ? Buffer.concat(captured).toString('utf8') : '';
     } finally {
       clearTimeout(idleTimer);
       clearTimeout(killTimer);
-      deps.signal.removeEventListener("abort", onAbort);
+      deps.signal.removeEventListener('abort', onAbort);
     }
   };
 
@@ -185,13 +245,13 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
   ) as Sh;
 
   const exec = async (argv: readonly string[], opts: ExecOptions = {}) => {
-    if (argv.length === 0) throw new Error("ctx.exec needs at least the program");
-    await run([...argv], `\`${truncate(argv.join(" "))}\``, opts, false);
+    if (argv.length === 0) throw new Error('ctx.exec needs at least the program');
+    await run([...argv], `\`${truncate(argv.join(' '))}\``, opts, false);
   };
   return { sh, exec };
 }
 
 function truncate(s: string, n = 120): string {
-  const one = s.replace(/\s+/g, " ").trim();
-  return one.length > n ? one.slice(0, n - 1) + "…" : one;
+  const one = s.replace(/\s+/g, ' ').trim();
+  return one.length > n ? one.slice(0, n - 1) + '…' : one;
 }

package/src/ctx/types.ts

@@ -1,6 +1,7 @@
-import type { Skipped } from "../core/handlers.ts";
-import type { FileRef } from "../core/models.ts";
-import type { DeclaredSecrets } from "../core/secrets.ts";
+import type { Skipped } from '../core/handlers.ts';
+import type { FileRef } from '../core/models.ts';
+import type { AnyConfigEntry, ConfigValues } from '../core/config.ts';
+import type { DeclaredSecrets } from '../core/secrets.ts';
 
 /** Facts about the current execution, from the service (see README "Environment"). */
 export interface RunInfo {
@@ -79,9 +80,11 @@ export interface OutputFileOptions {
   name?: string;
 }
 
-export interface Ctx<Sec extends string = string> {
+export interface Ctx<Sec extends string = string, Cfg extends AnyConfigEntry = never> {
   /** Exactly the secrets the step declares, read from the environment. */
   readonly secrets: DeclaredSecrets<Sec>;
+  /** Exactly the config entries the step declares, from the run's config snapshot (defaults applied). */
+  readonly config: ConfigValues<Cfg>;
   readonly sh: Sh;
   /** Run a binary directly, without a shell (works in shell-less images). Rejects on non-zero exit. */
   exec(argv: readonly string[], opts?: ExecOptions): Promise<void>;
@@ -108,6 +111,23 @@ export interface Ctx<Sec extends string = string> {
   readonly run: RunInfo;
   /** A writable scratch directory (`$OLVE_DIR/tmp`; images like kaniko have no /tmp). */
   readonly tmpDir: string;
+  /**
+   * Link to what the step made or deployed (a site, a release, an image), shown with the attempt in the
+   * UI and `pl run get`. Absolute http(s) URL; at most 10 per attempt.
+   */
+  link(url: string, label?: string): void;
   /** Runtime escape hatch: produce no output. Prefer `when` blocks. */
   skip(reason: string): Skipped;
+  /**
+   * This run's callback URL for an external input with `from: [callback()]` (of any step of the pipeline):
+   * hand it to the system that will answer. POST the value as JSON, or `{"$decline": "reason"}`.
+   */
+  inputUrl(step: string | { readonly name: string }, input: string): string;
 }
+
+/** The ctx a step's handler gets: a matrix step's also carries its cell (`ctx.cell`), in axis order. */
+export type StepCtx<Sec extends string, Cfg extends AnyConfigEntry, Cell> = Ctx<
+  Sec,
+  Cfg
+> &
+  ([Cell] extends [never] ? unknown : { readonly cell: Cell });

package/src/describe/config-schema.ts

@@ -0,0 +1,98 @@
+import { SECRET_REF_KIND } from '../core/config.ts';
+import { CONFIG_CASE_KEY, CONFIG_REF_KEY } from '../core/config-refs.ts';
+import type { JsonSchema } from './schemas.ts';
+
+/**
+ * The schemas at `path` inside an entry's schema (through properties and records): every union branch that has the field, except where
+ * `kase` (`<entry>.<path>.<discriminator>=<value>`) narrows a union to one branch.
+ */
+export function subSchemas(
+  schema: unknown,
+  path: readonly string[],
+  kase: string | undefined,
+  entry: string,
+): unknown[] {
+  let narrow: { at: string; discriminator: string; value: string } | undefined;
+  if (kase) {
+    const eq = kase.lastIndexOf('=');
+    const left = kase.slice(0, eq);
+    const dot = left.lastIndexOf('.');
+    narrow = {
+      at: left.slice(0, dot),
+      discriminator: left.slice(dot + 1),
+      value: kase.slice(eq + 1),
+    };
+  }
+  const walk = (node: unknown, rest: readonly string[], here: string): unknown[] => {
+    if (node === null || typeof node !== 'object') return [];
+    const o = node as JsonSchema;
+    const branches = (o.oneOf ?? o.anyOf) as JsonSchema[] | undefined;
+    if (Array.isArray(branches)) {
+      const chosen =
+        narrow && narrow.at === here
+          ? branches.filter(
+              (b) =>
+                (
+                  (b.properties as Record<string, JsonSchema> | undefined)?.[
+                    narrow!.discriminator
+                  ] as JsonSchema | undefined
+                )?.const === narrow!.value,
+            )
+          : branches;
+      return chosen.flatMap((b) => walk(b, rest, here));
+    }
+    if (rest.length === 0) return [node];
+    const props = o.properties as Record<string, JsonSchema> | undefined;
+    if (props && Object.hasOwn(props, rest[0]!))
+      return walk(props[rest[0]!], rest.slice(1), `${here}.${rest[0]}`);
+    if (o.additionalProperties && typeof o.additionalProperties === 'object')
+      return walk(o.additionalProperties, rest.slice(1), `${here}.${rest[0]}`);
+    return [];
+  };
+  return walk(schema, path, entry);
+}
+
+/** Secret names of every secretRef inside a config entry's JSON Schema. */
+export function secretRefsOf(schema: unknown): string[] {
+  const out = new Set<string>();
+  const walk = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(walk);
+    if (v === null || typeof v !== 'object') return;
+    const o = v as JsonSchema;
+    if (o['x-olve-kind'] === SECRET_REF_KIND) {
+      const name = (o.properties as { secret?: { const?: unknown } } | undefined)?.secret
+        ?.const;
+      if (typeof name === 'string') out.add(name);
+    }
+    Object.values(o).forEach(walk);
+  };
+  walk(schema);
+  return [...out].sort();
+}
+
+/** The `{"$config": "<entry>.<path>"[, "$case": …]}` references in a step's recorded settings. */
+export function recordedConfigRefs(
+  v: unknown,
+  out: { ref: string; case?: string }[] = [],
+): { ref: string; case?: string }[] {
+  if (Array.isArray(v)) v.forEach((x) => recordedConfigRefs(x, out));
+  else if (v !== null && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o).sort();
+    const isRef =
+      typeof o[CONFIG_REF_KEY] === 'string' &&
+      (keys.length === 1
+        ? keys[0] === CONFIG_REF_KEY
+        : keys.length === 2 &&
+          keys[0] === CONFIG_CASE_KEY &&
+          keys[1] === CONFIG_REF_KEY &&
+          typeof o[CONFIG_CASE_KEY] === 'string');
+    if (isRef)
+      out.push({
+        ref: o[CONFIG_REF_KEY] as string,
+        ...(keys.length === 2 ? { case: o[CONFIG_CASE_KEY] as string } : {}),
+      });
+    else Object.values(o).forEach((x) => recordedConfigRefs(x, out));
+  }
+  return out;
+}

package/src/describe/context.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import { CONFIG_NAME, isConfigEntry } from '../core/config.ts';
+import { MODEL_NAME, type AnyModel } from '../core/models.ts';
+import { SECRET_NAME, type Secret } from '../core/secrets.ts';
+import { RESERVED_STEP_NAMES, STEP_NAME, type AnyStep } from '../core/steps.ts';
+import { canonicalize } from '../util/canonical.ts';
+import { secretRefsOf } from './config-schema.ts';
+import type { ManifestT, ModelSchemasT } from './manifest-schema.ts';
+import { schemaViews, type JsonSchema } from './schemas.ts';
+
+/** Root name used in failure-handler mappings (the service supplies FailureContext under it). */
+export const FAILURE_ROOT = 'failure';
+const RESERVED = new Set([...RESERVED_STEP_NAMES, FAILURE_ROOT]);
+
+/** What a step can read at a point of the pipeline: its output model, whether it may have been skipped, and whether it is a matrix step. */
+export interface Avail {
+  model: string | null;
+  maybe: boolean;
+  matrix?: boolean;
+}
+
+/** A select case a step sits in: which select (numbered in describe order), which value, and its condition text. */
+export interface CaseOf {
+  select: number;
+  value: string;
+  cond: string;
+}
+
+interface ConfigUse {
+  description: string;
+  required: boolean;
+  schema: JsonSchema;
+  key: string;
+  secretRefs: string[];
+}
+
+// Two places are mutually exclusive when they sit in different cases of the same select.
+const exclusive = (a: readonly CaseOf[], b: readonly CaseOf[]) =>
+  a.some((x) => b.some((y) => y.select === x.select && y.value !== x.value));
+
+const byName = ([a]: [string, unknown], [b]: [string, unknown]) =>
+  a < b ? -1 : a > b ? 1 : 0;
+
+/** The problems found so far and the models, secrets, config entries and step names the pipeline uses. */
+export class DescribeContext {
+  readonly problems: string[];
+  readonly models = new Map<string, { schemas: ModelSchemasT; key: string }>();
+  readonly secrets = new Map<string, string>();
+  readonly configs = new Map<string, ConfigUse>();
+  readonly steps = new Map<string, AnyStep>();
+  private readonly placements = new Map<
+    string,
+    { step: AnyStep; cases: readonly CaseOf[] }[]
+  >();
+  private selects = 0;
+
+  constructor(problems: readonly string[]) {
+    this.problems = [...problems];
+  }
+
+  nextSelectId(): number {
+    return ++this.selects;
+  }
+
+  useModel(m: AnyModel, at: string): string {
+    const problems = this.problems;
+    if (!MODEL_NAME.test(m.name))
+      problems.push(`${at}: model name '${m.name}' must match ${MODEL_NAME}`);
+    let schemas: ModelSchemasT;
+    try {
+      schemas = schemaViews(m.schema);
+    } catch (e) {
+      problems.push(
+        `${at}: model '${m.name}' is not representable as JSON Schema (${(e as Error).message})`,
+      );
+      return m.name;
+    }
+    const key = JSON.stringify(schemas);
+    const prev = this.models.get(m.name);
+    if (!prev) this.models.set(m.name, { schemas, key });
+    else if (prev.key !== key)
+      problems.push(
+        `two different schemas are registered under the model name '${m.name}' (one schema per model name)`,
+      );
+    return m.name;
+  }
+
+  outputViewOf(modelName: string | null): JsonSchema | undefined {
+    return modelName ? this.models.get(modelName)?.schemas.output : undefined;
+  }
+
+  useSecret(s: Secret, at: string): string {
+    if (!SECRET_NAME.test(s.name))
+      this.problems.push(`${at}: secret name '${s.name}' must match ${SECRET_NAME}`);
+    const prev = this.secrets.get(s.name);
+    if (prev === undefined) this.secrets.set(s.name, s.description);
+    else if (prev !== s.description)
+      this.problems.push(
+        `secret '${s.name}' is declared twice with different descriptions`,
+      );
+    return s.name;
+  }
+
+  useConfig(e: unknown, at: string): string | undefined {
+    const problems = this.problems;
+    if (!isConfigEntry(e))
+      return void problems.push(
+        `${at}: config entries must be config("name", "description", schema)`,
+      );
+    if (!CONFIG_NAME.test(e.name))
+      problems.push(`${at}: config name '${e.name}' must match ${CONFIG_NAME}`);
+    let schema: JsonSchema;
+    try {
+      schema = z.toJSONSchema(e.schema, {
+        io: 'input',
+        target: 'draft-2020-12',
+      }) as JsonSchema;
+      delete schema.$schema;
+      schema = canonicalize(schema) as JsonSchema;
+    } catch (err) {
+      problems.push(
+        `${at}: config '${e.name}' is not representable as JSON Schema (${(err as Error).message})`,
+      );
+      return e.name;
+    }
+    const key = JSON.stringify([e.description, schema]);
+    const prev = this.configs.get(e.name);
+    if (!prev)
+      this.configs.set(e.name, {
+        description: e.description,
+        required: !e.schema.safeParse(undefined).success,
+        schema,
+        key,
+        secretRefs: secretRefsOf(schema),
+      });
+    else if (prev.key !== key)
+      problems.push(
+        `two different config entries are named '${e.name}' (one description and schema per config name)`,
+      );
+    return e.name;
+  }
+
+  registerStep(s: AnyStep, where: string, cases: readonly CaseOf[] = []): void {
+    const problems = this.problems;
+    if (typeof s.name !== 'string' || !STEP_NAME.test(s.name))
+      problems.push(
+        `${where}: step name '${String(s.name)}' must be lower-case kebab (${STEP_NAME})`,
+      );
+    if (RESERVED.has(s.name))
+      problems.push(`${where}: '${s.name}' is reserved and cannot be a step name`);
+    const prev = this.placements.get(s.name) ?? [];
+    if (prev.some((p) => !exclusive(p.cases, cases)))
+      problems.push(`duplicate step name '${s.name}'`);
+    else if (prev.some((p) => (p.step.output?.name ?? null) !== (s.output?.name ?? null)))
+      problems.push(
+        `step '${s.name}': its select cases must give it the same output model`,
+      );
+    else if (prev.some((p) => !p.step.matrix !== !s.matrix))
+      problems.push(
+        `step '${s.name}': its select cases must all make it a matrix step, or none`,
+      );
+    this.placements.set(s.name, [...prev, { step: s, cases }]);
+    if (!this.steps.has(s.name)) this.steps.set(s.name, s);
+  }
+
+  modelsSection(): ManifestT['models'] {
+    return Object.fromEntries([...this.models].map(([k, v]) => [k, v.schemas]));
+  }
+
+  secretsSection(): ManifestT['secrets'] {
+    return [...this.secrets]
+      .sort(byName)
+      .map(([name, description]) => ({ name, description }));
+  }
+
+  configSection(): Pick<ManifestT, 'config'> {
+    if (!this.configs.size) return {};
+    return {
+      config: [...this.configs].sort(byName).map(([name, c]) => ({
+        name,
+        description: c.description,
+        required: c.required,
+        schema: c.schema,
+      })),
+    };
+  }
+}