@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/op/adoption.ts

@@ -0,0 +1,241 @@
+/**
+ * The adoption ledger: which live resources this estate's markers can claim,
+ * read off `live-plan -json`'s document and rendered as text (#2105).
+ *
+ * Pure. No filesystem, no child process, no HCL parse — everything here is a
+ * projection of GitHub issue #788's `unowned` section, which is the one place
+ * choudoufu states both halves of the answer: the live resource sitting at a
+ * declared instance's identity, and the `tofu-estate`/`tofu-address` pair that
+ * would adopt it. Two tags is the whole ownership contract (choudoufu's
+ * `live/MARKERS.md`), so those two values are the whole of what an adoption
+ * needs to know.
+ *
+ * ## Why chant renders a ledger at all
+ *
+ * choudoufu prints its own, under `live-plan -adoption-only`, and it is the
+ * better report for a human at a terminal: it counts the marker-carrying and
+ * the identity-by-declaration halves of the declared population separately and
+ * says why each unadoptable instance is unadoptable. But `-adoption-only` and
+ * `-json` are refused together (`internal/command/live_plan.go`: "this run
+ * cannot produce both reports at once"), and an Op that reports adoptables
+ * needs the machine-readable document anyway — for the counts it publishes as
+ * outcome attributes, and for the addresses an adoption step acts on. So the
+ * ledger below is rendered from the document that run already has, in the row
+ * form `-adoption-only` prints, rather than paying for a third live read.
+ *
+ * ## Ambiguity
+ *
+ * `unowned[]` is one entry per live resource, keyed by the declared instance
+ * whose identity found it, so two live resources at one declared identity are
+ * two entries carrying the same `addr`. That is the ambiguous case: no single
+ * tag write claims the address, and picking one of the two is a decision about
+ * the estate rather than something a tool infers. {@link readAdoptionLedger}
+ * separates those into `contested` and never lets them into `adoptions`, and
+ * `TerraformAdoptOp` passes the contested list to its Adopt step so the Op's
+ * result names what it refused as well as what it wrote.
+ */
+
+/** One live resource a marker write would bind to a declared instance. */
+export interface AdoptionCandidate {
+  /** The declared instance address whose identity found the live resource. */
+  addr: string;
+  /** The live resource's type, as choudoufu's `unowned[].type`. */
+  type: string;
+  /** The identity the live resource was read with — the handle a human, or a tagging call, needs. */
+  identity: string;
+  /** The `tofu-estate` value that adopts it. */
+  markerEstate: string;
+  /** The `tofu-address` value that adopts it, escaped as choudoufu stores it. */
+  markerAddress: string;
+  /**
+   * The paste-ready tagging command choudoufu printed for this address under
+   * `live-plan -adoption-only`, when it printed one. Absent for a type whose
+   * service has its own tagging call this fork does not spell out (IAM,
+   * Route53, S3 and friends): the two marker values above are still the whole
+   * contract, but the caller has to write them itself.
+   */
+  command?: string;
+}
+
+/** What {@link readAdoptionLedger} found in one `live-plan -json` document. */
+export interface AdoptionLedger {
+  /** Candidates at an address exactly one live resource sits at. The adoptable set. */
+  adoptions: AdoptionCandidate[];
+  /**
+   * Every candidate at an address more than one live resource sits at. Never
+   * adopted: reported so a human can delete one or write the marker by hand.
+   * Both (or all) candidates for a contested address appear, so the report
+   * shows what the choice is between.
+   */
+  contested: AdoptionCandidate[];
+  /** How many distinct declared addresses are contested. */
+  ambiguous: number;
+}
+
+/** `unowned[]`'s entry shape, per choudoufu's `views.StatelessUnowned` json tags. */
+interface UnownedEntry {
+  addr?: unknown;
+  type?: unknown;
+  identity?: unknown;
+  tofu_estate?: unknown;
+  adopt_tofu_estate?: unknown;
+  adopt_tofu_address?: unknown;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/**
+ * Project a `live-plan -json` document's `unowned` section into the adoptable
+ * and the contested sets.
+ *
+ * An entry counts as a candidate only when choudoufu offered both marker
+ * values. Both empty means adoption was not this run's to offer — the resource
+ * belongs to another estate (`tofu_estate` names it), or the run had no estate
+ * name of its own — and such an entry is neither adoptable nor contested here,
+ * because there is no tag write to refuse.
+ *
+ * `commands` maps a declared address to the paste-ready tagging command
+ * choudoufu printed for it, from {@link parseAdoptionCommands}; omit it when
+ * the run had no `-adoption-only` render to read one out of.
+ */
+export function readAdoptionLedger(document: unknown, commands?: ReadonlyMap<string, string>): AdoptionLedger {
+  const unowned = (document as { unowned?: unknown } | null | undefined)?.unowned;
+  if (!Array.isArray(unowned)) return { adoptions: [], contested: [], ambiguous: 0 };
+
+  const byAddr = new Map<string, AdoptionCandidate[]>();
+  for (const raw of unowned) {
+    const e = (raw ?? {}) as UnownedEntry;
+    const markerEstate = str(e.adopt_tofu_estate);
+    const markerAddress = str(e.adopt_tofu_address);
+    if (!markerEstate && !markerAddress) continue;
+    const addr = str(e.addr);
+    const command = commands?.get(addr);
+    const candidate: AdoptionCandidate = {
+      addr,
+      type: str(e.type),
+      identity: str(e.identity),
+      markerEstate,
+      markerAddress,
+      ...(command ? { command } : {}),
+    };
+    const at = byAddr.get(addr);
+    if (at) at.push(candidate);
+    else byAddr.set(addr, [candidate]);
+  }
+
+  const adoptions: AdoptionCandidate[] = [];
+  const contested: AdoptionCandidate[] = [];
+  let ambiguous = 0;
+  for (const candidates of byAddr.values()) {
+    if (candidates.length === 1) {
+      adoptions.push(candidates[0]);
+    } else {
+      ambiguous++;
+      contested.push(...candidates);
+    }
+  }
+  return { adoptions, contested, ambiguous };
+}
+
+/**
+ * Pair each declared address in a `live-plan -adoption-only` render with the
+ * tagging command choudoufu printed under it.
+ *
+ * The render's "Adoptable now" rows are `  <addr> <- <type> <identity>`
+ * followed by indented detail lines, one of which is `      adopt with: <cmd>`
+ * (`internal/command/views/live_adoption.go`). choudoufu builds that command
+ * to be pasted verbatim: every interpolated value is shell-quoted, the tagging
+ * verb comes from its own botocore-derived table rather than a guess, and the
+ * provider configuration's region and endpoint ride along as `--region` and
+ * `--endpoint-url`, so the write lands where the resource is rather than
+ * wherever an operator's AWS CLI profile points. Re-deriving any of that from
+ * the two marker values alone would be a worse command, so this reads the one
+ * choudoufu already wrote.
+ *
+ * An address the render offered no command for is simply absent from the map.
+ */
+export function parseAdoptionCommands(ledgerText: string): Map<string, string> {
+  const commands = new Map<string, string>();
+  let current: string | undefined;
+  for (const line of ledgerText.split("\n")) {
+    const row = /^ {2}(\S+) <- \S+ /.exec(line);
+    if (row) {
+      current = row[1];
+      continue;
+    }
+    const cmd = /^ {6}(?:or )?adopt with: (.+)$/.exec(line);
+    if (cmd && current) {
+      commands.set(current, cmd[1].trim());
+      continue;
+    }
+    // A blank line ends a row's detail block; a non-indented line ends the
+    // section. Either way the next "adopt with:" belongs to nobody until the
+    // next row line names an address.
+    if (line.trim() === "" || !line.startsWith("    ")) current = undefined;
+  }
+  return commands;
+}
+
+const plural = (n: number, one: string, many: string): string => (n === 1 ? one : many);
+
+/**
+ * Render {@link readAdoptionLedger}'s answer as the text an issue or PR body
+ * carries under the plan.
+ *
+ * One line per adoptable match, naming the declared address, the live resource
+ * it binds, and the two tag values that adopt it, in the token forms
+ * `-adoption-only` prints them in (`<addr> <- <type> <identity>`,
+ * `tofu-estate=`, `tofu-address=`). Contested addresses follow, listed and not
+ * offered. An empty ledger still renders a line: "nothing adoptable" is a
+ * result a reader wants, and a section that vanishes reads as one that was
+ * never computed.
+ */
+export function renderAdoptionLedger(ledger: AdoptionLedger, estate?: string): string {
+  const where = estate ? `, estate ${JSON.stringify(estate)}` : "";
+  const lines: string[] = [];
+
+  if (ledger.adoptions.length === 0) {
+    lines.push(`Adoptable now: nothing${where}`, "");
+    lines.push(
+      "No live resource sits at a declared identity carrying a marker this estate could write. " +
+        "Anything the plan proposes creating, it proposes creating for real.",
+    );
+  } else {
+    lines.push(
+      `Adoptable now: ${ledger.adoptions.length} live ${plural(ledger.adoptions.length, "resource", "resources")}${where}`,
+      "",
+    );
+    lines.push(
+      "Each line is a live resource found at a declared resource's identity, carrying no marker for " +
+        "this estate. Writing the two tags shown adopts it; nothing is bound until they are written, " +
+        "because ownership is the tofu-estate and tofu-address pair and nothing else.",
+      "",
+    );
+    for (const c of ledger.adoptions) {
+      lines.push(
+        `  ${c.addr} <- ${c.type} ${c.identity}  write: ` +
+          `tofu-estate=${c.markerEstate} tofu-address=${c.markerAddress}`,
+      );
+    }
+  }
+
+  if (ledger.contested.length > 0) {
+    lines.push("");
+    lines.push(
+      `Ambiguous: ${ledger.ambiguous} declared ${plural(ledger.ambiguous, "address", "addresses")} ` +
+        "with more than one candidate",
+      "",
+    );
+    lines.push(
+      "More than one live resource sits at each of these declared identities, so no single tag write " +
+        "claims the address. None of them is adopted. Resolve it by deleting the duplicate or by " +
+        "writing the marker onto the one you mean.",
+      "",
+    );
+    for (const c of ledger.contested) {
+      lines.push(`  ${c.addr} <- ${c.type} ${c.identity}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/op/builders.test.ts

@@ -7,7 +7,15 @@
 
 import { describe, test, expect } from "vitest";
 import { isStepOutputRef, type StepOutputRef } from "@intentius/chant/op";
-import { terraformInit, terraformPlan, terraformApply, terraformShow } from "./builders";
+import {
+  terraformInit,
+  terraformPlan,
+  terraformApply,
+  terraformShow,
+  choudoufuLivePlan,
+  choudoufuLiveLs,
+  choudoufuLiveCheck,
+} from "./builders";
 
 describe("terraform typed step builders (#2086)", () => {
   test("terraformInit: root is positional, longInfra by default", () => {
@@ -73,18 +81,65 @@ describe("terraform typed step builders (#2086)", () => {
   test(".out throws when the producing step has no id", () => {
     expect(() => terraformPlan("app").out.planFile).toThrow(/has no id/);
   });
+
+  test("terraformApply: no opts at all is valid (#2103, a live root's bare apply)", () => {
+    expect(terraformApply("estate")).toMatchObject({
+      fn: "terraformApply",
+      args: { root: "estate" },
+      profile: "longInfra",
+    });
+    expect(terraformApply("estate").args?.planFile).toBeUndefined();
+  });
+});
+
+describe("choudoufu typed step builders (#2103)", () => {
+  test("choudoufuLivePlan: root is positional, longInfra by default, estate is optional", () => {
+    expect(choudoufuLivePlan("estate")).toMatchObject({
+      kind: "activity",
+      fn: "choudoufuLivePlan",
+      args: { root: "estate" },
+      profile: "longInfra",
+    });
+    expect(choudoufuLivePlan("estate", { estate: "prod-networking" })).toMatchObject({
+      args: { root: "estate", estate: "prod-networking" },
+    });
+  });
+
+  test("choudoufuLivePlan: .out refs for drift, unowned, adoptable and documentPath", () => {
+    const plan = choudoufuLivePlan("estate", { id: "live-plan" });
+    expect(isStepOutputRef(plan.out.drift as StepOutputRef)).toBe(true);
+    expect((plan.out.unowned as StepOutputRef).path).toBe("unowned");
+    expect((plan.out.adoptable as StepOutputRef).path).toBe("adoptable");
+    expect((plan.out.documentPath as StepOutputRef).path).toBe("documentPath");
+  });
+
+  test("choudoufuLiveLs: fastIdempotent by default", () => {
+    expect(choudoufuLiveLs("estate", { consistent: true })).toMatchObject({
+      fn: "choudoufuLiveLs",
+      args: { root: "estate", consistent: true },
+      profile: "fastIdempotent",
+    });
+  });
+
+  test("choudoufuLiveCheck: fastIdempotent by default, no opts needed at all", () => {
+    expect(choudoufuLiveCheck("estate")).toMatchObject({
+      kind: "activity",
+      fn: "choudoufuLiveCheck",
+      args: { root: "estate" },
+      profile: "fastIdempotent",
+    });
+  });
 });
 
 // ── Compile-time-only: authoring-time type errors (never executed) ──────────
 function _typeChecksOnly(): void {
-  // @ts-expect-error — planFile is required on an apply: this activity has no
-  // bare-apply mode, so omitting it is a compile error, not a runtime one.
-  terraformApply("app");
-
   // @ts-expect-error — "planfile" (wrong case) is not a key of TerraformApplyArgs.
   terraformApply("app", { planfile: "chant.tfplan" });
 
   // @ts-expect-error — `root` is positional; it is not a member of opts.
   terraformInit("app", { root: "other" });
+
+  // @ts-expect-error: "estatee" (typo) is not a key of ChoudoufuLivePlanArgs.
+  choudoufuLivePlan("estate", { estatee: "prod" });
 }
 void _typeChecksOnly;

package/src/op/builders.ts

@@ -27,6 +27,10 @@ import type {
   TerraformPlanArgs,
   TerraformApplyArgs,
   TerraformShowArgs,
+  ChoudoufuLivePlanArgs,
+  ChoudoufuLiveLsArgs,
+  ChoudoufuLiveCheckArgs,
+  ChoudoufuAdoptArgs,
 } from "./activities/terraform";
 
 /** Extra opts every wrapper below accepts alongside its activity's own fields. */
@@ -63,20 +67,104 @@ export const terraformPlan = (
 };
 
 /**
- * `terraform apply <planFile>` in the named root — the fully typed twin of the
+ * `terraform apply <planFile>` in the named root, the fully typed twin of the
  * `terraformApply` activity. `opts` is {@link TerraformApplyArgs} itself,
- * minus the positional `root`, so `planFile` stays required at the call site
- * and the activity's bare-apply refusal is a compile error rather than a
- * runtime one. Defaults to the `longInfra` profile.
+ * minus the positional `root`. `planFile` is optional in the type and
+ * required in practice, on a live root as much as a stock one: the activity
+ * refuses a missing one, and on a live root the file is the approval artifact
+ * choudoufu v0.13.0 re-plans against and refuses on a mismatch (choudoufu
+ * #878). Defaults to the `longInfra` profile.
  */
 export const terraformApply = (
   root: string,
-  opts: WithStepRefs<Omit<TerraformApplyArgs, "root">> & StepOpts,
+  opts?: WithStepRefs<Omit<TerraformApplyArgs, "root">> & StepOpts,
 ): NamedActivityStep => {
   const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
   return activity("terraformApply", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
 };
 
+/**
+ * `choudoufu live-plan -detailed-exitcode -json -estate=<estate>` in the
+ * named root, plus the human render. The fully typed twin of the
+ * `choudoufuLivePlan` activity (#2103). `opts` is {@link ChoudoufuLivePlanArgs}
+ * itself, minus the positional `root`; `estate` is optional, auto-detected
+ * from the root's `live` block or `estate.chdf.hcl` sidecar when omitted.
+ * Defaults to the `longInfra` profile: like `terraformPlan`, this reads the
+ * live system in full (the estate-wide sweep).
+ *
+ * Give this step an `id` to read `.out.drift`, `.out.unowned`,
+ * `.out.adoptable` or `.out.documentPath` from a later step.
+ */
+export const choudoufuLivePlan = (
+  root: string,
+  opts?: WithStepRefs<Omit<ChoudoufuLivePlanArgs, "root">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity(
+    "choudoufuLivePlan",
+    { root, ...args },
+    { profile: profile ?? "longInfra", ...(id ? { id } : {}) },
+  );
+};
+
+/**
+ * `choudoufu live-ls -estate=<estate> -json [-consistent]` in the named root,
+ * the fully typed twin of the `choudoufuLiveLs` activity (#2103). `opts` is
+ * {@link ChoudoufuLiveLsArgs} itself, minus the positional `root`. Defaults to
+ * the `fastIdempotent` profile: `live-ls` reads a tagging-API listing and
+ * calls no other provider.
+ */
+export const choudoufuLiveLs = (
+  root: string,
+  opts?: WithStepRefs<Omit<ChoudoufuLiveLsArgs, "root">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity(
+    "choudoufuLiveLs",
+    { root, ...args },
+    { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) },
+  );
+};
+
+/**
+ * `choudoufu live-check -json` in the named root, the fully typed twin of the
+ * `choudoufuLiveCheck` activity (#2103). `opts` is {@link ChoudoufuLiveCheckArgs}
+ * itself, minus the positional `root`. Defaults to the `fastIdempotent`
+ * profile: no cloud calls, no state.
+ */
+export const choudoufuLiveCheck = (
+  root: string,
+  opts?: WithStepRefs<Omit<ChoudoufuLiveCheckArgs, "root">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity(
+    "choudoufuLiveCheck",
+    { root, ...args },
+    { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) },
+  );
+};
+
+/**
+ * Write the ownership markers that claim an adoption ledger's matches, in the
+ * named root. The fully typed twin of the `choudoufuAdopt` activity (#2105).
+ * `opts` is {@link ChoudoufuAdoptArgs} itself, minus the positional `root`, so
+ * `adoptions` is required at the call site — an adopt step with nothing to
+ * adopt is an authoring mistake, not a no-op worth defaulting to. Defaults to
+ * the `longInfra` profile: one tagging round trip per resource, against the
+ * cloud.
+ */
+export const choudoufuAdopt = (
+  root: string,
+  opts: WithStepRefs<Omit<ChoudoufuAdoptArgs, "root">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity(
+    "choudoufuAdopt",
+    { root, ...args },
+    { profile: profile ?? "longInfra", ...(id ? { id } : {}) },
+  );
+};
+
 /**
  * `terraform show` in the named root, over state or over a saved plan. `opts`
  * is {@link TerraformShowArgs} itself, minus the positional `root`. Defaults

package/src/op/resolve-root-mode.test.ts

@@ -0,0 +1,85 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { resolveRootModeSync } from "./resolve-root-mode";
+
+const dirs: string[] = [];
+
+function tempProject(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-tf-resolve-root-mode-"));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("resolveRootModeSync (#2106)", () => {
+  test("live: choudoufu binary and a declared estate", () => {
+    const project = tempProject();
+    mkdirSync(join(project, "root"), { recursive: true });
+    writeFileSync(
+      join(project, "root", "main.tf"),
+      ["terraform {", "  live {", '    estate = "fixture-estate"', "  }", "}", ""].join("\n"),
+    );
+    writeFileSync(
+      join(project, "chant.config.json"),
+      JSON.stringify({ terraform: { binary: "choudoufu", roots: { app: { dir: "./root" } } } }),
+    );
+    expect(resolveRootModeSync("app", project)).toEqual({ mode: "live", dir: join(project, "root") });
+  });
+
+  test("state: choudoufu binary but no declared estate", () => {
+    const project = tempProject();
+    mkdirSync(join(project, "root"), { recursive: true });
+    writeFileSync(join(project, "root", "main.tf"), 'resource "null_resource" "x" {}\n');
+    writeFileSync(
+      join(project, "chant.config.json"),
+      JSON.stringify({ terraform: { binary: "choudoufu", roots: { app: { dir: "./root" } } } }),
+    );
+    expect(resolveRootModeSync("app", project)).toEqual({ mode: "state", dir: join(project, "root") });
+  });
+
+  test("state: no binary declared at all, root dir need not even exist", () => {
+    const project = tempProject();
+    writeFileSync(join(project, "chant.config.json"), JSON.stringify({ terraform: { roots: { app: { dir: "./root" } } } }));
+    expect(resolveRootModeSync("app", project)).toEqual({ mode: "state", dir: join(project, "root") });
+  });
+
+  test("undefined: no chant.config.json findable from cwd", () => {
+    const project = tempProject();
+    expect(resolveRootModeSync("app", project)).toBeUndefined();
+  });
+
+  test("undefined: config found is chant.config.ts, not .json", () => {
+    const project = tempProject();
+    writeFileSync(join(project, "chant.config.ts"), "export default {} as const;\n");
+    expect(resolveRootModeSync("app", project)).toBeUndefined();
+  });
+
+  test("undefined: config exists but names no such root", () => {
+    const project = tempProject();
+    writeFileSync(
+      join(project, "chant.config.json"),
+      JSON.stringify({ terraform: { binary: "choudoufu", roots: { other: { dir: "./root" } } } }),
+    );
+    expect(resolveRootModeSync("app", project)).toBeUndefined();
+  });
+
+  test("undefined: choudoufu binary but the root directory does not exist", () => {
+    const project = tempProject();
+    writeFileSync(
+      join(project, "chant.config.json"),
+      JSON.stringify({ terraform: { binary: "choudoufu", roots: { app: { dir: "./missing" } } } }),
+    );
+    expect(resolveRootModeSync("app", project)).toBeUndefined();
+  });
+
+  test("defaults cwd to process.cwd() when omitted", () => {
+    // No assertion on the result (process.cwd() during a test run is
+    // unpredictable), only that it does not throw with no argument.
+    expect(() => resolveRootModeSync("app")).not.toThrow();
+  });
+});

package/src/op/resolve-root-mode.ts

@@ -0,0 +1,72 @@
+/**
+ * Best-effort, synchronous read of whether a named `terraform.roots` entry is
+ * live: `terraform.binary` is `"choudoufu"` and the root's directory declares
+ * an estate — a `live { }` block or an `estate.chdf.hcl` sidecar (#2103).
+ *
+ * Two callers decide something at build time, before any activity runs, and
+ * neither can afford the async work `../op/activities/terraform.ts`'s own
+ * `resolveRoot` does (`loadChantConfigUpward`, a full `chant.config.ts`/`.json`
+ * walk):
+ *
+ *   - `TerraformApplyOp` (`../composites/terraform-apply-op.ts`) decides which
+ *     phase shape to build — a stock plan-file pairing or a live re-plan-at-
+ *     apply shape — before any step is emitted.
+ *   - TF101 (`../lint/rules/plan-before-apply.ts`) decides whether a
+ *     `terraformApply` call it is statically inspecting is exempt from the
+ *     plan-file pairing it otherwise enforces.
+ *
+ * Both run in the build process (`chant build`/`chant lint`) rather than in
+ * an activity at run time, so a synchronous read is available, but only the
+ * cheap half of it: `findProjectConfig` (`@intentius/chant/project-root`) is a plain, already-
+ * synchronous upward filesystem walk, but a `chant.config.ts` is project-
+ * authored code, and evaluating it synchronously outside chant's own
+ * config-sandbox machinery is more than either caller's best-effort question
+ * is worth. So this reads `chant.config.json` only; a project on a `.ts`
+ * config, or with no config discoverable at all, or naming no matching root,
+ * resolves to `undefined` — "unknown" reads as "stock" to both callers, which
+ * is the conservative direction: TF101 keeps firing, and the composite keeps
+ * building the plan-file-carrying shape.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { findProjectConfig } from "@intentius/chant/project-root";
+import type { TerraformConfig } from "../config";
+import { detectLiveEstate } from "./activities/live-detect";
+
+export interface ResolvedRootMode {
+  /** `"live"` when `terraform.binary` is `"choudoufu"` and the root declares an estate; `"state"` otherwise. */
+  mode: "live" | "state";
+  /** The root module directory, resolved to an absolute path. */
+  dir: string;
+}
+
+/**
+ * Resolve `rootName`'s mode against the nearest `chant.config.json` found by
+ * walking up from `cwd` (default `process.cwd()`, matching every other
+ * `cwd`-defaulting option in this lexicon). `undefined` when that cannot be
+ * done with a plain, synchronous read: no config found, the config found is
+ * `chant.config.ts`, the config declares no such root, or the root's
+ * directory does not exist.
+ */
+export function resolveRootModeSync(rootName: string, cwd?: string): ResolvedRootMode | undefined {
+  const { dir: projectRoot, configPath } = findProjectConfig(resolve(cwd ?? process.cwd()));
+  if (!configPath || !configPath.endsWith(".json")) return undefined;
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return undefined;
+  }
+
+  const terraform = (raw as { terraform?: TerraformConfig } | null)?.terraform;
+  const root = terraform?.roots?.[rootName];
+  if (!terraform || !root || typeof root.dir !== "string") return undefined;
+
+  const dir = resolve(projectRoot, root.dir);
+  if (terraform.binary !== "choudoufu") return { mode: "state", dir };
+  if (!existsSync(dir)) return undefined;
+
+  return { mode: detectLiveEstate(dir) !== undefined ? "live" : "state", dir };
+}