@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

package/src/op/activities/choudoufu.test.ts

@@ -0,0 +1,725 @@
+/**
+ * choudoufu-specific activity tests (#2103): the three new activities, the
+ * `terraformApply` live-root branch, and the version check. Same
+ * `node:child_process` mock as `terraform.test.ts`; nothing here runs
+ * choudoufu or terraform.
+ */
+
+import { describe, test, expect, beforeEach, afterAll, afterEach, vi } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  terraformApply,
+  choudoufuLivePlan,
+  choudoufuLiveLs,
+  choudoufuLiveCheck,
+  choudoufuAdopt,
+  terraformApplyCommand,
+  classifyApprovalRefusal,
+  choudoufuLivePlanCommand,
+  choudoufuLiveLsCommand,
+  choudoufuLiveCheckCommand,
+  countLivePlanUnowned,
+  parseChoudoufuPlanSummary,
+  isOlderVersion,
+  parseChoudoufuVersion,
+  __resetChoudoufuVersionCheckForTests,
+  DEFAULT_LIVE_PLAN_DOCUMENT_FILE,
+  MIN_CHOUDOUFU_VERSION,
+  CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL,
+  CHOUDOUFU_WRONG_ESTATE_REFUSAL,
+} from "./terraform";
+
+// ── The child-process stub (mirrors terraform.test.ts) ──────────────────────
+
+interface ExecCall {
+  cmd: string;
+  opts: { cwd?: string; env?: Record<string, string>; signal?: AbortSignal };
+}
+
+const execCalls: ExecCall[] = [];
+
+type Reply = { stdout: string; stderr: string } | Error;
+let replies: Array<{ match: string; reply: Reply }> = [];
+
+function execError(code: number, stderr: string, stdout = ""): Error & { code: number; stdout: string; stderr: string } {
+  return Object.assign(new Error(`Command failed (exit ${code})`), { code, stdout, stderr });
+}
+
+/** Every exec call's command, excluding the `choudoufu version` check every activity call triggers once. */
+function commandsRun(): string[] {
+  return execCalls.filter((c) => c.cmd !== "choudoufu version").map((c) => c.cmd);
+}
+
+// Partial mock: `@intentius/chant/op` reaches core's base activities
+// statically now (#2117), and they need the real `execFile`/`spawn` to load.
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  const custom = Symbol.for("nodejs.util.promisify.custom");
+  const exec = ((_cmd: string, _opts: unknown, cb?: (...a: unknown[]) => void) => {
+    cb?.(new Error("unmocked exec path"));
+  }) as unknown as Record<symbol, unknown>;
+  exec[custom] = async (cmd: string, opts?: ExecCall["opts"]) => {
+    execCalls.push({ cmd, opts: opts ?? {} });
+    for (const { match, reply } of replies) {
+      if (cmd.includes(match)) {
+        if (reply instanceof Error) throw reply;
+        return reply;
+      }
+    }
+    return { stdout: "", stderr: "" };
+  };
+  return { ...actual, exec };
+});
+
+// ── A real project config to resolve roots against ──────────────────────────
+
+const workspaces: string[] = [];
+
+/** Write a throwaway project with a `terraform` namespace and a live root directory. */
+function liveProject(opts: { withLiveBlock?: boolean; withSidecar?: boolean } = {}): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-tf-choudoufu-"));
+  workspaces.push(dir);
+  const rootDir = join(dir, "estate");
+  mkdirSync(rootDir, { recursive: true });
+
+  if (opts.withSidecar) {
+    writeFileSync(join(rootDir, "estate.chdf.hcl"), 'estate = "prod-networking"\n');
+    writeFileSync(join(rootDir, "main.tf"), 'resource "null_resource" "x" {}\n');
+  } else if (opts.withLiveBlock !== false) {
+    writeFileSync(
+      join(rootDir, "main.tf"),
+      ["terraform {", "  live {", '    estate = "prod-networking"', "  }", "}", "", 'resource "null_resource" "x" {}', ""].join(
+        "\n",
+      ),
+    );
+  } else {
+    writeFileSync(join(rootDir, "main.tf"), 'resource "null_resource" "x" {}\n');
+  }
+
+  writeFileSync(
+    join(dir, "chant.config.json"),
+    JSON.stringify({ lexicons: ["terraform"], terraform: { binary: "choudoufu", roots: { estate: { dir: "./estate" } } } }, null, 2),
+  );
+  return dir;
+}
+
+afterAll(() => {
+  for (const dir of workspaces) rmSync(dir, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  execCalls.length = 0;
+  replies = [];
+  __resetChoudoufuVersionCheckForTests();
+});
+
+afterEach(() => {
+  __resetChoudoufuVersionCheckForTests();
+});
+
+// ── Pure command builders ────────────────────────────────────────────────────
+
+describe("apply on a live root is the stock command (#2106 follow-up)", () => {
+  test("no -auto-approve: a matched plan file applies without re-prompting, as stock's own apply does", () => {
+    expect(terraformApplyCommand({ binary: "choudoufu", planFile: "chant.tfplan" })).toBe(
+      "choudoufu apply -input=false chant.tfplan",
+    );
+  });
+});
+
+describe("classifyApprovalRefusal (#2106 follow-up)", () => {
+  test("names the change-set refusal", () => {
+    expect(classifyApprovalRefusal(`\nError: ${CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL}\n\nrows...`)).toBe(
+      "approval-mismatch",
+    );
+  });
+
+  test("names the estate refusal", () => {
+    expect(classifyApprovalRefusal(`\nError: ${CHOUDOUFU_WRONG_ESTATE_REFUSAL}\n`)).toBe("wrong-estate");
+  });
+
+  test("undefined for output carrying neither summary line", () => {
+    expect(classifyApprovalRefusal("Error: something else entirely")).toBeUndefined();
+  });
+});
+
+describe("choudoufuLivePlanCommand (#2103)", () => {
+  test("json form carries -detailed-exitcode, -json and -estate", () => {
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", estate: "prod", json: true })).toBe(
+      "choudoufu live-plan -detailed-exitcode -json -estate=prod",
+    );
+  });
+
+  test("text form omits -json", () => {
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", estate: "prod", json: false })).toBe(
+      "choudoufu live-plan -detailed-exitcode -estate=prod",
+    );
+  });
+
+  test("an estate needing shell quoting is quoted", () => {
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", estate: "has space", json: true })).toContain(
+      "-estate='has space'",
+    );
+  });
+
+  // choudoufu refuses `-estate` beside a `live` block or an `estate.chdf.hcl`
+  // sidecar, and since v0.14.0 it does not need one there (choudoufu #894, PR
+  // 915). Omitting the option is how a declared root is run.
+  test("no estate emits no -estate, for a root that names its own (choudoufu #894)", () => {
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", json: true })).toBe(
+      "choudoufu live-plan -detailed-exitcode -json",
+    );
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", json: false, noColor: true })).toBe(
+      "choudoufu live-plan -detailed-exitcode -no-color",
+    );
+  });
+
+  test("-adoption-only and -no-color ride the human form (#2105)", () => {
+    expect(
+      choudoufuLivePlanCommand({ binary: "choudoufu", estate: "prod", json: false, adoptionOnly: true, noColor: true }),
+    ).toBe("choudoufu live-plan -detailed-exitcode -adoption-only -no-color -estate=prod");
+  });
+
+  test("-adoption-only with -json is refused here, as choudoufu refuses it (#2105)", () => {
+    expect(() =>
+      choudoufuLivePlanCommand({ binary: "choudoufu", estate: "prod", json: true, adoptionOnly: true }),
+    ).toThrow(/cannot be combined/);
+  });
+});
+
+describe("choudoufuLiveLsCommand (#2103)", () => {
+  test("carries -estate and -json", () => {
+    expect(choudoufuLiveLsCommand({ binary: "choudoufu", estate: "prod" })).toBe(
+      "choudoufu live-ls -estate=prod -json",
+    );
+  });
+
+  test("-consistent is opt-in", () => {
+    expect(choudoufuLiveLsCommand({ binary: "choudoufu", estate: "prod", consistent: true })).toBe(
+      "choudoufu live-ls -estate=prod -json -consistent",
+    );
+  });
+});
+
+describe("choudoufuLiveCheckCommand (#2103)", () => {
+  test("live-check -json, no DIR argument", () => {
+    expect(choudoufuLiveCheckCommand({ binary: "choudoufu" })).toBe("choudoufu live-check -json");
+  });
+});
+
+describe("countLivePlanUnowned (#2103)", () => {
+  test("counts unowned entries and the adoptable subset", () => {
+    const doc = {
+      unowned: [
+        { addr: "aws_vpc.a", adopt_tofu_estate: "prod", adopt_tofu_address: "aws_vpc.a" },
+        { addr: "aws_vpc.b" },
+        { addr: "aws_vpc.c", adopt_tofu_address: "aws_vpc.c" },
+      ],
+    };
+    expect(countLivePlanUnowned(doc)).toEqual({ unowned: 3, adoptable: 2 });
+  });
+
+  test("zero when the document has no unowned array", () => {
+    expect(countLivePlanUnowned({})).toEqual({ unowned: 0, adoptable: 0 });
+    expect(countLivePlanUnowned(null)).toEqual({ unowned: 0, adoptable: 0 });
+  });
+});
+
+describe("parseChoudoufuPlanSummary (#2106)", () => {
+  test("parses the ordinary Plan: N to add, N to change, N to destroy. line", () => {
+    expect(parseChoudoufuPlanSummary("Plan: 3 to add, 1 to change, 2 to destroy.\n")).toEqual({
+      adds: 3,
+      changes: 1,
+      destroys: 2,
+    });
+  });
+
+  test("parses the import-prefixed form", () => {
+    expect(parseChoudoufuPlanSummary("Plan: 4 to import, 1 to add, 1 to change, 2 to destroy.\n")).toEqual({
+      adds: 1,
+      changes: 1,
+      destroys: 2,
+    });
+  });
+
+  test("zero counts for No changes.", () => {
+    expect(parseChoudoufuPlanSummary("No changes. Your infrastructure still matches the configuration.\n")).toEqual({
+      adds: 0,
+      changes: 0,
+      destroys: 0,
+    });
+  });
+
+  test("zero counts for a shape it does not recognize", () => {
+    expect(parseChoudoufuPlanSummary("")).toEqual({ adds: 0, changes: 0, destroys: 0 });
+  });
+});
+
+describe("isOlderVersion / parseChoudoufuVersion (#2103)", () => {
+  test("compares major.minor.patch numerically", () => {
+    expect(isOlderVersion("0.12.9", "0.13.0")).toBe(true);
+    expect(isOlderVersion("0.13.0", "0.13.0")).toBe(false);
+    expect(isOlderVersion("0.13.1", "0.13.0")).toBe(false);
+    expect(isOlderVersion("1.0.0", "0.13.0")).toBe(false);
+  });
+
+  test("parses the release version out of the human `version` output", () => {
+    expect(parseChoudoufuVersion("choudoufu v0.13.0 (based on OpenTofu v1.13.0)\non darwin_arm64")).toBe("0.13.0");
+  });
+
+  test("undefined for a dev build with no release tag baked in", () => {
+    expect(parseChoudoufuVersion("OpenTofu v1.13.0-dev\non darwin_arm64")).toBeUndefined();
+  });
+});
+
+// ── The version check, wired into every activity via resolveRoot ───────────
+
+describe("choudoufu version check (#2103)", () => {
+  test("refuses a binary older than the floor, which the -json document moved to v0.14.0", async () => {
+    const dir = liveProject();
+    replies.push({ match: "version", reply: { stdout: "choudoufu v0.13.0 (based on OpenTofu v1.13.0)\n", stderr: "" } });
+    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).rejects.toThrow(/older than.*v0\.14\.0/);
+  });
+
+  test("passes at exactly the minimum version", async () => {
+    const dir = liveProject();
+    replies.push({
+      match: "version",
+      reply: { stdout: `choudoufu v${MIN_CHOUDOUFU_VERSION} (based on OpenTofu v1.13.0)\n`, stderr: "" },
+    });
+    replies.push({ match: "live-check", reply: { stdout: "{}", stderr: "" } });
+    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).resolves.toBeDefined();
+  });
+
+  test("runs once per module load, not once per activity call", async () => {
+    const dir = liveProject();
+    replies.push({
+      match: "version",
+      reply: { stdout: `choudoufu v${MIN_CHOUDOUFU_VERSION} (based on OpenTofu v1.13.0)\n`, stderr: "" },
+    });
+    replies.push({ match: "live-check", reply: { stdout: "{}", stderr: "" } });
+    await choudoufuLiveCheck({ root: "estate", cwd: dir });
+    await choudoufuLiveCheck({ root: "estate", cwd: dir });
+    const versionCalls = execCalls.filter((c) => c.cmd === "choudoufu version");
+    expect(versionCalls).toHaveLength(1);
+  });
+
+  test("a dev build with no parsable release version is never refused", async () => {
+    const dir = liveProject();
+    replies.push({ match: "version", reply: { stdout: "OpenTofu v1.13.0-dev\non darwin_arm64\n", stderr: "" } });
+    replies.push({ match: "live-check", reply: { stdout: "{}", stderr: "" } });
+    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).resolves.toBeDefined();
+  });
+});
+
+// ── terraformApply on a live root ───────────────────────────────────────────
+
+describe("terraformApply on a live root (#2106 follow-up)", () => {
+  /** The version reply every activity call needs before it reaches the apply. */
+  function atMinimumVersion(): void {
+    replies.push({
+      match: "version",
+      reply: { stdout: `choudoufu v${MIN_CHOUDOUFU_VERSION} (based on OpenTofu v1.13.0)\n`, stderr: "" },
+    });
+  }
+
+  test("applies the plan file, the same command a stock root runs", async () => {
+    const dir = liveProject();
+    atMinimumVersion();
+    const result = await terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" });
+    expect(commandsRun()).toEqual(["choudoufu apply -input=false chant.tfplan"]);
+    expect(result).toEqual({ planFile: "chant.tfplan", dir: resolve(dir, "estate"), applied: true });
+  });
+
+  test("exit 3 with the change-set refusal comes back as a named result, not a throw", async () => {
+    const dir = liveProject();
+    atMinimumVersion();
+    replies.push({
+      match: "apply",
+      reply: execError(3, `\nError: ${CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL}\n\n  null_resource.second  Create  -\n`),
+    });
+    const result = await terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" });
+    expect(result.applied).toBe(false);
+    expect(result.refused).toBe("approval-mismatch");
+    expect(result.refusal).toContain(CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL);
+    expect(result.planFile).toBe("chant.tfplan");
+  });
+
+  test("exit 3 with the estate refusal is the sibling named result", async () => {
+    const dir = liveProject();
+    atMinimumVersion();
+    replies.push({ match: "apply", reply: execError(3, `\nError: ${CHOUDOUFU_WRONG_ESTATE_REFUSAL}\n`) });
+    const result = await terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" });
+    expect(result.refused).toBe("wrong-estate");
+  });
+
+  test("exit 1 stays a failure, so an ordinary breakage is never routed to a reviewer", async () => {
+    const dir = liveProject();
+    atMinimumVersion();
+    replies.push({ match: "apply", reply: execError(1, "Error: no valid credential sources found") });
+    await expect(terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" })).rejects.toThrow(
+      /Command failed \(exit 1\)/,
+    );
+  });
+
+  test("exit 3 carrying neither refusal line stays a failure", async () => {
+    const dir = liveProject();
+    atMinimumVersion();
+    replies.push({ match: "apply", reply: execError(3, "Error: something nobody has named yet") });
+    await expect(terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" })).rejects.toThrow(
+      /Command failed \(exit 3\)/,
+    );
+  });
+
+  test("reads the estate from the sidecar just as well", async () => {
+    const dir = liveProject({ withSidecar: true });
+    atMinimumVersion();
+    await terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" });
+    expect(commandsRun()).toEqual(["choudoufu apply -input=false chant.tfplan"]);
+  });
+
+  test("a missing plan file is refused on a live root too", async () => {
+    const dir = liveProject();
+    atMinimumVersion();
+    await expect(terraformApply({ root: "estate", cwd: dir })).rejects.toThrow(/planFile is required/);
+    expect(commandsRun()).toEqual([]);
+  });
+
+  test("a choudoufu root with no live declaration reads exit 3 as an ordinary failure", async () => {
+    const dir = liveProject({ withLiveBlock: false });
+    atMinimumVersion();
+    replies.push({ match: "apply", reply: execError(3, `\nError: ${CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL}\n`) });
+    await expect(terraformApply({ root: "estate", cwd: dir, planFile: "chant.tfplan" })).rejects.toThrow(
+      /Command failed \(exit 3\)/,
+    );
+  });
+});
+
+// ── choudoufuLivePlan ────────────────────────────────────────────────────────
+
+describe("choudoufuLivePlan (#2103)", () => {
+  const DOC = JSON.stringify({
+    estate: "prod-networking",
+    bound: [],
+    omissions: [],
+    unowned: [{ addr: "aws_vpc.solo", adopt_tofu_address: "aws_vpc.solo" }],
+  });
+
+  test("exit 0: no drift, the document is captured and written, the human plan comes from a second call", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: DOC, stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "No changes.\n", stderr: "" } });
+
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+    expect(result.drift).toBe(false);
+    expect(result.estate).toBe("prod-networking");
+    expect(result.json).toEqual(JSON.parse(DOC));
+    expect(result.text).toBe("No changes.\n");
+    expect(result.unowned).toBe(1);
+    expect(result.adoptable).toBe(1);
+    expect(result.documentPath).toBe(DEFAULT_LIVE_PLAN_DOCUMENT_FILE);
+    expect(result.adds).toBe(0);
+    expect(result.changes).toBe(0);
+    expect(result.destroys).toBe(0);
+
+    const written = readFileSync(join(result.dir, DEFAULT_LIVE_PLAN_DOCUMENT_FILE), "utf-8");
+    expect(JSON.parse(written)).toEqual(JSON.parse(DOC));
+
+    // The root names its own estate, so neither call carries `-estate`:
+    // choudoufu refuses the flag beside a declaration, and since v0.14.0 it
+    // reads the declared name itself (choudoufu #894, PR 915).
+    expect(commandsRun()).toEqual([
+      "choudoufu live-plan -detailed-exitcode -json",
+      "choudoufu live-plan -detailed-exitcode -no-color",
+    ]);
+  });
+
+  test("exit 2: drift, and the document is still captured", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: execError(2, "", DOC) });
+    replies.push({
+      match: "live-plan -detailed-exitcode -no-color",
+      reply: { stdout: "Plan: 2 to add, 0 to change, 1 to destroy.\n", stderr: "" },
+    });
+
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+    expect(result.drift).toBe(true);
+    expect(result.json).toEqual(JSON.parse(DOC));
+    // Parsed off the human render's own summary line, not off the document
+    // (#788's JSON carries no resource-change diff of its own — see
+    // ChoudoufuLivePlanResult's doc comment).
+    expect(result.adds).toBe(2);
+    expect(result.changes).toBe(0);
+    expect(result.destroys).toBe(1);
+  });
+
+  test("exit 1: throws with choudoufu's stderr attached", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: execError(1, "Error: something refused") });
+    await expect(choudoufuLivePlan({ root: "estate", cwd: dir })).rejects.toThrow(
+      /live-plan failed.*exit 1[\s\S]*something refused/,
+    );
+  });
+
+  test("a root declaring no estate carries the caller's as -estate", async () => {
+    const dir = liveProject({ withLiveBlock: false });
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: DOC, stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "", stderr: "" } });
+    await choudoufuLivePlan({ root: "estate", cwd: dir, estate: "other-estate" });
+    expect(commandsRun()[0]).toContain("-estate=other-estate");
+  });
+
+  // The declaration wins on the wire whatever the caller passes, because
+  // choudoufu refuses `-estate` beside one. The result still reports the
+  // estate the document names.
+  test("a root that declares its own estate emits no -estate, even when one is passed", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: DOC, stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "", stderr: "" } });
+    await choudoufuLivePlan({ root: "estate", cwd: dir, estate: "other-estate" });
+    expect(commandsRun().every((c) => !c.includes("-estate"))).toBe(true);
+  });
+
+  test("no estate anywhere: refused, and the plan itself never runs", async () => {
+    const dir = liveProject({ withLiveBlock: false });
+    await expect(choudoufuLivePlan({ root: "estate", cwd: dir })).rejects.toThrow(/no estate to run against/);
+    expect(commandsRun()).toHaveLength(0);
+  });
+});
+
+// ── choudoufuLivePlan's adoption ledger (#2105) ──────────────────────────────
+
+describe("choudoufuLivePlan adoption ledger (#2105)", () => {
+  const ADOPTABLE = JSON.stringify({
+    estate: "prod-networking",
+    bound: [{ addr: "aws_subnet.app", identity: "subnet-99" }],
+    omissions: [],
+    unowned: [
+      {
+        addr: "aws_vpc.main",
+        type: "aws_vpc",
+        identity: "vpc-0abc",
+        adopt_tofu_estate: "prod-networking",
+        adopt_tofu_address: "aws_vpc.main",
+      },
+    ],
+  });
+
+  const LEDGER_RENDER = [
+    "Adoptable now: 1 resource instance",
+    "",
+    "  aws_vpc.main <- aws_vpc vpc-0abc",
+    "      adopt with: aws ec2 create-tags --resources 'vpc-0abc' --tags 'Key=tofu-estate,Value=prod-networking'",
+    "      or write: tofu-estate=prod-networking tofu-address=aws_vpc.main",
+    "",
+  ].join("\n");
+
+  test("every run projects the document into a ledger, adoptions and contested", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
+    replies.push({
+      match: "live-plan -detailed-exitcode -no-color",
+      reply: { stdout: "Plan: 1 to add.\n", stderr: "" },
+    });
+
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+    expect(result.adoptions.map((c) => c.addr)).toEqual(["aws_vpc.main"]);
+    expect(result.contested).toEqual([]);
+    expect(result.ambiguous).toBe(0);
+    expect(result.ledger).toContain(
+      "  aws_vpc.main <- aws_vpc vpc-0abc  write: tofu-estate=prod-networking tofu-address=aws_vpc.main",
+    );
+  });
+
+  test("`finding` is the plan text and then the ledger, and carries no JSON", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
+    replies.push({
+      match: "live-plan -detailed-exitcode -no-color",
+      reply: { stdout: "Plan: 1 to add.\n", stderr: "" },
+    });
+
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+    expect(result.finding.startsWith("Plan: 1 to add.")).toBe(true);
+    expect(result.finding).toContain("Adoptable now: 1 live resource");
+    // The document's bound section names a resource the ledger has no reason
+    // to mention; if any of the JSON leaked into `finding`, this is where.
+    expect(result.finding).not.toContain("subnet-99");
+    expect(result.finding).not.toContain("adopt_tofu_address");
+  });
+
+  test("adoptionOnly renders the human half as choudoufu's ledger and reads its commands", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
+    replies.push({ match: "-adoption-only", reply: { stdout: LEDGER_RENDER, stderr: "" } });
+
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir, adoptionOnly: true });
+    expect(commandsRun()).toEqual([
+      "choudoufu live-plan -detailed-exitcode -json",
+      "choudoufu live-plan -detailed-exitcode -adoption-only -no-color",
+    ]);
+    expect(result.adoptions[0].command).toBe(
+      "aws ec2 create-tags --resources 'vpc-0abc' --tags 'Key=tofu-estate,Value=prod-networking'",
+    );
+  });
+
+  test("without adoptionOnly a candidate carries the marker values and no command", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "", stderr: "" } });
+
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+    expect(result.adoptions[0].command).toBeUndefined();
+    expect(result.adoptions[0].markerAddress).toBe("aws_vpc.main");
+  });
+});
+
+// ── choudoufuAdopt (#2105) ───────────────────────────────────────────────────
+
+describe("choudoufuAdopt (#2105)", () => {
+  const candidate = (addr: string, identity: string, command?: string) => ({
+    addr,
+    type: "aws_vpc",
+    identity,
+    markerEstate: "prod-networking",
+    markerAddress: addr,
+    ...(command ? { command } : {}),
+  });
+
+  test("runs each candidate's own tagging command, in the root directory", async () => {
+    const dir = liveProject();
+    const result = await choudoufuAdopt({
+      root: "estate",
+      cwd: dir,
+      adoptions: [
+        candidate("aws_vpc.main", "vpc-0abc", "aws ec2 create-tags --resources 'vpc-0abc'"),
+        candidate("aws_subnet.app", "subnet-01", "aws ec2 create-tags --resources 'subnet-01'"),
+      ],
+    });
+    expect(result.mechanism).toBe("tag-write");
+    expect(result.adopted).toEqual(["aws_vpc.main", "aws_subnet.app"]);
+    expect(result.adoptedCount).toBe(2);
+    expect(commandsRun()).toEqual([
+      "aws ec2 create-tags --resources 'vpc-0abc'",
+      "aws ec2 create-tags --resources 'subnet-01'",
+    ]);
+    expect(
+      execCalls.filter((c) => c.cmd !== "choudoufu version").every((c) => c.opts.cwd === resolve(dir, "estate")),
+    ).toBe(true);
+  });
+
+  test("a candidate with no printed command is refused, naming both marker values", async () => {
+    const dir = liveProject();
+    const result = await choudoufuAdopt({
+      root: "estate",
+      cwd: dir,
+      adoptions: [candidate("aws_iam_role.app", "app-role")],
+    });
+    expect(result.adopted).toEqual([]);
+    expect(result.refused).toHaveLength(1);
+    expect(result.refused[0].reason).toContain("tofu-estate=prod-networking");
+    expect(result.refused[0].reason).toContain("tofu-address=aws_iam_role.app");
+    expect(commandsRun()).toEqual([]);
+  });
+
+  test("a contested candidate is reported and never written", async () => {
+    const dir = liveProject();
+    const result = await choudoufuAdopt({
+      root: "estate",
+      cwd: dir,
+      adoptions: [],
+      contested: [
+        candidate("aws_vpc.main", "vpc-0abc", "aws ec2 create-tags --resources 'vpc-0abc'"),
+        candidate("aws_vpc.main", "vpc-0def", "aws ec2 create-tags --resources 'vpc-0def'"),
+      ],
+    });
+    expect(result.adopted).toEqual([]);
+    expect(result.ambiguous).toBe(1);
+    expect(result.refused.map((r) => r.identity)).toEqual(["vpc-0abc", "vpc-0def"]);
+    expect(result.refused[0].reason).toContain("more than one live resource");
+    // A contested candidate carries a command; running it anyway is the whole
+    // thing this refuses to do.
+    expect(commandsRun()).toEqual([]);
+  });
+
+  test("nothing to adopt runs nothing and fails nothing", async () => {
+    const dir = liveProject();
+    const result = await choudoufuAdopt({ root: "estate", cwd: dir, adoptions: [] });
+    expect(result).toMatchObject({ adopted: [], adoptedCount: 0, refused: [], ambiguous: 0 });
+    expect(commandsRun()).toEqual([]);
+  });
+});
+
+// ── choudoufuLiveLs ──────────────────────────────────────────────────────────
+
+describe("choudoufuLiveLs (#2103)", () => {
+  test("lists the estate as JSON", async () => {
+    const dir = liveProject();
+    const listing = JSON.stringify([{ arn: "arn:aws:ec2:...:vpc/vpc-1", type: "aws_vpc", address: "aws_vpc.main" }]);
+    replies.push({ match: "live-ls", reply: { stdout: listing, stderr: "" } });
+
+    const result = await choudoufuLiveLs({ root: "estate", cwd: dir });
+    expect(result.estate).toBe("prod-networking");
+    expect(result.json).toEqual(JSON.parse(listing));
+    expect(commandsRun()).toEqual(["choudoufu live-ls -estate=prod-networking -json"]);
+  });
+
+  test("-consistent is forwarded", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-ls", reply: { stdout: "[]", stderr: "" } });
+    await choudoufuLiveLs({ root: "estate", cwd: dir, consistent: true });
+    expect(commandsRun()[0]).toContain("-consistent");
+  });
+});
+
+// ── choudoufuLiveCheck ───────────────────────────────────────────────────────
+
+describe("choudoufuLiveCheck (#2103)", () => {
+  test("exit 0: not refused", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-check", reply: { stdout: '{"instances":[]}', stderr: "" } });
+    const result = await choudoufuLiveCheck({ root: "estate", cwd: dir });
+    expect(result.refused).toBe(false);
+    expect(result.json).toEqual({ instances: [] });
+    expect(commandsRun()).toEqual(["choudoufu live-check -json"]);
+  });
+
+  test("non-zero exit: refused, not thrown, and the output is still captured", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-check", reply: execError(1, "", '{"instances":[{"refused":true}]}') });
+    const result = await choudoufuLiveCheck({ root: "estate", cwd: dir });
+    expect(result.refused).toBe(true);
+    expect(result.json).toEqual({ instances: [{ refused: true }] });
+  });
+
+  test("runs with no estate at all: live-check needs none", async () => {
+    const dir = liveProject({ withLiveBlock: false });
+    replies.push({ match: "live-check", reply: { stdout: "{}", stderr: "" } });
+    const result = await choudoufuLiveCheck({ root: "estate", cwd: dir });
+    expect(result.refused).toBe(false);
+  });
+});
+
+// Defensive, and no longer describing a live defect: choudoufu v0.14.0 keeps
+// `-json` stdout to the document, so the slice is the identity on every
+// supported binary. These cases pin the behaviour that makes keeping it cheap:
+// a stray writer ahead of the document costs a slice rather than a parse
+// failure, and a stdout with no document at all still reaches `JSON.parse`
+// with its real text.
+describe("liveDocumentFrom (defensive, choudoufu #894 fixed in v0.14.0)", () => {
+  test("skips any line that precedes the document, if a writer ever puts one there", async () => {
+    const { liveDocumentFrom } = await import("./terraform");
+    const stdout = 'aws_vpc.main: Refreshing state... [id=vpc-1]\naws_subnet.a: Refreshing state...\n{\n  "bound": []\n}\n';
+    expect(JSON.parse(liveDocumentFrom(stdout))).toEqual({ bound: [] });
+  });
+  test("returns a clean document unchanged", async () => {
+    const { liveDocumentFrom } = await import("./terraform");
+    expect(liveDocumentFrom('{\n  "bound": []\n}\n')).toBe('{\n  "bound": []\n}\n');
+  });
+  test("returns the input unchanged when no line opens a document, so JSON.parse reports the real text", async () => {
+    const { liveDocumentFrom } = await import("./terraform");
+    expect(liveDocumentFrom("Error: boom\n")).toBe("Error: boom\n");
+  });
+});