@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/dist/changed-roots.js

@@ -9,14 +9,17 @@
  * in a local module it calls (followed through modules that call modules),
  * or is one of its var files.
  *
- * The module calls are read with a regex over the root's `.tf` and `.tofu`
+ * The module calls are read with a regex over the root's HCL configuration
  * files, the way `./op/activities/live-detect.ts` reads a live block, so
- * this stays out of the HCL parser's dependency graph. Only a `source` that
+ * this stays out of the HCL parser's dependency graph. Which files those are
+ * follows the root's binary through the lexicon's one lister (chant#4457):
+ * `.tf`, plus `.tofu` for a tofu or choudoufu root. Only a `source` that
  * starts with `./` or `../` is followed; a registry or git source is a
  * version pin in the root's own files, which a change to it already touches.
  */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, posix, relative, resolve, sep } from "node:path";
+import { isJsonConfigFile, listConfigFilesSafe } from "./hcl/files.js";
 /** `source = "./..."` or `"../..."` inside a module block. Other sources are not on disk here. */
 const LOCAL_SOURCE = /\bsource\s*=\s*"(\.{1,2}\/[^"]*)"/g;
 const toPosix = (p) => p.split(sep).join("/");
@@ -25,18 +28,11 @@ function projectRelative(projectRoot, dir) {
     const rel = toPosix(relative(projectRoot, dir));
     return rel === "" ? "." : posix.normalize(rel).replace(/\/+$/, "");
 }
-/** Local module directories `dir` calls, read from its HCL files. */
-function localModuleDirs(dir) {
-    let names;
-    try {
-        names = readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
+/** Local module directories `dir` calls, read from the HCL configuration files `binary` reads. */
+function localModuleDirs(dir, binary) {
     const out = [];
-    for (const name of names) {
-        if (!name.endsWith(".tf") && !name.endsWith(".tofu"))
+    for (const name of listConfigFilesSafe(dir, binary)) {
+        if (isJsonConfigFile(name))
             continue;
         let text;
         try {
@@ -58,7 +54,7 @@ function localModuleDirs(dir) {
  * Every path, relative to `projectRoot`, whose change touches `root`: its
  * directory, each local module it reaches, and its var files.
  */
-export function rootWatchPaths(projectRoot, root) {
+export function rootWatchPaths(projectRoot, root, binary) {
     const rootDir = resolve(projectRoot, root.dir);
     const seen = new Set();
     const queue = [rootDir];
@@ -67,7 +63,7 @@ export function rootWatchPaths(projectRoot, root) {
         if (seen.has(dir))
             continue;
         seen.add(dir);
-        queue.push(...localModuleDirs(dir));
+        queue.push(...localModuleDirs(dir, binary));
     }
     const paths = [...seen].map((d) => projectRelative(projectRoot, d));
     for (const file of root.varFiles ?? [])
@@ -85,11 +81,11 @@ function covers(path, file) {
  * sorted. `changedFiles` are relative to `projectRoot` with `/` separators,
  * as `git diff --name-only --relative` prints them.
  */
-export function changedRoots(projectRoot, roots, changedFiles) {
+export function changedRoots(projectRoot, roots, changedFiles, binary) {
     const files = changedFiles.map((f) => posix.normalize(f));
     const touched = [];
     for (const [name, root] of Object.entries(roots)) {
-        const watch = rootWatchPaths(projectRoot, root);
+        const watch = rootWatchPaths(projectRoot, root, binary);
         if (files.some((f) => watch.some((p) => covers(p, f))))
             touched.push(name);
     }

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,oCAAoC,CAAC;AAE5F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAW3E,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAiDvG;AAED,0CAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzD;AA4BD,qHAAqH;AACrH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG;IAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAqBjG;AA+CD,eAAO,MAAM,iBAAiB,EAAE,YAO/B,CAAC"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,oCAAoC,CAAC;AAE5F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAW3E,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAkDvG;AAED,0CAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzD;AA4BD,qHAAqH;AACrH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG;IAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAqBjG;AA+CD,eAAO,MAAM,iBAAiB,EAAE,YAO/B,CAAC"}

package/dist/commands.js

@@ -16,8 +16,8 @@
 import { splitJoinedFlags, unknownFlagError } from "@intentius/chant/cli/command-group";
 const USAGE = "usage: chant terraform pin-rollout --module <source> --from <pin> --to <pin> [--root <dir>]... [--depends-on <dir>=<dir>]... " +
     "[--ts-source <dir>=<file>]... [--canary <dir>]... [--waves-from <file> [--waves-prefix <dir>]] [--pull-request] " +
-    "[--base <branch>] [--remote <name>] [--applied-check <name>] [--json]";
-const VALUE_FLAGS = new Set(["--module", "--from", "--to", "--root", "--depends-on", "--ts-source", "--canary", "--waves-from", "--waves-prefix", "--base", "--remote", "--applied-check"]);
+    "[--base <branch>] [--remote <name>] [--applied-check <name>] [--binary <terraform|tofu|choudoufu>] [--json]";
+const VALUE_FLAGS = new Set(["--module", "--from", "--to", "--root", "--depends-on", "--ts-source", "--canary", "--waves-from", "--waves-prefix", "--base", "--remote", "--applied-check", "--binary"]);
 const BOOLEAN_FLAGS = new Set(["--pull-request", "--json"]);
 /** Parse the verb's flags into the activity's args. Throws on an unknown flag or a missing value. */
 export function parsePinRolloutArgs(rawArgs) {
@@ -68,6 +68,7 @@ export function parsePinRolloutArgs(rawArgs) {
         ...(one("--base") ? { base: one("--base") } : {}),
         ...(one("--remote") ? { remote: one("--remote") } : {}),
         ...(one("--applied-check") ? { appliedCheck: one("--applied-check") } : {}),
+        ...(one("--binary") ? { binary: one("--binary") } : {}),
     };
     return { args, json: flags.has("--json") };
 }
@@ -183,6 +184,6 @@ export const terraformCommands = {
     description: "Terraform and OpenTofu roots: roll a module version out as one pin-bump PR per wave; write a run report from a saved plan",
     commands: [
         { name: "pin-rollout", description: "Read a pin-bump rollout's state and open the next wave's PR when it is due", handler: runPinRolloutVerb },
-        { name: "report", description: "Write a terragucci.report/v1 run report and its index row from show -json of a composed plan", handler: runReportVerb },
+        { name: "report", description: "Write a terragucci.report/v1 run report, its change set and its index row from show -json of a composed plan", handler: runReportVerb },
     ],
 };

package/dist/components/capability-plugin.d.ts

@@ -38,9 +38,27 @@
  * when both roots are in the change.
  *
  * A root whose `vars` read an output not known yet (`DeployContext.unresolvedInputs`)
- * is not planned: terraform takes no unknown variable. Its member gets a hole
- * naming the roots it waits on and no artifact, and the run that applies it
- * plans it once their outputs are known.
+ * cannot be planned as it stands: terraform takes no unknown variable. It is
+ * previewed instead (#4463, `./placeholder-preview.ts`): planned with a
+ * stand-in per variable that holds no value, typed from the root's
+ * `variable` block, with every attribute and output a stand-in drives marked
+ * unknown after apply. The member lists the variables under `placeholders`,
+ * and its artifact is the preview's shape, never a plan file. The apply plans
+ * the root again once the upstream applied, and core covers that round with
+ * the first approval when its shape is within the preview's; a `run` handed
+ * the shape itself holds the fresh plan to it. When no preview can be made
+ * (an undeclared variable, a `count` or `for_each` over a stand-in, a
+ * placeholder plan that fails) the member stays a hole naming the roots it
+ * waits on, and the hole's reason says why there is no preview.
+ *
+ * ## The plan's shape (#4436)
+ *
+ * `plan` also answers `shape`, `terraformPlanShape` over `show -json`: each
+ * resource the plan changes with its action, type, replacement, the
+ * attributes that differ and the ones unknown after apply. Core's
+ * `coveredRound` compares it with the shape of a later plan of the root. A
+ * previewed root's shape lists the upstreams it read as unknown inputs; a
+ * root that stays a hole has no plan, so no shape, and stays uncovered.
  *
  * ## choudoufu roots in a gated wave (#3459)
  *
@@ -63,9 +81,30 @@
  *
  * chant's waves stay the order. Each root is its own one-root set, so
  * choudoufu's wave over it is always wave 1.
+ *
+ * ## Composed runs (#4447)
+ *
+ * With `terraform.compose.enabled`, a group core forms of `terraform-apply`
+ * components that read each other (ws-107) plans as one plan and applies as
+ * one apply of a composed root, and a member's read of another member's new
+ * output is not a hole: the apply passes the value on. `groupReads`,
+ * `groupFallback`, `planGroup` and `runGroup` are in `./compose-group.ts`.
+ *
+ * ## A choudoufu member's outputs, for another member (#4455)
+ *
+ * The plugin also contributes {@link choudoufuOutputSource} to core's
+ * `member-outputs` verb (`CapabilityPlugin.engineOutputSources`), which is
+ * how a chant member's parameters read a choudoufu member of the same
+ * workspace: `choudoufu output -json` in the member's directory for the
+ * applied values, and `live-plan-set -json` over it for the planned ones,
+ * read the way `plan` reads a root's (`terraformPlannedOutputs`). The member
+ * is not a `terraform.roots` entry of the reading project; its directory
+ * comes from the workspace declaration.
  */
 import type { Capability, PlannedOutputs } from "@intentius/chant/components/capability";
+import { type PlanShapeArtifact } from "@intentius/chant/components/covered-round";
 import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import type { EngineOutputSource, EnginePlannedOutputs } from "@intentius/chant/components/verbs/member-outputs";
 /** The `terraform-apply` step's input. */
 export interface TerraformApplyStepInput {
     /** Key into `terraform.roots`. Also the member's name in a wave's set digest. */
@@ -92,6 +131,29 @@ export interface TerraformApplyStepOutput {
  * only a part of it is.
  */
 export declare function terraformPlannedOutputs(json: unknown): PlannedOutputs;
+/**
+ * What a choudoufu member's set plan says about its outputs (#4455), for
+ * `member-outputs`: {@link terraformPlannedOutputs} of the embedded plan,
+ * chant's digest of that plan, and whether it has changes to apply.
+ */
+export declare function choudoufuMemberPlannedOutputs(set: {
+    planDigest: string;
+    changed: boolean;
+    json: unknown;
+}): EnginePlannedOutputs;
+/**
+ * The choudoufu engine's member outputs (#4455): what core's
+ * `member-outputs` reads a workspace member of kind `choudoufu` through.
+ * Applied values from the member's root outputs (the record store, for a
+ * live estate); planned values from its one-root set plan.
+ */
+export declare const choudoufuOutputSource: EngineOutputSource;
+/** The plan file a preview writes, removed once it is read: a plan made with stand-ins must never apply. */
+export declare const PREVIEW_PLAN_FILE = ".chant-preview.tfplan";
+/** What a previewed root hands `run` (#4463): the shape its plan had with stand-in values. Never a plan file. */
+export interface TerraformShapeArtifact extends PlanShapeArtifact {
+    kind: "terraform-apply-shape";
+}
 /**
  * choudoufu refused the plan `run` was handed by its wave (its exit 3):
  * the live system moved since the plan, or the plan names another estate.

package/dist/components/capability-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAiC,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAGxH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAWzG,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AA0CD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAerE;AAwBD;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAEpB,IAAI,EAAE,MAAM;IADxC,QAAQ,CAAC,SAAS,QAAQ;IAC1B,YAA4B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAGxD;CACF;AA+CD,eAAO,MAAM,wBAAwB,EAAE,UAAU,CAAC,uBAAuB,EAAE,wBAAwB,CA0DlG,CAAC;AAEF,eAAO,MAAM,uBAAuB;aAClC,KAAK,YAAG,iBAAiB;CACjB,CAAC;AAEX,eAAO,MAAM,yBAAyB,EAAE,gBAWvC,CAAC"}
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAiC,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAExH,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,2CAA2C,CAAC;AAGnD,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AACzG,OAAO,KAAK,EAAmB,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAC;AAoBlI,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AA8CD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAerE;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,oBAAoB,CAEhI;AAID;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,kBAInC,CAAC;AA4BF,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,0BAA0B,CAAC;AAEzD,iHAAiH;AACjH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,IAAI,EAAE,uBAAuB,CAAC;CAC/B;AAqFD;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAEpB,IAAI,EAAE,MAAM;IADxC,QAAQ,CAAC,SAAS,QAAQ;IAC1B,YAA4B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAGxD;CACF;AA+CD,eAAO,MAAM,wBAAwB,EAAE,UAAU,CAAC,uBAAuB,EAAE,wBAAwB,CA8ElG,CAAC;AAEF,eAAO,MAAM,uBAAuB;aAClC,KAAK,YAAG,iBAAiB;CACjB,CAAC;AAEX,eAAO,MAAM,yBAAyB,EAAE,gBAcvC,CAAC"}

package/dist/components/capability-plugin.js

@@ -38,9 +38,27 @@
  * when both roots are in the change.
  *
  * A root whose `vars` read an output not known yet (`DeployContext.unresolvedInputs`)
- * is not planned: terraform takes no unknown variable. Its member gets a hole
- * naming the roots it waits on and no artifact, and the run that applies it
- * plans it once their outputs are known.
+ * cannot be planned as it stands: terraform takes no unknown variable. It is
+ * previewed instead (#4463, `./placeholder-preview.ts`): planned with a
+ * stand-in per variable that holds no value, typed from the root's
+ * `variable` block, with every attribute and output a stand-in drives marked
+ * unknown after apply. The member lists the variables under `placeholders`,
+ * and its artifact is the preview's shape, never a plan file. The apply plans
+ * the root again once the upstream applied, and core covers that round with
+ * the first approval when its shape is within the preview's; a `run` handed
+ * the shape itself holds the fresh plan to it. When no preview can be made
+ * (an undeclared variable, a `count` or `for_each` over a stand-in, a
+ * placeholder plan that fails) the member stays a hole naming the roots it
+ * waits on, and the hole's reason says why there is no preview.
+ *
+ * ## The plan's shape (#4436)
+ *
+ * `plan` also answers `shape`, `terraformPlanShape` over `show -json`: each
+ * resource the plan changes with its action, type, replacement, the
+ * attributes that differ and the ones unknown after apply. Core's
+ * `coveredRound` compares it with the shape of a later plan of the root. A
+ * previewed root's shape lists the upstreams it read as unknown inputs; a
+ * root that stays a hole has no plan, so no shape, and stays uncovered.
  *
  * ## choudoufu roots in a gated wave (#3459)
  *
@@ -63,10 +81,39 @@
  *
  * chant's waves stay the order. Each root is its own one-root set, so
  * choudoufu's wave over it is always wave 1.
+ *
+ * ## Composed runs (#4447)
+ *
+ * With `terraform.compose.enabled`, a group core forms of `terraform-apply`
+ * components that read each other (ws-107) plans as one plan and applies as
+ * one apply of a composed root, and a member's read of another member's new
+ * output is not a hole: the apply passes the value on. `groupReads`,
+ * `groupFallback`, `planGroup` and `runGroup` are in `./compose-group.ts`.
+ *
+ * ## A choudoufu member's outputs, for another member (#4455)
+ *
+ * The plugin also contributes {@link choudoufuOutputSource} to core's
+ * `member-outputs` verb (`CapabilityPlugin.engineOutputSources`), which is
+ * how a chant member's parameters read a choudoufu member of the same
+ * workspace: `choudoufu output -json` in the member's directory for the
+ * applied values, and `live-plan-set -json` over it for the planned ones,
+ * read the way `plan` reads a root's (`terraformPlannedOutputs`). The member
+ * is not a `terraform.roots` entry of the reading project; its directory
+ * comes from the workspace declaration.
  */
+import { rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { PlanShapeMovedError, planShapeDifferences, planShapeDigest, } from "@intentius/chant/components/covered-round";
 import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
-import { choudoufuPlanSet, choudoufuWaveApply, choudoufuWaveRoot, terraformApply, terraformInit, terraformOutputs, terraformPlan, } from "../op/activities/terraform.js";
+import { choudoufuMemberOutputs, choudoufuMemberPlanSet, choudoufuPlanSet, choudoufuWaveApply, choudoufuWaveRoot, terraformApply, terraformInit, terraformOutputs, terraformPlan, } from "../op/activities/terraform.js";
+import { terraformPlanShape } from "../plan-shape.js";
+import { terraformChangeSetPart } from "../change-set.js";
+import { rootTexts } from "../compose/hcl.js";
+import { declaredVariables } from "../compose/root.js";
+import { terraformComposeGroup } from "./compose-group.js";
+import { markPlaceholderDriven, placeholderVars, waitingHole } from "./placeholder-preview.js";
 const rootArgs = (input) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}) });
 function requireRoot(input) {
     if (typeof input.root !== "string" || input.root === "") {
@@ -76,10 +123,14 @@ function requireRoot(input) {
 async function planRoot(input, targets) {
     requireRoot(input);
     await terraformInit(rootArgs(input));
+    // One `show -json` per plan (#4479): its document is the digest, the change
+    // set, the planned outputs and the shape. Nothing here reads the
+    // `-no-color` render, so the plan skips it.
     const planned = await terraformPlan({
         ...rootArgs(input),
         ...(input.vars ? { vars: input.vars } : {}),
         ...(targets && targets.length > 0 ? { targets } : {}),
+        text: false,
     });
     return {
         planFile: planned.planFile,
@@ -127,12 +178,34 @@ export function terraformPlannedOutputs(json) {
     return { known, unknown };
 }
 /**
- * The member of a root whose `vars` read outputs not known yet (#3999): no
- * plan, a hole naming whose outputs it waits on, and a digest over the root,
- * the vars as resolved and those names.
+ * What a choudoufu member's set plan says about its outputs (#4455), for
+ * `member-outputs`: {@link terraformPlannedOutputs} of the embedded plan,
+ * chant's digest of that plan, and whether it has changes to apply.
+ */
+export function choudoufuMemberPlannedOutputs(set) {
+    return { ...terraformPlannedOutputs(set.json), planDigest: set.planDigest, changes: set.changed };
+}
+const memberArgs = (ref) => ({ member: ref.member, dir: ref.dir, projectRoot: ref.workspaceRoot });
+/**
+ * The choudoufu engine's member outputs (#4455): what core's
+ * `member-outputs` reads a workspace member of kind `choudoufu` through.
+ * Applied values from the member's root outputs (the record store, for a
+ * live estate); planned values from its one-root set plan.
+ */
+export const choudoufuOutputSource = {
+    kinds: ["choudoufu"],
+    applied: (_ctx, ref) => choudoufuMemberOutputs(memberArgs(ref)),
+    planned: async (_ctx, ref) => choudoufuMemberPlannedOutputs(await choudoufuMemberPlanSet(memberArgs(ref))),
+};
+const resolvedVars = (input) => Object.fromEntries(Object.entries(input.vars ?? {}).map(([k, v]) => [k, v === undefined ? null : v]));
+/**
+ * The member of a root whose `vars` read outputs not known yet and that
+ * could not be previewed (#3999, #4463): no plan, a hole naming whose outputs
+ * it waits on and, when a preview was tried, why it was not possible, and a
+ * digest over the root, the vars as resolved and those names.
  */
-function waitingRoot(ctx, input, unresolved) {
-    const vars = Object.fromEntries(Object.entries(input.vars ?? {}).map(([k, v]) => [k, v === undefined ? null : v]));
+function waitingRoot(ctx, input, unresolved, noPreview) {
+    const vars = resolvedVars(input);
     const planDigest = computePlanDigest("terraform-apply-unresolved", { env: ctx.env, root: input.root, vars, unresolved });
     const changeSet = {
         member: {
@@ -141,12 +214,99 @@ function waitingRoot(ctx, input, unresolved) {
             planner: "chant",
             status: "planned",
             planDigest,
-            holes: [{ address: input.root, type: "terraform_root", reason: `inputs from ${unresolved.join(", ")}; planned again once they apply` }],
+            holes: [waitingHole(input.root, unresolved, noPreview)],
         },
         entries: [],
     };
     return { member: input.root, planDigest, changeSet, ...(ctx.targets?.length ? { targets: ctx.targets } : {}) };
 }
+/** The plan file a preview writes, removed once it is read: a plan made with stand-ins must never apply. */
+export const PREVIEW_PLAN_FILE = ".chant-preview.tfplan";
+function isShapeArtifact(value) {
+    const v = value;
+    return v?.kind === "terraform-apply-shape" && typeof v.digest === "string" && typeof v.shape === "object" && v.shape !== null;
+}
+/** The root's directory, as `terraform.roots` names it from the nearest `chant.config.*`, and the configured binary. */
+async function rootDir(input) {
+    const start = resolve(input.cwd ?? process.cwd());
+    const { config, configPath } = await loadChantConfigUpward(start);
+    const terraform = config.terraform;
+    const dir = terraform?.roots?.[input.root]?.dir;
+    if (dir === undefined)
+        return undefined;
+    return { dir: resolve(configPath ? dirname(configPath) : start, dir), ...(terraform?.binary ? { binary: terraform.binary } : {}) };
+}
+const firstLines = (err) => {
+    const text = (err instanceof Error ? err.message : String(err)).trim();
+    const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+    return lines.slice(0, 4).join(" ").slice(0, 600);
+};
+/**
+ * Preview a root whose `vars` read outputs not known yet (#4463): plan it
+ * with a typed stand-in per such variable, mark what the stand-ins drive
+ * unknown, and answer the change set, the planned outputs and the shape of
+ * that plan, with the shape as the artifact. The plan file is removed. When
+ * no preview can be made, the member stays a hole saying why.
+ */
+async function previewRoot(ctx, input, unresolved, targets) {
+    const root = await rootDir(input);
+    if (root === undefined)
+        return waitingRoot(ctx, input, unresolved, `no root named "${input.root}" in terraform.roots to read its variables from`);
+    const { dir } = root;
+    // #4457: the same files the binary reads (`.tofu` only for tofu and choudoufu).
+    const stand = placeholderVars(input.vars, declaredVariables(rootTexts(dir, root.binary)));
+    if (typeof stand === "string")
+        return waitingRoot(ctx, input, unresolved, stand);
+    let planned;
+    try {
+        await terraformInit(rootArgs(input));
+        planned = await terraformPlan({
+            ...rootArgs(input),
+            vars: stand.vars,
+            planFile: PREVIEW_PLAN_FILE,
+            ...(targets ? { targets } : {}),
+            text: false,
+        });
+    }
+    catch (err) {
+        return waitingRoot(ctx, input, unresolved, `the plan with stand-in values failed: ${firstLines(err)}`);
+    }
+    finally {
+        rmSync(join(dir, PREVIEW_PLAN_FILE), { force: true });
+    }
+    const marked = markPlaceholderDriven(planned.json, stand.placeholders);
+    if ("refused" in marked)
+        return waitingRoot(ctx, input, unresolved, marked.refused);
+    const placeholders = stand.placeholders.map((name) => `var.${name}`);
+    const shape = terraformPlanShape(marked.plan, input.root, { unknownInputs: unresolved });
+    const artifact = { kind: "terraform-apply-shape", member: input.root, shape, digest: planShapeDigest(shape) };
+    const part = terraformChangeSetPart({
+        member: input.root,
+        plan: marked.plan,
+        ...(planned.changeSet?.member.planner ? { planner: planned.changeSet.member.planner } : {}),
+        ...(planned.changeSet?.member.scope ? { scope: planned.changeSet.member.scope } : {}),
+    });
+    // The stand-ins' values are not real, so the digest is over the preview's shape and entries, never the raw plan.
+    const planDigest = computePlanDigest("terraform-apply-preview", {
+        env: ctx.env,
+        root: input.root,
+        vars: resolvedVars(input),
+        unresolved,
+        placeholders,
+        shape: artifact.digest,
+        entries: part.entries,
+    });
+    const changeSet = { ...part, member: { ...part.member, planDigest, placeholders } };
+    return {
+        member: input.root,
+        planDigest,
+        artifact,
+        changeSet,
+        outputs: terraformPlannedOutputs(marked.plan),
+        shape,
+        ...(targets ? { targets } : {}),
+    };
+}
 /**
  * choudoufu refused the plan `run` was handed by its wave (its exit 3):
  * the live system moved since the plan, or the plan names another estate.
@@ -203,9 +363,9 @@ export const terraformApplyCapability = {
     async plan(ctx, input) {
         requireRoot(input);
         const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
-        if (unresolved.length > 0)
-            return waitingRoot(ctx, input, unresolved);
         const targets = ctx.targets && ctx.targets.length > 0 ? ctx.targets : undefined;
+        if (unresolved.length > 0)
+            return previewRoot(ctx, input, unresolved, targets);
         // A targeted root plans with `plan -target`, never as a choudoufu one-root set.
         const wave = targets ? { wave: false } : await choudoufuWaveRoot({ ...rootArgs(input), ...(input.vars ? { vars: input.vars } : {}) });
         if (wave.wave) {
@@ -214,7 +374,7 @@ export const terraformApplyCapability = {
                 planDigest: set.planDigest,
                 choudoufu: { planSetFile: set.planSetFile, setDigest: set.setDigest },
             };
-            return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet, outputs: terraformPlannedOutputs(set.json) };
+            return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet, outputs: terraformPlannedOutputs(set.json), shape: terraformPlanShape(set.json, input.root) };
         }
         const { changeSet, json, ...planned } = await planRoot(input, targets);
         return {
@@ -223,6 +383,7 @@ export const terraformApplyCapability = {
             artifact: planned,
             ...(changeSet ? { changeSet } : {}),
             outputs: terraformPlannedOutputs(json),
+            shape: terraformPlanShape(json, input.root),
             ...(targets ? { targets } : {}),
         };
     },
@@ -233,10 +394,30 @@ export const terraformApplyCapability = {
         await terraformInit(rootArgs(input));
         return terraformOutputs(rootArgs(input));
     },
+    // #4447 (ws-107): a group core forms of components that read each other plans and applies as one composed run
+    // when `terraform.compose.enabled` is set (./compose-group.ts). Delegates, so the methods are read when called.
+    groupReads: (ctx, members) => terraformComposeGroup.groupReads(ctx, members),
+    groupFallback: (ctx, members) => terraformComposeGroup.groupFallback(ctx, members),
+    planGroup: (ctx, members) => terraformComposeGroup.planGroup(ctx, members),
+    runGroup: (ctx, run, members) => terraformComposeGroup.runGroup(ctx, run, members),
     async run(ctx, input) {
         const fromWave = ctx.plans?.[input.root];
         if (isChoudoufuWavePlan(fromWave))
             return runChoudoufuWave(ctx, input, fromWave);
+        if (isShapeArtifact(fromWave)) {
+            // A root previewed with stand-ins (#4463): plan it now with the real
+            // values, and apply that plan only when it is within the preview's shape.
+            const fresh = await planRoot(input, ctx.targets);
+            const differences = planShapeDifferences(fromWave.shape, terraformPlanShape(fresh.json, input.root));
+            if (differences.length > 0)
+                throw new PlanShapeMovedError(input.root, differences);
+            const applied = await terraformApply({ ...rootArgs(input), planFile: fresh.planFile });
+            if (!applied.applied) {
+                throw new Error(`terraform-apply: root "${input.root}" refused the plan it was given (${applied.refused ?? "refused"}). ${applied.refusal ?? ""}`);
+            }
+            const outputs = await terraformOutputs(rootArgs(input));
+            return { root: input.root, planDigest: fresh.planDigest, fromWavePlan: false, outputs };
+        }
         const planned = isPlannedRoot(fromWave)
             ? fromWave
             : await planRoot(input, ctx.targets).then(({ planFile, planDigest }) => ({ planFile, planDigest }));
@@ -268,4 +449,7 @@ export const terraformCapabilityPlugin = {
     families() {
         return TERRAFORM_VERB_FAMILIES;
     },
+    engineOutputSources() {
+        return [choudoufuOutputSource];
+    },
 };

package/dist/components/compose-group.d.ts

@@ -0,0 +1,145 @@
+/**
+ * `terraform-apply`'s group methods (chant#4447, ws-107): core forms a group
+ * of `terraform-apply` components that read each other, and these plan it
+ * as one plan and apply it as one apply of a composed root, so a value one
+ * root creates reaches its readers inside that apply.
+ *
+ * - `groupReads` reports to core each member's `terraform_remote_state` and
+ *   `terraform_estate_outputs` reads of another, as the composition finds
+ *   them, so roots wired in HCL alone form a group. Nothing while
+ *   `terraform.compose.enabled` is unset.
+ * - `groupFallback` answers `off` while `terraform.compose.enabled` is unset,
+ *   else builds the {@link Composition} (#4438) from the files, the config
+ *   and each member's cloud identity, and answers its fallback, if any. A
+ *   member the composition leaves out is dropped with its own kind and
+ *   reason, and core forms the group again from the rest (#4419 ruling 1).
+ *   A composition of estates also asks `choudoufu version` (#4445).
+ *   Nothing plans.
+ * - `planGroup` builds the composition again, plans it once with
+ *   `ComposedRun` (#4444) or, for estates, `EstateRun` (#4445), and answers
+ *   each member's part (#4442): its change-set part, planned outputs and
+ *   shape, with its own plan's digest. The group's digest is the composed
+ *   plan's with the generated files. The run is released before it returns,
+ *   with no lock taken, so a plan that core then refuses or makes wait
+ *   leaves no lock held and no file changed.
+ * - `runGroup` plans once more, this time under each state's lock, and
+ *   applies only when that plan's digest is the one `planGroup` answered;
+ *   otherwise it throws a moved plan and nothing applies. Whatever happens,
+ *   it releases the run. Each member's outputs come from the run: its part
+ *   of the working state's `show -json` for roots with state, the post-apply
+ *   plan's `prior_state` for estates.
+ *
+ * Each member's identity is `ci.identity.cloud` resolved for its root as
+ * the target (`resolveTargetCloudIdentity`, #4332), by the root's key or its
+ * directory, whichever a rule's target glob matches, compared by
+ * `identityKey`, so members that apply under different identities do not
+ * compose (#4438's `identity`).
+ */
+import type { CapabilityGroupOutcome, CapabilityGroupPlan, GroupContext, GroupFallback, GroupMember, GroupRun, ReportedGroupRead } from "@intentius/chant/components/capability";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { type TargetCloudIdentityLookup } from "@intentius/chant/workspace/ci-cloud-identity";
+import { type Composition } from "../compose.js";
+import type { TerraformConfig } from "../config.js";
+import { type BinaryExec } from "../state/exec.js";
+import { type ComposedRunner } from "../compose/estate.js";
+/** The step input as the group methods read it; `TerraformApplyStepInput` in ./capability-plugin.ts. */
+interface StepInput {
+    root: string;
+    vars?: Record<string, unknown>;
+    cwd?: string;
+}
+/** The project a group's roots belong to. */
+export interface ComposeProject {
+    /** Where `chant.config.*` was found: roots resolve against it and `.chant-compose/` is written there. */
+    projectRoot: string;
+    terraform: TerraformConfig;
+}
+/** What a runner is built from. */
+export interface GroupRunnerOptions extends ComposeProject {
+    composition: Composition;
+    /** Take each state's lock: `runGroup` does, `planGroup` does not. */
+    lock: boolean;
+    /** Each member's step `vars` as written, by component. */
+    vars: Record<string, Record<string, unknown> | undefined>;
+    /** The outputs of components outside the group that a member's `vars` read. */
+    componentOutputs: Record<string, Record<string, unknown>>;
+    env: NodeJS.ProcessEnv;
+    /** A directory of the run's own, removed after the run is released. */
+    work: string;
+}
+/** What the group methods use, each replaceable in a test. */
+export interface ComposeGroupDeps {
+    /** The project's config. Default: `loadChantConfigUpward` from the current directory. */
+    project?: () => Promise<ComposeProject>;
+    /** The run for a composition. Default: `EstateRun` when `estate` is set, else `ComposedRun`. */
+    runner?: (o: GroupRunnerOptions) => ComposedRunner;
+    /**
+     * Each target's cloud identity for `env` (`resolveTargetCloudIdentity`,
+     * #4332), or undefined when there is no workspace to read. Default:
+     * `declaredTargetCloudIdentity` from the project root.
+     */
+    identity?: (projectRoot: string, env: string) => Promise<TargetCloudIdentityLookup | undefined>;
+    /** How `choudoufu version` runs. Default `runBinary`. */
+    exec?: BinaryExec;
+    /** A root's outputs as its state holds them, for a member whose part of the working state could not be shown. Default `terraformOutputs`. */
+    outputs?: (root: string) => Promise<Record<string, unknown>>;
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+}
+/** The group methods `terraform-apply` declares. */
+export interface ComposeGroupMethods {
+    groupReads(ctx: GroupContext, members: readonly GroupMember<StepInput>[]): Promise<ReportedGroupRead[]>;
+    groupFallback(ctx: GroupContext, members: readonly GroupMember<StepInput>[]): Promise<GroupFallback | undefined>;
+    planGroup(ctx: GroupContext, members: readonly GroupMember<StepInput>[]): Promise<CapabilityGroupPlan>;
+    runGroup(ctx: GroupContext, run: GroupRun, members: readonly GroupMember<StepInput>[]): Promise<CapabilityGroupOutcome>;
+}
+/** The members as components, each deploying its one step, for `compositionIfEnabled`. */
+export declare function memberComponents(members: readonly GroupMember<StepInput>[]): DriverComponent[];
+/**
+ * Each member's identity as `compositionFor` compares it: `identityKey` of
+ * `lookup` for the member's root, which a rule's target globs match by the
+ * root's key in `terraform.roots` or by its directory relative to the
+ * project (the first declared rule that either matches wins). Undefined
+ * without a lookup, so no member falls back as `identity`.
+ */
+export declare function memberIdentity(project: ComposeProject, members: readonly GroupMember<StepInput>[], lookup: TargetCloudIdentityLookup | undefined): ((member: string) => string | undefined) | undefined;
+/**
+ * The composition of exactly the group's members (core has already formed the
+ * group), or undefined when `terraform.compose` is not enabled.
+ */
+export declare function groupComposition(project: ComposeProject, members: readonly GroupMember<StepInput>[], env: NodeJS.ProcessEnv, identity?: (member: string) => string | undefined): Composition | undefined;
+/**
+ * The members' HCL reads of each other (#4447): each `terraform_remote_state`
+ * block whose state is another member's backend, and each
+ * `terraform_estate_outputs` block naming another member's estate, as the
+ * composition finds them. Each output the reader's code takes off the block
+ * is one read, `<upstream>.<output>` as a `stackOutput()` read is named; a
+ * block whose outputs the code does not name one by one is one read with
+ * the block's address as `ref`. Core cannot see these in the step's `vars`.
+ */
+export declare function hclGroupReads(project: ComposeProject, members: readonly GroupMember<StepInput>[]): ReportedGroupRead[];
+/**
+ * What core is told of the group (#4419 ruling 1): the whole change's
+ * fallback when it is not `one-root`; else each member the composition left
+ * out as a drop with its own kind and reason, so core groups the rest
+ * again without them; else `one-root`. Undefined when every member
+ * composes.
+ */
+export declare function groupFallbackOf(c: Composition, members: readonly string[]): GroupFallback | undefined;
+/**
+ * The outputs of components outside the group that the members' `vars`
+ * read, recovered from each member's input, which core resolved against
+ * them: `writeComposedRoot` turns those reads into literals.
+ */
+export declare function outsideOutputs(members: readonly GroupMember<StepInput>[]): Record<string, Record<string, unknown>>;
+/** A composed plan that no longer matches the one approved. Core's moved-plan mark, so nothing applies and the command exits 3. */
+export declare class ComposedPlanMovedError extends Error {
+    readonly planMoved = true;
+    constructor(message: string);
+}
+/** The group methods, with `deps` in place of the defaults. */
+export declare function composeGroup(deps?: ComposeGroupDeps): ComposeGroupMethods;
+/** The group methods `terraform-apply` uses. */
+export declare const terraformComposeGroup: ComposeGroupMethods;
+export {};
+//# sourceMappingURL=compose-group.d.ts.map