@intentius/chant 0.107.1 → 0.108.1

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

@@ -0,0 +1,288 @@
+/**
+ * #3573 — the root CI file that runs `chant ci tick`: which workflows trigger
+ * it, what it says, and `chant ci workflow` writing and recording it under
+ * the generated-file rules (ws-042, #2524 D14).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import { GENERATED_MARKER } from "../discovery/files";
+import type { CommandContext } from "../cli/registry";
+import { parseYAMLDocument } from "../yaml";
+import { runCiWorkflow } from "./ci-green-cli";
+import { CI_GREEN_WORKFLOW_FILE, jobCheckRuns, renderCiGreenWorkflow, workflowsHolding } from "./ci-green-workflow";
+import { parseDeclaration } from "./declaration";
+import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+
+afterAll(cleanScratch);
+
+/** A parsed workflow, read by key path in the assertions. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Yaml = Record<string, any>;
+
+const GREEN = {
+  branch: "main",
+  phases: { lint: ["lint"], test: ["test", "e2e (*)"], macos: { runs: ["macos (test)"], skipped: "pass" }, docs: ["docs"] },
+  require: ["lint", "test", "macos"],
+};
+const green = parseDeclaration(JSON.stringify({ name: "w", schema: 1, members: [], ci: { green: GREEN } }), "chant.workspace.json").ci!.green!;
+
+const CI = `name: ci
+on: push
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+  test:
+    runs-on: ubuntu-latest
+  e2e:
+    strategy:
+      matrix:
+        browser: [chromium, webkit]
+`;
+const MACOS = `on: push
+jobs:
+  mac:
+    name: macos (\${{ matrix.target }})
+    strategy:
+      matrix:
+        target: [test, webkit]
+`;
+const DOCS = `name: docs
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+`;
+
+describe("the workflows that hold required check runs (#3573)", () => {
+  test("a job reports its name or id, with matrix values or a called workflow's job after it", () => {
+    expect(jobCheckRuns(parseYAMLDocument(CI))).toEqual(["lint", "test", "e2e", "e2e (*)"]);
+    expect(jobCheckRuns(parseYAMLDocument(MACOS))).toEqual(["macos (*)"]);
+    expect(jobCheckRuns({ jobs: { deploy: { uses: "./.github/workflows/deploy.yml" } } })).toEqual(["deploy", "deploy / *"]);
+  });
+
+  test("keeps the workflows whose jobs meet a required phase's pattern, by name or by path", () => {
+    const scan = workflowsHolding(green, [
+      { path: ".github/workflows/ci.yml", text: CI },
+      { path: ".github/workflows/macos.yml", text: MACOS },
+      { path: ".github/workflows/docs.yml", text: DOCS },
+      { path: ".github/workflows/broken.yml", text: "jobs: [" },
+    ]);
+    // docs is a declared phase but not a required one, so its workflow does not trigger a tick.
+    expect(scan).toEqual({ workflows: [".github/workflows/macos.yml", "ci"], unmatched: [], unreadable: [".github/workflows/broken.yml"] });
+    expect(workflowsHolding(green, [{ path: ".github/workflows/ci.yml", text: CI }]).unmatched).toEqual([{ phase: "macos", pattern: "macos (test)" }]);
+  });
+
+  test("runs the tick on completion of each, on a 15-minute cron, one at a time, with the rights it needs", () => {
+    const text = renderCiGreenWorkflow({ green, workflows: ["ci", "macos"], chantVersion: "0.108.0", workspaceRoot: "." });
+    const doc = parseYAMLDocument(text) as Yaml;
+    expect(doc.name).toBe("chant-ci-green");
+    expect(doc.on.workflow_run).toEqual({ workflows: ["ci", "macos"], types: ["completed"], branches: ["main"] });
+    expect(doc.on.schedule).toEqual([{ cron: "*/15 * * * *" }]);
+    expect(doc.concurrency).toEqual({ group: "chant-ci-green", "cancel-in-progress": false });
+    expect(doc.permissions).toEqual({ contents: "write", checks: "read" });
+    const steps = doc.jobs.tick.steps;
+    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0 } });
+    expect(steps[2].run).toBe("npx --yes @intentius/chant@0.108.0 ci tick");
+    expect(steps[2]["working-directory"]).toBeUndefined();
+    expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+    const nested = parseYAMLDocument(renderCiGreenWorkflow({ green, workflows: ["ci"], chantVersion: "0.108.0", workspaceRoot: "infra" })) as Yaml;
+    expect(nested.jobs.tick.steps[2]["working-directory"]).toBe("infra");
+  });
+
+  test("--chant replaces the npx pin, and --install adds a cached install step before the tick", () => {
+    const own = parseYAMLDocument(
+      renderCiGreenWorkflow({ green, workflows: ["ci"], chantVersion: "0.108.0", workspaceRoot: ".", chant: "npx tsx packages/core/src/cli/main.ts", install: "npm install --ignore-scripts", npmLock: "package-lock.json" }),
+    ) as Yaml;
+    const steps = own.jobs.tick.steps;
+    expect(steps[1].with).toEqual({ "node-version": "24", cache: "npm" });
+    expect(steps[2]).toEqual({ name: "Install what the tick runs", run: "npm install --ignore-scripts" });
+    expect(steps[3].run).toBe("npx tsx packages/core/src/cli/main.ts ci tick");
+
+    // In a nested workspace root both steps run there, and the cache keys on that root's lockfile.
+    const nested = parseYAMLDocument(
+      renderCiGreenWorkflow({ green, workflows: ["ci"], chantVersion: "0.108.0", workspaceRoot: "infra", chant: "npx chant", install: "npm ci", npmLock: "infra/package-lock.json" }),
+    ) as Yaml;
+    expect(nested.jobs.tick.steps[1].with).toEqual({ "node-version": "24", cache: "npm", "cache-dependency-path": "infra/package-lock.json" });
+    expect(nested.jobs.tick.steps[2]["working-directory"]).toBe("infra");
+    expect(nested.jobs.tick.steps[3]["working-directory"]).toBe("infra");
+
+    // A command YAML would misread as a mapping or a comment stays one string.
+    const odd = parseYAMLDocument(renderCiGreenWorkflow({ green, workflows: ["ci"], chantVersion: "0.108.0", workspaceRoot: ".", chant: "env A=b: c # x chant" })) as Yaml;
+    expect(odd.jobs.tick.steps).toHaveLength(3);
+    expect(odd.jobs.tick.steps[1].with).toEqual({ "node-version": "24" });
+    expect(odd.jobs.tick.steps[2].run).toBe("env A=b: c # x chant ci tick");
+  });
+});
+
+describe("the token the tick pushes its tags with (#3573)", () => {
+  const base = { green, workflows: ["ci"], chantVersion: "0.108.0", workspaceRoot: "." };
+
+  test("without one, checkout persists the Actions token and the tick reads check runs with it", () => {
+    const steps = (parseYAMLDocument(renderCiGreenWorkflow(base)) as Yaml).jobs.tick.steps;
+    expect(steps[0].with.token).toBeUndefined();
+    expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+  });
+
+  test("--token-secret checks out with the secret, so the push uses it, and nothing else changes", () => {
+    const plain = renderCiGreenWorkflow(base);
+    const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
+    const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
+    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN }}" } });
+    // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
+    expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+    expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
+    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN }}\n", "")).toBe(plain);
+  });
+
+  test("--app-id-var and --app-key-secret mint an App token before the checkout and check out with it", () => {
+    const steps = (parseYAMLDocument(renderCiGreenWorkflow({ ...base, push: { appIdVar: "CI_GREEN_APP_ID", appKeySecret: "CI_GREEN_APP_KEY" } })) as Yaml).jobs.tick.steps;
+    expect(steps[0]).toMatchObject({
+      id: "app-token",
+      uses: "actions/create-github-app-token@v2",
+      with: { "app-id": "${{ vars.CI_GREEN_APP_ID }}", "private-key": "${{ secrets.CI_GREEN_APP_KEY }}" },
+    });
+    expect(steps[1].with.token).toBe("${{ steps.app-token.outputs.token }}");
+    expect(steps[3].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+  });
+});
+
+describe("chant ci workflow (#3573)", () => {
+  test("writes the file with its header, records it on the member it ran in, and writes the same bytes twice", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, {
+      "chant.workspace.json": declaration([{ name: "root", dir: ".", kind: "other", because: "the repository" }], { ci: { green: GREEN } }),
+      ".github/workflows/ci.yml": CI,
+      ".github/workflows/macos.yml": MACOS,
+    });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const ctx = { args: { ciWorkflows: ["release"] } } as unknown as CommandContext;
+      expect(await runCiWorkflow(ctx)).toBe(0);
+      const file = join(root, CI_GREEN_WORKFLOW_FILE);
+      const first = readFileSync(file, "utf-8");
+      expect(first.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --workflow release (in the member's directory)`);
+      expect((parseYAMLDocument(first) as Yaml).on.workflow_run.workflows).toEqual([".github/workflows/macos.yml", "ci", "release"]);
+      const record = JSON.parse(readFileSync(join(root, ".chant", "generated.json"), "utf-8"));
+      expect(record.files).toEqual([{ path: CI_GREEN_WORKFLOW_FILE, command: "chant ci workflow --workflow release" }]);
+      // The scan skips the file it writes, so regenerating is byte-identical.
+      expect(await runCiWorkflow(ctx)).toBe(0);
+      expect(readFileSync(file, "utf-8")).toBe(first);
+    } finally {
+      cwd.mockRestore();
+      log.mockRestore();
+      error.mockRestore();
+    }
+  });
+
+  test("--chant and --install go into the file and its header, and regenerate byte-identically", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, {
+      "chant.workspace.json": declaration([], { ci: { green: GREEN } }),
+      "package-lock.json": "{}",
+      ".github/workflows/ci.yml": CI,
+      ".github/workflows/macos.yml": MACOS,
+    });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const ctx = { args: { ciChant: "npx tsx packages/core/src/cli/main.ts", ciInstall: "npm install --ignore-scripts" } } as unknown as CommandContext;
+      expect(await runCiWorkflow(ctx)).toBe(0);
+      const file = join(root, CI_GREEN_WORKFLOW_FILE);
+      const first = readFileSync(file, "utf-8");
+      expect(first.split("\n")[0]).toBe(
+        `# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --chant 'npx tsx packages/core/src/cli/main.ts' --install 'npm install --ignore-scripts' (in the workspace root)`,
+      );
+      const steps = (parseYAMLDocument(first) as Yaml).jobs.tick.steps;
+      expect(steps[1].with.cache).toBe("npm");
+      expect(steps[2].run).toBe("npm install --ignore-scripts");
+      expect(steps[3].run).toBe("npx tsx packages/core/src/cli/main.ts ci tick");
+      expect(await runCiWorkflow(ctx)).toBe(0);
+      expect(readFileSync(file, "utf-8")).toBe(first);
+    } finally {
+      cwd.mockRestore();
+      log.mockRestore();
+      error.mockRestore();
+    }
+  });
+
+  test("--token-secret goes into the file and its header, and without it the bytes are what they were", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, { "chant.workspace.json": declaration([], { ci: { green: GREEN } }), ".github/workflows/ci.yml": CI, ".github/workflows/macos.yml": MACOS });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const file = join(root, CI_GREEN_WORKFLOW_FILE);
+      expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(0);
+      const plain = readFileSync(file, "utf-8");
+      expect(plain).not.toMatch(/token:|secrets\./);
+
+      expect(await runCiWorkflow({ args: { ciTokenSecret: "CI_GREEN_TOKEN" } } as unknown as CommandContext)).toBe(0);
+      const withToken = readFileSync(file, "utf-8");
+      expect(withToken.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --token-secret CI_GREEN_TOKEN (in the workspace root)`);
+      const steps = (parseYAMLDocument(withToken) as Yaml).jobs.tick.steps;
+      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN }}");
+      expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+
+      const app = { args: { ciAppIdVar: "CI_GREEN_APP_ID", ciAppKeySecret: "CI_GREEN_APP_KEY" } } as unknown as CommandContext;
+      expect(await runCiWorkflow(app)).toBe(0);
+      expect(readFileSync(file, "utf-8").split("\n")[0]).toBe(
+        `# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --app-id-var CI_GREEN_APP_ID --app-key-secret CI_GREEN_APP_KEY (in the workspace root)`,
+      );
+
+      // Dropping the flag writes the bytes chant 0.108.0 wrote.
+      expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(0);
+      expect(readFileSync(file, "utf-8")).toBe(plain);
+    } finally {
+      cwd.mockRestore();
+      log.mockRestore();
+      error.mockRestore();
+    }
+  });
+
+  test("refuses a half-given App, both kinds of token at once, and a name GitHub wouldn't accept", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, { "chant.workspace.json": declaration([], { ci: { green: GREEN } }), ".github/workflows/ci.yml": CI });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const errors: string[] = [];
+    const error = vi.spyOn(console, "error").mockImplementation((s: unknown) => void errors.push(String(s)));
+    try {
+      const run = (args: Record<string, string>) => runCiWorkflow({ args } as unknown as CommandContext);
+      expect(await run({ ciAppIdVar: "APP_ID" })).toBe(1);
+      expect(errors.pop()).toMatch(/both the App's id and its key/);
+      expect(await run({ ciTokenSecret: "T", ciAppIdVar: "APP_ID", ciAppKeySecret: "APP_KEY" })).toBe(1);
+      expect(errors.pop()).toMatch(/one or the other/);
+      expect(await run({ ciTokenSecret: "ci-green token" })).toBe(1);
+      expect(errors.pop()).toMatch(/--token-secret takes a secret or variable name/);
+      expect(existsSync(join(root, CI_GREEN_WORKFLOW_FILE))).toBe(false);
+    } finally {
+      cwd.mockRestore();
+      error.mockRestore();
+    }
+  });
+
+  test("refuses to write a workflow nothing but the schedule would trigger", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "root", dir: ".", kind: "other", because: "x" }], { ci: { green: GREEN } }) });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const errors: string[] = [];
+    const error = vi.spyOn(console, "error").mockImplementation((s: unknown) => void errors.push(String(s)));
+    try {
+      expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(1);
+      expect(errors.join("\n")).toMatch(/--workflow <name>/);
+      expect(existsSync(join(root, CI_GREEN_WORKFLOW_FILE))).toBe(false);
+    } finally {
+      cwd.mockRestore();
+      error.mockRestore();
+    }
+  });
+});

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

@@ -0,0 +1,252 @@
+/**
+ * The root CI file that runs `chant ci tick` (#3573, ws-103; ws-042 for its
+ * place at the repository root, #2524 D14 for its header and record).
+ *
+ * `chant ci workflow` writes `.github/workflows/chant-ci-green.yml`. It runs
+ * the tick when a workflow that holds a required check run completes on the
+ * branch, so a result or a re-run is acted on within seconds, and every 15
+ * minutes as a backstop for a dropped or late event. One concurrency group
+ * that never cancels keeps ticks one at a time.
+ *
+ * GitHub's `workflow_run` names workflows, and `ci.green` names check runs,
+ * so the generator reads the repository's other workflow files and keeps
+ * each workflow with a job whose check-run name meets one of a required
+ * phase's patterns. A job's check run is its `name`, or its id, with
+ * ` (<matrix values>)` after it for a matrix job and ` / <job>` after it for
+ * a job that calls a reusable workflow; a `${{ }}` expression stands for
+ * anything. `--workflow <name>` adds a workflow the scan can't see.
+ *
+ * The tick runs the published chant that wrote the file, through npx.
+ * `--chant <command>` runs another one instead, and `--install <command>`
+ * adds a step that installs it, with setup-node caching npm's downloads when
+ * the workspace root has a `package-lock.json`. chant's own repository uses
+ * both to run its source at the commit it checks out.
+ *
+ * The tick pushes its tags with the credentials actions/checkout leaves in
+ * the clone, the Actions token by default. GitHub treats a new ref to a
+ * commit whose workflow files differ from the default branch's as an update
+ * to those workflows, and the Actions token can never hold the `workflows`
+ * permission, so it is refused there. `--token-secret <NAME>` checks out
+ * with `secrets.<NAME>` instead, and `--app-id-var <VAR> --app-key-secret
+ * <NAME>` mints a GitHub App token first and checks out with that. The
+ * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
+ * a fine-grained personal access token can't call the Checks API.
+ *
+ * Like a member's pipelines (./member-pipeline.ts), the file starts with the
+ * generated-file header naming the command, and the member whose directory
+ * the command runs in records it in its generated-file record, so `WSP081`
+ * allows one declarer.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { GENERATED_MARKER } from "../discovery/files";
+import { parseYAMLDocument } from "../yaml";
+import type { CiGreen } from "./declaration";
+import { matchesCheckRun } from "./ci-green";
+
+/** Where the workflow goes, relative to the repository root. */
+export const CI_GREEN_WORKFLOW_FILE = ".github/workflows/chant-ci-green.yml";
+export const CI_GREEN_WORKFLOW_NAME = "chant-ci-green";
+
+/** One workflow file as the scan reads it. */
+export interface WorkflowSource {
+  /** Relative to the repository root, such as `.github/workflows/ci.yml`. */
+  path: string;
+  text: string;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const EXPRESSION = /\$\{\{[^}]*\}\}/g;
+
+/** The check-run names a workflow's jobs report, as patterns: `*` stands for what an expression or a matrix fills in. */
+export function jobCheckRuns(doc: unknown): string[] {
+  if (!isObject(doc) || !isObject(doc.jobs)) return [];
+  const out: string[] = [];
+  for (const [id, job] of Object.entries(doc.jobs)) {
+    if (!isObject(job)) continue;
+    const named = typeof job.name === "string" ? job.name : id;
+    const base = named.replace(EXPRESSION, "*");
+    out.push(base);
+    if (isObject(job.strategy) && job.strategy.matrix !== undefined && base === named) out.push(`${base} (*)`);
+    if (typeof job.uses === "string") out.push(`${base} / *`);
+  }
+  return out;
+}
+
+/** Whether two patterns can name the same check run: either matches the other with its `*` filled in. */
+function meet(a: string, b: string): boolean {
+  return matchesCheckRun(a, b.replace(/\*/g, "x")) || matchesCheckRun(b, a.replace(/\*/g, "x"));
+}
+
+/** The name `workflow_run` knows a workflow by: its `name`, or its path when it has none or the name is an expression. */
+function workflowName(doc: unknown, path: string): string {
+  return isObject(doc) && typeof doc.name === "string" && !doc.name.includes("${{") ? doc.name : path;
+}
+
+export interface WorkflowScan {
+  /** The workflows holding a required check run, sorted. */
+  workflows: string[];
+  /** Required patterns no job of any workflow meets. */
+  unmatched: { phase: string; pattern: string }[];
+  /** Workflow files that could not be parsed. */
+  unreadable: string[];
+}
+
+/** Find the workflows that hold the required phases' check runs. */
+export function workflowsHolding(green: CiGreen, sources: readonly WorkflowSource[]): WorkflowScan {
+  const patterns = green.require.flatMap((name) => green.phases.find((p) => p.name === name)!.runs.map((pattern) => ({ phase: name, pattern })));
+  const workflows = new Set<string>();
+  const met = new Set<string>();
+  const unreadable: string[] = [];
+  for (const s of sources) {
+    let doc: unknown;
+    try {
+      doc = parseYAMLDocument(s.text);
+    } catch {
+      unreadable.push(s.path);
+      continue;
+    }
+    const runs = jobCheckRuns(doc);
+    for (const p of patterns) {
+      if (!runs.some((r) => meet(p.pattern, r))) continue;
+      workflows.add(workflowName(doc, s.path));
+      met.add(`${p.phase}\0${p.pattern}`);
+    }
+  }
+  return {
+    workflows: [...workflows].sort(),
+    unmatched: patterns.filter((p) => !met.has(`${p.phase}\0${p.pattern}`)),
+    unreadable,
+  };
+}
+
+/** The repository's GitHub workflow files, other than `skip`. */
+export function readWorkflowSources(repoRoot: string, skip: string): WorkflowSource[] {
+  const dir = join(repoRoot, ".github", "workflows");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /\.ya?ml$/.test(f))
+    .sort()
+    .map((f) => `.github/workflows/${f}`)
+    .filter((p) => p !== skip)
+    .map((path) => ({ path, text: readFileSync(join(repoRoot, path), "utf-8") }));
+}
+
+const q = (s: string) => JSON.stringify(s);
+
+export interface WorkflowInput {
+  green: CiGreen;
+  /** The workflows whose completion triggers a tick. */
+  workflows: readonly string[];
+  /** The chant the tick runs, `@intentius/chant` at this version. */
+  chantVersion: string;
+  /**
+   * The command that runs chant, with `ci tick` after it, in place of
+   * `npx --yes @intentius/chant@<chantVersion>`. chant's own repository runs
+   * its source this way, so the tick tests the commit it checks out.
+   */
+  chant?: string;
+  /** A step before the tick that installs what `chant` needs, run where the tick runs. */
+  install?: string;
+  /** With `install`, the `package-lock.json` setup-node caches npm's downloads by, from the repository root. */
+  npmLock?: string;
+  /** The workspace root relative to the repository root, `.` for the root itself. */
+  workspaceRoot: string;
+  /** How the tag push authenticates, when not with the Actions token. */
+  push?: PushToken;
+}
+
+/**
+ * A token the checkout persists for the tick's `git push`: a repository
+ * secret, or a GitHub App's installation token minted from its id (an
+ * Actions variable) and private key (a secret).
+ */
+export type PushToken = { secret: string } | { appIdVar: string; appKeySecret: string };
+
+/** A secret or variable name GitHub accepts: letters, digits and underscores, not starting with a digit. */
+export const ACTIONS_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The workflow's YAML, without the generated-file header. Deterministic: the same input writes the same bytes. */
+export function renderCiGreenWorkflow(input: WorkflowInput): string {
+  const { green } = input;
+  const where = input.workspaceRoot === "." ? [] : [`        working-directory: ${q(input.workspaceRoot)}`];
+  const cache = input.install && input.npmLock ? ["          cache: npm", ...(input.npmLock === "package-lock.json" ? [] : [`          cache-dependency-path: ${q(input.npmLock)}`])] : [];
+  const tick = input.chant ? q(`${input.chant} ci tick`) : `npx --yes @intentius/chant@${input.chantVersion} ci tick`;
+  const push = input.push;
+  const mint =
+    push && "appIdVar" in push
+      ? [
+          "      - name: Mint a GitHub App token that may push tags to commits that change workflows",
+          "        id: app-token",
+          "        uses: actions/create-github-app-token@v2",
+          "        with:",
+          `          app-id: \${{ vars.${push.appIdVar} }}`,
+          `          private-key: \${{ secrets.${push.appKeySecret} }}`,
+        ]
+      : [];
+  const token = !push ? [] : ["secret" in push ? `          token: \${{ secrets.${push.secret} }}` : "          token: ${{ steps.app-token.outputs.token }}"];
+  const lines = [
+    `name: ${CI_GREEN_WORKFLOW_NAME}`,
+    "",
+    "# Tags each commit on the branch that passed its required phases ci/green/<sha>,",
+    "# and a green commit that later fails one ci/revoked/<sha> (#3573).",
+    "on:",
+    "  workflow_run:",
+    "    workflows:",
+    ...input.workflows.map((w) => `      - ${q(w)}`),
+    "    types:",
+    "      - completed",
+    "    branches:",
+    `      - ${q(green.branch)}`,
+    "  schedule:",
+    "    - cron: \"*/15 * * * *\"",
+    "  workflow_dispatch: {}",
+    "",
+    "# One tick at a time, and a tick in progress is never cancelled.",
+    "concurrency:",
+    `  group: ${CI_GREEN_WORKFLOW_NAME}`,
+    "  cancel-in-progress: false",
+    "",
+    "permissions:",
+    "  contents: write",
+    "  checks: read",
+    "",
+    "jobs:",
+    "  tick:",
+    "    runs-on: ubuntu-latest",
+    "    timeout-minutes: 15",
+    "    steps:",
+    ...mint,
+    "      - uses: actions/checkout@v6",
+    "        with:",
+    `          ref: ${q(green.branch)}`,
+    "          fetch-depth: 0",
+    ...token,
+    "      - uses: actions/setup-node@v6",
+    "        with:",
+    "          node-version: \"24\"",
+    ...cache,
+    ...(input.install ? ["      - name: Install what the tick runs", ...where, `        run: ${q(input.install)}`] : []),
+    "      - name: Tag the commits that turned green, revoke the ones that turned red",
+    ...where,
+    "        env:",
+    "          GITHUB_TOKEN: ${{ github.token }}",
+    "          GIT_COMMITTER_NAME: github-actions[bot]",
+    "          GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com",
+    `        run: ${tick}`,
+  ];
+  return lines.join("\n") + "\n";
+}
+
+/** The header line naming the command that regenerates the file, and where to run it. */
+export function ciGreenHeader(command: string, where: "member" | "root"): string {
+  return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the ${where === "member" ? "member's directory" : "workspace root"})\n`;
+}
+
+/** Write the file, creating its directory. Returns the path relative to the current directory. */
+export function writeWorkflowFile(target: string, text: string): string {
+  mkdirSync(dirname(resolve(target)), { recursive: true });
+  writeFileSync(target, text);
+  return relative(process.cwd(), target).split(sep).join("/") || target;
+}