@intentius/chant-lexicon-terraform 0.124.31 → 0.124.33

package/dist/change-set.js

@@ -0,0 +1,234 @@
+/**
+ * Change-set adapters for the terraform family (#3181): a `terraform show
+ * -json` plan from terraform, tofu or choudoufu, and a choudoufu set plan
+ * document (`live-plan-set -json`, choudoufu#1752), each into
+ * `@intentius/chant/change-set` parts.
+ *
+ * A member's plan digest is {@link terraformPlanDigest}, the value a
+ * `TerraformApplyOp` gate on that root binds (#2300), so a change set over
+ * one root and a gate over the same root agree on what changed.
+ *
+ * This module imports `./plan-digest` and chant's `change-set` and
+ * `lifecycle/plan-digest` subpaths, never the lexicon's entry point, so it
+ * bundles without TypeScript or the lint rules (#3421).
+ */
+import { terraformPlanDigest } from "./plan-digest.js";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** Whether a sensitivity or unknown map marks anything under it `true`. */
+function marks(v) {
+    if (v === true)
+        return true;
+    if (Array.isArray(v))
+        return v.some(marks);
+    if (isObject(v))
+        return Object.values(v).some(marks);
+    return false;
+}
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((x, i) => sameJson(x, b[i]));
+    if (isObject(a) && isObject(b)) {
+        const ka = Object.keys(a);
+        return ka.length === Object.keys(b).length && ka.every((k) => k in b && sameJson(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * The planner a root's binary names: `choudoufu` and `tofu` by name, and
+ * `terraform` for anything else, a path to terraform included.
+ */
+export function plannerForBinary(binary) {
+    const base = (binary ?? "terraform").split(/[\\/]/).pop() ?? "";
+    if (base.startsWith("choudoufu"))
+        return "choudoufu";
+    if (base.startsWith("tofu"))
+        return "tofu";
+    return "terraform";
+}
+/**
+ * The action a `resource_changes` entry's `actions` array means. Delete then
+ * create and create then delete are both a replace; the order is the
+ * disruption ({@link disruptionFor}).
+ */
+export function actionFor(actions) {
+    const a = Array.isArray(actions) ? actions.map(String) : [];
+    if (a.length === 2 && a.includes("delete") && a.includes("create"))
+        return "replace";
+    if (a.length === 1) {
+        switch (a[0]) {
+            case "create":
+            case "update":
+            case "delete":
+            case "read":
+            case "no-op":
+            case "forget":
+                return a[0];
+        }
+    }
+    throw new Error(`a plan entry has actions ${JSON.stringify(actions)}, which the change set has no action for`);
+}
+function disruptionFor(actions, action) {
+    switch (action) {
+        case "update": return "in-place";
+        case "delete": return "destroy";
+        case "replace": return actions[0] === "create" ? "replace" : "destroy";
+        default: return undefined;
+    }
+}
+/** A resource address's module path, name and index, read off the address when the entry does not carry them. */
+export function parseTerraformAddress(address) {
+    // Module segments, then [data.]type.name[index]. Index brackets may hold a quoted key with dots in it.
+    const re = /^((?:module\.[^.[\]]+(?:\[(?:"(?:[^"\\]|\\.)*"|\d+)\])?\.)*)(?:data\.)?([^.[\]]+)\.([^.[\]]+)(?:\[("(?:[^"\\]|\\.)*"|\d+)\])?$/;
+    const m = re.exec(address);
+    if (!m)
+        return { type: "unknown", name: address };
+    const module = m[1] ? m[1].slice(0, -1) : undefined;
+    const index = m[4] === undefined ? undefined : m[4].startsWith('"') ? JSON.parse(m[4]) : Number(m[4]);
+    return { ...(module ? { module } : {}), type: m[2], name: m[3], ...(index !== undefined ? { index } : {}) };
+}
+/** The attributes one change writes, top-level, with sensitive values left out. */
+function attributesFor(change, action) {
+    if (action === "delete" || action === "no-op" || action === "forget" || action === "read")
+        return [];
+    const before = isObject(change.before) ? change.before : {};
+    const after = isObject(change.after) ? change.after : {};
+    const afterUnknown = isObject(change.after_unknown) ? change.after_unknown : {};
+    const beforeSensitive = isObject(change.before_sensitive) ? change.before_sensitive : {};
+    const afterSensitive = isObject(change.after_sensitive) ? change.after_sensitive : {};
+    const forcing = new Set((Array.isArray(change.replace_paths) ? change.replace_paths : [])
+        .map((p) => (Array.isArray(p) ? p[0] : undefined))
+        .filter((k) => typeof k === "string"));
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after), ...Object.keys(afterUnknown)])].sort();
+    const out = [];
+    for (const k of keys) {
+        const unknown = marks(afterUnknown[k]);
+        const hasBefore = action !== "create" && before[k] !== undefined && before[k] !== null;
+        const hasAfter = after[k] !== undefined && after[k] !== null;
+        if (action === "create" ? !hasAfter && !unknown : !unknown && sameJson(before[k] ?? null, after[k] ?? null))
+            continue;
+        const sensitive = marks(beforeSensitive[k]) || marks(afterSensitive[k]);
+        out.push({
+            path: k,
+            ...(sensitive ? { sensitive: true } : {
+                ...(hasBefore ? { before: before[k] } : {}),
+                ...(hasAfter && !unknown ? { after: after[k] } : {}),
+            }),
+            ...(unknown ? { unknown: true } : {}),
+            ...(forcing.has(k) ? { forcesReplacement: true } : {}),
+        });
+    }
+    return out;
+}
+function regionOf(change) {
+    for (const side of [change.after, change.before]) {
+        if (isObject(side) && typeof side.region === "string" && side.region !== "")
+            return side.region;
+    }
+    return undefined;
+}
+/**
+ * One terraform-family root's part, from its `show -json` plan.
+ *
+ * Every `resource_changes` entry becomes an entry, no-op and read included.
+ * A plan stock marked `errored` is a failed member: its entries are kept,
+ * but nothing should apply it.
+ */
+export function terraformChangeSetPart(input) {
+    const plan = isObject(input.plan) ? input.plan : {};
+    const planner = input.planner ?? "terraform";
+    const raw = Array.isArray(plan.resource_changes) ? plan.resource_changes : [];
+    const entries = raw.map((r) => {
+        const rc = isObject(r) ? r : {};
+        const change = isObject(rc.change) ? rc.change : {};
+        const address = String(rc.address ?? "");
+        const parsed = parseTerraformAddress(address);
+        const action = actionFor(change.actions);
+        const disruption = disruptionFor(change.actions, action);
+        const region = regionOf(change);
+        const index = rc.index !== undefined && rc.index !== null ? rc.index : parsed.index;
+        const module = typeof rc.module_address === "string" ? rc.module_address : parsed.module;
+        return {
+            member: input.member,
+            lexicon: "terraform",
+            planner,
+            address,
+            type: typeof rc.type === "string" ? rc.type : parsed.type,
+            name: typeof rc.name === "string" ? rc.name : parsed.name,
+            ...(index !== undefined ? { index } : {}),
+            ...(module ? { module } : {}),
+            ...(typeof rc.deposed === "string" ? { deposed: rc.deposed } : {}),
+            action,
+            ...(isObject(change.importing) ? { importing: true } : {}),
+            ...(disruption ? { disruption } : {}),
+            ...(region ? { region } : {}),
+            ...(input.scope ? { scope: input.scope } : {}),
+            attributes: attributesFor(change, action),
+        };
+    });
+    const sideEffects = (Array.isArray(plan.action_invocations) ? plan.action_invocations : []).map(sideEffectFor);
+    const errored = plan.errored === true;
+    return {
+        member: {
+            member: input.member,
+            lexicon: "terraform",
+            planner,
+            ...(input.scope ? { scope: input.scope } : {}),
+            status: errored ? "failed" : "planned",
+            ...(errored ? { error: `${planner} marked the plan errored` } : {}),
+            planDigest: terraformPlanDigest(plan),
+            ...(input.nativeDigest ? { nativeDigest: input.nativeDigest } : {}),
+            holes: [],
+        },
+        entries,
+        ...(sideEffects.length > 0 ? { sideEffects } : {}),
+    };
+}
+/**
+ * One `action_invocations` entry of a plan (Terraform 1.14): the action's
+ * address and type, and, for a lifecycle trigger, the resource and event.
+ */
+function sideEffectFor(raw) {
+    const inv = isObject(raw) ? raw : {};
+    const type = typeof inv.type === "string" ? inv.type : "unknown";
+    const lifecycle = isObject(inv.lifecycle_action_trigger) ? inv.lifecycle_action_trigger : {};
+    return {
+        address: typeof inv.address === "string" ? inv.address : type,
+        type,
+        ...(typeof lifecycle.triggering_resource_address === "string" ? { trigger: lifecycle.triggering_resource_address } : {}),
+        ...(typeof lifecycle.action_trigger_event === "string" ? { event: lifecycle.action_trigger_event } : {}),
+    };
+}
+/**
+ * One part per root of a choudoufu set plan (choudoufu#1752). A planned
+ * root is {@link terraformChangeSetPart} over its embedded plan, with the
+ * estate as scope and choudoufu's own root digest as `nativeDigest`. A
+ * failed root is a failed member with its error and no plan digest.
+ */
+export function choudoufuSetPlanParts(input) {
+    const doc = isObject(input.document) ? input.document : {};
+    if (!Array.isArray(doc.roots))
+        throw new Error('not a choudoufu set plan document: no top-level "roots"');
+    return doc.roots.map((r) => {
+        const member = input.memberFor ? input.memberFor(r.root, r.estate || undefined) : r.root;
+        const scope = r.estate || undefined;
+        if (r.status === "planned" && isObject(r.plan)) {
+            return terraformChangeSetPart({ member, plan: r.plan, planner: "choudoufu", ...(scope ? { scope } : {}), ...(r.digest ? { nativeDigest: r.digest } : {}) });
+        }
+        return {
+            member: {
+                member,
+                lexicon: "terraform",
+                planner: "choudoufu",
+                ...(scope ? { scope } : {}),
+                status: "failed",
+                error: r.error || `the root did not plan (${r.status ?? "no status"}${r.stage ? `, at ${r.stage}` : ""})`,
+                planDigest: null,
+                ...(r.digest ? { nativeDigest: r.digest } : {}),
+                holes: [],
+            },
+            entries: [],
+        };
+    });
+}

package/dist/changed-roots.js

@@ -0,0 +1,97 @@
+/**
+ * Which `terraform.roots` a change touched (#3183), from the changed files
+ * alone.
+ *
+ * A root is hand-written HCL, not chant source, so `chant lifecycle affected`
+ * never sees it move: its artifact diff covers what chant builds. A pull
+ * request's plan needs the roots a change reaches, and this answers that
+ * from paths: a root is touched when a changed file sits in its directory,
+ * 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`
+ * 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
+ * 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 { join, posix, relative, resolve, sep } from "node:path";
+/** `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("/");
+/** `dir` relative to `projectRoot`, `/`-separated, without a trailing slash; `.` for the root itself. */
+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 [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith(".tf") && !name.endsWith(".tofu"))
+            continue;
+        let text;
+        try {
+            text = readFileSync(join(dir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const m of text.matchAll(LOCAL_SOURCE)) {
+            // A `//subdir` suffix names a directory inside the source.
+            const target = resolve(dir, m[1].replace("//", "/"));
+            if (existsSync(target) && statSync(target).isDirectory())
+                out.push(target);
+        }
+    }
+    return out;
+}
+/**
+ * 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) {
+    const rootDir = resolve(projectRoot, root.dir);
+    const seen = new Set();
+    const queue = [rootDir];
+    while (queue.length > 0) {
+        const dir = queue.shift();
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        queue.push(...localModuleDirs(dir));
+    }
+    const paths = [...seen].map((d) => projectRelative(projectRoot, d));
+    for (const file of root.varFiles ?? [])
+        paths.push(projectRelative(projectRoot, resolve(rootDir, file)));
+    return [...new Set(paths)].sort();
+}
+/** Whether `file` is `path` or sits under it. Both relative to the project, `/`-separated. */
+function covers(path, file) {
+    if (path === ".")
+        return !file.startsWith("../");
+    return file === path || file.startsWith(`${path}/`);
+}
+/**
+ * The names of the roots in `roots` that a change to `changedFiles` touches,
+ * sorted. `changedFiles` are relative to `projectRoot` with `/` separators,
+ * as `git diff --name-only --relative` prints them.
+ */
+export function changedRoots(projectRoot, roots, changedFiles) {
+    const files = changedFiles.map((f) => posix.normalize(f));
+    const touched = [];
+    for (const [name, root] of Object.entries(roots)) {
+        const watch = rootWatchPaths(projectRoot, root);
+        if (files.some((f) => watch.some((p) => covers(p, f))))
+            touched.push(name);
+    }
+    return touched.sort();
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,44 @@
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const overview = `
+The Terraform lexicon reads an estate's existing \`.tf\` files. There is no
+generated resource surface here and nothing is emitted back over the HCL:
+Terraform's types live in provider registries, one schema per provider and
+version, and an estate that already has a root module does not need a second,
+generated copy of it.
+
+What you declare is the directory. Each entry in \`terraform.roots\` names a
+root module; \`buildRoots()\` parses it at build time and every HCL block joins
+the build as an entity keyed \`<root>/<address>\`, carrying the block body
+verbatim. Those entities are what the post-synth checks and \`chant audit\`
+read.
+
+See [Getting Started](getting-started/) for the config shape, the block-to-entity
+mapping, and what TF001 reports.
+`;
+/**
+ * Generate the docs site for the terraform lexicon.
+ *
+ * `basePath` is what the unified site at /chant needs so assets and internal
+ * links resolve once this site is copied under it (scripts/build-docs.test.ts
+ * asserts it). Authored pages come from `docs/pages/` by default.
+ */
+export async function generateDocs(options) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "terraform",
+        displayName: "Terraform",
+        description: "Existing Terraform root modules as declarable chant entities",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/terraform/",
+        overview,
+        serviceFromType: (type) => type.split("::")[1] ?? type,
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (options?.verbose) {
+        console.error(`Generated ${result.pages.size} documentation pages`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./generate.js";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+// src/codegen/generate-cli.ts -> src/codegen -> src -> package root.
+// Two dirnames land in src/ and the first generate writes src/src/generated/ (#1614).
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result, pkgDir);

package/dist/codegen/generate.js

@@ -0,0 +1,59 @@
+/**
+ * Generation for the terraform lexicon: there is nothing to generate.
+ *
+ * Every other lexicon fetches one upstream schema and emits typed resource
+ * classes from it. Terraform has no such thing. Its resource surface lives in
+ * provider registries, one schema per provider and per version, and this
+ * lexicon does not model it: an estate's `.tf` files are read as they are
+ * (see `../hcl/parse.ts`) and the blocks become entities with their bodies
+ * carried verbatim. So `core`'s `generatePipeline` is not called at all, and
+ * this returns the empty result the packaging pipeline needs to assemble a
+ * bundle.
+ *
+ * The registry is still written, empty, because `validate` reads it and
+ * `writeBundleSpec` derives `dist/meta.json` from it. An empty registry is the
+ * honest statement that this lexicon exports no generated resource classes.
+ */
+import { writeGeneratedArtifacts } from "@intentius/chant/codegen/generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+/** Filename of the generated registry, read back by `../validate.ts`. */
+export const LEXICON_JSON_FILENAME = "lexicon-terraform.json";
+const EMPTY_INDEX_TS = `// Code generated by chant generate. DO NOT EDIT.
+// The terraform lexicon models no upstream schema, so there are no resource
+// classes to export. See src/codegen/generate.ts.
+export {};
+`;
+const EMPTY_TYPES_DTS = `// Code generated by chant generate. DO NOT EDIT.
+export {};
+`;
+export async function generate(options) {
+    const result = {
+        lexiconJSON: `${JSON.stringify({}, null, 2)}\n`,
+        typesDTS: EMPTY_TYPES_DTS,
+        indexTS: EMPTY_INDEX_TS,
+        resources: 0,
+        properties: 0,
+        enums: 0,
+        warnings: [],
+    };
+    if (options?.verbose) {
+        console.error("terraform generates no types: the .tf files an estate already has are the input");
+    }
+    return result;
+}
+/**
+ * Write generated files to the package directory.
+ */
+export function writeGeneratedFiles(result, pkgDir) {
+    // This file lives in src/codegen/, so the package root is three levels up.
+    const dir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    writeGeneratedArtifacts({
+        baseDir: dir,
+        files: {
+            [LEXICON_JSON_FILENAME]: result.lexiconJSON,
+            "index.d.ts": result.typesDTS,
+            "index.ts": result.indexTS,
+        },
+    });
+}

package/dist/codegen/package.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { terraformPlugin } from "../plugin.js";
+/**
+ * This package's `src/` directory. `packagePipeline` scans it for the rule
+ * files that go into `dist/rules/`, so it must be `src/` and not `src/codegen/`
+ * (which is where `dirname(import.meta.url)` alone lands, and where
+ * `lint/rules` does not exist). `lexicons/aws/src/codegen/package.ts` resolves
+ * it the same way.
+ */
+const srcDir = dirname(moduleSourceDir(import.meta.url));
+/** The published version, so the manifest cannot drift from package.json. */
+function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * Package the terraform lexicon for distribution.
+ */
+export async function packageLexicon(options) {
+    const version = packageVersion();
+    const { spec, stats } = await packagePipeline({
+        generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+        buildManifest: () => ({
+            name: "terraform",
+            version,
+            chantVersion: ">=0.1.0",
+            namespace: "Terraform",
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(terraformPlugin.skills?.() ?? []),
+        version,
+    }, options);
+    return { spec, stats };
+}

package/dist/commands.js

@@ -0,0 +1,106 @@
+/**
+ * `chant terraform pin-rollout`: one run of a pin-bump rollout (#3189), from
+ * the command line. The `TerraformPinRolloutOp` composite runs the same code
+ * as an Op step.
+ *
+ *     chant terraform pin-rollout --module <source> --from <pin> --to <pin>
+ *       [--root <dir>]... [--depends-on <dir>=<dir>]... [--ts-source <dir>=<file>]...
+ *       [--canary <dir>]... [--waves-from <live-waves.json> [--waves-prefix <dir>]]
+ *       [--pull-request] [--base <branch>] [--remote <name>] [--applied-check <name>] [--json]
+ *
+ * Without `--pull-request` it reports the next wave and opens nothing. Exit
+ * 0 when the rollout is complete or a wave's PR was opened (or would be), 3
+ * when it is waiting on a merge or an apply (a gate is a fact, #2119), and 1
+ * when it stopped on a failed root or a closed PR.
+ */
+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"]);
+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) {
+    const tokens = splitJoinedFlags(rawArgs, BOOLEAN_FLAGS);
+    const values = new Map();
+    const flags = new Set();
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (BOOLEAN_FLAGS.has(t)) {
+            flags.add(t);
+            continue;
+        }
+        if (!VALUE_FLAGS.has(t))
+            throw t.startsWith("-") ? unknownFlagError(t, USAGE) : new Error(`unexpected argument "${t}"\n${USAGE}`);
+        const v = tokens[++i];
+        if (v === undefined || v.startsWith("--"))
+            throw new Error(`${t} needs a value\n${USAGE}`);
+        values.set(t, [...(values.get(t) ?? []), v]);
+    }
+    const one = (flag) => values.get(flag)?.at(-1);
+    const pairs = (flag) => (values.get(flag) ?? []).map((v) => {
+        const eq = v.indexOf("=");
+        if (eq <= 0 || eq === v.length - 1)
+            throw new Error(`${flag} takes <dir>=<value>, got "${v}"`);
+        return [v.slice(0, eq), v.slice(eq + 1)];
+    });
+    for (const required of ["--module", "--from", "--to"])
+        if (!one(required))
+            throw new Error(`${required} is required\n${USAGE}`);
+    const dependsOn = pairs("--depends-on");
+    const tsSource = new Map(pairs("--ts-source"));
+    const named = [...new Set([...(values.get("--root") ?? []), ...dependsOn.map(([r]) => r), ...tsSource.keys()])];
+    const roots = named.length > 0
+        ? named.map((root) => {
+            const deps = dependsOn.filter(([r]) => r === root).map(([, d]) => d);
+            return { root, ...(deps.length > 0 ? { dependsOn: deps } : {}), ...(tsSource.has(root) ? { tsSource: tsSource.get(root) } : {}) };
+        })
+        : undefined;
+    const args = {
+        module: one("--module"),
+        from: one("--from"),
+        to: one("--to"),
+        mode: flags.has("--pull-request") ? "pull-request" : "report",
+        ...(roots ? { roots } : {}),
+        ...(values.has("--canary") ? { canaries: values.get("--canary") } : {}),
+        ...(one("--waves-from") ? { wavesFrom: one("--waves-from") } : {}),
+        ...(one("--waves-prefix") ? { wavesPrefix: one("--waves-prefix") } : {}),
+        ...(one("--base") ? { base: one("--base") } : {}),
+        ...(one("--remote") ? { remote: one("--remote") } : {}),
+        ...(one("--applied-check") ? { appliedCheck: one("--applied-check") } : {}),
+    };
+    return { args, json: flags.has("--json") };
+}
+/** Exit status for a rollout's status. */
+export function pinRolloutExitCode(status) {
+    if (status === "waiting")
+        return 3;
+    if (status === "stopped")
+        return 1;
+    return 0;
+}
+async function runPinRolloutVerb(ctx) {
+    let parsed;
+    try {
+        parsed = parsePinRolloutArgs(ctx.rawArgs);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const { readPinRollout } = await import("./op/activities/pin-rollout.js");
+    try {
+        const result = await readPinRollout(parsed.args);
+        console.log(parsed.json ? JSON.stringify(result, null, 2) : result.summary);
+        return pinRolloutExitCode(result.status);
+    }
+    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 }],
+};

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

@@ -20,12 +20,28 @@
  * that file and nothing else. terraform and tofu refuse a saved plan whose
  * state moved since it was written; choudoufu re-plans against the live
  * system and refuses with exit 3 when its fresh plan differs (choudoufu
- * #878). Either refusal fails the step.
+ * #878). Either refusal fails the step. choudoufu's refusal of a plan the
+ * wave handed `run` throws {@link TerraformPlanMovedError}, so the command
+ * that applied it exits 3 (#3997). terraform's and tofu's stale-plan error
+ * is not classified and exits 1.
  *
  * Run without a wave plan (`chant run --components`, or a fan-out with no
  * wave gate), `run` plans and applies in one go, which is what `terraform
  * apply` with no plan file does too.
  *
+ * ## What the plan says about the root's outputs (#3999)
+ *
+ * `plan` answers the outputs the root will have once that plan applies
+ * (`terraformPlannedOutputs`): `show -json`'s `planned_values.outputs`, less
+ * each output whose `output_changes` entry is unknown after apply. A pull
+ * request's plan reads a dependent's `stackOutput()` references from there
+ * 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.
+ *
  * ## choudoufu roots in a gated wave (#3459)
  *
  * A live choudoufu root that `live-plan-set` can plan as chant would (no
@@ -48,7 +64,7 @@
  * chant's waves stay the order. Each root is its own one-root set, so
  * choudoufu's wave over it is always wave 1.
  */
-import type { Capability } from "@intentius/chant/components/capability";
+import type { Capability, PlannedOutputs } from "@intentius/chant/components/capability";
 import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
 /** The `terraform-apply` step's input. */
 export interface TerraformApplyStepInput {
@@ -68,6 +84,26 @@ export interface TerraformApplyStepOutput {
     /** `terraform output -json`, as `{ name: value }`. */
     outputs: Record<string, unknown>;
 }
+/**
+ * The outputs a root will have once the plan `json` (`show -json`) applies
+ * (#3999). An output is known when `planned_values.outputs` gives its value
+ * and its `output_changes` entry marks no part of it unknown after apply.
+ * Every other output the plan names is unknown, the whole output even when
+ * only a part of it is.
+ */
+export declare function terraformPlannedOutputs(json: unknown): PlannedOutputs;
+/**
+ * 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.
+ * Nothing was applied. `planMoved` is core's mark for a moved plan
+ * (`isPlanMovedError`), so the command that applied it exits 3, as for the
+ * other capabilities that refuse a moved plan (#3997).
+ */
+export declare class TerraformPlanMovedError extends Error {
+    readonly root: string;
+    readonly planMoved = true;
+    constructor(root: string, message: string);
+}
 export declare const terraformApplyCapability: Capability<TerraformApplyStepInput, TerraformApplyStepOutput>;
 export declare const TERRAFORM_VERB_FAMILIES: {
     readonly apply: readonly ["terraform-apply"];