@intentius/chant 0.124.30 → 0.124.31

package/src/workspace/ci-run-index.test.ts

@@ -0,0 +1,353 @@
+/**
+ * #4098: the run index `chant ci run --report-url` keeps at the report URL.
+ *
+ * The runs are real `ci run` jobs in a temp repository with a stub chant and
+ * a file:// report URL in another temp directory. The jobs do not push, so
+ * nothing reaches chant/lifecycle or a remote. No test makes a network call.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, declaration, git, repoFixture, scratchDir, validSchema, writeFiles } from "./__fixtures__/contract-repo";
+import { ciRun } from "./ci-run";
+import { readCiSecrets } from "./ci-secrets";
+import {
+  addRunEntry,
+  CI_RUN_INDEX_KEY,
+  CI_RUN_INDEX_LIMIT,
+  CI_RUN_INDEX_SCHEMA_ID,
+  formatCiRunIndex,
+  readCiRunIndex,
+  updateCiRunIndex,
+  type CiRunIndex,
+  type CiRunIndexEntry,
+} from "./ci-run-index";
+import { parseReportUrl, reportGet, reportKey, type ReportTarget } from "../pr-report-url";
+import schema from "./ci-run-index.schema.json";
+
+afterAll(cleanScratch);
+
+const JOB_IMAGE = "chant-ci-run-index-test:local";
+const HOST = { PATH: process.env.PATH, HOME: process.env.HOME, GITHUB_TOKEN: "t", GITHUB_REPOSITORY: "acme/estate" };
+
+/** The repository every test starts from, built once: one member, and two commits. */
+const repoTemplate = repoFixture(() => {
+  const root = scratchDir("chant-ci-run-index-template-");
+  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");
+  writeFiles(root, {
+    "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }]),
+    ".gitignore": ".chant/pr/\n",
+    "app/a.txt": "a\n",
+  });
+  const commit = (msg: string) => {
+    execFileSync("git", ["-c", "commit.gpgsign=false", "add", "-A"], { cwd: root, stdio: "ignore" });
+    execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-q", "-m", msg], { cwd: root, stdio: "ignore" });
+    return git(root, "rev-parse", "HEAD");
+  };
+  commit("init");
+  writeFiles(root, { "app/a.txt": "b\n" });
+  commit("change");
+  return root;
+}, "chant-ci-run-index-");
+
+/** A repository with one member, and a stub chant that writes the report FAKE_REPORT gives it and exits $FAKE_EXIT. */
+function workspace(): { app: string; base: string; sha: string; chant: string } {
+  const root = repoTemplate();
+  const base = git(root, "rev-parse", "HEAD~1");
+  const sha = git(root, "rev-parse", "HEAD");
+  const file = join(scratchDir("chant-ci-run-index-bin-"), "chant");
+  writeFileSync(
+    file,
+    [
+      "#!/bin/sh",
+      "mkdir -p .chant/pr",
+      'if [ -n "$FAKE_REPORT" ]; then printf "%s" "$FAKE_REPORT" > ".chant/pr/$2.json"; else echo "{}" > ".chant/pr/$2.json"; fi',
+      'exit "${FAKE_EXIT:-0}"',
+      "",
+    ].join("\n"),
+  );
+  chmodSync(file, 0o755);
+  return { app: join(root, "app"), base, sha, chant: file };
+}
+
+const reportsDir = () => scratchDir("chant-ci-run-index-reports-");
+const urlOf = (dir: string) => pathToFileURL(dir).href;
+const indexOf = (dir: string): CiRunIndex => JSON.parse(readFileSync(join(dir, CI_RUN_INDEX_KEY), "utf-8"));
+
+const { expectValid } = contract(schema);
+
+async function job(w: ReturnType<typeof workspace>, dir: string, over: Partial<Parameters<typeof ciRun>[0]> & { hostEnv?: Record<string, string | undefined> } = {}) {
+  return ciRun({
+    image: JOB_IMAGE,
+    cwd: w.app,
+    job: "plan",
+    env: "prod",
+    forge: "forgejo",
+    base: w.base,
+    pr: 7,
+    chant: w.chant,
+    hostEnv: HOST,
+    push: false,
+    output: join(scratchDir("chant-ci-run-index-out-"), "pr"),
+    loop: { reportUrl: urlOf(dir) },
+    ...over,
+  });
+}
+
+const ENTRY: CiRunIndexEntry = {
+  job: "plan",
+  pr: 1,
+  commit: "a".repeat(40),
+  status: "ok",
+  started: "2026-10-18T12:00:00.000Z",
+  ended: "2026-10-18T12:00:01.000Z",
+  runId: "r0",
+  key: reportKey(1, "a".repeat(40)),
+  runOrigin: { forge: "chant" },
+};
+
+describe("the ci-run-index schema (#4098)", () => {
+  test("is a valid schema with the contract's id", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(CI_RUN_INDEX_SCHEMA_ID);
+  });
+
+  test("a failed entry without a failure code does not validate", () => {
+    const doc = { $schema: CI_RUN_INDEX_SCHEMA_ID, contract: 1, chant: "0.124.30", updated: "2026-10-18T12:00:00.000Z", runs: [{ ...ENTRY, status: "fail" }] };
+    expect(contract(schema).validate(doc)).toBe(false);
+    expectValid({ ...doc, runs: [{ ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
+  });
+});
+
+describe("chant ci run with --report-url keeps the run index (#4098)", () => {
+  test("the index is created, grows newest first, carries every field and validates", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const plan = await job(w, dir, { runId: "run-plan" });
+    expect(plan.status).toBe("ok");
+    expect(plan.warnings).toEqual([]);
+    const apply = await job(w, dir, { job: "apply", pr: undefined, runId: "run-apply", hostEnv: { ...HOST, FAKE_REPORT: JSON.stringify({ pr: 7, status: "applied" }) }, passEnv: ["FAKE_REPORT"] });
+    expect(apply.status).toBe("ok");
+
+    const index = indexOf(dir);
+    expectValid(index);
+    expect(index.runs.map((r) => r.runId)).toEqual(["run-apply", "run-plan"]);
+    expect(index.runs[1]).toEqual({
+      job: "plan",
+      pr: 7,
+      commit: w.sha,
+      status: "ok",
+      started: plan.record.started,
+      ended: plan.record.ended,
+      runId: "run-plan",
+      key: `7/${w.sha}/app`,
+      member: "app",
+      runOrigin: { forge: "chant" },
+    });
+    // The apply found its pull request in its own report.
+    expect(index.runs[0]).toMatchObject({ job: "apply", pr: 7, key: `7/${w.sha}/app` });
+    expect(readdirSync(join(dir, "runs"))).toEqual(["index.json"]);
+    expect(formatCiRunIndex(index).split("\n")).toHaveLength(2);
+  });
+
+  test("a job with no pull request is keyed unknown", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    await job(w, dir, { job: "apply", pr: undefined, runId: "r-apply" });
+    const [run] = indexOf(dir).runs;
+    expect(run).toMatchObject({ pr: null, key: `unknown/${w.sha}/app` });
+    expectValid(indexOf(dir));
+  });
+
+  test("the index keeps the newest entries up to the limit", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    for (const n of [1, 2, 3]) await job(w, dir, { runId: `run-${n}`, runIndexLimit: 2 });
+    expect(indexOf(dir).runs.map((r) => r.runId)).toEqual(["run-3", "run-2"]);
+    expect(CI_RUN_INDEX_LIMIT).toBe(200);
+  });
+
+  test("a failed job carries its failure code", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const failed = await job(w, dir, { runId: "run-fail", hostEnv: { ...HOST, FAKE_EXIT: "3" }, passEnv: ["FAKE_EXIT"] });
+    expect(failed.status).toBe("fail");
+    const [run] = indexOf(dir).runs;
+    expect(run).toMatchObject({ status: "fail", failure: { code: "command-failed" }, runId: "run-fail" });
+    expectValid(indexOf(dir));
+
+    const refused = await job(w, dir, {
+      job: "apply",
+      runId: "run-refused",
+      hostEnv: { ...HOST, FAKE_EXIT: "1", FAKE_REPORT: JSON.stringify({ pr: 7, status: "refused", refusal: "not-approved" }) },
+      passEnv: ["FAKE_EXIT", "FAKE_REPORT"],
+    });
+    expect(refused.status).toBe("fail");
+    expect(indexOf(dir).runs[0]).toMatchObject({ failure: { code: "not-approved" } });
+  });
+
+  test("a secret the job's report names as its failure never reaches the index (#4096)", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const SECRET = "s3cret-pass-1";
+    const secretsFile = join(scratchDir("chant-ci-run-index-secrets-"), "secrets.env");
+    writeFileSync(secretsFile, `DB_PASSWORD=${SECRET}\n`, { mode: 0o600 });
+    const leaky = join(scratchDir("chant-ci-run-index-bin-"), "chant");
+    writeFileSync(
+      leaky,
+      [
+        "#!/bin/sh",
+        "mkdir -p .chant/pr",
+        // The refusal becomes the index's failure code, and the message and output carry the secret too.
+        'printf \'{"stage":"apply","pr":7,"status":"refused","refusal":"denied-%s","message":"failed with %s"}\' "$DB_PASSWORD" "$DB_PASSWORD" > .chant/pr/pr-apply.json',
+        'echo "login refused for $DB_PASSWORD" >&2',
+        "exit 3",
+        "",
+      ].join("\n"),
+    );
+    chmodSync(leaky, 0o755);
+    const r = await job(w, dir, { job: "apply", chant: leaky, runId: "run-leak", secrets: readCiSecrets(secretsFile) });
+    expect(r.status).toBe("fail");
+    const text = readFileSync(join(dir, CI_RUN_INDEX_KEY), "utf-8");
+    expect(text).not.toContain(SECRET);
+    expect(indexOf(dir).runs[0]).toMatchObject({ status: "fail", failure: { code: "denied-***" } });
+    expectValid(indexOf(dir));
+  });
+
+  test("a corrupt index is replaced with a warning and the job stays ok", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    mkdirSync(join(dir, "runs"));
+    writeFileSync(join(dir, CI_RUN_INDEX_KEY), "{ not json");
+    const r = await job(w, dir, { runId: "run-after-corrupt" });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toHaveLength(1);
+    expect(r.warnings[0]).toMatch(/run index at .*runs\/index\.json is replaced, since it is not JSON/);
+    expect(indexOf(dir).runs.map((x) => x.runId)).toEqual(["run-after-corrupt"]);
+    expectValid(indexOf(dir));
+  });
+
+  test("an index that cannot be read or written warns and leaves the job ok", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    // A file where the runs folder goes: the index can be neither read nor written.
+    writeFileSync(join(dir, "runs"), "in the way");
+    const r = await job(w, dir, { runId: "run-blocked" });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toHaveLength(1);
+    expect(r.warnings[0]).toMatch(/could not read the run index at .*, so it is not updated/);
+    expect(readFileSync(join(dir, "runs"), "utf-8")).toBe("in the way");
+  });
+
+  test("a report URL that does not parse warns, and without --report-url nothing is written", async () => {
+    const w = workspace();
+    const bad = await job(w, reportsDir(), { loop: { reportUrl: "ftp://example.invalid/x" } });
+    expect(bad.status).toBe("ok");
+    expect(bad.warnings[0]).toMatch(/the run index is not updated: --report-url ftp/);
+    const dir = reportsDir();
+    const none = await job(w, dir, { loop: {} });
+    expect(none.warnings).toEqual([]);
+    expect(existsSync(join(dir, "runs"))).toBe(false);
+  });
+});
+
+describe("updating the index", () => {
+  const target = (dir: string): ReportTarget => parseReportUrl(urlOf(dir)) as ReportTarget;
+
+  test("an upload error warns and nothing throws", async () => {
+    const warnings: string[] = [];
+    await updateCiRunIndex({
+      target: target(reportsDir()),
+      entry: ENTRY,
+      warn: (m) => warnings.push(m),
+      put: async () => {
+        throw new Error("aws s3 cp exited 1: AccessDenied");
+      },
+    });
+    expect(warnings).toEqual([expect.stringMatching(/could not write the run index at .*: aws s3 cp exited 1: AccessDenied/)]);
+  });
+
+  test("a read error other than a missing object leaves the index alone", async () => {
+    const warnings: string[] = [];
+    let wrote = false;
+    await updateCiRunIndex({
+      target: target(reportsDir()),
+      entry: ENTRY,
+      warn: (m) => warnings.push(m),
+      get: async () => {
+        throw new Error("aws s3 cp exited 1: AccessDenied");
+      },
+      put: async () => {
+        wrote = true;
+      },
+    });
+    expect(wrote).toBe(false);
+    expect(warnings[0]).toMatch(/could not read the run index/);
+  });
+
+  test("an index of a newer contract is left as it is", async () => {
+    const warnings: string[] = [];
+    let wrote = false;
+    await updateCiRunIndex({
+      target: target(reportsDir()),
+      entry: ENTRY,
+      warn: (m) => warnings.push(m),
+      get: async () => JSON.stringify({ contract: 2, runs: [] }),
+      put: async () => {
+        wrote = true;
+      },
+    });
+    expect(wrote).toBe(false);
+    expect(warnings[0]).toMatch(/is contract 2, which this chant does not write/);
+  });
+
+  test("updates in one process take turns, and a run id is kept once", async () => {
+    const dir = reportsDir();
+    const warn = (m: string) => {
+      throw new Error(m);
+    };
+    await Promise.all([1, 2, 3, 4].map((n) => updateCiRunIndex({ target: target(dir), entry: { ...ENTRY, runId: `r${n}` }, warn })));
+    expect(indexOf(dir).runs.map((r) => r.runId).sort()).toEqual(["r1", "r2", "r3", "r4"]);
+    await updateCiRunIndex({ target: target(dir), entry: { ...ENTRY, runId: "r2", status: "fail", failure: { code: "x" } }, warn });
+    const runs = indexOf(dir).runs;
+    expect(runs).toHaveLength(4);
+    expect(runs[0]).toMatchObject({ runId: "r2", status: "fail" });
+    expect(addRunEntry([ENTRY], { ...ENTRY, runId: "r9" }, 1).map((r) => r.runId)).toEqual(["r9"]);
+  });
+
+  test("the file write goes through a rename, so no temporary file is left", async () => {
+    const dir = reportsDir();
+    await updateCiRunIndex({ target: target(dir), entry: ENTRY, warn: () => {} });
+    expect(readdirSync(join(dir, "runs"))).toEqual(["index.json"]);
+  });
+
+  test("readCiRunIndex reads what was written, null for none, and says why for a bad one", async () => {
+    const dir = reportsDir();
+    expect(await readCiRunIndex(target(dir))).toBeNull();
+    await updateCiRunIndex({ target: target(dir), entry: ENTRY, warn: () => {} });
+    expect((await readCiRunIndex(target(dir)))?.runs).toEqual([ENTRY]);
+    writeFileSync(join(dir, CI_RUN_INDEX_KEY), "nope");
+    await expect(readCiRunIndex(target(dir))).rejects.toThrow(/is unusable: it is not JSON/);
+  });
+
+  test("an s3 get treats a missing object as none, with a stub in place of the AWS CLI", async () => {
+    const s3 = parseReportUrl("s3://bucket/prefix") as ReportTarget;
+    const calls: string[][] = [];
+    const absent = reportGet(s3, async (args) => {
+      calls.push(args);
+      throw new Error("aws s3 cp exited 1: An error occurred (404) when calling the HeadObject operation: Key not found");
+    });
+    expect(await absent(CI_RUN_INDEX_KEY)).toBeNull();
+    expect(calls[0]).toEqual(["s3", "cp", "s3://bucket/prefix/runs/index.json", "-", "--only-show-errors"]);
+    const denied = reportGet(s3, async () => {
+      throw new Error("aws s3 cp exited 1: AccessDenied");
+    });
+    await expect(denied(CI_RUN_INDEX_KEY)).rejects.toThrow(/AccessDenied/);
+  });
+});

package/src/workspace/ci-run-index.ts

@@ -0,0 +1,192 @@
+/**
+ * The run index (#4098, epic #4101): where the chant runner says which jobs it
+ * ran, at the `--report-url` root, for behold and the demo kiosk to find runs
+ * without a forge or a workflow file.
+ *
+ * ```
+ * <url>/runs/index.json
+ * ```
+ *
+ * One document, `ci-run-index/v1` (`ci-run-index.schema.json`). Each settled
+ * `chant ci run` job with `--report-url` set adds an entry to its front, so
+ * the newest run is first, and the list is cut to the newest `limit` entries,
+ * 200 by default. An entry's `key` is the folder the job's report went to
+ * (`reportKey`, `<pr>/<commit>`), so a reader goes from the index to
+ * `<url>/<key>/pr-<job>.json`.
+ *
+ * The update reads the index, changes it and writes it back through the same
+ * `file://` and `s3://` paths the report upload uses (pr-report-url.ts). A
+ * `file://` write goes through a temporary name and a rename. Two runners
+ * updating one index at once can lose an entry, and that is out of scope:
+ * `chant ci serve` is one host. Within one process the updates for one URL
+ * take turns, so `ci serve --max-jobs 2` does not race itself.
+ *
+ * An index that can't be parsed is replaced with a warning. An index this
+ * chant can't read for any other reason, or a newer contract, is left alone
+ * with a warning. Nothing here fails a job.
+ */
+
+import type { RunOrigin } from "../lifecycle/release-ledger";
+import type { CommandContext } from "../cli/registry";
+import { formatError } from "../cli/format";
+import { parseReportUrl, reportGet, reportPut, type ReportGet, type ReportPut, type ReportTarget } from "../pr-report-url";
+import { readerVersion } from "./declaration";
+
+export const CI_RUN_INDEX_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json";
+export const CI_RUN_INDEX_CONTRACT = 1;
+/** The first chant that writes the index. */
+export const CI_RUN_INDEX_FLOOR = "0.124.31";
+/** Where the index is kept, below the report URL. */
+export const CI_RUN_INDEX_KEY = "runs/index.json";
+/** How many entries the index keeps unless told otherwise. */
+export const CI_RUN_INDEX_LIMIT = 200;
+
+/** One job the runner ran. */
+export interface CiRunIndexEntry {
+  job: "plan" | "apply";
+  /** The pull request, or null when the job found none. */
+  pr: number | null;
+  commit: string;
+  status: "ok" | "fail";
+  /** Why a failed job failed: the `failure.code` of its run record. */
+  failure?: { code: string };
+  member?: string;
+  started: string;
+  ended: string;
+  runId: string;
+  /** The folder the job's report is under, below the report URL: `<pr>/<commit>[/<member>]`. */
+  key: string;
+  runOrigin: RunOrigin;
+}
+
+export interface CiRunIndex {
+  $schema: typeof CI_RUN_INDEX_SCHEMA_ID;
+  contract: typeof CI_RUN_INDEX_CONTRACT;
+  chant: string;
+  /** When the index was last written. */
+  updated: string;
+  /** Newest first. */
+  runs: CiRunIndexEntry[];
+}
+
+const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** The index as `text` holds it, or why it can't be used: `corrupt` is replaced, `newer` is left alone. */
+export function parseCiRunIndex(text: string): { index: CiRunIndex } | { corrupt: string } | { newer: number } {
+  let doc: unknown;
+  try {
+    doc = JSON.parse(text);
+  } catch (err) {
+    return { corrupt: `it is not JSON (${messageOf(err)})` };
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return { corrupt: "it is not an object" };
+  const d = doc as { contract?: unknown; runs?: unknown };
+  if (typeof d.contract === "number" && d.contract > CI_RUN_INDEX_CONTRACT) return { newer: d.contract };
+  if (d.contract !== CI_RUN_INDEX_CONTRACT) return { corrupt: "it is not a ci-run-index document" };
+  if (!Array.isArray(d.runs)) return { corrupt: "it has no runs list" };
+  const runs = d.runs.filter((r): r is CiRunIndexEntry => r !== null && typeof r === "object" && typeof (r as { runId?: unknown }).runId === "string");
+  return { index: { ...(doc as CiRunIndex), runs } };
+}
+
+/** `entry` at the front of `runs`, replacing an entry with its run id, cut to the newest `limit`. */
+export function addRunEntry(runs: readonly CiRunIndexEntry[], entry: CiRunIndexEntry, limit: number): CiRunIndexEntry[] {
+  return [entry, ...runs.filter((r) => r.runId !== entry.runId)].slice(0, limit);
+}
+
+/** The turn each index URL is waiting for, so updates in one process run one after another. */
+const turns = new Map<string, Promise<void>>();
+
+/**
+ * Add `entry` to the index at `target`. Never throws: a problem is a warning
+ * and the index stays as it was, or is replaced when it was unreadable JSON.
+ */
+export function updateCiRunIndex(input: {
+  target: ReportTarget;
+  entry: CiRunIndexEntry;
+  limit?: number;
+  warn: (message: string) => void;
+  now?: () => Date;
+  put?: ReportPut;
+  get?: ReportGet;
+}): Promise<void> {
+  const where = `${input.target.url}/${CI_RUN_INDEX_KEY}`;
+  const put = input.put ?? reportPut(input.target);
+  const get = input.get ?? reportGet(input.target);
+  const limit = Math.max(1, Math.floor(input.limit ?? CI_RUN_INDEX_LIMIT));
+  const work = async (): Promise<void> => {
+    let runs: CiRunIndexEntry[] = [];
+    try {
+      const text = await get(CI_RUN_INDEX_KEY);
+      if (text !== null) {
+        const parsed = parseCiRunIndex(text);
+        if ("corrupt" in parsed) input.warn(`the run index at ${where} is replaced, since ${parsed.corrupt}`);
+        else if ("newer" in parsed) return input.warn(`the run index at ${where} is contract ${parsed.newer}, which this chant does not write; it is left as it is`);
+        else runs = parsed.index.runs;
+      }
+    } catch (err) {
+      return input.warn(`could not read the run index at ${where}, so it is not updated: ${messageOf(err)}`);
+    }
+    const index: CiRunIndex = {
+      $schema: CI_RUN_INDEX_SCHEMA_ID,
+      contract: CI_RUN_INDEX_CONTRACT,
+      chant: readerVersion(),
+      updated: (input.now?.() ?? new Date()).toISOString(),
+      runs: addRunEntry(runs, input.entry, limit),
+    };
+    try {
+      await put(CI_RUN_INDEX_KEY, JSON.stringify(index, null, 2) + "\n", "application/json");
+    } catch (err) {
+      input.warn(`could not write the run index at ${where}: ${messageOf(err)}`);
+    }
+  };
+  const previous = turns.get(where) ?? Promise.resolve();
+  const next = previous.then(work, work);
+  const settled = next.catch(() => undefined);
+  turns.set(where, settled);
+  void settled.then(() => {
+    if (turns.get(where) === settled) turns.delete(where);
+  });
+  return next.catch((err) => input.warn(`could not update the run index at ${where}: ${messageOf(err)}`));
+}
+
+/** The index at `target`, or null when none is there. Throws a line a person can read when it can't be read. */
+export async function readCiRunIndex(target: ReportTarget, get: ReportGet = reportGet(target)): Promise<CiRunIndex | null> {
+  const where = `${target.url}/${CI_RUN_INDEX_KEY}`;
+  const text = await get(CI_RUN_INDEX_KEY);
+  if (text === null) return null;
+  const parsed = parseCiRunIndex(text);
+  if ("corrupt" in parsed) throw new Error(`the run index at ${where} is unusable: ${parsed.corrupt}`);
+  if ("newer" in parsed) throw new Error(`the run index at ${where} is contract ${parsed.newer}; this chant reads contract ${CI_RUN_INDEX_CONTRACT}`);
+  return parsed.index;
+}
+
+/** The text `chant ci runs` prints: one line per run, newest first. */
+export function formatCiRunIndex(index: CiRunIndex): string {
+  if (index.runs.length === 0) return "no runs in the index";
+  return index.runs
+    .map((r) => {
+      const pr = r.pr === null ? "no PR" : `PR ${r.pr}`;
+      const why = r.status === "fail" ? ` (${r.failure?.code ?? "failed"})` : "";
+      return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}`;
+    })
+    .join("\n");
+}
+
+const RUNS_USAGE = "chant ci runs --report-url <s3://<bucket>/<prefix> | file://<directory>> [--json]";
+
+/** `chant ci runs` (#4098): list the index at the report URL. */
+export async function runCiRuns(ctx: CommandContext): Promise<number> {
+  try {
+    const raw = ctx.args.reportUrl;
+    if (!raw) throw new Error("--report-url names where the index is kept");
+    const target = parseReportUrl(raw);
+    if ("error" in target) throw new Error(target.error);
+    const index = await readCiRunIndex(target);
+    if (index === null) throw new Error(`there is no run index at ${target.url}/${CI_RUN_INDEX_KEY}`);
+    console.log(ctx.args.json ? JSON.stringify(index, null, 2) : formatCiRunIndex(index));
+    return 0;
+  } catch (err) {
+    console.error(formatError({ message: `chant ci runs: ${messageOf(err)}`, hint: RUNS_USAGE }));
+    return 1;
+  }
+}