@intentius/chant 0.124.28 → 0.124.29

package/src/pr-report-url.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `--report-url` (#4007): the URL forms, the key, and the upload of a run's
+ * events as it goes: one upload in flight at a time, a failure that warns
+ * and never stops the run, and a last upload that carries everything. The
+ * s3 scheme runs a fake AWS CLI; nothing here reaches a network.
+ */
+
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { openPrReportUpload, parseReportUrl, reportKey, reportPut, type ReportPut } from "./pr-report-url";
+
+const line = (type: string, extra: Record<string, unknown> = {}): string => JSON.stringify({ type, ...extra }) + "\n";
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-report-url-"));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe("parseReportUrl", () => {
+  test("reads s3 and file URLs and refuses anything else", () => {
+    expect(parseReportUrl("s3://bucket/a/b/")).toEqual({ scheme: "s3", url: "s3://bucket/a/b", bucket: "bucket", prefix: "a/b" });
+    expect(parseReportUrl("s3://bucket")).toEqual({ scheme: "s3", url: "s3://bucket", bucket: "bucket", prefix: "" });
+    expect(parseReportUrl(pathToFileURL(dir).href)).toMatchObject({ scheme: "file", dir });
+    expect(parseReportUrl("https://example.invalid/x")).toHaveProperty("error");
+  });
+
+  test("keys by pull request and commit, and by member after them", () => {
+    expect(reportKey(12, "abc")).toBe("12/abc");
+    expect(reportKey(null, "abc")).toBe("unknown/abc");
+    expect(reportKey(12, "abc", "api")).toBe("12/abc/api");
+  });
+});
+
+describe("openPrReportUpload", () => {
+  /** A put whose uploads finish only when the test says, recording what each carried. */
+  function heldPut() {
+    const calls: Array<{ key: string; body: string; finish: (err?: Error) => void }> = [];
+    let inFlight = 0;
+    let most = 0;
+    const put: ReportPut = (key, body) =>
+      new Promise<void>((resolve, reject) => {
+        inFlight++;
+        most = Math.max(most, inFlight);
+        calls.push({ key, body, finish: (err) => { inFlight--; if (err) reject(err); else resolve(); } });
+      });
+    return { put, calls, most: () => most };
+  }
+
+  test("uploads the events on each settle, never two at once, and the settles that came meanwhile in one more", async () => {
+    const held = heldPut();
+    const upload = openPrReportUpload({ target: { scheme: "s3", url: "s3://b", bucket: "b", prefix: "" }, key: "12/abc", stage: "apply", warn: () => {}, put: held.put });
+    upload.line(line("run-start"));
+    expect(held.calls).toHaveLength(0);
+    upload.line(line("wave-start", { wave: 1 }));
+    upload.line(line("component-settle", { wave: 1 }));
+    expect(held.calls).toHaveLength(1);
+    upload.line(line("wave-settle", { wave: 1 }));
+    upload.line(line("wave-start", { wave: 2 }));
+    upload.line(line("component-settle", { wave: 2 }));
+    // Both settles wait behind the one in flight, and go up as one.
+    expect(held.calls).toHaveLength(1);
+    held.calls[0]!.finish();
+    await new Promise((r) => setImmediate(r));
+    expect(held.calls).toHaveLength(2);
+    expect(held.calls[1]!.body.split("\n").filter(Boolean)).toHaveLength(6);
+    expect(held.calls[1]!.key).toBe("12/abc/pr-apply.events.jsonl");
+
+    upload.file("pr-apply.json", "{}\n");
+    const closing = upload.close();
+    await new Promise((r) => setImmediate(r));
+    // The last upload waits for the one in flight.
+    expect(held.calls).toHaveLength(2);
+    held.calls[1]!.finish();
+    await new Promise((r) => setImmediate(r));
+    held.calls[2]!.finish();
+    await new Promise((r) => setImmediate(r));
+    held.calls[3]!.finish();
+    await closing;
+    expect(held.calls.map((c) => c.key)).toEqual(["12/abc/pr-apply.events.jsonl", "12/abc/pr-apply.events.jsonl", "12/abc/pr-apply.events.jsonl", "12/abc/pr-apply.json"]);
+    expect(held.most()).toBe(1);
+  });
+
+  test("a failed upload as the run goes warns once and the run goes on; the last one is tried again", async () => {
+    const warnings: string[] = [];
+    let fail = true;
+    const put: ReportPut = async (key) => {
+      if (fail) throw new Error(`no bucket for ${key}`);
+    };
+    const upload = openPrReportUpload({ target: { scheme: "s3", url: "s3://b", bucket: "b", prefix: "" }, key: "12/abc", stage: "apply", warn: (m) => warnings.push(m), put });
+    upload.line(line("component-settle"));
+    await new Promise((r) => setImmediate(r));
+    upload.line(line("wave-settle"));
+    await new Promise((r) => setImmediate(r));
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toMatch(/as the run went: no bucket .*The run goes on/);
+    fail = false;
+    await upload.close();
+    expect(warnings).toHaveLength(1);
+  });
+
+  test("file://: each settle replaces the events file whole, so it holds a wave's settle before the next wave starts", async () => {
+    const target = parseReportUrl(pathToFileURL(dir).href);
+    if ("error" in target) throw new Error(target.error);
+    const upload = openPrReportUpload({ target, key: "12/abc", stage: "apply", warn: () => {} });
+    upload.line(line("run-start"));
+    upload.line(line("wave-settle", { wave: 1 }));
+    await new Promise((r) => setImmediate(r));
+    const events = join(dir, "12", "abc", "pr-apply.events.jsonl");
+    expect(await readFile(events, "utf8")).toBe(line("run-start") + line("wave-settle", { wave: 1 }));
+    upload.line(line("run-settle"));
+    upload.file("change-set.json", "{}\n");
+    await upload.close();
+    expect((await readFile(events, "utf8")).split("\n").filter(Boolean)).toHaveLength(3);
+    expect(await readFile(join(dir, "12", "abc", "change-set.json"), "utf8")).toBe("{}\n");
+  });
+
+  test("s3://: the AWS CLI copies each object from its stdin, with the content type, and chant hands it no credential", async () => {
+    const runs: Array<{ args: string[]; stdin: string }> = [];
+    const put = reportPut({ scheme: "s3", url: "s3://b/p", bucket: "b", prefix: "p" }, async (args, stdin) => {
+      runs.push({ args, stdin });
+    });
+    await put("12/abc/pr-plan.json", "{}\n", "application/json");
+    expect(runs).toEqual([{ args: ["s3", "cp", "-", "s3://b/p/12/abc/pr-plan.json", "--content-type", "application/json", "--only-show-errors"], stdin: "{}\n" }]);
+  });
+});

package/src/pr-report-url.ts

@@ -0,0 +1,209 @@
+/**
+ * `pr-plan --report-url` and `pr-apply --report-url` (#4007): copy a stage's
+ * report, its change set and its run events where a reader outside CI can
+ * fetch them, keyed by pull request and commit.
+ *
+ * ```
+ * <url>/<pr>/<commit>/pr-<stage>.json
+ * <url>/<pr>/<commit>/change-set.json
+ * <url>/<pr>/<commit>/pr-<stage>.events.jsonl   (with --events-json)
+ * ```
+ *
+ * `<pr>` is the pull or merge request number, or `unknown` when pr-apply
+ * found none, and `<commit>` is the full sha the stage ran on: the pull
+ * request's head for pr-plan, the pushed commit for pr-apply. A workspace
+ * member's loop (`--member`) adds `/<member>` after the commit. There is no
+ * index: a reader that knows the pull request and the commit knows the key.
+ * The events file is named for its stage because pr-plan and pr-apply run on
+ * the same commit when a pull request merges by fast-forward.
+ *
+ * The events file is uploaded again, whole, each time a wave, a component or
+ * the run settles, so a reader polling the URL sees each wave as it applies.
+ * One upload of it is in flight at a time: a settle while one is in flight
+ * asks for one more after it, with everything written by then. A failed
+ * upload is a warning and the run goes on. The last upload, after the run
+ * settles, carries the whole stream, and the report and the change set go
+ * with it.
+ *
+ * Two schemes. `file://<dir>` writes under a directory, each file through a
+ * temporary name and a rename, so a reader never sees half a file. `s3://
+ * <bucket>/<prefix>` runs the AWS CLI (`aws s3 cp - <s3 url>`, the body on
+ * its stdin), which reads its credentials, region and endpoint from the
+ * environment the job gives it, the way the aws lexicon's `s3-sync` does.
+ * chant passes it no credential and prints none: a failed upload prints the
+ * CLI's own error line.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Where `--report-url` points. */
+export type ReportTarget =
+  | { scheme: "file"; url: string; dir: string }
+  | { scheme: "s3"; url: string; bucket: string; prefix: string };
+
+/** `--report-url` read, or why it can't be. */
+export function parseReportUrl(raw: string): ReportTarget | { error: string } {
+  const url = raw.trim();
+  if (url.startsWith("file://")) {
+    let dir: string;
+    try {
+      dir = fileURLToPath(url);
+    } catch (err) {
+      return { error: `--report-url ${url}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!isAbsolute(dir)) return { error: `--report-url ${url}: a file URL names an absolute directory` };
+    return { scheme: "file", url: url.replace(/\/+$/, ""), dir };
+  }
+  const s3 = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
+  if (s3) {
+    const prefix = s3[2]!.replace(/\/+$/, "");
+    return { scheme: "s3", url: `s3://${s3[1]}${prefix ? `/${prefix}` : ""}`, bucket: s3[1]!, prefix };
+  }
+  return { error: `--report-url ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
+}
+
+/** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */
+export function reportKey(pr: number | null, commit: string, member?: string): string {
+  return [pr === null ? "unknown" : String(pr), commit, ...(member ? [member] : [])].join("/");
+}
+
+/** The events file of a stage. */
+export const reportEventsFile = (stage: "plan" | "apply"): string => `pr-${stage}.events.jsonl`;
+
+/** Puts one object: `key` below the URL. Rejects with a line a person can read. */
+export type ReportPut = (key: string, body: string, contentType: string) => Promise<void>;
+
+/** Runs the AWS CLI with `args` and `stdin`, rejecting with its error line on a non-zero exit. */
+export type AwsCli = (args: string[], stdin: string) => Promise<void>;
+
+const AWS_BINARY = "aws";
+
+/** The AWS CLI on PATH. */
+export const realAwsCli: AwsCli = (args, stdin) =>
+  new Promise((resolvePut, reject) => {
+    const child = spawn(AWS_BINARY, args, { stdio: ["pipe", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderr.length < 4096) stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      reject(new Error(err.code === "ENOENT" ? "the AWS CLI (aws) is not on PATH; an s3 report URL is uploaded with it" : err.message)),
+    );
+    child.on("close", (code) => {
+      if (code === 0) return resolvePut();
+      const line = stderr.trim().split("\n").filter(Boolean).at(-1) ?? "";
+      reject(new Error(`aws s3 cp exited ${code}${line ? `: ${line.slice(0, 300)}` : ""}`));
+    });
+    child.stdin.on("error", () => {
+      // The CLI exited before reading its input; its exit says why.
+    });
+    child.stdin.end(stdin);
+  });
+
+/** A put for `target`. `aws` replaces the AWS CLI in a test. */
+export function reportPut(target: ReportTarget, aws: AwsCli = realAwsCli): ReportPut {
+  if (target.scheme === "file") {
+    return async (key, body) => {
+      const path = join(target.dir, ...key.split("/"));
+      mkdirSync(dirname(path), { recursive: true });
+      const temp = `${path}.${process.pid}.tmp`;
+      writeFileSync(temp, body);
+      renameSync(temp, path);
+    };
+  }
+  return (key, body, contentType) => {
+    const object = `s3://${target.bucket}/${target.prefix ? `${target.prefix}/` : ""}${key}`;
+    return aws(["s3", "cp", "-", object, "--content-type", contentType, "--only-show-errors"], body);
+  };
+}
+
+/** A stage's upload: its events as they are written, and its files at the end. */
+export interface PrReportUpload {
+  /** The folder the stage's files go to: `<url>/<key>`. */
+  readonly where: string;
+  /** One line of the stage's run-event stream. A wave, component or run settle uploads the events. */
+  line(line: string): void;
+  /** A file to upload when the stage closes, replacing one of the same name. */
+  file(name: string, body: string): void;
+  /** Wait for the upload in flight, then upload the whole stream and the files. Never throws. */
+  close(): Promise<void>;
+}
+
+const UPLOAD_ON = new Set(["wave-settle", "component-settle", "run-settle"]);
+const NDJSON = "application/x-ndjson";
+const JSON_TYPE = "application/json";
+
+const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** Open a stage's upload to `target` under `key`. `warn` prints a warning line. */
+export function openPrReportUpload(input: {
+  target: ReportTarget;
+  key: string;
+  stage: "plan" | "apply";
+  warn: (message: string) => void;
+  put?: ReportPut;
+}): PrReportUpload {
+  const put = input.put ?? reportPut(input.target);
+  const where = `${input.target.url}/${input.key}`;
+  const eventsKey = `${input.key}/${reportEventsFile(input.stage)}`;
+  const files = new Map<string, string>();
+  let events = "";
+  let inFlight: Promise<void> | undefined;
+  let again = false;
+  let warned = false;
+
+  const pushEvents = (): void => {
+    if (inFlight) {
+      again = true;
+      return;
+    }
+    inFlight = put(eventsKey, events, NDJSON)
+      .catch((err) => {
+        if (warned) return;
+        warned = true;
+        input.warn(`could not upload the run's events to ${where} as the run went: ${messageOf(err)}. The run goes on, and its end tries again.`);
+      })
+      .finally(() => {
+        inFlight = undefined;
+        if (again) {
+          again = false;
+          pushEvents();
+        }
+      });
+  };
+
+  return {
+    where,
+    line(line) {
+      events += line;
+      let type: unknown;
+      try {
+        type = (JSON.parse(line) as { type?: unknown }).type;
+      } catch {
+        return;
+      }
+      if (typeof type === "string" && UPLOAD_ON.has(type)) pushEvents();
+    },
+    file(name, body) {
+      files.set(name, body);
+    },
+    async close() {
+      again = false;
+      while (inFlight) await inFlight;
+      const uploads: Array<[string, string, string]> = [
+        ...(events ? [[eventsKey, events, NDJSON] as [string, string, string]] : []),
+        ...[...files].map(([name, body]): [string, string, string] => [`${input.key}/${name}`, body, JSON_TYPE]),
+      ];
+      for (const [key, body, type] of uploads) {
+        try {
+          await put(key, body, type);
+        } catch (err) {
+          input.warn(`could not upload ${key.slice(input.key.length + 1)} to ${where}: ${messageOf(err)}`);
+        }
+      }
+    },
+  };
+}

package/src/provenance.ts

@@ -297,6 +297,6 @@ export interface BuildParamProvenance {
   name: string;
   /** The resolved, type-coerced value actually bound to `params.<name>` for this build. */
   value: string | number | boolean;
-  /** Which input supplied the value. */
-  source: "cli" | "params-file" | "env" | "default";
+  /** Which input supplied the value: `flag:<name>` names the workspace flag record it came from (#4024). */
+  source: "cli" | "params-file" | "env" | "default" | `flag:${string}`;
 }

package/src/run-event-store.ts

@@ -8,13 +8,14 @@
  * as `--events-json` prints them. It sits beside the in-flight records
  * (`./op/run-live.ts`), outside the working tree and off `chant/lifecycle`:
  * the run ledger's growth is #4036's concern and these files add none to it.
- * Unlike the in-flight record they are kept after the run settles. They are
- * never pruned here; retention is #4036's.
+ * Unlike the in-flight record they are kept after the run settles, until
+ * `chant lifecycle gc --yes` deletes the ones its retention policy lets go
+ * (#4036, {@link planRunEventPrune}).
  *
  * Every write is best-effort. A run whose events cannot be kept still runs.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gitCommonDir } from "./op/run-live";
 import type { RunEvent } from "./run-event";
@@ -211,3 +212,62 @@ export async function readRunEvents(
     }
   }
 }
+
+/** One run's event file, as retention sees it (#4036). */
+export interface RunEventFile {
+  file: string;
+  bytes: number;
+  /** The file's last write, ISO-8601. */
+  modified: string;
+}
+
+/** What {@link planRunEventPrune} would delete and keep. */
+export interface RunEventPrune {
+  /** The directory read, or null outside a checkout. */
+  dir: string | null;
+  remove: RunEventFile[];
+  keep: RunEventFile[];
+}
+
+/**
+ * Which run event files the policy lets go (#4036): every file older than
+ * `days` by its last write, apart from the newest `keep`. A run still going
+ * writes its file as it goes, so it is never older than the window. Reads
+ * only; {@link pruneRunEvents} deletes.
+ */
+export async function planRunEventPrune(cwd: string, policy: { days: number; keep: number }, now: Date): Promise<RunEventPrune> {
+  const dir = await runEventsDir(cwd);
+  if (!dir || !existsSync(dir)) return { dir, remove: [], keep: [] };
+  const files: Array<RunEventFile & { ms: number }> = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const file = join(dir, entry);
+    try {
+      const st = statSync(file);
+      if (!st.isFile()) continue;
+      files.push({ file, bytes: st.size, modified: new Date(st.mtimeMs).toISOString(), ms: st.mtimeMs });
+    } catch {
+      // Gone between the listing and the stat.
+    }
+  }
+  files.sort((a, b) => b.ms - a.ms || (a.file < b.file ? -1 : 1));
+  const cutoff = now.getTime() - policy.days * 86_400_000;
+  const remove: RunEventFile[] = [];
+  const keep: RunEventFile[] = [];
+  files.forEach(({ ms, ...f }, i) => (i >= policy.keep && ms < cutoff ? remove : keep).push(f));
+  return { dir, remove, keep };
+}
+
+/** Delete the files a plan lets go. Returns how many were deleted; a file already gone is not counted. */
+export function pruneRunEvents(plan: RunEventPrune): number {
+  let n = 0;
+  for (const f of plan.remove) {
+    try {
+      rmSync(f.file);
+      n++;
+    } catch {
+      // Already gone.
+    }
+  }
+  return n;
+}

package/src/run-event-stream.ts

@@ -46,7 +46,8 @@ const GATE_PREFIX = "gate:";
 /**
  * A run-event body as the older `RunProgressEvent`, or undefined when that
  * stream had no such event. It never printed a gate step, a skipped step,
- * a phase outside a component or a gate's decision, so those map to nothing
+ * a phase outside a component, a gate's decision or a component the run did
+ * not start (`blocked`, `already-applied`, #4007), so those map to nothing
  * and `--progress-json` prints what it printed before #4041.
  */
 export function progressOfRunEvent(body: RunEventBody): RunProgressEvent | undefined {
@@ -79,6 +80,8 @@ export function progressOfRunEvent(body: RunEventBody): RunProgressEvent | undef
         ? undefined
         : { type: "phase-done", component: body.component, phase: body.phase, status: progressStatus(body.status) };
     case "component-settle":
+      // A component the run did not start (#4007) was never in the older stream.
+      if (body.status === "blocked" || body.status === "already-applied") return undefined;
       return { type: "component-done", wave: body.wave, component: body.component, status: progressStatus(body.status) };
     case "wave-settle":
       return { type: "wave-done", wave: body.wave, status: progressStatus(body.status) };

package/src/run-event.ts

@@ -126,11 +126,31 @@ export interface RunEventComponentStart {
   component: string;
 }
 
+/**
+ * How a component settled: a {@link RunEventSettleStatus}, or one of two
+ * statuses for a component the run did not start (#4007), added within
+ * contract 1 by chant 0.124.29. `blocked`: a dependency failed or stopped at
+ * a gate, so it never ran. `already-applied`: an earlier attempt that this
+ * run resumed applied it. Neither has a `component-start` before it. A reader
+ * that knows only the four settle statuses reads either as a component that
+ * did not run in this run.
+ */
+export type RunEventComponentSettleStatus = RunEventSettleStatus | "blocked" | "already-applied";
+
+/** The first chant that writes `blocked`, `already-applied` and `blockedBy` on `component-settle` (#4007). */
+export const RUN_EVENT_COMPONENT_SKIP_FLOOR = "0.124.29";
+
 export interface RunEventComponentSettle {
   type: "component-settle";
+  /**
+   * 1-based, into `run-start`'s `waves`. On an `already-applied` settle it is
+   * the wave the component had in the derivation the earlier attempt ran.
+   */
   wave: number;
   component: string;
-  status: RunEventSettleStatus;
+  status: RunEventComponentSettleStatus;
+  /** With `blocked`: the failed or gated component the run reached this one from. */
+  blockedBy?: string;
 }
 
 /** An Op's phase, a component composition's phase, or a pipeline's stage. `component` is null outside a component run. */

package/src/workspace/__fixtures__/flag-workspace.ts

@@ -0,0 +1,132 @@
+/**
+ * A workspace with feature flags (#4024), for the flag tests: a throwaway git
+ * repository with a decision kind, the reference workspace's work kind, and
+ * the canonical flag kind chant ships at `reference-kinds/flag`.
+ *
+ * - The decision kind closes `confirmed` and `superseded`. d-001 is
+ *   confirmed, d-002 is only decided.
+ * - W-001 implements d-001, so its work is settled. W-002 implements d-002.
+ * - The flag `old-banner` hides W-001, so it is due for removal (stale).
+ * - The flag `new-checkout` hides W-002 and backs the build parameter
+ *   `newCheckout` of member `shop`: on in dev, off in prod, and no value in
+ *   staging.
+ * - Member `shop` has a component whose deploy declares a gate, so every
+ *   environment it builds for has one. Member `blog` has a component with
+ *   no gate.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { git, repo } from "./contract-repo";
+
+const HERE = import.meta.dirname;
+const REPO_ROOT = join(HERE, "..", "..", "..", "..", "..");
+const REF = join(REPO_ROOT, "reference-workspace");
+const ref = (path: string) => readFileSync(join(REF, path), "utf-8");
+const canonical = (file: string) => readFileSync(join(HERE, "..", "reference-kinds", "flag", file), "utf-8");
+
+const DECISION_KIND = `export const recordKind = {
+  name: "decision",
+  location: { dir: ".", match: "^d-[0-9]{3}-.+\\\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:test:decision:1", path: "decision.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["proposed", "decided", "confirmed", "superseded"],
+  closedStates: ["confirmed", "superseded"],
+  approval: { proposed: 0, decided: 1, confirmed: 2, superseded: 2 },
+  supersedes: { field: "supersedes" },
+};
+`;
+
+const DECISION_SCHEMA = JSON.stringify(
+  {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: "urn:test:decision:1",
+    type: "object",
+    required: ["id", "state"],
+    properties: { id: { type: "string" }, state: { type: "string" }, supersedes: { type: "array", items: { type: "string" } } },
+  },
+  null,
+  2,
+);
+
+const decision = (id: string, state: string) => `---\nid: "${id}"\nstate: "${state}"\nsupersedes: []\n---\n\n# ${id}\n`;
+
+export function workItem(id: string, implementsIds: string[], state = "in-progress"): string {
+  const data = {
+    schema: 1,
+    id,
+    title: `Work ${id}`,
+    state,
+    implements: implementsIds,
+    needs: [],
+    constrains: ["member:shop"],
+    evidence: [],
+    owner: "alice",
+    opened_on: "2026-10-01",
+    ...(state === "done" ? { closed_on: "2026-10-10" } : {}),
+    source: { kind: "workspace", member: "shop" },
+    supersedes: [],
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+export function flagRecord(id: string, fields: { work: string; member: string; param: string; values: Record<string, string | number | boolean>; owner?: string }): string {
+  const data = { schema: 1, id, owner: fields.owner ?? "alice", work: fields.work, member: fields.member, param: fields.param, values: fields.values };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+/** A component file whose deploy declares a gate when `gated` is set. */
+export function componentFile(name: string, gated: boolean): string {
+  const steps = gated ? `[{ kind: "gate", gate: "prod-release" }, { kind: "apply", template: "dist/${name}.json" }]` : `[{ kind: "apply", template: "dist/${name}.json" }]`;
+  return `export const ${name} = { name: "${name}", dependsOn: [], deploy: [{ phase: "Apply", steps: ${steps} }] };\n`;
+}
+
+/** The flag workspace's files, with `overrides` laid over them (a null value removes a file). */
+export function flagWorkspaceFiles(overrides: Record<string, string | null> = {}): Record<string, string> {
+  const files: Record<string, string | null> = {
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "flags",
+        schema: 1,
+        members: [
+          { name: "shop", dir: "shop", kind: "chant" },
+          { name: "blog", dir: "blog", kind: "chant" },
+        ],
+        records: [{ kind: "decisions/decision.kind.mjs" }, { kind: "work/work.kind.mjs" }, { kind: "flags/flag.kind.mjs" }],
+      },
+      null,
+      2,
+    ),
+    "shop/chant.config.ts": `export default { environments: ["dev", "staging", "prod"] };\n`,
+    "shop/shop.component.ts": componentFile("shop", true),
+    "blog/chant.config.ts": `export default { environments: ["dev", "prod"] };\n`,
+    "blog/blog.component.ts": componentFile("blog", false),
+    "decisions/decision.kind.mjs": DECISION_KIND,
+    "decisions/decision.schema.json": DECISION_SCHEMA,
+    "decisions/d-001-the-banner.md": decision("d-001", "confirmed"),
+    "decisions/d-002-the-checkout.md": decision("d-002", "decided"),
+    "work/work.kind.mjs": ref("work/work.kind.mjs").replace('    answers: "../answers/answer.kind.mjs",\n', ""),
+    "work/work.schema.json": ref("work/work.schema.json"),
+    "work/W-001-the-banner.md": workItem("W-001", ["d-001"], "done"),
+    "work/W-002-the-checkout.md": workItem("W-002", ["d-002"]),
+    "flags/flag.kind.mjs": canonical("flag.kind.mjs"),
+    "flags/flag.schema.json": canonical("flag.schema.json"),
+    "flags/old-banner.flag.md": flagRecord("old-banner", { work: "W-001", member: "blog", param: "banner", values: { dev: true, prod: true } }),
+    "flags/new-checkout.flag.md": flagRecord("new-checkout", { work: "W-002", member: "shop", param: "newCheckout", values: { dev: true, prod: false } }),
+    ...overrides,
+  };
+  return Object.fromEntries(Object.entries(files).filter((e): e is [string, string] => e[1] !== null));
+}
+
+/** The flag workspace in a new git repository, committed. */
+export function flagWorkspace(overrides: Record<string, string | null> = {}): string {
+  const root = repo(flagWorkspaceFiles(overrides));
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "flags");
+  return root;
+}