@intentius/chant 0.124.32 → 0.124.34

package/src/workspace/ci-runner-start.ts

@@ -0,0 +1,193 @@
+/**
+ * `chant ci runner-start sign|verify` and `chant ci run --require-runner-start`
+ * (#4147): the runner-start statement (../runner-start.ts) checked against
+ * `.chant/trust.json` at base.
+ *
+ * - `sign` is for the provisioner that starts a runner for one job: it signs
+ *   the job's ids with a runner key the job never holds and prints the
+ *   envelope, which the provisioner puts where the job looks for it.
+ * - `verify` is for the job: it names itself from the forge's variables,
+ *   reads the statement, and fails unless a runner key `.chant/trust.json`
+ *   at base lists, whose principal holds the `runner` role, signed it for
+ *   this job.
+ * - `ci run --require-runner-start` makes the same check before the job's
+ *   first step, so an apply refuses before it trades for any credentials.
+ *
+ * Requiring the statement is opt-in (#4156). With nothing asking for it,
+ * nothing reads it, and a runner with none never refuses, warns or hides
+ * anything.
+ *
+ * {@link runnerStartReadiness} says whether a repository could require it
+ * at base, and what is missing, for the isolated-runners security group
+ * (#4168, section 8), whose WSP165 check reports these gaps.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { CommandContext } from "../cli/registry";
+import { formatError } from "../cli/format";
+import {
+  ciJobFromEnv,
+  RUNNER_START_SIGNER_ROLE,
+  signRunnerStart,
+  verifyRunnerStartForJob,
+  type CiJobIdentity,
+  type CiSystem,
+  type RunnerStartVerdict,
+} from "../runner-start";
+import { gitRevisionSource } from "./record-source";
+import { gitTop } from "./tree";
+import { loadRunnerKey } from "./trust/dsse";
+import { emptyPolicy, readTrustPolicy, type TrustPolicy } from "./trust/policy";
+
+/** The policy at `base` in the repository around `cwd`. */
+function policyAt(top: string, base: string): TrustPolicy {
+  return readTrustPolicy(gitRevisionSource(top, base), base);
+}
+
+/**
+ * Check this job's runner-start statement against `.chant/trust.json` at
+ * `base`. `commit` is the commit the job runs, in place of the forge's
+ * variable. Never throws.
+ */
+export function checkRunnerStart(input: { top: string; base: string; env?: Record<string, string | undefined>; commit?: string; readFile?: (path: string) => string }): RunnerStartVerdict {
+  const policy = policyAt(input.top, input.base);
+  if (policy.problems.length > 0) return { status: "untrusted", reason: `.chant/trust.json at ${input.base.slice(0, 12)} cannot be read: ${policy.problems.join("; ")}` };
+  return verifyRunnerStartForJob({
+    runners: policy.runners,
+    roles: policy.roles,
+    ...(input.env ? { env: input.env } : {}),
+    ...(input.commit ? { commit: input.commit } : {}),
+    ...(input.readFile ? { readFile: input.readFile } : {}),
+  });
+}
+
+/** One thing a repository lacks before it can require runner-start statements. */
+export interface RunnerStartGap {
+  /** Not a read-contract reason code: the isolated-runners group (#4168) maps each to its own security code. */
+  gap: "no-runner-key" | "no-runner-role" | "trust-unreadable";
+  reason: string;
+}
+
+/**
+ * Whether `.chant/trust.json` in `policy` lets a job require a runner-start
+ * statement: a key under `runners` whose principal holds the `runner` role.
+ * `configured` is true when there are no gaps. For the isolated-runners
+ * security group (#4168); nothing here refuses or warns.
+ */
+export function runnerStartReadiness(policy: TrustPolicy): { configured: boolean; gaps: RunnerStartGap[] } {
+  const gaps: RunnerStartGap[] = [];
+  if (policy.problems.length > 0) {
+    gaps.push({ gap: "trust-unreadable", reason: `.chant/trust.json cannot be read: ${policy.problems.join("; ")}` });
+    return { configured: false, gaps };
+  }
+  if (policy.runners.length === 0) {
+    gaps.push({ gap: "no-runner-key", reason: ".chant/trust.json lists no key under runners for a provisioner to sign with: chant workspace trust runner add <principal> --key <ssh-ed25519 line>" });
+  } else {
+    const holders = new Set((policy.roles[RUNNER_START_SIGNER_ROLE] ?? []).map((p) => p.normalize("NFKC").trim().toLowerCase()));
+    if (!policy.runners.some((r) => holders.has(r.principal.normalize("NFKC").trim().toLowerCase()))) {
+      gaps.push({ gap: "no-runner-role", reason: `no principal under runners holds the ${RUNNER_START_SIGNER_ROLE} role in .chant/trust.json: "roles": { "${RUNNER_START_SIGNER_ROLE}": ["<principal>"] }` });
+    }
+  }
+  return { configured: gaps.length === 0, gaps };
+}
+
+/** {@link runnerStartReadiness} for the repository around `cwd` at `base` (default `HEAD`). */
+export function runnerStartReadinessAt(cwd: string, base = "HEAD"): { configured: boolean; gaps: RunnerStartGap[] } {
+  const top = gitTop(cwd);
+  if (!top) return runnerStartReadiness(emptyPolicy(null, [`${cwd} is not in a git repository`]));
+  const commit = revParse(top, base);
+  return runnerStartReadiness(commit ? policyAt(top, commit) : emptyPolicy(null, [`${base} is not a commit`]));
+}
+
+function revParse(top: string, rev: string): string | undefined {
+  try {
+    return execFileSync("git", ["rev-parse", "--verify", "-q", `${rev}^{commit}`], { cwd: top, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The base `verify` reads trust at: `--base`, else the remote's default branch, else `HEAD`. */
+function verifyBase(top: string, base?: string): string {
+  const rev = base ?? (revParse(top, "refs/remotes/origin/HEAD") ? "refs/remotes/origin/HEAD" : "HEAD");
+  const commit = revParse(top, rev);
+  if (!commit) throw new Error(`--base ${rev} is not a commit in this repository`);
+  return commit;
+}
+
+/** The job named by `--job`: JSON, or `@<file>` holding it. */
+export function parseJobSpec(spec: string): CiJobIdentity {
+  const text = spec.startsWith("@") ? readFileSync(resolve(spec.slice(1)), "utf8") : spec;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new Error("--job takes the job as JSON, or @<file> holding it: {\"system\":\"github\",\"repo\":\"owner/name\",\"run\":\"<id>\",\"attempt\":\"1\",\"job\":\"apply\",\"commit\":\"<sha>\",\"runner\":\"<name>\"}");
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("--job takes a JSON object");
+  const o = raw as Record<string, unknown>;
+  const str = (k: string): string | undefined => (o[k] === undefined ? undefined : String(o[k]));
+  const known = ["system", "repo", "run", "attempt", "job", "commit", "runner"];
+  const extra = Object.keys(o).filter((k) => !known.includes(k));
+  if (extra.length > 0) throw new Error(`--job has fields chant does not know: ${extra.join(", ")}`);
+  return {
+    system: (str("system") ?? "") as CiSystem,
+    repo: str("repo") ?? "",
+    run: str("run") ?? "",
+    attempt: str("attempt") ?? "1",
+    job: str("job") ?? "",
+    commit: str("commit") ?? "",
+    ...(str("runner") ? { runner: str("runner")! } : {}),
+  };
+}
+
+const USAGE = "chant ci runner-start sign --key <runner key.pem> --principal <name> --job <json|@file> [-o <file>]\n  chant ci runner-start verify [--base <rev>] [--commit <sha>] [--json]";
+
+/** `chant ci runner-start sign|verify`. */
+export async function runCiRunnerStart(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const action = args.extraPositional;
+  try {
+    if (action === "sign") {
+      if (!args.key) throw new Error("--key names the provisioner's runner key, an Ed25519 private key in PEM, which the job never holds");
+      if (!args.ciPrincipal) throw new Error("--principal names the principal .chant/trust.json lists the key for under runners");
+      if (!args.ciJob) throw new Error("--job names the job the runner was started for, as JSON or @<file>");
+      const job = parseJobSpec(args.ciJob);
+      const pem = readFileSync(resolve(args.key), "utf8");
+      const loaded = loadRunnerKey(pem);
+      const envelope = signRunnerStart(job, { principal: args.ciPrincipal, key: loaded.key, publicKey: loaded.publicKey });
+      const text = `${JSON.stringify(envelope)}\n`;
+      if (args.output) writeFileSync(resolve(args.output), text, { mode: 0o644 });
+      else process.stdout.write(text);
+      return 0;
+    }
+    if (action === "verify") {
+      const top = gitTop(process.cwd());
+      if (!top) throw new Error("verify reads .chant/trust.json at a commit, and this directory is not in a git repository");
+      const base = verifyBase(top, args.base);
+      const verdict = checkRunnerStart({ top, base, ...(args.commit ? { commit: args.commit } : {}) });
+      if (args.json) process.stdout.write(`${JSON.stringify({ ...verdict, base })}\n`);
+      else console.error(`ci runner-start: ${verdict.status}: ${verdict.reason}`);
+      return verdict.status === "verified" ? 0 : 1;
+    }
+    throw new Error(`ci runner-start takes sign or verify${action ? `, not ${JSON.stringify(action)}` : ""}`);
+  } catch (err) {
+    console.error(formatError({ message: `chant ci runner-start: ${err instanceof Error ? err.message : String(err)}`, hint: USAGE }));
+    return 1;
+  }
+}
+
+/**
+ * The check `ci run --require-runner-start` makes before the job's first
+ * step: the statement for this job, verified against `.chant/trust.json` at
+ * `base`. Throws with the verdict's reason unless it verified.
+ */
+export function requireRunnerStart(input: { top: string; base: string; commit: string; env: Record<string, string | undefined> }): Extract<RunnerStartVerdict, { status: "verified" }> {
+  const named = ciJobFromEnv(input.env);
+  if (!named.ok) throw new Error(`--require-runner-start needs a forge job to check: ${named.reason}`);
+  const verdict = checkRunnerStart({ top: input.top, base: input.base, env: input.env, commit: input.commit });
+  if (verdict.status !== "verified") throw new Error(`--require-runner-start: ${verdict.status}: ${verdict.reason}`);
+  return verdict;
+}

package/src/workspace/ci-serve-builds.test.ts

@@ -0,0 +1,86 @@
+/**
+ * #4169 — `ci serve --build-command` serves each `ci/build/<sha>` tag once,
+ * within `maxJobs`, and records how each build ended.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { buildRequestAnnotation, requestedBuild } from "./ci-builds";
+import { ciServeBuilds, ciServePass, formatCiServeEvent, newCiServeRuntime, type CiServeEvent, type CiServeOptions } from "./ci-serve";
+import type { CiGreen } from "./declaration";
+
+afterAll(cleanScratch);
+
+const GREEN = { branch: "main", phases: [], require: ["suites"] } as unknown as CiGreen;
+
+function clone(): { root: string; shas: string[] } {
+  const origin = scratchDir("chant-serve-builds-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-serve-builds-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "remote", "add", "origin", origin);
+  const shas: string[] = [];
+  for (const n of ["a", "b"]) {
+    writeFiles(root, { [`${n}.txt`]: `${n}\n` });
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", n);
+    shas.push(git(root, "rev-parse", "HEAD"));
+    const r = requestedBuild(GREEN, shas.at(-1)!, ["suites"], new Date(`2026-10-20T1${shas.length}:00:00Z`));
+    git(root, "tag", "-a", "-m", buildRequestAnnotation(r), r.tag, r.commit);
+  }
+  git(root, "push", "-q", "origin", "main", "--tags");
+  // The serve's clone learns the tags from the forge.
+  for (const s of shas) git(root, "tag", "-d", `ci/build/${s}`);
+  return { root, shas };
+}
+
+const options = (root: string, built: string[], log: CiServeEvent[], extra: Partial<CiServeOptions> = {}): CiServeOptions => ({
+  cwd: root,
+  forge: "github",
+  repo: "acme/app",
+  env: "prod",
+  client: { openPullRequests: async () => [], branchHead: async () => undefined },
+  stateDir: join(root, ".serve"),
+  buildCommand: "true",
+  build: async ({ request }) => (built.push(request.commit), request.commit === built[0] ? 0 : 2),
+  log: (e) => log.push(e),
+  ...extra,
+});
+
+describe("ci serve --build-command (#4169)", () => {
+  test("serves each request once, oldest first, within maxJobs, and records how it ended", async () => {
+    const { root, shas } = clone();
+    const built: string[] = [];
+    const log: CiServeEvent[] = [];
+    const rt = newCiServeRuntime();
+    const first = ciServeBuilds(options(root, built, log), rt);
+    expect(first.events.map((e) => e.type === "build" && e.status)).toEqual(["started", "held"]);
+    await Promise.all(first.started);
+    const second = ciServeBuilds(options(root, built, log), rt);
+    await Promise.all(second.started);
+    expect(built).toEqual(shas);
+    const state = JSON.parse(readFileSync(join(root, ".serve", "chant-apply-prod.json"), "utf-8"));
+    expect(Object.fromEntries(Object.entries(state.builds).map(([k, v]) => [k, (v as { status: string }).status]))).toEqual({ [`build:${shas[0]}`]: "ok", [`build:${shas[1]}`]: "fail" });
+    // Served once: another pass starts nothing.
+    expect(ciServeBuilds(options(root, built, log), rt).started).toEqual([]);
+    expect(log.map((e) => formatCiServeEvent(e))).toContain(`the build of suites at ${shas[1].slice(0, 12)} failed with exit code 2`);
+  });
+
+  test("without --build-command a pass leaves the tags alone; the default build runs the command in a worktree of the commit", async () => {
+    const { root, shas } = clone();
+    const log: CiServeEvent[] = [];
+    await ciServePass({ ...options(root, [], log), buildCommand: undefined });
+    expect(log.filter((e) => e.type === "build")).toEqual([]);
+    const out = join(root, ".serve-out");
+    await ciServePass({ ...options(root, [], log), build: undefined, buildCommand: `git rev-parse HEAD >> ${out}; echo "$CHANT_BUILD_PHASES $CHANT_BUILD_REASON" >> ${out}`, maxJobs: 2 });
+    expect(existsSync(out)).toBe(true);
+    const lines = readFileSync(out, "utf-8").trim().split("\n");
+    expect(lines.filter((l) => /^[0-9a-f]{40}$/.test(l)).sort()).toEqual([...shas].sort());
+    expect(lines.filter((l) => l === "suites requested")).toHaveLength(2);
+  });
+});

package/src/workspace/ci-serve.test.ts

@@ -143,6 +143,8 @@ function serve(app: string, client: CiServeForge, extra: Partial<CiServeOptions>
       client,
       stateDir: state,
       holder: "serve-test",
+      // Most tests here cover the apply on merge, which #4168 made opt-in; the record tests pass false.
+      applyOnMerge: true,
       // A job image of its own, so no setup line downloads OpenTofu.
       job: { image: "chant-ci-serve-test:local", chant: fakeChant(), hostEnv: env, passEnv: Object.keys(hostEnv ?? {}) },
       log: (e) => events.push(e),
@@ -177,6 +179,63 @@ const isAncestor = (cwd: string, a: string, b: string): boolean => {
 const argsOf = (report: string, stage: string): string[] => readFileSync(join(report, `${stage}.args`), "utf-8").trimEnd().split("\n");
 const ofType = <T extends CiServeEvent["type"]>(events: CiServeEvent[], type: T) => events.filter((e): e is Extract<CiServeEvent, { type: T }> => e.type === type);
 
+describe("ci serve records each merge unless apply on merge is opted in (#4168)", () => {
+  test("a merge to the target branch gets the record job, measured from the head before it, and no resume record", async () => {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const { opts, events, state } = serve(app, forge, { applyOnMerge: false });
+    await ciServePass(opts);
+    const merged = commit(root, "app/merged.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = merged;
+    forge.merges.set(merged, 21);
+
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "record", commit: merged, base: main, pr: 21, status: "ok" })]);
+    const argv = argsOf(pass.jobs[0]!.report!, "pr-record");
+    expect(argv.slice(0, 4)).toEqual(["components", "pr-record", "--base", main]);
+    expect(argv).not.toContain("--resume");
+    expect(ofType(events, "started")[0]).not.toHaveProperty("resume");
+    expect(existsSync(join(state, "resume"))).toBe(false);
+    const saved = readCiServeState(join(state, `${prApplyGroup("prod", "app")}.json`), { forge: "forgejo", repo: "demo/estate", env: "prod", branch: "main" });
+    expect(saved.target).toBe(merged);
+    expect(saved.jobs[ciServeKey({ job: "record", commit: merged })]).toMatchObject({ status: "ok" });
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+  });
+
+  test("each settled job runs the tick, and a tick that fails is an error event, never a failed job", async () => {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const ticks: string[] = [];
+    let fail = false;
+    const { opts, events } = serve(app, forge, {
+      applyOnMerge: false,
+      tick: async () => {
+        ticks.push("tick");
+        if (fail) throw new Error("forge said no");
+        return ["ci/green/abc"];
+      },
+    });
+    await ciServePass(opts);
+    expect(ticks).toEqual([]);
+    const merged = commit(root, "app/merged.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = merged;
+    await ciServePass(opts);
+    expect(ticks).toEqual(["tick"]);
+    expect(ofType(events, "tick")).toEqual([{ type: "tick", made: ["ci/green/abc"] }]);
+    expect(formatCiServeEvent({ type: "tick", made: ["ci/green/abc"] })).toBe("ci tick made ci/green/abc");
+
+    fail = true;
+    const next = commit(root, "app/next.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = next;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs[0]).toMatchObject({ job: "record", status: "ok" });
+    expect(ofType(events, "error").map((e) => e.message)).toContain("ci tick after a job settled: forge said no");
+  });
+});
+
 describe("chant ci serve (#4095)", () => {
   test("one poll plans a new pull request head once, and skips forks and authors not given", async () => {
     const { root, app, main } = workspace();