@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/op/activities/terraform.js

@@ -44,10 +44,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.js";
 import { choudoufuSetPlanParts, plannerForBinary, terraformChangeSetPart } from "../../change-set.js";
 import { detectLiveEstate } from "./live-detect.js";
+import { backendConfigValues } from "../../backend-config.js";
+import { lockTimeoutArgs } from "../../lock-timeout.js";
+import { coneArgs, readPlanCone } from "../../cone.js";
 import { parseAdoptionCommands, readAdoptionLedger, renderAdoptionLedger, } from "../adoption.js";
 const execAsync = promisify(exec);
 /**
@@ -100,6 +104,34 @@ export const MIN_CHOUDOUFU_VERSION = "0.15.0";
  * choudoufu#1754, and {@link choudoufuPlanSet} refuses it.
  */
 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
@@ -151,16 +183,21 @@ export function terraformEnvironment(root) {
         ...(root?.workspace ? { TF_WORKSPACE: root.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) {
     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(" ");
 }
 /**
@@ -172,6 +209,8 @@ export function terraformPlanCommand(opts) {
     const parts = [opts.binary, "plan", "-input=false", "-detailed-exitcode"];
     if (opts.destroy)
         parts.push("-destroy");
+    for (const flag of opts.extra ?? [])
+        parts.push(quoteArg(flag));
     for (const target of [...new Set(opts.targets ?? [])].sort())
         parts.push(`-target=${quoteArg(target)}`);
     for (const varFile of opts.varFiles ?? [])
@@ -191,7 +230,8 @@ export function terraformPlanCommand(opts) {
  * own `apply <planfile>` does, so no `-auto-approve` is needed or passed.
  */
 export function terraformApplyCommand(opts) {
-    return `${opts.binary} apply -input=false ${quoteArg(opts.planFile)}`;
+    const extra = (opts.extra ?? []).map((f) => ` ${quoteArg(f)}`).join("");
+    return `${opts.binary} apply -input=false${extra} ${quoteArg(opts.planFile)}`;
 }
 /**
  * `live-plan -detailed-exitcode [-json] [-estate=<estate>]`. `-json` is what
@@ -229,6 +269,39 @@ export function choudoufuLivePlanCommand(opts) {
         parts.push(`-estate=${quoteArg(opts.estate)}`);
     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) {
+    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, output) {
+    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) {
     const parts = [opts.binary, "live-ls", `-estate=${quoteArg(opts.estate)}`, "-json"];
@@ -428,7 +501,7 @@ async function resolveRoot(args, signal) {
             (known.length > 0 ? `known roots: ${known.join(", ")}` : "the namespace declares no roots"));
     }
     const binary = terraformBinary(namespace);
-    const dir = resolve(projectRoot, root.dir);
+    const dir = resolve(projectRoot, args.dir ?? root.dir);
     await ensureChoudoufuVersion(binary, signal);
     const estate = binary === "choudoufu" ? detectLiveEstate(dir) : undefined;
     // `estate` stays what it has always been: the estate the root's own HCL
@@ -477,8 +550,8 @@ function report(stdout, stderr) {
 }
 // ── 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(args, signal) {
@@ -486,16 +559,53 @@ export async function terraformInit(args, signal) {
     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);
-    return { dir, ...(root.workspace ? { workspace: root.workspace } : {}) };
+    // 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 = { dir, ...(root.workspace ? { workspace: root.workspace } : {}), ...(rootPath !== undefined ? { rootPath } : {}) };
+    let out;
+    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, outputs) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    return Object.assign(e, { knownOutputs: outputs });
+}
+/**
+ * `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) {
+    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
@@ -507,9 +617,13 @@ export async function terraformInit(args, signal) {
  * provider.
  */
 export async function terraformPlan(args, signal) {
-    const { binary, root, dir } = await resolveRoot(args, signal);
+    const { binary, root, dir, live } = await resolveRoot(args, signal);
     const planFile = args.planFile ?? DEFAULT_PLAN_FILE;
     const env = terraformEnvironment(root);
+    const lock = args.lockTimeout !== undefined ? lockTimeoutArgs("plan", args.lockTimeout) : [];
+    // #4545: a cone only on a live root that is not an estate file; -target and -destroy plan in full.
+    const fixed = [...(args.destroy ? ["-destroy"] : []), ...((args.targets ?? []).length > 0 ? ["-target"] : [])];
+    const cone = args.cone !== undefined ? coneArgs(binary, args.cone, fixed, live && !existsSync(join(dir, "estate.chdf.hcl"))) : [];
     const cmd = terraformPlanCommand({
         binary,
         planFile,
@@ -517,11 +631,14 @@ export async function terraformPlan(args, signal) {
         ...(args.vars ? { vars: args.vars } : {}),
         ...(args.destroy ? { destroy: true } : {}),
         ...(args.targets && args.targets.length > 0 ? { targets: args.targets } : {}),
+        ...(cone.length + lock.length > 0 ? { extra: [...cone, ...lock] } : {}),
     });
     let changed;
+    let output = "";
     try {
         const { stdout, stderr } = await run(cmd, dir, env, signal);
         report(stdout, stderr);
+        output = `${stdout}\n${stderr}`;
         changed = false;
     }
     catch (err) {
@@ -535,17 +652,18 @@ export async function terraformPlan(args, signal) {
             throw new Error(`${binary} plan failed in ${dir} (exit ${failure.code})${detail ? `\n${detail}` : ""}`);
         }
         report(failure.stdout ?? "", failure.stderr ?? "");
+        output = `${failure.stdout ?? ""}\n${failure.stderr ?? ""}`;
         changed = true;
     }
     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 = JSON.parse(jsonRun.stdout);
     return {
         changed,
         planFile,
         dir,
         json,
-        text: textRun.stdout,
+        text,
         planDigest: terraformPlanDigest(json),
         changeSet: terraformChangeSetPart({
             member: args.root,
@@ -554,6 +672,7 @@ export async function terraformPlan(args, signal) {
             ...((root.estate ?? root.workspace) ? { scope: root.estate ?? root.workspace } : {}),
         }),
         ...countPlanChanges(json),
+        ...(cone.length > 0 ? { cone: readPlanCone(output, join(dir, planFile), args.cone) } : {}),
     };
 }
 /**
@@ -598,7 +717,8 @@ export async function terraformApply(args, signal) {
             "Pass the Plan step's own output (`plan.out.planFile`).");
     }
     const planFile = args.planFile;
-    const cmd = terraformApplyCommand({ binary, planFile });
+    const lock = args.lockTimeout !== undefined ? lockTimeoutArgs("apply", args.lockTimeout) : [];
+    const cmd = terraformApplyCommand({ binary, planFile, ...(lock.length > 0 ? { extra: lock } : {}) });
     try {
         const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);
         report(stdout, stderr);
@@ -629,7 +749,10 @@ export async function terraformApply(args, signal) {
  * asked for the values to hand them on.
  */
 export async function terraformOutputs(args, signal) {
-    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 }, signal) {
     const { stdout } = await run(`${binary} output -json`, dir, terraformEnvironment(root), signal);
     const parsed = JSON.parse(stdout || "{}");
     return Object.fromEntries(Object.entries(parsed).map(([name, entry]) => [name, entry?.value]));
@@ -694,7 +817,7 @@ export async function choudoufuWaveRoot(args, signal) {
     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);
@@ -764,15 +887,18 @@ function fromProject(projectRoot, path) {
  * `live-wave-apply` hands back to choudoufu with the set digest.
  */
 export async function choudoufuPlanSet(args, signal) {
-    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, key, signal) {
     const { binary, root, dir, projectRoot } = resolved;
     if (binary !== "choudoufu")
-        throw new Error(`choudoufuPlanSet: root "${args.root}" runs ${binary}, not 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);
+        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")) });
     let stdout;
@@ -790,11 +916,42 @@ export async function choudoufuPlanSet(args, signal) {
         report("", failure.stderr ?? "");
         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 };
 }
+async function resolveMemberRoot(args, signal) {
+    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, signal) {
+    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, signal) {
+    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);
+}
 /**
  * The resume file to hand choudoufu for `setDigest`, from what an earlier
  * attempt carried, or `undefined`. choudoufu refuses a resume file written
@@ -958,6 +1115,7 @@ export function terraformInitLine(opts) {
     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`);
 }
@@ -1019,7 +1177,12 @@ export function rootIsInitialised(dir, env = process.env) {
 export async function terraformPlanRead(args, signal) {
     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) => new TerraformPlanReadError("not-initialised", `terraform.roots.${args.root} (${dir}) ${detail}: run \`${initLine}\` first. chant never runs init on a read, since init writes into the root.`, dir, initLine);
     if (!rootIsInitialised(dir, { ...process.env, ...env }))
         throw notInitialised("has never been initialised");
@@ -1255,6 +1418,43 @@ export async function choudoufuLivePlan(args, signal) {
         ...parseChoudoufuPlanSummary(text),
     };
 }
+/**
+ * `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, signal) {
+    const resolved = await resolveRoot(args, signal);
+    const { binary, dir } = resolved;
+    const env = terraformEnvironment(resolved.root);
+    const estateFlag = 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;
+        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/dist/op/activity-contracts.d.ts

@@ -37,6 +37,7 @@ export declare const terraformInitContract: import("@intentius/chant/op").Activi
 }, {
     dir: string;
     workspace?: string | undefined;
+    rootPath?: string | undefined;
 }>;
 export declare const terraformPlanContract: import("@intentius/chant/op").ActivityContract<{
     root: string;
@@ -155,6 +156,32 @@ export declare const choudoufuAdoptContract: import("@intentius/chant/op").Activ
     ambiguous: number;
     dir: string;
 }>;
+/**
+ * `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 declare const choudoufuPlanSetContract: import("@intentius/chant/op").ActivityContract<{
+    root: string;
+    cwd?: string | undefined;
+}, {
+    setDigest: string;
+    rootDigest: string;
+    planDigest: string;
+    changed: boolean;
+    json: unknown;
+    changeSet: {
+        member: {
+            [x: string]: unknown;
+            member: string;
+            planDigest: string | null;
+        };
+        entries: unknown[];
+    };
+    planSetFile: string;
+    root: string;
+}>;
 /**
  * `terraformPinRollout` (#3189). It names no `terraform.roots` key: a rollout
  * moves a module's pin across many roots, found by directory, so it carries no

package/dist/op/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+BH,eAAO,MAAM,qBAAqB;;;;;;;;EASjC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;EAoBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;EAWlC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;EAYjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;EASnC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;EAKtC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;EAgBlC,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BvC,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+BH,eAAO,MAAM,qBAAqB;;;;;;;;;EAUjC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;EAoBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;EAWlC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;EAYjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;EASnC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;EAKtC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;EAgBlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAcpC,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BvC,CAAC"}

package/dist/op/activity-contracts.js

@@ -57,7 +57,9 @@ export const terraformInitContract = activityContract("terraformInit", z.strictO
     ...rootArgs,
     upgrade: z.boolean().optional(),
     reconfigure: z.boolean().optional(),
-}), z.object({ dir: z.string(), workspace: z.string().optional() }), rootEntity);
+}), 
+// `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);
 export const terraformPlanContract = activityContract("terraformPlan", z.strictObject({
     ...rootArgs,
     planFile: z.string().optional(),
@@ -127,6 +129,22 @@ export const choudoufuAdoptContract = activityContract("choudoufuAdopt", z.stric
     ambiguous: z.number(),
     dir: z.string(),
 }), 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/dist/op/builders.d.ts

@@ -15,7 +15,7 @@
  * path a second time.
  */
 import { type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
-import type { TerraformInitArgs, TerraformPlanArgs, TerraformApplyArgs, TerraformShowArgs, ChoudoufuLivePlanArgs, ChoudoufuLiveLsArgs, ChoudoufuLiveCheckArgs, ChoudoufuAdoptArgs } from "./activities/terraform.js";
+import type { TerraformInitArgs, TerraformPlanArgs, TerraformApplyArgs, TerraformShowArgs, ChoudoufuLivePlanArgs, ChoudoufuLiveLsArgs, ChoudoufuLiveCheckArgs, ChoudoufuAdoptArgs, TerraformRootArgs } from "./activities/terraform.js";
 import type { TerraformPinRolloutArgs } from "./activities/pin-rollout.js";
 /** Extra opts every wrapper below accepts alongside its activity's own fields. */
 type StepOpts = {
@@ -95,6 +95,12 @@ export declare const choudoufuAdopt: (root: string, opts: WithStepRefs<Omit<Chou
  * provider.
  */
 export declare const terraformShow: (root: string, opts?: WithStepRefs<Omit<TerraformShowArgs, "root">> & StepOpts) => NamedActivityStep;
+/**
+ * `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 declare const choudoufuPlanSet: (root: string, opts?: WithStepRefs<Omit<TerraformRootArgs, "root">> & StepOpts) => NamedActivityStep;
 /**
  * One run of a pin-bump rollout (#3189). `opts` is
  * {@link TerraformPinRolloutArgs} itself. It names no root: the rollout finds

package/dist/op/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,kFAAkF;AAClF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC/D,iBAGF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,SACtB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAClE,iBAOF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,SACpB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAChE,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SACvB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KACnE,iBAOF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,QACN,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,SAAU,YAAY,CAAC,uBAAuB,CAAC,GAAG,QAAQ,KAAG,iBAG5F,CAAC"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,kFAAkF;AAClF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC/D,iBAGF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,SACtB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAClE,iBAOF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,SACpB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAChE,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SACvB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KACnE,iBAOF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,QACN,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,SACrB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,SAAU,YAAY,CAAC,uBAAuB,CAAC,GAAG,QAAQ,KAAG,iBAG5F,CAAC"}

package/dist/op/builders.js

@@ -112,6 +112,15 @@ export const terraformShow = (root, opts) => {
     const { args, profile, id } = takeProfileAndId(opts);
     return activity("terraformShow", { root, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
 };
+/**
+ * `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, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    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/dist/pin/consumers.d.ts

@@ -0,0 +1,35 @@
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { normalizeModuleSource, PUBLIC_REGISTRY_HOST } from "../registry/source-forms.js";
+import { type ModuleCallPin } from "./source.js";
+export { normalizeModuleSource, PUBLIC_REGISTRY_HOST };
+/** One module call in a consuming repo. */
+export interface ModuleConsumer {
+    /** The root (or Terragrunt unit) directory, from the repo's top, `/`-separated. */
+    root: string;
+    /** The file holding the call, from the repo's top. */
+    file: string;
+    /** The block: `module.<name>`, or `terragrunt.terraform` for a unit's source. */
+    address: string;
+    /** `terraform` for a module block, `terragrunt` for a unit's `terraform { source }`. */
+    kind: "terraform" | "terragrunt";
+    /** The `source` as written. */
+    source: string;
+    /** The module the call names: the source with the pin taken out, normalised. */
+    module: string;
+    /** The pinned version, tag, digest or ref, or null when the call pins none. */
+    pin: string | null;
+    /** Where the pin is, as `readModulePin` reads it. */
+    at: ModuleCallPin["at"];
+    param?: ModuleCallPin["param"];
+    /** Why there is no pin, when `pin` is null. */
+    unpinned?: string;
+}
+/** A source names a local directory, not a published module. */
+export declare function isLocalSource(source: string): boolean;
+/**
+ * Every module call in `roots` (directories from `repo`), sorted by root,
+ * file and address. A root whose files cannot be parsed throws, naming the
+ * root, so a check job fails loudly instead of listing fewer consumers.
+ */
+export declare function moduleConsumers(repo: string, roots: readonly string[], parser?: Hcl2Json): Promise<ModuleConsumer[]>;
+//# sourceMappingURL=consumers.d.ts.map

package/dist/pin/consumers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumers.d.ts","sourceRoot":"","sources":["../../src/pin/consumers.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAEpE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAE7D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAEvD,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,EAAE,WAAW,GAAG,YAAY,CAAC;IACjC,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,qDAAqD;IACrD,EAAE,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAMD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAgC1H"}