@intentius/chant 0.107.1 → 0.108.1

package/src/project-codegen.ts

@@ -0,0 +1,296 @@
+/**
+ * Project-local code generation: typed code a lexicon generates into the
+ * project from sources the project declares in `chant.config.ts` (a CRD file,
+ * a Helm chart), as opposed to the types a lexicon ships in its package.
+ *
+ * The split of work:
+ *
+ * - A lexicon implements {@link ProjectCodegen} (the plugin's
+ *   `projectCodegen()` hook). It says what its declared inputs are
+ *   ({@link ProjectCodegen.inputs}, offline), renders files from them
+ *   ({@link ProjectCodegen.generate}, may fetch), and optionally reads its own
+ *   committed output back when a build starts ({@link ProjectCodegen.load}).
+ * - Core owns the output directory, writes the files, and records a digest of
+ *   the inputs beside them in {@link STAMP_FILE}. `chant generate` is the only
+ *   writer.
+ * - Every build compares the inputs' digest with the recorded one before it
+ *   serializes ({@link checkProjectCodegen}, wired in through the build-root
+ *   contributors in ./cli/plugins.ts). A mismatch fails the build. The build
+ *   never fetches and never regenerates, so it stays offline and the committed
+ *   output is what a fresh clone typechecks against.
+ *
+ * Output lives in `<codegen.outDir>/<lexicon>/`, default `src/generated/<lexicon>/`,
+ * relative to the directory holding `chant.config.*`.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { canonicalJson } from "./effect-receipt";
+import { GENERATED_MARKER } from "./discovery/files";
+
+/** Default output directory, relative to the project root. */
+export const DEFAULT_CODEGEN_OUT_DIR = "src/generated";
+
+/** The file core writes beside a lexicon's generated files: the inputs digest and the file list. */
+export const STAMP_FILE = "chant-codegen.json";
+
+/**
+ * Header for generated TypeScript. It carries discovery's generated-file
+ * marker (`./discovery/files.ts`), so the build and `chant lint` do not treat
+ * the generated module as authored source; project files still import it.
+ */
+export const GENERATED_TS_HEADER = `// ${GENERATED_MARKER}. Run \`chant generate\` to update.`;
+
+/** What a lexicon's project-codegen hooks receive. */
+export interface ProjectCodegenContext {
+  /** The directory holding `chant.config.*`. Relative paths in the config resolve against it. */
+  projectRoot: string;
+  /** The resolved project configuration; a lexicon reads its own namespace. */
+  config: Record<string, unknown>;
+  /** Absolute directory this lexicon's files go in (`<codegen.outDir>/<lexicon>`). */
+  outDir: string;
+}
+
+/** Extra context for {@link ProjectCodegen.generate}. */
+export interface ProjectCodegenGenerateContext extends ProjectCodegenContext {
+  /**
+   * The fetch remote sources go through. Absent means the global `fetch`.
+   * Tests pass a fake so no network is touched.
+   */
+  fetch?: typeof fetch;
+}
+
+/** What {@link ProjectCodegen.generate} returns. */
+export interface ProjectCodegenOutput {
+  /** File contents keyed by path relative to `outDir`, `/`-separated. */
+  files: Record<string, string>;
+  /** One line per generated item, printed by `chant generate`. */
+  summary?: string[];
+}
+
+/**
+ * A lexicon's project-local code generation (the plugin's `projectCodegen()`
+ * hook).
+ */
+export interface ProjectCodegen {
+  /**
+   * The declared inputs, as a JSON value, or `undefined` when the project
+   * declares none. Must not touch the network: the build calls it on every
+   * run. A local file is described by a hash of its content, a remote source
+   * by its pin (a version, a sha256), so editing a local file or changing a
+   * pin changes the value. Core hashes the value; the lexicon never sees the
+   * digest.
+   */
+  inputs(ctx: ProjectCodegenContext): Promise<unknown | undefined> | unknown | undefined;
+  /** Render the files from the declared inputs. May fetch, through `ctx.fetch`. */
+  generate(ctx: ProjectCodegenGenerateContext): Promise<ProjectCodegenOutput>;
+  /**
+   * Read the committed output back at the start of a build, once the inputs
+   * are known to match it. The k8s lexicon registers the generated kinds here
+   * so its serializer and the CRD spec checks know them even when discovery
+   * ran in a sandboxed child process.
+   */
+  load?(ctx: ProjectCodegenContext): Promise<void> | void;
+}
+
+/** The recorded stamp. */
+export interface ProjectCodegenStamp {
+  /** `sha256:<hex>` of the canonical JSON of {@link ProjectCodegen.inputs}. */
+  inputs: string;
+  /** The files written, relative to the lexicon's output directory. */
+  files: string[];
+}
+
+/** The minimal plugin shape these functions need. */
+export interface ProjectCodegenPlugin {
+  readonly name: string;
+  projectCodegen?(): ProjectCodegen;
+}
+
+/** Resolve the output root (`codegen.outDir`, default {@link DEFAULT_CODEGEN_OUT_DIR}) against the project root. */
+export function resolveCodegenRoot(projectRoot: string, config: Record<string, unknown>): string {
+  const codegen = config.codegen as { outDir?: unknown } | undefined;
+  const outDir = typeof codegen?.outDir === "string" && codegen.outDir.length > 0 ? codegen.outDir : DEFAULT_CODEGEN_OUT_DIR;
+  return resolve(projectRoot, outDir);
+}
+
+/** The context for one lexicon. */
+export function projectCodegenContext(
+  lexicon: string,
+  projectRoot: string,
+  config: Record<string, unknown>,
+): ProjectCodegenContext {
+  return { projectRoot, config, outDir: join(resolveCodegenRoot(projectRoot, config), lexicon) };
+}
+
+/** `sha256:<hex>` of a JSON value's canonical form. */
+export function digestInputs(inputs: unknown): string {
+  return `sha256:${createHash("sha256").update(canonicalJson(inputs)).digest("hex")}`;
+}
+
+/** Read a lexicon's stamp, or `undefined` when it has none (or it does not parse). */
+export function readStamp(outDir: string): ProjectCodegenStamp | undefined {
+  const path = join(outDir, STAMP_FILE);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<ProjectCodegenStamp>;
+    if (typeof parsed.inputs !== "string" || !Array.isArray(parsed.files)) return undefined;
+    return { inputs: parsed.inputs, files: parsed.files.filter((f): f is string => typeof f === "string") };
+  } catch {
+    return undefined;
+  }
+}
+
+/** One lexicon's result from {@link generateProjectCode}. */
+export interface ProjectCodegenResult {
+  lexicon: string;
+  /** The lexicon's output directory. */
+  outDir: string;
+  /** `written`: files (re)generated. `removed`: nothing declared, old output deleted. `none`: nothing declared, nothing there. */
+  status: "written" | "removed" | "none";
+  files: string[];
+  summary: string[];
+}
+
+/**
+ * `chant generate` for one lexicon: render its files, write them, delete
+ * files a previous run wrote that this one did not, and record the stamp.
+ * With nothing declared, a previous run's output is removed.
+ */
+export async function generateProjectCode(
+  plugin: ProjectCodegenPlugin,
+  projectRoot: string,
+  config: Record<string, unknown>,
+  options: { fetch?: typeof fetch } = {},
+): Promise<ProjectCodegenResult | undefined> {
+  const codegen = plugin.projectCodegen?.();
+  if (!codegen) return undefined;
+  const ctx = projectCodegenContext(plugin.name, projectRoot, config);
+  const previous = readStamp(ctx.outDir);
+  const inputs = await codegen.inputs(ctx);
+
+  if (inputs === undefined) {
+    if (!previous) return { lexicon: plugin.name, outDir: ctx.outDir, status: "none", files: [], summary: [] };
+    removeFiles(ctx.outDir, [...previous.files, STAMP_FILE]);
+    return { lexicon: plugin.name, outDir: ctx.outDir, status: "removed", files: previous.files, summary: [] };
+  }
+
+  const output = await codegen.generate({ ...ctx, ...(options.fetch ? { fetch: options.fetch } : {}) });
+  const files = Object.keys(output.files).sort();
+  for (const file of files) {
+    const target = safeJoin(ctx.outDir, file);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, output.files[file]);
+  }
+  if (previous) {
+    const keep = new Set(files);
+    removeFiles(ctx.outDir, previous.files.filter((f) => !keep.has(f)));
+  }
+  const stamp: ProjectCodegenStamp = { inputs: digestInputs(inputs), files };
+  mkdirSync(ctx.outDir, { recursive: true });
+  writeFileSync(join(ctx.outDir, STAMP_FILE), JSON.stringify(stamp, null, 2) + "\n");
+  return { lexicon: plugin.name, outDir: ctx.outDir, status: "written", files, summary: output.summary ?? [] };
+}
+
+/** The outcome of {@link checkProjectCodegen} for one lexicon. */
+export type ProjectCodegenCheck =
+  | { status: "current" | "none" }
+  | { status: "missing" | "drift" | "orphan"; message: string };
+
+/**
+ * Whether a lexicon's committed output matches its declared inputs. Offline.
+ *
+ * - `none`: nothing declared, nothing generated.
+ * - `current`: the recorded digest matches and every recorded file exists.
+ * - `missing`: sources are declared and there is no output (or a recorded file is gone).
+ * - `drift`: the declared sources changed since the output was generated.
+ * - `orphan`: nothing is declared any more, but generated output remains.
+ */
+export async function checkProjectCodegen(
+  plugin: ProjectCodegenPlugin,
+  projectRoot: string,
+  config: Record<string, unknown>,
+): Promise<ProjectCodegenCheck> {
+  const codegen = plugin.projectCodegen?.();
+  if (!codegen) return { status: "none" };
+  const ctx = projectCodegenContext(plugin.name, projectRoot, config);
+  const where = displayPath(projectRoot, ctx.outDir);
+  const stamp = readStamp(ctx.outDir);
+  const inputs = await codegen.inputs(ctx);
+
+  if (inputs === undefined) {
+    if (!stamp) return { status: "none" };
+    return {
+      status: "orphan",
+      message: `${where} holds generated ${plugin.name} code, but chant.config declares no ${plugin.name} sources for it. Run \`chant generate\` to remove it.`,
+    };
+  }
+  if (!stamp) {
+    return {
+      status: "missing",
+      message: `chant.config declares ${plugin.name} sources to generate, but ${where} has no generated code. Run \`chant generate\` and commit the result.`,
+    };
+  }
+  const absent = stamp.files.filter((f) => !existsSync(safeJoin(ctx.outDir, f)));
+  if (absent.length > 0) {
+    return {
+      status: "missing",
+      message: `generated ${plugin.name} file(s) missing from ${where}: ${absent.join(", ")}. Run \`chant generate\` and commit the result.`,
+    };
+  }
+  if (stamp.inputs !== digestInputs(inputs)) {
+    return {
+      status: "drift",
+      message: `generated ${plugin.name} code in ${where} is out of date: its declared sources changed since it was generated. Run \`chant generate\` and commit the result.`,
+    };
+  }
+  return { status: "current" };
+}
+
+/**
+ * The build's side of project codegen for one plugin: check the committed
+ * output against the declared inputs, throw on any mismatch, and let the
+ * lexicon load its output when it is current. Called once per top-level
+ * build, before serialization.
+ */
+export async function prepareProjectCodegen(
+  plugin: ProjectCodegenPlugin,
+  projectRoot: string,
+  config: Record<string, unknown>,
+): Promise<void> {
+  const check = await checkProjectCodegen(plugin, projectRoot, config);
+  if ("message" in check) throw new Error(check.message);
+  if (check.status === "none") return;
+  await plugin.projectCodegen?.().load?.(projectCodegenContext(plugin.name, projectRoot, config));
+}
+
+function removeFiles(outDir: string, files: string[]): void {
+  for (const file of files) {
+    rmSync(safeJoin(outDir, file), { force: true });
+  }
+  pruneEmptyDirs(outDir);
+}
+
+/** Remove empty directories under (and including) `dir`. */
+function pruneEmptyDirs(dir: string): void {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) pruneEmptyDirs(join(dir, entry.name));
+  }
+  if (readdirSync(dir).length === 0) rmdirSync(dir);
+}
+
+/** Join a recorded relative path onto `outDir`, refusing one that escapes it. */
+function safeJoin(outDir: string, file: string): string {
+  const target = resolve(outDir, file);
+  if (isAbsolute(file) || (target !== outDir && !target.startsWith(outDir + sep))) {
+    throw new Error(`generated file path "${file}" is outside ${outDir}`);
+  }
+  return target;
+}
+
+function displayPath(projectRoot: string, path: string): string {
+  const rel = relative(projectRoot, path);
+  return rel === "" ? "." : rel.split(sep).join("/");
+}

package/src/workspace/ci-green-cli.ts

@@ -0,0 +1,118 @@
+/**
+ * `chant ci` (#3573, ws-103): which commits passed CI.
+ *
+ *   ci last-green [--json]               the newest commit on the branch with a green tag and no revoked tag
+ *   ci tick [--dry-run] [--forge github] tag the commits that turned green, revoke the ones that turned red
+ *   ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>]
+ *               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
+ *                                        write the root CI file that runs the tick
+ *
+ * `last-green --json` prints `ci-last-green.schema.json`. The tick and the
+ * workflow print text.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { findWorkspaceRoot } from "../project-root";
+import { ciTick, CiGreenError, formatTick, lastGreen } from "./ci-green";
+import { ciForgeFromEnv } from "./ci-green-forge";
+import { ACTIONS_NAME, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, type PushToken, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
+import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
+import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline";
+import { gitTop, workingTree } from "./tree";
+
+const USAGE = "chant ci last-green [--json] | ci tick [--dry-run] [--forge github] | ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>] [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]";
+
+export async function runCiLastGreen(ctx: CommandContext): Promise<number> {
+  const doc = lastGreen({ cwd: process.cwd() });
+  if (ctx.args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: doc.error.message, hint: USAGE }));
+    return 1;
+  }
+  if (!doc.commit) {
+    console.error(`No first-parent commit of ${doc.ref} has a ci/green tag without a ci/revoked one. Fetch the tags first: git fetch origin --tags`);
+    return 1;
+  }
+  console.log(doc.commit.sha);
+  return 0;
+}
+
+const describe = (err: unknown) => (err instanceof WorkspaceReadError ? err.describe() : err instanceof Error ? err.message : String(err));
+
+export async function runCiTick(ctx: CommandContext): Promise<number> {
+  try {
+    const forge = ciForgeFromEnv(ctx.args.forge ?? "github");
+    const result = await ciTick({ cwd: process.cwd(), forge, dryRun: ctx.args.dryRun === true });
+    console.log(formatTick(result, ctx.args.dryRun === true));
+    return 0;
+  } catch (err) {
+    console.error(formatError({ message: `chant ci tick: ${describe(err)}`, hint: USAGE }));
+    return 1;
+  }
+}
+
+/** The push token the flags ask for, or none for the Actions token. Throws on a half-given or clashing pair. */
+function pushToken(args: CommandContext["args"]): PushToken | undefined {
+  const { ciTokenSecret: secret, ciAppIdVar: appIdVar, ciAppKeySecret: appKeySecret } = args;
+  for (const [flag, name] of [["--token-secret", secret], ["--app-id-var", appIdVar], ["--app-key-secret", appKeySecret]] as const) {
+    if (name !== undefined && !ACTIONS_NAME.test(name)) throw new Error(`${flag} takes a secret or variable name, letters, digits and underscores, not ${JSON.stringify(name)}`);
+  }
+  if (secret !== undefined && (appIdVar !== undefined || appKeySecret !== undefined)) throw new Error("--token-secret and --app-id-var/--app-key-secret each name the push token; pass one or the other");
+  if ((appIdVar === undefined) !== (appKeySecret === undefined)) throw new Error("a GitHub App token needs both the App's id and its key: --app-id-var <VAR> --app-key-secret <NAME>");
+  if (secret !== undefined) return { secret };
+  if (appIdVar !== undefined && appKeySecret !== undefined) return { appIdVar, appKeySecret };
+  return undefined;
+}
+
+export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
+  const cwd = process.cwd();
+  try {
+    const push = pushToken(ctx.args);
+    const found = findWorkspaceRoot(cwd);
+    if (!found) throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root");
+    const declaration = readDeclaration(workingTree(found.dir));
+    const green = declaration.ci?.green;
+    if (!green) throw new CiGreenError("ci-green-undeclared", `${declaration.file} declares no ci.green, so there is nothing for the workflow to run`);
+    // git reports its top with symlinks resolved (/private/var on macOS), so resolve the root too.
+    const root = realpathSync(found.dir);
+    const repoRoot = gitTop(root) ?? root;
+    const member = resolveMemberContext(cwd, found);
+    const target = ctx.args.output ? resolve(realpathSync(cwd), ctx.args.output) : join(repoRoot, CI_GREEN_WORKFLOW_FILE);
+    const fromRepo = relative(repoRoot, target).split(sep).join("/");
+
+    const scan = workflowsHolding(green, readWorkflowSources(repoRoot, fromRepo));
+    const extra = ctx.args.ciWorkflows ?? [];
+    const workflows = [...new Set([...scan.workflows, ...extra])].sort();
+    for (const f of scan.unreadable) console.error(`warning: ${f} is not valid YAML, so its jobs were not read`);
+    for (const u of scan.unmatched) console.error(`warning: no job in .github/workflows/ reports a check run matching ${JSON.stringify(u.pattern)} (phase ${u.phase}); pass --workflow <name> for the workflow that does`);
+    if (workflows.length === 0) {
+      throw new Error("no workflow in .github/workflows/ holds a check run of a required phase, so nothing would trigger the tick but its schedule; name one with --workflow <name>");
+    }
+
+    const base = member ? member.memberRoot : root;
+    const parts = ["chant", "ci", "workflow", ...extra.flatMap((w) => ["--workflow", w])];
+    if (ctx.args.output) parts.push("--output", relative(base, target).split(sep).join("/"));
+    if (ctx.args.ciChant) parts.push("--chant", ctx.args.ciChant);
+    if (ctx.args.ciInstall) parts.push("--install", ctx.args.ciInstall);
+    if (push && "secret" in push) parts.push("--token-secret", push.secret);
+    if (push && "appIdVar" in push) parts.push("--app-id-var", push.appIdVar, "--app-key-secret", push.appKeySecret);
+    const command = parts.map(shellArg).join(" ");
+    const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
+    // The install runs in the workspace root, so its lockfile there keys setup-node's npm cache.
+    const npmLock = ctx.args.ciInstall && existsSync(join(root, "package-lock.json")) ? (workspaceRoot === "." ? "package-lock.json" : `${workspaceRoot}/package-lock.json`) : undefined;
+    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push });
+    const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
+    if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
+    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}, and every 15 minutes.`);
+    return 0;
+  } catch (err) {
+    console.error(formatError({ message: `chant ci workflow: ${describe(err)}`, hint: USAGE }));
+    return 1;
+  }
+}

package/src/workspace/ci-green-forge.test.ts

@@ -0,0 +1,66 @@
+/**
+ * #3573 — the check-run client `chant ci tick` reads, driven through a
+ * recording `fetch` with no network.
+ */
+
+import { describe, expect, test } from "vitest";
+import { ForgeApiError, ForgeEnvironmentError, type ForgeFetch } from "../pr-forge";
+import { ciForgeFromEnv, CiForgeUnsupportedError, githubCiForge } from "./ci-green-forge";
+
+const SHA = "a".repeat(40);
+
+function fakeFetch(pages: Record<number, unknown> | number): { fetch: ForgeFetch; urls: string[]; headers: Record<string, string>[] } {
+  const urls: string[] = [];
+  const headers: Record<string, string>[] = [];
+  const fetch: ForgeFetch = async (url, init) => {
+    urls.push(url);
+    headers.push(init.headers);
+    if (typeof pages === "number") return { ok: false, status: pages, text: async () => '{"message":"nope"}' };
+    const page = Number(new URL(url).searchParams.get("page"));
+    return { ok: true, status: 200, text: async () => JSON.stringify(pages[page] ?? { total_count: 0, check_runs: [] }) };
+  };
+  return { fetch, urls, headers };
+}
+
+const apiRun = (id: number, extra: Record<string, unknown> = {}) => ({
+  id,
+  name: `job ${id}`,
+  status: "completed",
+  conclusion: "success",
+  started_at: "2026-10-06T10:00:00Z",
+  completed_at: "2026-10-06T10:05:00Z",
+  html_url: `https://github.com/acme/app/runs/${id}`,
+  ...extra,
+});
+
+describe("the GitHub check-run client (#3573)", () => {
+  test("reads every attempt across pages", async () => {
+    const first = Array.from({ length: 100 }, (_, i) => apiRun(i + 1));
+    const { fetch, urls, headers } = fakeFetch({
+      1: { total_count: 101, check_runs: first },
+      2: { total_count: 101, check_runs: [apiRun(101, { status: "in_progress", conclusion: null, completed_at: null })] },
+    });
+    const runs = await githubCiForge({ apiBase: "https://api.github.com/", repo: "acme/app", token: "t0k", fetch }).checkRuns(SHA);
+    expect(urls).toEqual([
+      `https://api.github.com/repos/acme/app/commits/${SHA}/check-runs?filter=all&per_page=100&page=1`,
+      `https://api.github.com/repos/acme/app/commits/${SHA}/check-runs?filter=all&per_page=100&page=2`,
+    ]);
+    expect(headers[0].Authorization).toBe("Bearer t0k");
+    expect(runs).toHaveLength(101);
+    expect(runs[0]).toEqual({ id: 1, name: "job 1", status: "completed", conclusion: "success", completedAt: "2026-10-06T10:05:00Z", url: "https://github.com/acme/app/runs/1" });
+    expect(runs[100]).toMatchObject({ id: 101, status: "in_progress", conclusion: null });
+  });
+
+  test("an error status is an error, not an empty list", async () => {
+    const { fetch } = fakeFetch(403);
+    await expect(githubCiForge({ apiBase: "https://api.github.com", repo: "acme/app", token: "t", fetch }).checkRuns(SHA)).rejects.toBeInstanceOf(ForgeApiError);
+  });
+
+  test("comes from the job's environment, and refuses the forges with no check-run client yet", () => {
+    const { fetch } = fakeFetch({});
+    expect(ciForgeFromEnv("github", { GITHUB_REPOSITORY: "acme/app", GITHUB_TOKEN: "t" }, fetch).kind).toBe("github");
+    expect(() => ciForgeFromEnv("github", { GITHUB_TOKEN: "t" })).toThrow(ForgeEnvironmentError);
+    expect(() => ciForgeFromEnv("gitlab", {})).toThrow(CiForgeUnsupportedError);
+    expect(() => ciForgeFromEnv("forgejo", {})).toThrow(/GitHub only/);
+  });
+});

package/src/workspace/ci-green-forge.ts

@@ -0,0 +1,111 @@
+/**
+ * What `chant ci tick` asks of a forge (#3573, ws-103): every check run on a
+ * commit, every attempt of each, so the tick can judge a phase by each run's
+ * latest attempt.
+ *
+ * The tags themselves are git's, pushed to the remote like any other ref, so
+ * the forge is asked for check runs and nothing else. GitHub is the one
+ * forge implemented. Forgejo reports commit statuses rather than check runs,
+ * and GitLab reports pipeline jobs; each can implement {@link CiForge} by
+ * mapping those to {@link CheckRun}s, and until one does `--forge` refuses
+ * them by name.
+ *
+ * The client takes a `fetch` like the pull-request loop's (`../pr-forge.ts`),
+ * so the tests drive it with a recording fake and no network.
+ */
+
+import { ForgeApiError, ForgeEnvironmentError, type ForgeFetch, type ForgeKind } from "../pr-forge";
+
+/** One attempt of one check run on a commit. */
+export interface CheckRun {
+  /** The forge's id. A later attempt of the same check has a larger one. */
+  id: number;
+  name: string;
+  /** `completed` once it has finished; `queued`, `in_progress`, `waiting`, `requested` or `pending` before. */
+  status: string;
+  /** Set once completed: `success`, `failure`, `skipped`, `cancelled`, `neutral`, `timed_out`, `action_required` or `stale`. */
+  conclusion: string | null;
+  completedAt: string | null;
+  url: string | null;
+}
+
+export interface CiForge {
+  kind: ForgeKind;
+  /** Every check run on `sha`, every attempt. */
+  checkRuns(sha: string): Promise<CheckRun[]>;
+}
+
+export interface GithubCiForgeOptions {
+  /** `$GITHUB_API_URL`: `https://api.github.com` or `<host>/api/v3`. */
+  apiBase: string;
+  /** `owner/name`. */
+  repo: string;
+  token: string;
+  fetch?: ForgeFetch;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+/** A GitHub client (github.com or GitHub Enterprise Server) for check runs. The token needs `checks: read`. */
+export function githubCiForge(opts: GithubCiForgeOptions): CiForge {
+  const root = opts.apiBase.replace(/\/+$/, "");
+  const fetchImpl = opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch);
+  const headers = { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" };
+  return {
+    kind: "github",
+    async checkRuns(sha) {
+      // filter=all: every attempt, not only the newest per suite, so a re-run's
+      // own run is judged against the run it replaced by id.
+      const out: CheckRun[] = [];
+      for (let page = 1; page <= 50; page++) {
+        const url = `${root}/repos/${opts.repo}/commits/${sha}/check-runs?filter=all&per_page=100&page=${page}`;
+        const res = await fetchImpl(url, { method: "GET", headers });
+        const text = await res.text();
+        if (!res.ok) throw new ForgeApiError("GET", url, res.status, text);
+        const body: unknown = text ? JSON.parse(text) : null;
+        const runs = isObject(body) && Array.isArray(body.check_runs) ? body.check_runs : [];
+        for (const r of runs) {
+          if (!isObject(r) || typeof r.id !== "number" || typeof r.name !== "string") continue;
+          out.push({
+            id: r.id,
+            name: r.name,
+            status: str(r.status) ?? "queued",
+            conclusion: str(r.conclusion),
+            completedAt: str(r.completed_at),
+            url: str(r.html_url),
+          });
+        }
+        const total = isObject(body) && typeof body.total_count === "number" ? body.total_count : 0;
+        if (runs.length < 100 || out.length >= total) break;
+      }
+      return out;
+    },
+  };
+}
+
+/** Thrown for a forge `chant ci tick` has no check-run client for yet. */
+export class CiForgeUnsupportedError extends Error {
+  constructor(kind: string) {
+    super(`check runs are read from GitHub only so far, and --forge asked for ${kind}; see #3573`);
+    this.name = "CiForgeUnsupportedError";
+  }
+}
+
+/**
+ * A check-run client for `kind` from the CI job's environment: the token is
+ * `CHANT_FORGE_TOKEN` when set, else `GITHUB_TOKEN` or `GH_TOKEN`, and the
+ * repository is `GITHUB_REPOSITORY`.
+ */
+export function ciForgeFromEnv(kind: string = "github", env: Record<string, string | undefined> = process.env, fetchImpl?: ForgeFetch): CiForge {
+  if (kind !== "github") throw new CiForgeUnsupportedError(kind);
+  const token = env.CHANT_FORGE_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN;
+  const missing = [...(env.GITHUB_REPOSITORY ? [] : ["GITHUB_REPOSITORY"]), ...(token ? [] : ["GITHUB_TOKEN or CHANT_FORGE_TOKEN"])];
+  if (missing.length > 0) throw new ForgeEnvironmentError("github", missing);
+  return githubCiForge({
+    apiBase: env.GITHUB_API_URL ?? "https://api.github.com",
+    repo: env.GITHUB_REPOSITORY!,
+    token: token!,
+    ...(fetchImpl ? { fetch: fetchImpl } : {}),
+  });
+}