@intentius/chant-lexicon-terraform 0.124.51 → 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

@@ -22,5 +22,10 @@ export declare function parsePinRolloutArgs(rawArgs: string[]): {
 };
 /** Exit status for a rollout's status. */
 export declare function pinRolloutExitCode(status: string): number;
+/** Parse `chant terraform report`'s flags. Throws on an unknown flag, a missing value or a missing required flag. */
+export declare function parseReportArgs(rawArgs: string[]): {
+    values: Map<string, string>;
+    json: boolean;
+};
 export declare const terraformCommands: CommandGroup;
 //# sourceMappingURL=commands.d.ts.map

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;AAqBD,eAAO,MAAM,iBAAiB,EAAE,YAI/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") };
 }
@@ -99,8 +100,90 @@ async function runPinRolloutVerb(ctx) {
         return 1;
     }
 }
+const REPORT_USAGE = "usage: chant terraform report --stage tf-plan|tf-apply --plan <show.json> [--applied <show-after-apply.json>] (--out <dir> | --to <url>) " +
+    "[--project <host/path>] [--commit <sha>] [--pull-request <n>] [--binary <name>] [--binary-version <v>] [--root-dir <dir>] [--self-root <dir>] [--repo <dir>] " +
+    "[--started <iso>] [--finished <iso>] [--json]";
+const REPORT_VALUE_FLAGS = new Set(["--stage", "--plan", "--applied", "--out", "--to", "--project", "--commit", "--pull-request", "--binary", "--binary-version", "--root-dir", "--self-root", "--repo", "--started", "--finished"]);
+/** Parse `chant terraform report`'s flags. Throws on an unknown flag, a missing value or a missing required flag. */
+export function parseReportArgs(rawArgs) {
+    const tokens = splitJoinedFlags(rawArgs, new Set(["--json"]));
+    const values = new Map();
+    let json = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === "--json") {
+            json = true;
+            continue;
+        }
+        if (!REPORT_VALUE_FLAGS.has(t))
+            throw t.startsWith("-") ? unknownFlagError(t, REPORT_USAGE) : new Error(`unexpected argument "${t}"\n${REPORT_USAGE}`);
+        const v = tokens[++i];
+        if (v === undefined || v.startsWith("--"))
+            throw new Error(`${t} needs a value\n${REPORT_USAGE}`);
+        values.set(t, v);
+    }
+    const stage = values.get("--stage");
+    if (stage !== "tf-plan" && stage !== "tf-apply")
+        throw new Error(`--stage is tf-plan or tf-apply\n${REPORT_USAGE}`);
+    if (!values.has("--plan"))
+        throw new Error(`--plan is required\n${REPORT_USAGE}`);
+    if (stage === "tf-apply" && !values.has("--applied"))
+        throw new Error(`--stage tf-apply needs --applied, the show -json of a plan made after the apply\n${REPORT_USAGE}`);
+    if (values.has("--out") === values.has("--to"))
+        throw new Error(`give one of --out <dir> and --to <url>\n${REPORT_USAGE}`);
+    return { values, json };
+}
+async function runReportVerb(ctx) {
+    try {
+        const { values, json } = parseReportArgs(ctx.rawArgs);
+        const { readFileSync } = await import("node:fs");
+        const { runFactsFromEnv, terraformReport, writeReport, httpStore, dirStore, moduleEstates, atmosStackReads, topModule } = await import("./report.js");
+        const read = (flag) => {
+            const file = values.get(flag);
+            try {
+                return JSON.parse(readFileSync(file, "utf8"));
+            }
+            catch (err) {
+                throw new Error(`${flag} ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        const run = runFactsFromEnv(process.env, { pullRequest: values.get("--pull-request"), project: values.get("--project"), commit: values.get("--commit") });
+        const plan = read("--plan");
+        // The plan holds no `live` block: each module's estate is read from its directory, <repo>/<root-dir>/<module>.
+        const repo = values.get("--repo") ?? process.env.GITHUB_WORKSPACE ?? process.cwd();
+        const modules = [...new Set((plan.resource_changes ?? []).map((r) => topModule(String(r.module_address ?? r.address ?? ""))).filter((m) => m !== undefined))];
+        const estates = moduleEstates(repo, values.get("--root-dir") ?? "", modules);
+        // An Atmos repo wires its components with !terraform.output in the stack manifests, which the plan does not keep.
+        const componentReads = atmosStackReads(repo);
+        const result = terraformReport({
+            stage: values.get("--stage"),
+            plan,
+            ...(Object.keys(estates).length > 0 ? { estates } : {}),
+            ...(Object.keys(componentReads).length > 0 ? { componentReads } : {}),
+            ...(values.has("--applied") ? { applied: read("--applied") } : {}),
+            run,
+            ...(values.has("--binary") ? { binary: values.get("--binary") } : {}),
+            ...(values.has("--binary-version") ? { binaryVersion: values.get("--binary-version") } : {}),
+            ...(values.has("--root-dir") ? { rootDir: values.get("--root-dir") } : {}),
+            ...(values.has("--self-root") ? { selfRoot: values.get("--self-root") } : {}),
+            ...(values.has("--started") ? { started: values.get("--started") } : {}),
+            finished: values.get("--finished") ?? new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+        });
+        const store = values.has("--out") ? dirStore(values.get("--out")) : httpStore(values.get("--to"));
+        const keys = await writeReport(store, result);
+        console.log(json ? JSON.stringify({ path: result.path, keys, row: result.row }, null, 2) : `wrote ${keys.join(", ")}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}
 export const terraformCommands = {
     name: "terraform",
-    description: "Terraform and OpenTofu roots: roll a module version out as one pin-bump PR per wave",
-    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 }],
+    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, 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];
+    },
 };