@intentius/chant 0.124.51 → 0.124.54

package/src/workspace/promote-waves.test.ts

@@ -0,0 +1,296 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { contentDigest } from "../content-digest";
+import type { GateLedgerPort } from "../op/gate";
+import type { PromoteRunner } from "./promote";
+import { parseStateMappings, planWaves, promoteWavesCommand, stateRefusal, type WavesSummary } from "./promote-waves";
+
+const git = (cwd: string, ...a: string[]) => execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", ...a], { cwd, encoding: "utf-8" });
+
+interface Pending {
+  gate: string;
+  planDigest?: string;
+  description?: string;
+  timestamp: string;
+}
+
+/** A gate ledger in memory: pending facts as evaluateGate records them, and approvals of the newest one per gate. */
+function ledger(): GateLedgerPort & { pending: Pending[]; approve(gate: string): void } {
+  const pending: Pending[] = [];
+  const resolutions: unknown[] = [];
+  return {
+    pending,
+    async read() {
+      return { resolutions, pending } as never;
+    },
+    async appendPending(input: Record<string, unknown>) {
+      const record = { version: 1, kind: "pending", ...input };
+      pending.push(record as unknown as Pending);
+      return { record, pushed: false } as never;
+    },
+    approve(gate: string) {
+      const standing = pending.filter((p) => p.gate === gate).at(-1)!;
+      const after = new Date(new Date(standing.timestamp).getTime() + 1000).toISOString();
+      resolutions.push({ version: 1, op: "workspace-promote", gate, planDigest: standing.planDigest, resolvedBy: "alex", outcome: "approved", timestamp: after });
+    },
+  } as never;
+}
+
+/** The report the fake live-import prints for an estate, in choudoufu's layout: two verified, one unadmitted. */
+const reportFor = (estate: string, extra = "") =>
+  [
+    `Ratifying /s/${estate}.tfstate for estate "${estate}" against the live system. This was read-only: nothing was written.`,
+    "",
+    "VERIFIED (2) - verified against the live system:",
+    `  aws_s3_bucket.${estate}                    aws_s3_bucket            live id: ${estate}-bucket`,
+    "    matches",
+    `  aws_sqs_queue.${estate}                    aws_sqs_queue            live id: ${estate}-queue`,
+    "    matches",
+    "",
+    "UNADMITTED_TYPE (1) - outside the admitted type set:",
+    "  aws_x.y                                    aws_x                    live id: -",
+    "    not admitted",
+    "",
+    `2 of 3 resource instance(s) are eligible for stamping (VERIFIED or DRIFTED).${extra}`,
+    "",
+  ].join("\n");
+
+describe("planWaves (#4461)", () => {
+  test("the canary is wave 1, the rest follow in order at the wave size", () => {
+    expect(planWaves(["a", "b", "c", "d", "e"], ["c"], 2)).toEqual([["c"], ["a", "b"], ["d", "e"]]);
+    expect(planWaves(["a", "b", "c"], [], 5)).toEqual([["a"], ["b", "c"]]);
+    expect(() => planWaves(["a"], ["z"], 1)).toThrow(/--canary z/);
+    expect(() => planWaves(["a"], [], 0)).toThrow(/--wave-size/);
+  });
+  test("--state takes <member>=<path>", () => {
+    expect(parseStateMappings(["a=/s/a.tfstate", "b=x=y"])).toEqual({ a: "/s/a.tfstate", b: "x=y" });
+    expect(() => parseStateMappings(["/s/a.tfstate"])).toThrow(/<member>=/);
+  });
+});
+
+describe("chant workspace promote --all (#4461)", () => {
+  let root: string;
+  let states: string;
+  let calls: { argv: string[]; cwd: string }[];
+  let failCheck: Set<string>;
+  let reportExtra: Map<string, string>;
+  /** Members whose next `live-import -approve` fails, once each. */
+  let failStampOnce: Set<string>;
+
+  const memberOf = (argv: string[], cwd: string): string => argv.find((a) => a.startsWith("-estate="))?.slice("-estate=".length) ?? basename(cwd);
+  const runner: PromoteRunner = async (argv, cwd) => {
+    calls.push({ argv, cwd });
+    const member = memberOf(argv, cwd);
+    if (argv[1] === "live-check") return failCheck.has(member) ? { exitCode: 2, output: "unsupported construct: provisioner" } : { exitCode: 0, output: "" };
+    if (argv.includes("-approve") && failStampOnce.delete(member)) return { exitCode: 1, output: "Error: the live system refused the stamp write" };
+    if (argv.includes("-approve")) return { exitCode: 0, output: "2 resource(s) newly stamped, 0 already stamped, 0 newly recorded, 0 re-recorded for sensitivity only, 0 already recorded, 0 failed, 1 skipped.\n" };
+    return { exitCode: 0, output: reportFor(member, reportExtra.get(member)) };
+  };
+
+  const v4 = JSON.stringify({ version: 4, terraform_version: "1.5.7", serial: 1, lineage: "l", outputs: {}, resources: [] });
+  const members = ["a", "b", "c", "d"];
+
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    calls = [];
+    failCheck = new Set();
+    reportExtra = new Map();
+    failStampOnce = new Set();
+    root = mkdtempSync(join(tmpdir(), "chant-promote-waves-"));
+    states = mkdtempSync(join(tmpdir(), "chant-promote-waves-states-"));
+    git(root, "init", "-q", "-b", "main");
+    for (const m of members) {
+      mkdirSync(join(root, m));
+      writeFileSync(join(root, m, "main.tf"), "# tf\n");
+      writeFileSync(join(states, `${m}.tfstate`), v4);
+    }
+    writeFileSync(
+      join(root, "chant.workspace.json"),
+      JSON.stringify({ name: "w", schema: 1, members: members.map((m) => ({ name: m, dir: m, kind: "terraform" })) }, null, 2) + "\n",
+    );
+    git(root, "add", "-A");
+    git(root, "commit", "-qm", "init");
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+    rmSync(states, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  const kinds = () => Object.fromEntries(JSON.parse(readFileSync(join(root, "chant.workspace.json"), "utf-8")).members.map((m: { name: string; kind: string }) => [m.name, m.kind]));
+  const outcomes = (s: WavesSummary) => Object.fromEntries(s.roots.map((r) => [r.member, r.outcome]));
+  const promote = (l: GateLedgerPort, extra: { canary?: string[]; waveSize?: number } = {}) =>
+    promoteWavesCommand({ root, all: true, stateDir: states, canary: ["b"], waveSize: 2, json: true, runner, ledger: l, ...extra });
+
+  test("a failing canary stops every later wave and leaves the tree alone", async () => {
+    const l = ledger();
+    failCheck.add("b");
+    const s = await promote(l);
+    expect(s.waves).toEqual([["b"], ["a", "c"], ["d"]]);
+    expect(outcomes(s)).toEqual({ b: "checks-failed", a: "not-run", c: "not-run", d: "not-run" });
+    expect(s.exitCode).toBe(1);
+    expect(calls.every((c) => basename(c.cwd) === "b")).toBe(true);
+    expect(l.pending).toHaveLength(0);
+    expect(kinds()).toEqual({ a: "terraform", b: "terraform", c: "terraform", d: "terraform" });
+    expect(git(root, "status", "--porcelain")).toBe("");
+  });
+
+  test("one gate per root, each bound to that root's own live-import report digest", async () => {
+    const l = ledger();
+
+    const first = await promote(l);
+    expect(outcomes(first)).toEqual({ b: "gated", a: "not-run", c: "not-run", d: "not-run" });
+    expect(first.exitCode).toBe(3);
+    expect(l.pending.map((p) => p.gate)).toEqual(["b"]);
+    const b = first.roots.find((r) => r.member === "b")!;
+    expect(b.reportDigest).toBe(contentDigest(reportFor("b").trimEnd()));
+    expect(l.pending[0].planDigest).toBe(b.digest);
+    expect(l.pending[0].description).toContain(b.reportDigest);
+    expect(b.eligible).toEqual({ stampable: 2, total: 3 });
+    expect(b.unadmitted).toBe(1);
+
+    l.approve("b");
+    calls = [];
+    const second = await promote(l);
+    expect(outcomes(second)).toEqual({ b: "applied", a: "gated", c: "gated", d: "not-run" });
+    expect(second.roots.find((r) => r.member === "b")!.stamped).toEqual({ newly: 2, already: 0, failed: 0 });
+    // The stamp runs in b's staging directory, where its choudoufu init ran, not in the tree (chant#4492).
+    const bInit = calls.find((c) => c.argv[1] === "init" && basename(c.cwd) === "b")!;
+    expect(calls.filter((c) => c.argv.includes("-approve")).map((c) => c.cwd)).toEqual([bInit.cwd]);
+    expect(bInit.cwd).not.toBe(join(realpathSync(root), "b"));
+    expect(kinds()).toMatchObject({ b: "choudoufu", a: "terraform", c: "terraform" });
+
+    const gateOf = (m: string) => l.pending.filter((p) => p.gate === m);
+    const rowOf = (s: WavesSummary, m: string) => s.roots.find((r) => r.member === m)!;
+    expect(gateOf("a")).toHaveLength(1);
+    expect(gateOf("c")).toHaveLength(1);
+    expect(gateOf("a")[0].planDigest).toBe(rowOf(second, "a").digest);
+    expect(gateOf("c")[0].planDigest).toBe(rowOf(second, "c").digest);
+    expect(rowOf(second, "a").digest).not.toBe(rowOf(second, "c").digest);
+    expect(rowOf(second, "a").reportDigest).toBe(contentDigest(reportFor("a").trimEnd()));
+    expect(rowOf(second, "c").reportDigest).toBe(contentDigest(reportFor("c").trimEnd()));
+
+    // a's approval is for the report its approver read: a changed report is a new digest and stays gated.
+    l.approve("a");
+    l.approve("c");
+    reportExtra.set("a", "\nDRIFTED (1) - verified, but drifted from the live system:");
+    const third = await promote(l);
+    expect(outcomes(third)).toMatchObject({ b: "already-promoted", a: "gated", c: "applied", d: "not-run" });
+    expect(kinds()).toMatchObject({ a: "terraform", c: "choudoufu" });
+  });
+
+  test("within a wave a failed root leaves the others to run, and the next wave waits", async () => {
+    const l = ledger();
+    await promote(l);
+    l.approve("b");
+    failCheck.add("a");
+    const s = await promote(l);
+    expect(outcomes(s)).toEqual({ b: "applied", a: "checks-failed", c: "gated", d: "not-run" });
+    expect(s.exitCode).toBe(1);
+    expect(l.pending.filter((p) => p.gate === "a")).toHaveLength(0);
+    expect(kinds()).toMatchObject({ a: "terraform", b: "choudoufu", c: "terraform", d: "terraform" });
+    expect(s.roots.find((r) => r.member === "d")!.reason).toMatch(/wave 2 did not land \(a checks-failed, c gated\)/);
+  });
+
+  test("re-running over a landed workspace is a no-op", async () => {
+    const l = ledger();
+    const all = { waveSize: 3 };
+    await promote(l, all);
+    l.approve("b");
+    await promote(l, all);
+    for (const m of ["a", "c", "d"]) l.approve(m);
+    const landed = await promote(l, all);
+    expect(outcomes(landed)).toEqual({ b: "already-promoted", a: "applied", c: "applied", d: "applied" });
+    expect(landed.exitCode).toBe(0);
+
+    calls = [];
+    const pendingBefore = l.pending.length;
+    const again = await promote(l, all);
+    expect(outcomes(again)).toEqual({ b: "already-promoted", a: "already-promoted", c: "already-promoted", d: "already-promoted" });
+    expect(again.exitCode).toBe(0);
+    expect(again.outcome).toBe("landed");
+    expect(calls).toHaveLength(0);
+    expect(l.pending).toHaveLength(pendingBefore);
+  });
+
+  test("a re-run after a failed live-import -approve retries the stamp instead of reporting already-promoted (#4485)", async () => {
+    const l = ledger();
+    await promote(l);
+    l.approve("b");
+    failStampOnce.add("b");
+    const failed = await promote(l);
+    const row = (s: WavesSummary, m: string) => s.roots.find((r) => r.member === m)!;
+    expect(row(failed, "b").outcome).toBe("stamp-failed");
+    expect(row(failed, "b").reason).toContain(`choudoufu live-import -state=${join(states, "b.tfstate")} -estate=b -approve`);
+    expect(failed.exitCode).toBe(1);
+    // The kind was written; the stamp is kept as pending.
+    expect(kinds()).toMatchObject({ b: "choudoufu" });
+    expect(existsSync(join(root, ".chant", "workspace-promote", "b.stamp.json"))).toBe(true);
+
+    calls = [];
+    const retried = await promote(l);
+    expect(row(retried, "b").outcome).toBe("applied");
+    expect(row(retried, "b").stamped).toEqual({ newly: 2, already: 0, failed: 0 });
+    // Only the stamp ran for b, in a staging of its own whose init installed the providers (chant#4492): no live-check, no report, no new gate.
+    const forB = calls.filter((c) => memberOf(c.argv, c.cwd) === "b");
+    expect(forB.map((c) => c.argv.slice(1))).toEqual([
+      ["init", "-input=false", "-backend=false", "-no-color"],
+      ["live-import", `-state=${join(states, "b.tfstate")}`, "-estate=b", "-approve"],
+    ]);
+    expect(forB[1]!.cwd).toBe(forB[0]!.cwd);
+    expect(forB[1]!.cwd).not.toBe(join(realpathSync(root), "b"));
+    expect(l.pending.filter((p) => p.gate === "b")).toHaveLength(1);
+    expect(existsSync(join(root, ".chant", "workspace-promote", "b.stamp.json"))).toBe(false);
+    // The canary landed, so wave 2 ran.
+    expect(outcomes(retried)).toMatchObject({ a: "gated", c: "gated" });
+
+    // Once stamped, a re-run reports it promoted and runs nothing for it.
+    calls = [];
+    const again = await promote(l);
+    expect(row(again, "b").outcome).toBe("already-promoted");
+    expect(calls.some((c) => memberOf(c.argv, c.cwd) === "b")).toBe(false);
+  });
+
+  test("a stamp that fails again stays stamp-failed with the command, and the later waves wait (#4485)", async () => {
+    const l = ledger();
+    await promote(l);
+    l.approve("b");
+    failStampOnce.add("b");
+    await promote(l);
+    failStampOnce.add("b");
+    const s = await promote(l);
+    const b = s.roots.find((r) => r.member === "b")!;
+    expect(b.outcome).toBe("stamp-failed");
+    expect(b.reason).toMatch(/failed again; live-import is safe to re-run: `choudoufu live-import -state=.* -estate=b -approve` in b/);
+    expect(outcomes(s)).toEqual({ b: "stamp-failed", a: "not-run", c: "not-run", d: "not-run" });
+    expect(existsSync(join(root, ".chant", "workspace-promote", "b.stamp.json"))).toBe(true);
+  });
+
+  test("a root without a local v4 state is refused by name and stages nothing", async () => {
+    const l = ledger();
+    writeFileSync(join(root, "a", "backend.tf"), 'terraform {\n  backend "s3" {}\n}\n');
+    git(root, "add", "-A");
+    git(root, "commit", "-qm", "s3");
+    rmSync(join(states, "a.tfstate"));
+    writeFileSync(join(states, "c.tfstate"), JSON.stringify({ version: 3, serial: 1 }));
+    const s = await promoteWavesCommand({ root, all: true, stateDir: states, canary: ["b"], waveSize: 3, json: true, runner, ledger: l });
+    l.approve("b");
+    const second = await promoteWavesCommand({ root, all: true, stateDir: states, canary: ["b"], waveSize: 3, json: true, runner, ledger: l });
+    expect(outcomes(s).b).toBe("gated");
+    const row = (m: string) => second.roots.find((r) => r.member === m)!;
+    expect(row("a").outcome).toBe("refused");
+    expect(row("a").reason).toMatch(/a uses the s3 backend .*terraform state pull/);
+    expect(row("c").outcome).toBe("refused");
+    expect(row("c").reason).toMatch(/version 3 state; live-import reads version 4/);
+    expect(row("d").outcome).toBe("gated");
+    expect(calls.some((c) => memberOf(c.argv, c.cwd) === "a" || memberOf(c.argv, c.cwd) === "c")).toBe(false);
+  });
+
+  test("stateRefusal accepts a local v4 state", () => {
+    expect(stateRefusal("a", join(root, "a"), join(states, "a.tfstate"))).toBeUndefined();
+  });
+});

package/src/workspace/promote-waves.ts

@@ -0,0 +1,340 @@
+/**
+ * `chant workspace promote --all` (#4461): adopt a workspace of plain
+ * Terraform roots into choudoufu in waves, a canary first.
+ *
+ * Each root goes through {@link promoteCommand} on its own, so each root has
+ * its own gate, `workspace-promote/<member>`, whose digest binds that root's
+ * own `live-import` report. A root that fails leaves every other root as it
+ * was: its staging ran in a worktree, and nothing of it reached the tree.
+ *
+ * The order:
+ *
+ * - The canary (`--canary <member>`, else the first candidate in declaration
+ *   order) is wave 1. Unless every canary lands, no other wave runs.
+ * - The rest follow in declaration order, `--wave-size` roots a wave. Every
+ *   root of a wave is tried even when one of them fails, and the next wave
+ *   runs only when the whole wave landed.
+ *
+ * A root lands when it was applied, was already promoted, or (under
+ * `--dry-run`) staged cleanly. A gated root has not landed: approve its gate
+ * and run the same command again. Roots already of kind `choudoufu` report
+ * `already-promoted` and are not staged again, so a re-run over a workspace
+ * that has landed is a no-op. A root whose kind was written but whose
+ * `live-import -approve` failed is kind `choudoufu` with a pending stamp
+ * (#4485): a re-run retries the stamp, and the root lands once it passes or
+ * stays `stamp-failed` with the command to run.
+ *
+ * Before a root is staged its state is checked: `live-import` reads a local
+ * tfstate of format version 4, so a missing state under a remote backend, or
+ * a state of another version, refuses that root by name.
+ */
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { GateLedgerPort } from "../op/gate";
+import { readDeclaration } from "./declaration";
+import { PROMOTE_GATED_EXIT, PromoteError, promoteCommand, readPendingStamp, retryPendingStamp, stampCommand, type PromoteResult, type PromoteRunner } from "./promote";
+import { workingTree } from "./tree";
+
+export const DEFAULT_WAVE_SIZE = 5;
+
+export type WaveRootOutcome =
+  /** Staged, approved, kind written and markers stamped. */
+  | "applied"
+  /** Already of kind choudoufu (or above): nothing to do. */
+  | "already-promoted"
+  /** `--dry-run`: staged and checked, no gate recorded. */
+  | "dry-run"
+  /** A gate is pending for this root's digest. */
+  | "gated"
+  /** live-check or the live-import report failed in staging. */
+  | "checks-failed"
+  /** The state is not a local v4 tfstate. */
+  | "refused"
+  /** The kind was written but `live-import -approve` failed. */
+  | "stamp-failed"
+  /** Anything else that stopped the root (uncommitted changes, a patch that no longer applies). */
+  | "failed"
+  /** An earlier wave did not land. */
+  | "not-run";
+
+const LANDED: ReadonlySet<WaveRootOutcome> = new Set(["applied", "already-promoted", "dry-run"]);
+
+export interface WaveRootResult {
+  member: string;
+  wave: number;
+  canary: boolean;
+  outcome: WaveRootOutcome;
+  kind: string;
+  state?: string;
+  digest?: string;
+  reportDigest?: string;
+  /** From the report: instances eligible for stamping, of the total. */
+  eligible?: { stampable: number; total: number };
+  /** From the report: instances outside the admitted type set, never stamped. */
+  unadmitted?: number;
+  /** From the stamp report under -approve. */
+  stamped?: { newly: number; already: number; failed: number };
+  reason?: string;
+}
+
+export interface WavesSummary {
+  outcome: "landed" | "gated" | "failed" | "dry-run";
+  exitCode: number;
+  waves: string[][];
+  roots: WaveRootResult[];
+}
+
+export interface PromoteWavesOptions {
+  root: string;
+  /** Every terraform member, and every choudoufu member (which reports already-promoted). */
+  all?: boolean;
+  /** `--state <member>=<path>`, repeatable. Without `all`, the members named here are the set. */
+  states?: Record<string, string>;
+  /** `--state-dir <dir>`: a member's state is `<dir>/<member>.tfstate`. */
+  stateDir?: string;
+  canary?: string[];
+  waveSize?: number;
+  dryRun?: boolean;
+  json?: boolean;
+  /** For tests. */
+  runner?: PromoteRunner;
+  ledger?: GateLedgerPort;
+  now?: string;
+}
+
+/** Parse `--state <member>=<path>` values. */
+export function parseStateMappings(values: readonly string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const v of values) {
+    const at = v.indexOf("=");
+    if (at <= 0 || at === v.length - 1) throw new PromoteError(`--state with --all takes <member>=<terraform.tfstate>: got "${v}"`);
+    const member = v.slice(0, at);
+    if (out[member] !== undefined) throw new PromoteError(`--state names ${member} twice`);
+    out[member] = v.slice(at + 1);
+  }
+  return out;
+}
+
+/** The waves: the canaries first, then the rest in declaration order, `size` at a time. */
+export function planWaves(candidates: readonly string[], canary: readonly string[], size: number): string[][] {
+  if (!Number.isInteger(size) || size < 1) throw new PromoteError(`--wave-size needs a whole number from 1: got ${size}`);
+  for (const c of canary) {
+    if (!candidates.includes(c)) throw new PromoteError(`--canary ${c} is not one of the roots being promoted (${candidates.join(", ") || "none"})`);
+  }
+  const first = canary.length > 0 ? [...new Set(canary)] : candidates.slice(0, 1);
+  const rest = candidates.filter((m) => !first.includes(m));
+  const waves = first.length > 0 ? [first] : [];
+  for (let i = 0; i < rest.length; i += size) waves.push(rest.slice(i, i + size));
+  return waves;
+}
+
+/** The backend a root's .tf files declare, or undefined for none or `local`. */
+export function remoteBackend(dir: string): string | undefined {
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".tf"));
+  } catch {
+    return undefined;
+  }
+  for (const f of files) {
+    const text = readFileSync(join(dir, f), "utf-8").replace(/^\s*(#|\/\/).*$/gm, "");
+    const backend = /\bbackend\s+"([^"]+)"/.exec(text);
+    if (backend && backend[1] !== "local") return backend[1];
+    if (/^\s*cloud\s*\{/m.test(text)) return "cloud";
+  }
+  return undefined;
+}
+
+/**
+ * Why `state` cannot feed `live-import` for `member`, or undefined when it
+ * can: it must be a local tfstate of format version 4.
+ */
+export function stateRefusal(member: string, memberDir: string, state: string): string | undefined {
+  const backend = remoteBackend(memberDir);
+  if (!existsSync(state)) {
+    if (backend) {
+      return `${member} uses the ${backend} backend and has no local state at ${state}: live-import reads a local tfstate, so run \`terraform state pull > ${state}\` in ${memberDir} first (or pass --state ${member}=<pulled file>)`;
+    }
+    return `${member} has no state at ${state}: pass --state ${member}=<terraform.tfstate> or --state-dir <dir>`;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(state, "utf-8"));
+  } catch {
+    return `${member}: ${state} is not a JSON tfstate`;
+  }
+  const version = (parsed as { version?: unknown } | null)?.version;
+  if (version !== 4) {
+    const hint = (parsed as { backend?: unknown } | null)?.backend !== undefined
+      ? " It looks like .terraform/terraform.tfstate, the backend's settings: run `terraform state pull` for the state itself."
+      : "";
+    return `${member}: ${state} is a version ${String(version)} state; live-import reads version 4 only (Terraform 0.12 and later).${hint}`;
+  }
+  return undefined;
+}
+
+function reportCounts(r: PromoteResult): Pick<WaveRootResult, "eligible" | "unadmitted"> {
+  if (!r.adoption) return {};
+  return {
+    eligible: { stampable: r.adoption.claimed, total: r.adoption.total },
+    unadmitted: r.adoption.entries.filter((e) => e.status === "UNADMITTED_TYPE").length,
+  };
+}
+
+function stampCounts(text: string | undefined): WaveRootResult["stamped"] {
+  const m = text ? /(\d+) resource\(s\) newly stamped, (\d+) already stamped, .*?(\d+) failed/.exec(text) : null;
+  return m ? { newly: Number(m[1]), already: Number(m[2]), failed: Number(m[3]) } : undefined;
+}
+
+function rootOutcome(r: PromoteResult): WaveRootOutcome {
+  if (r.outcome === "applied") return r.exitCode === 0 ? "applied" : "stamp-failed";
+  if (r.outcome === "top-of-ladder") return "already-promoted";
+  return r.outcome;
+}
+
+export async function promoteWavesCommand(opts: PromoteWavesOptions): Promise<WavesSummary> {
+  const root = resolve(opts.root);
+  const decl = readDeclaration(workingTree(root));
+  const states = opts.states ?? {};
+  const say = (m: string): void => {
+    if (!opts.json) console.error(m);
+  };
+
+  for (const name of Object.keys(states)) {
+    if (!decl.members.some((m) => m.name === name)) throw new PromoteError(`--state names ${name}, which the declaration has no member of`);
+  }
+  const selected = decl.members.filter((m) => (opts.all ? m.kind === "terraform" || m.kind === "choudoufu" : states[m.name] !== undefined));
+  if (selected.length === 0) {
+    throw new PromoteError(opts.all ? "the declaration has no member of kind terraform to promote" : "name the roots with --state <member>=<path>, or pass --all");
+  }
+  for (const m of selected) {
+    if (m.kind !== "terraform" && m.kind !== "choudoufu") throw new PromoteError(`${m.name} is kind ${m.kind}; promote --all adopts terraform roots into choudoufu`);
+  }
+
+  // The waves are planned over every selected root, promoted or not, so a
+  // re-run keeps the same waves and the same canary: an already promoted
+  // root lands in its wave without being staged.
+  const waves = planWaves(selected.map((m) => m.name), opts.canary ?? [], opts.waveSize ?? DEFAULT_WAVE_SIZE);
+  const byName = new Map(selected.map((m) => [m.name, m]));
+  const roots: WaveRootResult[] = [];
+
+  const stateFor = (name: string): string => {
+    const dir = byName.get(name)!.dir;
+    if (states[name] !== undefined) return resolve(states[name]);
+    if (opts.stateDir) return resolve(opts.stateDir, `${name}.tfstate`);
+    return join(root, dir, "terraform.tfstate");
+  };
+
+  let stopped: string | undefined;
+  for (const [i, wave] of waves.entries()) {
+    const n = i + 1;
+    const canary = i === 0;
+    if (stopped) {
+      for (const name of wave) roots.push({ member: name, wave: n, canary, outcome: "not-run", kind: byName.get(name)!.kind, reason: stopped });
+      continue;
+    }
+    say(formatInfo(`wave ${n}${canary ? " (canary)" : ""}: ${wave.join(", ")}`));
+    const results: WaveRootResult[] = [];
+    for (const name of wave) {
+      const member = byName.get(name)!;
+      const state = stateFor(name);
+      if (member.kind !== "terraform") {
+        const pending = member.kind === "choudoufu" ? readPendingStamp(realpathSync(root), name) : undefined;
+        if (!pending || opts.dryRun) {
+          const why = pending ? `already kind ${member.kind}; its stamp is pending and --dry-run does not retry it` : `already kind ${member.kind}; nothing staged`;
+          results.push({ member: name, wave: n, canary, outcome: pending ? "stamp-failed" : "already-promoted", kind: member.kind, reason: why });
+          continue;
+        }
+        // #4485: the kind was written and the stamp failed; retry the stamp, against the state this run names if it names one.
+        const explicit = states[name] !== undefined || opts.stateDir !== undefined ? stateFor(name) : undefined;
+        const row: WaveRootResult = { member: name, wave: n, canary, outcome: "stamp-failed", kind: member.kind, state: explicit ?? pending.state };
+        try {
+          const r = (await retryPendingStamp({ root, member: name, ...(explicit ? { state: explicit } : {}), ...(opts.json !== undefined ? { json: opts.json } : {}), ...(opts.runner ? { runner: opts.runner } : {}) }))!;
+          row.outcome = rootOutcome(r);
+          const stamped = stampCounts(r.followUpOutput);
+          if (stamped) row.stamped = stamped;
+          row.reason = row.outcome === "applied"
+            ? `kind written by an earlier run; its failed stamp was retried and passed`
+            : `kind written, but ${r.followUpFailed} failed again; live-import is safe to re-run: ${stampCommand({ name, dir: member.dir }, row.state!)}`;
+        } catch (err) {
+          if (!(err instanceof PromoteError)) throw err;
+          row.reason = err.message;
+          say(formatError({ message: `${name}: ${err.message}` }));
+        }
+        results.push(row);
+        continue;
+      }
+      const row: WaveRootResult = { member: name, wave: n, canary, outcome: "failed", kind: member.kind, state };
+      const refusal = stateRefusal(name, join(root, member.dir), state);
+      if (refusal) {
+        row.outcome = "refused";
+        row.reason = refusal;
+        say(formatError({ message: refusal }));
+        results.push(row);
+        continue;
+      }
+      try {
+        const r = await promoteCommand({
+          root,
+          member: name,
+          state,
+          dryRun: opts.dryRun,
+          json: opts.json,
+          nested: true,
+          ...(opts.runner ? { runner: opts.runner } : {}),
+          ...(opts.ledger ? { ledger: opts.ledger } : {}),
+          ...(opts.now ? { now: opts.now } : {}),
+        });
+        row.outcome = rootOutcome(r);
+        if (r.digest) row.digest = r.digest;
+        if (r.reportDigest) row.reportDigest = r.reportDigest;
+        Object.assign(row, reportCounts(r));
+        const stamped = stampCounts(r.followUpOutput);
+        if (stamped) row.stamped = stamped;
+        if (row.outcome === "checks-failed") row.reason = r.failureOutput?.split("\n").at(-1) || "a staging check failed";
+        if (row.outcome === "stamp-failed") {
+          row.reason = `kind written, but ${r.followUpFailed} failed; run this again to retry the stamp, or run it by hand (live-import is safe to re-run): ${stampCommand({ name, dir: member.dir }, state)}`;
+        }
+        if (row.outcome === "gated") row.reason = `approve with \`chant approve workspace-promote ${name}\`, then run this again`;
+      } catch (err) {
+        if (!(err instanceof PromoteError)) throw err;
+        row.outcome = "failed";
+        row.reason = err.message;
+        say(formatError({ message: `${name}: ${err.message}` }));
+      }
+      results.push(row);
+    }
+    roots.push(...results);
+    const short = results.filter((r) => !LANDED.has(r.outcome));
+    if (short.length > 0) {
+      stopped = `${canary ? "the canary wave" : `wave ${n}`} did not land (${short.map((r) => `${r.member} ${r.outcome}`).join(", ")})`;
+    }
+  }
+
+  const failed = roots.some((r) => r.outcome === "refused" || r.outcome === "checks-failed" || r.outcome === "failed" || r.outcome === "stamp-failed");
+  const gated = roots.some((r) => r.outcome === "gated");
+  const outcome: WavesSummary["outcome"] = failed ? "failed" : gated ? "gated" : opts.dryRun ? "dry-run" : "landed";
+  const exitCode = failed ? 1 : gated ? PROMOTE_GATED_EXIT : 0;
+  const summary: WavesSummary = { outcome, exitCode, waves, roots };
+
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    say("");
+    for (const r of roots) {
+      const counts = [
+        r.eligible ? `${r.eligible.stampable} of ${r.eligible.total} stampable` : "",
+        r.unadmitted ? `${r.unadmitted} unadmitted, not stamped` : "",
+        r.stamped ? `${r.stamped.newly} newly stamped, ${r.stamped.already} already stamped, ${r.stamped.failed} failed` : "",
+      ].filter(Boolean).join("; ");
+      const where = `wave ${r.wave}${r.canary ? " canary" : ""}`;
+      const line = `${r.member}  ${where}  ${r.outcome}${counts ? `  (${counts})` : ""}${r.reason ? `: ${r.reason}` : ""}`;
+      say(LANDED.has(r.outcome) ? formatInfo(line) : r.outcome === "gated" || r.outcome === "not-run" ? formatWarning({ message: line }) : formatError({ message: line }));
+    }
+    if (outcome === "landed") say(formatSuccess(`every root landed. Review and commit the declaration.`));
+    else if (outcome === "gated") say(formatInfo("approve the pending gates and run the same command again; landed roots are not staged twice"));
+  }
+  return summary;
+}