@intentius/chant-lexicon-terraform 0.124.51 → 0.124.54

package/src/op/activities/terraform.ts

@@ -45,12 +45,14 @@ import { tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { resolve, dirname, join, relative, sep } from "node:path";
 import { loadChantConfigUpward } from "@intentius/chant/config";
+import { findWorkspaceRoot } from "@intentius/chant/project-root";
 import { liveReadKey, memoLiveRead } from "@intentius/chant/live-read-session";
 import { terraformPlanDigest } from "../../plan-digest";
 import { choudoufuSetPlanParts, plannerForBinary, terraformChangeSetPart } from "../../change-set";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
 import type { TerraformConfig, TerraformRootConfig } from "../../config";
 import { detectLiveEstate } from "./live-detect";
+import { backendConfigValues } from "../../backend-config";
 import {
   parseAdoptionCommands,
   readAdoptionLedger,
@@ -116,6 +118,36 @@ export const MIN_CHOUDOUFU_VERSION = "0.15.0";
  */
 export const MIN_CHOUDOUFU_WAVES_VERSION = "0.22.0";
 
+/**
+ * The choudoufu release a composed run of estates needs (#4445): a root with
+ * no `live` block that calls estate directories as modules, planned and
+ * applied as one walk, with a `terraform_estate_outputs` read of another
+ * estate in the run answered inside it (choudoufu#2059, first released in
+ * v0.31.0). Only the composed estate run (`compose/estate.ts`) checks it;
+ * below it the members plan wave by wave. A dev build names no release and
+ * passes, as for the other floors.
+ */
+export const MIN_CHOUDOUFU_ESTATES_VERSION = "0.31.0";
+
+/**
+ * The choudoufu release whose `live-graph -json -from-plan=<file>` prints the
+ * engine graph document (chant#4520's design section 4, choudoufu#2285), the
+ * one `describeResources()` reads engine facts from on a live root
+ * (chant#4528). choudoufu's changelog lists the command under
+ * `v0.32.0 (Unreleased)`, so this is the version it releases as. The chant
+ * side of the same contract, the first chant that writes those facts, is
+ * `ENGINE_FACTS_FLOOR` in core's engine-facts.ts, which is NEXT_RELEASE
+ * until the cut.
+ *
+ * Not a refusal. Facts are for people and never feed a decision, so a
+ * choudoufu without the command (a usage error, see
+ * {@link classifyLiveGraphFailure}) leaves `facts` absent with one note
+ * naming this version, and the rest of the read is unchanged. The check is
+ * the capability, not the version string: a local or dev build names a
+ * version below this or none at all, and still carries the command.
+ */
+export const MIN_CHOUDOUFU_GRAPH_VERSION = "0.32.0";
+
 /**
  * Where a choudoufu root's wave files live, relative to the project root:
  * `<root>/plan-set.json` (the set plan document chant planned and the
@@ -191,6 +223,14 @@ export interface TerraformPlanArgs extends TerraformRootArgs {
    * of that file changes nothing else.
    */
   targets?: string[];
+  /**
+   * `false` skips `show -no-color`, the human-readable render (#4479). The
+   * plan then runs one `show` process, `show -json`, whose document gives the
+   * digest, the change set and everything a caller derives from `json`, and
+   * {@link TerraformPlanResult.text} is `""`. For a caller that never reads
+   * the text, such as the `terraform-apply` capability. Default: `true`.
+   */
+  text?: boolean;
 }
 
 export interface TerraformApplyArgs extends TerraformRootArgs {
@@ -280,6 +320,13 @@ export interface TerraformInitResult {
   dir: string;
   /** Workspace the run selected via `TF_WORKSPACE`, when the root names one. */
   workspace?: string;
+  /**
+   * The root module directory relative to the chant workspace root, with `/`
+   * separators (chant#4482), when the root sits inside a workspace. A
+   * TerraformApplyOp publishes it as the `TerraformRootPath` run outcome, so a
+   * ledger read can name the member whose directory holds the root it applied.
+   */
+  rootPath?: string;
 }
 
 /** Counts projected out of a plan's `resource_changes`. */
@@ -304,7 +351,7 @@ export interface TerraformPlanResult extends PlanChangeCounts {
   dir: string;
   /** `terraform show -json <planFile>`, parsed. */
   json: unknown;
-  /** `terraform show -no-color <planFile>` — the human-readable plan. */
+  /** `terraform show -no-color <planFile>` — the human-readable plan. `""` when the plan ran with `text: false`. */
   text: string;
   /**
    * This plan's identity (#2300) — {@link terraformPlanDigest} over
@@ -537,19 +584,24 @@ export function terraformEnvironment(root?: Pick<TerraformRootConfig, "workspace
   };
 }
 
-/** `terraform init`, with the root's `backendConfig` as `-backend-config=k=v` flags. */
+/**
+ * `terraform init`, with the root's `backendConfigFiles` as
+ * `-backend-config=<path>` flags and then its `backendConfig` as
+ * `-backend-config=k=v` flags (chant#4459): init applies later flags over
+ * earlier ones, so a pair overrides a file. A path is passed as written; init
+ * runs in the root's directory, which a relative one resolves against.
+ */
 export function terraformInitCommand(opts: {
   binary: string;
   backendConfig?: Record<string, string>;
+  backendConfigFiles?: readonly string[];
   upgrade?: boolean;
   reconfigure?: boolean;
 }): string {
   const parts = [opts.binary, "init", "-input=false"];
   if (opts.upgrade) parts.push("-upgrade");
   if (opts.reconfigure) parts.push("-reconfigure");
-  for (const [key, value] of Object.entries(opts.backendConfig ?? {})) {
-    parts.push(`-backend-config=${quoteArg(`${key}=${value}`)}`);
-  }
+  for (const value of backendConfigValues(opts)) parts.push(`-backend-config=${quoteArg(value)}`);
   return parts.join(" ");
 }
 
@@ -629,6 +681,37 @@ export function choudoufuLivePlanCommand(opts: {
   return parts.join(" ");
 }
 
+/**
+ * `live-graph -json -from-plan=<file> [-estate=<estate>]` (choudoufu#2285).
+ * No `DIR` argument: like {@link choudoufuLiveCheckCommand}, the activity
+ * runs in the root directory, which is DIR's default. `-estate` follows
+ * {@link choudoufuLivePlanCommand}'s rule: only for a root that does not
+ * name its own estate. `-history` is never passed: record versions take a
+ * listing per record and `s3:ListBucketVersions`, and an observation read
+ * has no use for them (the #4520 ruling, Q6: opt-in).
+ */
+export function choudoufuLiveGraphCommand(opts: { binary: string; fromPlan: string; estate?: string }): string {
+  const parts = [opts.binary, "live-graph", "-json", `-from-plan=${quoteArg(opts.fromPlan)}`];
+  if (opts.estate !== undefined) parts.push(`-estate=${quoteArg(opts.estate)}`);
+  return parts.join(" ");
+}
+
+/**
+ * Whether a failed `live-graph` run is a choudoufu that has no such command
+ * or flag (`"unsupported"`), or a real failure (`"failed"`). Older builds
+ * answer an unknown command two ways: the new CLI prints `OpenTofu has no
+ * command named "live-graph"` and exits 1 (cmd/choudoufu/command_main.go),
+ * and the older mitchellh/cli path prints its usage and exits 127. A build
+ * whose `live-graph` predates `-from-plan` fails the flag parse with `flag
+ * provided but not defined`.
+ */
+export function classifyLiveGraphFailure(code: unknown, output: string): "unsupported" | "failed" {
+  if (code === 127) return "unsupported";
+  if (/no command named "?live-graph"?/i.test(output)) return "unsupported";
+  if (/flag provided but not defined: -(?:from-plan|json|estate)\b/.test(output)) return "unsupported";
+  return "failed";
+}
+
 /** `live-ls -estate=<estate> -json [-consistent]`. */
 export function choudoufuLiveLsCommand(opts: { binary: string; estate: string; consistent?: boolean }): string {
   const parts = [opts.binary, "live-ls", `-estate=${quoteArg(opts.estate)}`, "-json"];
@@ -917,8 +1000,8 @@ function report(stdout: string, stderr: string): void {
 // ── Activities ──────────────────────────────────────────────────────────────
 
 /**
- * `terraform init` in the named root, with the root's `backendConfig` supplied
- * as `-backend-config` flags. Uses the longInfra profile: init downloads
+ * `terraform init` in the named root, with the root's `backendConfigFiles` and
+ * `backendConfig` supplied as `-backend-config` flags. Uses the longInfra profile: init downloads
  * providers and modules, a network call of unpredictable size.
  */
 export async function terraformInit(
@@ -929,19 +1012,55 @@ export async function terraformInit(
   const cmd = terraformInitCommand({
     binary,
     ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+    ...(root.backendConfigFiles ? { backendConfigFiles: root.backendConfigFiles } : {}),
     ...(args.upgrade ? { upgrade: true } : {}),
     ...(args.reconfigure ? { reconfigure: true } : {}),
   });
 
-  const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);
-  report(stdout, stderr);
+  // Known once the root resolves, before init runs (chant#4512), so a failed
+  // init still publishes them and the ledger names the root it was for.
+  const rootPath = workspaceRelativePath(dir);
+  const result: TerraformInitResult = { dir, ...(root.workspace ? { workspace: root.workspace } : {}), ...(rootPath !== undefined ? { rootPath } : {}) };
+
+  let out: { stdout: string; stderr: string };
+  try {
+    out = await run(cmd, dir, terraformEnvironment(root), signal);
+  } catch (err) {
+    throw withKnownOutputs(err, result);
+  }
+  report(out.stdout, out.stderr);
+  return result;
+}
+
+/**
+ * `err` carrying `outputs` as the outputs the activity knew when it failed
+ * (chant#4512): the `knownOutputs` property core's executor reads a failed
+ * step's outcome attributes from (core's `withKnownOutputs`). It is set here
+ * rather than imported so the lexicon needs no newer core; an older executor
+ * reads the error as any other failure.
+ */
+function withKnownOutputs(err: unknown, outputs: object): Error {
+  const e = err instanceof Error ? err : new Error(String(err));
+  return Object.assign(e, { knownOutputs: outputs });
+}
 
-  return { dir, ...(root.workspace ? { workspace: root.workspace } : {}) };
+/**
+ * `dir` relative to the chant workspace that holds it, `/`-separated, or
+ * undefined outside a workspace or outside its root (chant#4482). The
+ * workspace root `"."` stands for itself.
+ */
+export function workspaceRelativePath(dir: string): string | undefined {
+  const found = findWorkspaceRoot(dir);
+  if (!found) return undefined;
+  const rel = relative(found.dir, dir);
+  if (rel.startsWith("..")) return undefined;
+  return rel === "" ? "." : rel.split(sep).join("/");
 }
 
 /**
  * `terraform plan -detailed-exitcode -out=<planFile>` in the named root, then
- * `terraform show` over the written plan in both `-json` and `-no-color` form.
+ * `terraform show` over the written plan in both `-json` and `-no-color` form
+ * (`-json` alone with `text: false`).
  *
  * The exit code is the answer, not an error condition: 0 is a plan with no
  * changes, 2 is a plan with changes, and anything else, 1 included, is a
@@ -989,7 +1108,7 @@ export async function terraformPlan(
   }
 
   const jsonRun = await run(terraformShowCommand({ binary, json: true, planFile }), dir, env, signal);
-  const textRun = await run(terraformShowCommand({ binary, json: false, planFile }), dir, env, signal);
+  const text = args.text === false ? "" : (await run(terraformShowCommand({ binary, json: false, planFile }), dir, env, signal)).stdout;
   const json: unknown = JSON.parse(jsonRun.stdout);
 
   return {
@@ -997,7 +1116,7 @@ export async function terraformPlan(
     planFile,
     dir,
     json,
-    text: textRun.stdout,
+    text,
     planDigest: terraformPlanDigest(json),
     changeSet: terraformChangeSetPart({
       member: args.root,
@@ -1092,7 +1211,11 @@ export async function terraformOutputs(
   args: TerraformRootArgs,
   signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
-  const { binary, root, dir } = await resolveRoot(args, signal);
+  return outputsIn(await resolveRoot(args, signal), signal);
+}
+
+/** `<binary> output -json` in a resolved root, as `{ name: value }`. */
+async function outputsIn({ binary, root, dir }: ResolvedRoot, signal?: AbortSignal): Promise<Record<string, unknown>> {
   const { stdout } = await run(`${binary} output -json`, dir, terraformEnvironment(root), signal);
   const parsed = JSON.parse(stdout || "{}") as Record<string, { value?: unknown }>;
   return Object.fromEntries(Object.entries(parsed).map(([name, entry]) => [name, entry?.value]));
@@ -1174,7 +1297,7 @@ export async function choudoufuWaveRoot(
   if (resolved.root.varFiles && resolved.root.varFiles.length > 0) {
     return { wave: false, reason: "the root has var files, which live-plan-set does not take" };
   }
-  if (resolved.root.backendConfig && Object.keys(resolved.root.backendConfig).length > 0) {
+  if ((resolved.root.backendConfig && Object.keys(resolved.root.backendConfig).length > 0) || (resolved.root.backendConfigFiles?.length ?? 0) > 0) {
     return { wave: false, reason: "the root has backend config, which live-plan-set does not take" };
   }
   const root = choudoufuSetRootPath(resolved.projectRoot, resolved.dir);
@@ -1275,13 +1398,17 @@ export interface ChoudoufuPlanSetResult extends ChoudoufuPlanSet {
  * `live-wave-apply` hands back to choudoufu with the set digest.
  */
 export async function choudoufuPlanSet(args: TerraformRootArgs, signal?: AbortSignal): Promise<ChoudoufuPlanSetResult> {
-  const resolved = await resolveRoot(args, signal);
+  return planSetIn(await resolveRoot(args, signal), args.root, signal);
+}
+
+/** {@link choudoufuPlanSet} over a resolved root, `key` naming it in errors, in the waves directory and as the change-set member. */
+async function planSetIn(resolved: ResolvedRoot, key: string, signal?: AbortSignal): Promise<ChoudoufuPlanSetResult> {
   const { binary, root, dir, projectRoot } = resolved;
-  if (binary !== "choudoufu") throw new Error(`choudoufuPlanSet: root "${args.root}" runs ${binary}, not choudoufu`);
+  if (binary !== "choudoufu") throw new Error(`choudoufuPlanSet: root "${key}" runs ${binary}, not choudoufu`);
   await ensureChoudoufuWavesVersion(binary, signal);
   const rootPath = choudoufuSetRootPath(projectRoot, dir);
-  if (rootPath === undefined) throw new Error(`choudoufuPlanSet: root "${args.root}" (${dir}) is not inside ${projectRoot}`);
-  const wavesDir = choudoufuWavesDir(projectRoot, args.root);
+  if (rootPath === undefined) throw new Error(`choudoufuPlanSet: root "${key}" (${dir}) is not inside ${projectRoot}`);
+  const wavesDir = choudoufuWavesDir(projectRoot, key);
   mkdirSync(wavesDir, { recursive: true });
   const cmd = choudoufuPlanSetCommand({ binary, root: rootPath, outDir: fromProject(projectRoot, join(wavesDir, "out")) });
 
@@ -1299,12 +1426,64 @@ export async function choudoufuPlanSet(args: TerraformRootArgs, signal?: AbortSi
     stdout = failure.stdout ?? "";
   }
 
-  const parsed = parseChoudoufuPlanSet(stdout, { member: args.root, root: rootPath });
+  const parsed = parseChoudoufuPlanSet(stdout, { member: key, root: rootPath });
   const planSetFile = join(wavesDir, "plan-set.json");
   writeFileSync(planSetFile, stdout);
   return { ...parsed, planSetFile, root: rootPath };
 }
 
+// ── A choudoufu workspace member's outputs (#4455) ─────────────────────────
+
+/**
+ * A choudoufu member of the workspace, as `member-outputs` names it: not a
+ * `terraform.roots` entry of the reading project but a directory the
+ * workspace declaration gives. Its binary is `choudoufu`, it has no var
+ * files, workspace or backend config, and it runs from `projectRoot`, a
+ * directory above it (the workspace root), since `live-plan-set` plans only
+ * roots inside the directory it runs in.
+ */
+export interface ChoudoufuMemberArgs {
+  /** The member's name: the waves directory's name, and the plan's member in errors. */
+  member: string;
+  /** The member's directory, absolute. */
+  dir: string;
+  /** Where `live-plan-set` runs from, absolute: a directory above `dir`. */
+  projectRoot: string;
+}
+
+async function resolveMemberRoot(args: ChoudoufuMemberArgs, signal?: AbortSignal): Promise<ResolvedRoot> {
+  const binary = "choudoufu";
+  await ensureChoudoufuVersion(binary, signal);
+  const dir = resolve(args.dir);
+  const estate = detectLiveEstate(dir);
+  return { binary, root: { dir }, dir, ...(estate !== undefined ? { estate } : {}), live: estate !== undefined, projectRoot: resolve(args.projectRoot) };
+}
+
+/**
+ * The member's outputs as applied (#4455): `choudoufu init`, then `choudoufu
+ * output -json` in its directory, the read the `terraform-apply` capability's
+ * `outputs` makes for a root. A live estate's outputs come from its record
+ * store.
+ */
+export async function choudoufuMemberOutputs(args: ChoudoufuMemberArgs, signal?: AbortSignal): Promise<Record<string, unknown>> {
+  const resolved = await resolveMemberRoot(args, signal);
+  const { stdout, stderr } = await run(terraformInitCommand({ binary: resolved.binary }), resolved.dir, terraformEnvironment(resolved.root), signal);
+  report(stdout, stderr);
+  return outputsIn(resolved, signal);
+}
+
+/**
+ * The member planned as a one-root set (#4455), the way a choudoufu root in
+ * a gated wave is ({@link choudoufuPlanSet}): `live-plan-set -json` from
+ * `projectRoot`. The document's embedded plan carries `planned_values` and
+ * `output_changes`, which say what the member's outputs will be.
+ */
+export async function choudoufuMemberPlanSet(args: ChoudoufuMemberArgs, signal?: AbortSignal): Promise<ChoudoufuPlanSetResult> {
+  const resolved = await resolveMemberRoot(args, signal);
+  if (!resolved.live) throw new Error(`choudoufu member "${args.member}" (${resolved.dir}) declares no live estate, so live-plan-set cannot plan it`);
+  return planSetIn(resolved, args.member, signal);
+}
+
 /**
  * What a choudoufu root keeps in the fan-out's attempt record (#3459):
  * choudoufu's resume file, under the set digest it was written for.
@@ -1514,10 +1693,11 @@ export function terraformPlanReadCommand(opts: { binary: string; planFile: strin
  * The one line a person runs to initialise a root chant refuses to plan,
  * with the root's `backendConfig` carried, so it can be pasted as printed.
  */
-export function terraformInitLine(opts: { binary: string; dir: string; backendConfig?: Record<string, string> }): string {
+export function terraformInitLine(opts: { binary: string; dir: string; backendConfig?: Record<string, string>; backendConfigFiles?: readonly string[] }): string {
   const init = terraformInitCommand({
     binary: opts.binary,
     ...(opts.backendConfig ? { backendConfig: opts.backendConfig } : {}),
+    ...(opts.backendConfigFiles ? { backendConfigFiles: opts.backendConfigFiles } : {}),
   });
   return init.replace(`${opts.binary} init`, `${opts.binary} -chdir=${quoteArg(opts.dir)} init`);
 }
@@ -1629,7 +1809,12 @@ export async function terraformPlanRead(
 ): Promise<TerraformPlanReadResult> {
   const { binary, root, dir } = await resolveRoot(args, signal);
   const env = terraformEnvironment(root);
-  const initLine = terraformInitLine({ binary, dir, ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}) });
+  const initLine = terraformInitLine({
+    binary,
+    dir,
+    ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+    ...(root.backendConfigFiles ? { backendConfigFiles: root.backendConfigFiles } : {}),
+  });
   const notInitialised = (detail: string): TerraformPlanReadError =>
     new TerraformPlanReadError(
       "not-initialised",
@@ -1912,6 +2097,65 @@ export async function choudoufuLivePlan(
   };
 }
 
+/** What {@link choudoufuLiveGraph} resolved. */
+export type ChoudoufuLiveGraphResult =
+  | {
+      /** choudoufu printed the engine graph document. */
+      supported: true;
+      /** The document, parsed: a GraphIR v1 with `meta.engineGraph` (chant#4527's schema). */
+      json: unknown;
+      /** Absolute path of the root module directory. */
+      dir: string;
+    }
+  | {
+      /** This choudoufu has no `live-graph -from-plan` (older than {@link MIN_CHOUDOUFU_GRAPH_VERSION}). */
+      supported: false;
+      /** choudoufu's own first line, for the note. */
+      detail: string;
+      dir: string;
+    };
+
+export interface ChoudoufuLiveGraphArgs extends TerraformRootArgs {
+  /** Absolute path of the `live-plan -json` document this graph takes its facts from. */
+  fromPlan: string;
+  /** The estate (`-estate`), for a root that does not declare its own. */
+  estate?: string;
+}
+
+/**
+ * `choudoufu live-graph -json -from-plan=<file>` (choudoufu#2285, read by
+ * chant#4528): the root's graph as one engine graph document, its facts taken
+ * from a `live-plan -json` document this process already read. No second live
+ * read: choudoufu builds the graph from the configuration and that file
+ * alone, starts no provider and calls no cloud, so facts and verdicts come
+ * from the same refresh (choudoufu #1014).
+ *
+ * A usage error ({@link classifyLiveGraphFailure}) resolves `supported:
+ * false` rather than throwing, since the caller degrades to no facts; any
+ * other failure throws with choudoufu's output. Warnings (an empty scope
+ * estate, a plan without `observed_at`) go to stderr and are echoed like
+ * every other activity's.
+ */
+export async function choudoufuLiveGraph(args: ChoudoufuLiveGraphArgs, signal?: AbortSignal): Promise<ChoudoufuLiveGraphResult> {
+  const resolved = await resolveRoot(args, signal);
+  const { binary, dir } = resolved;
+  const env = terraformEnvironment(resolved.root);
+  const estateFlag: { estate?: string } = resolved.estate === undefined && args.estate !== undefined ? { estate: args.estate } : {};
+  const cmd = choudoufuLiveGraphCommand({ binary, fromPlan: args.fromPlan, ...estateFlag });
+  try {
+    const { stdout, stderr } = await run(cmd, dir, env, signal);
+    if (stderr) console.error(stderr);
+    return { supported: true, json: JSON.parse(liveDocumentFrom(stdout)), dir };
+  } catch (err) {
+    const failure = err as ExecFailure;
+    if (typeof failure.code !== "number") throw err;
+    const output = `${failure.stderr ?? ""}\n${failure.stdout ?? ""}`;
+    const detail = output.trim().split("\n").find((line) => line.trim() !== "")?.trim() ?? `exit ${failure.code}`;
+    if (classifyLiveGraphFailure(failure.code, output) === "unsupported") return { supported: false, detail, dir };
+    throw new Error(`${binary} live-graph failed in ${dir} (exit ${failure.code})${detail ? `\n${output.trim()}` : ""}`);
+  }
+}
+
 /**
  * `choudoufu live-ls -estate=<estate> -json [-consistent]`: every resource
  * the account holds under the estate, read straight from the Resource Groups

package/src/op/activity-contracts.test.ts

@@ -23,6 +23,7 @@ const ACTIVITY_NAMES = [
   "choudoufuLiveLs",
   "choudoufuLiveCheck",
   "choudoufuAdopt",
+  "choudoufuPlanSet",
   "terraformPinRollout",
 ];
 

package/src/op/activity-contracts.ts

@@ -66,7 +66,8 @@ export const terraformInitContract = activityContract(
     upgrade: z.boolean().optional(),
     reconfigure: z.boolean().optional(),
   }),
-  z.object({ dir: z.string(), workspace: z.string().optional() }),
+  // `rootPath` (#4482) is what TerraformApplyOp's Init step publishes as `TerraformRootPath`; OPS012 checks it here.
+  z.object({ dir: z.string(), workspace: z.string().optional(), rootPath: z.string().optional() }),
   rootEntity,
 );
 
@@ -181,6 +182,28 @@ export const choudoufuAdoptContract = activityContract(
   rootEntity,
 );
 
+/**
+ * `choudoufuPlanSet` (#4483): one live choudoufu root planned as a one-root
+ * set. `changeSet` is the root's part, the field an Op hands to
+ * `composeChangeSet`; `planDigest` is what a gate binds; `planSetFile` and
+ * `setDigest` are what a later `live-wave-apply` takes.
+ */
+export const choudoufuPlanSetContract = activityContract(
+  "choudoufuPlanSet",
+  z.strictObject({ ...rootArgs }),
+  z.object({
+    setDigest: z.string(),
+    rootDigest: z.string(),
+    planDigest: z.string(),
+    changed: z.boolean(),
+    json: z.unknown(),
+    changeSet: z.object({ member: z.object({ member: z.string(), planDigest: z.string().nullable() }).passthrough(), entries: z.array(z.unknown()) }),
+    planSetFile: z.string(),
+    root: z.string(),
+  }),
+  rootEntity,
+);
+
 /** One root of a pin-bump rollout ({@link PinRoot} in `../pin/waves.ts`). */
 const pinRoot = z.strictObject({ root: z.string(), dependsOn: z.array(z.string()).optional(), tsSource: z.string().optional() });
 

package/src/op/builders.ts

@@ -31,6 +31,7 @@ import type {
   ChoudoufuLiveLsArgs,
   ChoudoufuLiveCheckArgs,
   ChoudoufuAdoptArgs,
+  TerraformRootArgs,
 } from "./activities/terraform";
 import type { TerraformPinRolloutArgs } from "./activities/pin-rollout";
 
@@ -186,6 +187,19 @@ export const terraformShow = (
   );
 };
 
+/**
+ * `choudoufuPlanSet` (#4483): `live-plan-set -json` over one live choudoufu
+ * root. Hand `step.out.changeSet` from each root's step to `composeChangeSet`
+ * to make one change-set document over several roots, such as one per cloud.
+ */
+export const choudoufuPlanSet = (
+  root: string,
+  opts?: WithStepRefs<Omit<TerraformRootArgs, "root">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("choudoufuPlanSet", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
 /**
  * One run of a pin-bump rollout (#3189). `opts` is
  * {@link TerraformPinRolloutArgs} itself. It names no root: the rollout finds

package/src/pin/bundle.test.ts

@@ -38,6 +38,8 @@ describe("the pin bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?(packages|lexicons)\//, "$1/")).sort()).toEqual([
+      // The one config-file lister (chant#4457): node built-ins only, kept apart from the HCL parser.
+      "lexicons/terraform/src/hcl/files.ts",
       "lexicons/terraform/src/pin/edit.ts",
       "lexicons/terraform/src/pin/forge.ts",
       "lexicons/terraform/src/pin/index.ts",

package/src/pin/edit.ts

@@ -24,6 +24,7 @@
 
 import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { movePin, type PinMove } from "./source";
+import { isJsonConfigFile, jsonConfigTree } from "../hcl/files";
 import { escapeHcl, scanBlocks, unescapeHcl, type ScannedAttribute, type ScannedBlock } from "./scan";
 
 /** What to move: a module, named by its source without the pin, from one pin to another. */
@@ -99,6 +100,7 @@ interface Splice {
  * is reported with its reason and left as it was.
  */
 export async function editPins(text: string, file: string, request: PinRequest, parser: Hcl2Json): Promise<PinEditResult> {
+  if (isJsonConfigFile(file)) return jsonPins(text, file, request);
   const terragrunt = isTerragruntFile(file);
   const tree = (await parser.parse(file, text)) as Tree;
   const blocks = scanBlocks(text, file);
@@ -155,3 +157,31 @@ export async function editPins(text: string, file: string, request: PinRequest,
 function rewriteLiteral(raw: string, was: string, value: string): string {
   return raw === was ? value : escapeHcl(value);
 }
+
+/**
+ * The calls of the module in a `.tf.json` or `.tofu.json` file (chant#4457).
+ * The pin edit splices HCL text and has no splice for JSON syntax, so a call
+ * that would move is refused by name and the file is left as it is; a call
+ * already at the new pin, or at another one, reads as it does in HCL.
+ */
+function jsonPins(text: string, file: string, request: PinRequest): PinEditResult {
+  const calls: PinCallResult[] = [];
+  let tree: Record<string, unknown>;
+  try {
+    tree = jsonConfigTree(text);
+  } catch (err) {
+    return { content: text, calls: [{ outcome: "refused", reason: `not JSON the binary reads: ${err instanceof Error ? err.message : String(err)}`, file, call: "(file)" }] };
+  }
+  const modules = (tree.module && typeof tree.module === "object" ? tree.module : {}) as Record<string, unknown>;
+  for (const [name, bodies] of Object.entries(modules)) {
+    for (const body of Array.isArray(bodies) ? (bodies as Record<string, unknown>[]) : []) {
+      if (typeof body.source !== "string") continue;
+      const move = movePin(body.source, typeof body.version === "string" ? body.version : undefined, request);
+      if (!move) continue;
+      const at = { file, call: `module.${name}` };
+      if (move.outcome === "moved") calls.push({ outcome: "refused", reason: "the call is in Terraform's JSON syntax, which the pin edit does not write; move its pin by hand", ...at });
+      else calls.push({ ...move, ...at });
+    }
+  }
+  return { content: text, calls };
+}

package/src/pin/rollout.ts

@@ -48,6 +48,7 @@ import { editPins, type PinCallResult, type PinEditResult, type PinRequest } fro
 import { checkPinRequest, moduleOf } from "./source";
 import { planPinWaves, restrictWaves, terragruntDependencies, type PinRoot, type PinWave } from "./waves";
 import { ghPinForge, type PinForge } from "./forge";
+import { isConfigFileFor, listConfigFilesSafe } from "../hcl/files";
 
 const execFileAsync = /* @__PURE__ */ promisify(execFile);
 
@@ -83,6 +84,8 @@ export interface PinRolloutOptions extends PinRequest {
   editTs?: TsPinEditor;
   /** Markdown appended to a wave's PR body, such as the grouped plan summary of #3188 once a caller has the wave's plans. */
   planSummary?: (wave: PinWave) => Promise<string | undefined>;
+  /** The binary the roots run: `tofu` or `choudoufu` reads `.tofu` files too (chant#4457). Default `terraform`. */
+  binary?: string;
 }
 
 /** Where one root's pin stood on the base branch. */
@@ -169,22 +172,24 @@ export function pinWaveBranch(request: PinRequest, wave: number): string {
   return `chant/pin/${slug(request.module)}/${slug(request.to)}/wave-${wave}`;
 }
 
-/** The files the pin edit reads in a root directory: its `.tf` files and its `terragrunt.hcl`. */
-function rootFiles(worktree: string, root: string): string[] {
+/**
+ * The files the pin edit reads in a root directory: the configuration files
+ * the root's binary reads (the lexicon's one lister, chant#4457) and its
+ * `terragrunt.hcl`.
+ */
+function rootFiles(worktree: string, root: string, binary?: string): string[] {
   const dir = join(worktree, root);
   if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((f) => f.endsWith(".tf") || f === "terragrunt.hcl")
-    .sort()
-    .map((f) => posix.join(root, f));
+  const names = [...listConfigFilesSafe(dir, binary), ...(existsSync(join(dir, "terragrunt.hcl")) ? ["terragrunt.hcl"] : [])];
+  return names.sort().map((f) => posix.join(root, f));
 }
 
-/** Every directory under the worktree with a `.tf` file or a `terragrunt.hcl`. */
-function candidateRoots(worktree: string): string[] {
+/** Every directory under the worktree with a configuration file the binary reads, or a `terragrunt.hcl`. */
+function candidateRoots(worktree: string, binary?: string): string[] {
   const out: string[] = [];
   const walk = (rel: string) => {
     const entries = readdirSync(join(worktree, rel), { withFileTypes: true });
-    if (entries.some((e) => e.isFile() && (e.name.endsWith(".tf") || e.name === "terragrunt.hcl"))) out.push(rel || ".");
+    if (entries.some((e) => e.isFile() && (isConfigFileFor(e.name, binary) || e.name === "terragrunt.hcl"))) out.push(rel || ".");
     for (const e of entries) if (e.isDirectory() && !SKIP_DIRS.has(e.name)) walk(rel ? posix.join(rel, e.name) : e.name);
   };
   walk("");
@@ -201,7 +206,7 @@ async function editRoot(worktree: string, root: PinRoot, request: PinRequest, op
       return { state: { root: root.root, state: "refused", files, calls, reason: `generated from ${root.tsSource}, and this caller has no TypeScript editor` }, edits };
     }
   } else {
-    files = rootFiles(worktree, root.root);
+    files = rootFiles(worktree, root.root, options.binary);
   }
   for (const file of files) {
     const path = join(worktree, file);
@@ -302,7 +307,7 @@ export async function runPinRollout(options: PinRolloutOptions): Promise<PinRoll
   await run("git", ["worktree", "add", "--quiet", "--detach", worktree, baseRef], repo);
   try {
     // 1. Every root's pin on the base branch.
-    const declared = (options.roots ?? candidateRoots(worktree).map((root): PinRoot => ({ root }))).map((r) => ({
+    const declared = (options.roots ?? candidateRoots(worktree, options.binary).map((root): PinRoot => ({ root }))).map((r) => ({
       ...r,
       root: dirOf(r.root),
       ...(r.dependsOn ? { dependsOn: r.dependsOn.map(dirOf) } : {}),