@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/state-ops.js

@@ -0,0 +1,305 @@
+/**
+ * The binary runs outside op waves (#4618): the state-lock release, a state
+ * migration's writes and an ephemeral copy's plan and apply, as fixed
+ * operations of the terraform lexicon, with the gate and the records of
+ * #4551 around the ones that change state on their own.
+ *
+ * Each operation runs a fixed argument list. A caller names the root, the
+ * binary and what the operation acts on (a lock ID, a state file, a key
+ * suffix's backend settings), never extra arguments, so a product cannot
+ * turn an unlock into some other command.
+ *
+ * - `forceUnlockState` releases one lock by its ID with `force-unlock
+ *   -force`. It changes state on its own, so it runs under a gated request:
+ *   `gatedStateOp` asks for the request (`requestGate`), spends the approval
+ *   (`spendGatedRequest`, pushed before anything runs) and records how it
+ *   ended (`finishGatedRequest`, with the product's flat facts in `detail`).
+ * - `pushStateFile` writes one state file with `state push`, and
+ *   `planStateCheck` plans a root against its state (`-lock=false` while the
+ *   caller holds the lock itself) and reads the plan's JSON. A standalone
+ *   migration's writes run under one gated request whose attachment is the
+ *   proof, so the digest binds it. A migration inside a wave keeps the
+ *   wave's hold hook, which chant decides already.
+ * - `planCopy` initialises a root under the backend settings of its copy
+ *   (`init -reconfigure -backend-config=<k>=<v>`), plans it, a destroy too,
+ *   and reads the plan as a change-set part; `applyPlanFile` applies a saved
+ *   plan. A copy waits at chant's `pr-env` gate, which
+ *   `components/pr-env-run` decides and records (#4551 gap 4), so it takes
+ *   no request of its own.
+ *
+ * The capabilities at the end (`terraform-state-unlock`,
+ * `terraform-state-push`, `terraform-copy`) put the same operations in the
+ * plugin's registry, so a step names them by kind.
+ *
+ * The exec is injectable (`./state/exec.ts`), and so is the gated-request
+ * ledger, so a test runs no binary and writes no ledger.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { finishGatedRequest, gatedRequestDigest, readGatedRequests, requestGate, spendGatedRequest, } from "@intentius/chant/lifecycle/gated-request";
+import { plannerForBinary, terraformChangeSetPart } from "./change-set.js";
+import { DEFAULT_LOCK_TIMEOUT, lockTimeoutArgs } from "./lock-timeout.js";
+import { lastLines, runBinary } from "./state/exec.js";
+/** The ops the gated requests of this module wait at, one per kind, as terragucci named them. */
+export const STATE_OPS = {
+    unlock: "tf-unlock",
+    migrate: "tf-migrate",
+    export: "tf-state-export",
+};
+/** The request kinds of #4551's design. */
+export const STATE_OP_KINDS = {
+    unlock: "unlock",
+    migrate: "migrate",
+    export: "state-export",
+};
+/** A binary run that exited non-zero, with the tail of its output. */
+export class StateOpError extends Error {
+    constructor(root, command, code, tail) {
+        super(`${root}: ${command} failed (exit ${code})${tail ? `:\n${tail}` : ""}`);
+        this.root = root;
+        this.command = command;
+        this.code = code;
+        this.tail = tail;
+        this.name = "StateOpError";
+    }
+}
+/** A gated operation stopped for a person: its request waits for an approval. The command that ran it exits 3. */
+export class StateOpWaitingError extends Error {
+    constructor(op, subject, digest, command) {
+        super(`${op} ${subject} waits for an approval of ${digest}: ${command}`);
+        this.op = op;
+        this.subject = subject;
+        this.digest = digest;
+        this.command = command;
+        this.exitCode = CHANT_EXIT.waiting;
+        this.name = "StateOpWaitingError";
+    }
+}
+const ran = async (r, args, label) => {
+    const exec = r.exec ?? runBinary;
+    const done = await exec(r.binary, args, r.dir, r.env ?? process.env);
+    if (done.code !== 0)
+        throw new StateOpError(r.root, `${r.binary} ${label}`, done.code, lastLines(done.out, 10));
+    return done;
+};
+// ── the binary runs ─────────────────────────────────────────────────────────
+/** `init -input=false -no-color`, with `-reconfigure` and `-backend-config` pairs when given. */
+export async function initRoot(r) {
+    const configs = Object.entries(r.backendConfig ?? {}).map(([k, v]) => `-backend-config=${k}=${v}`);
+    await ran(r, ["init", "-input=false", "-no-color", ...(r.reconfigure || configs.length > 0 ? ["-reconfigure"] : []), ...configs], "init");
+}
+/**
+ * Release the state lock with this ID: `force-unlock -force -no-color <id>`.
+ * Run it under {@link gatedStateOp}; the binary releases whichever lock has
+ * the ID, so the approval binds the ID and the lock's location.
+ */
+export async function forceUnlockState(r) {
+    if (!r.id || r.id.startsWith("-"))
+        throw new Error(`${r.root}: "${r.id}" is not a lock ID`);
+    await ran(r, ["force-unlock", "-force", "-no-color", r.id], `force-unlock ${r.id}`);
+}
+/**
+ * Write a state file with `state push`. `lock: false` passes `-lock=false`,
+ * for a caller that holds the state's lock itself; `force` passes `-force`,
+ * for a push over an empty state of another lineage the caller checked.
+ */
+export async function pushStateFile(r) {
+    if (r.file.startsWith("-"))
+        throw new Error(`${r.root}: "${r.file}" is not a state file`);
+    await ran(r, ["state", "push", ...(r.lock === false ? ["-lock=false"] : []), ...(r.force ? ["-force"] : []), r.file], "state push");
+}
+async function planAndShow(r, planArgs, planFile) {
+    const plan = await ran(r, ["plan", "-input=false", "-no-color", ...planArgs, `-out=${planFile}`], "plan");
+    const show = await ran(r, ["show", "-json", planFile], "show -json");
+    let json;
+    try {
+        json = JSON.parse(show.stdout);
+    }
+    catch {
+        throw new StateOpError(r.root, `${r.binary} show -json`, 0, `printed no plan: ${lastLines(show.out, 10)}`);
+    }
+    return { planFile, json, summary: plan.out.match(/Plan: .*|No changes\..*/)?.[0] ?? "planned" };
+}
+/**
+ * Plan a root against its state and read the plan: the check a migration
+ * makes before and after it writes. `lock: false` passes `-lock=false`, for a
+ * caller that holds the lock itself.
+ */
+export function planStateCheck(r) {
+    return planAndShow(r, r.lock === false ? ["-lock=false"] : [], r.planFile);
+}
+/**
+ * Initialise a root under its copy's backend settings and plan it, a destroy
+ * with `destroy`. `backendConfig` is what makes it the copy (a state key with
+ * the copy's suffix), so it is required and never empty: without it the plan
+ * would be of the root's own state. Pass `init: false` for a root another
+ * tool initialised (a Terragrunt unit prepared with the suffix set).
+ */
+export async function planCopy(r) {
+    if (r.init !== false) {
+        if (Object.keys(r.backendConfig).length === 0)
+            throw new Error(`${r.root}: a copy needs the backend settings of its own state`);
+        await initRoot({ ...r, reconfigure: true });
+    }
+    const read = await planAndShow(r, [...lockTimeoutArgs("plan", r.lockTimeout ?? DEFAULT_LOCK_TIMEOUT, r.env ?? process.env), ...(r.destroy ? ["-destroy"] : [])], r.planFile);
+    const part = terraformChangeSetPart({ member: r.root, plan: read.json, planner: plannerForBinary(r.binary) });
+    return { ...read, part, planDigest: part.member.planDigest ?? "" };
+}
+/** Apply a saved plan, and nothing else: `apply -input=false -no-color <plan>`. */
+export async function applyPlanFile(r) {
+    await ran(r, ["apply", "-input=false", "-no-color", ...lockTimeoutArgs("apply", r.lockTimeout ?? DEFAULT_LOCK_TIMEOUT, r.env ?? process.env), r.planFile], "apply");
+}
+const chantLedger = { requestGate, spendGatedRequest, finishGatedRequest, readGatedRequests };
+/**
+ * The time a request was first asked, so asking again binds the same
+ * digest: chant's digest covers `at`, and a run that asked anew each time
+ * would never meet the approval of the last one. The newest standing,
+ * unspent request with the same kind, subject, requester and fields gives
+ * its `at`; with none, `now`.
+ */
+export async function requestedAt(op, request, options = {}) {
+    const now = options.now ?? new Date().toISOString();
+    const read = await (options.ledger ?? chantLedger).readGatedRequests(op, options.cwd ? { cwd: options.cwd } : undefined).catch(() => []);
+    const same = JSON.stringify(Object.entries(request.fields).sort());
+    const standing = read
+        .filter((g) => !g.applied && g.request.kind === request.kind && g.request.subject === request.subject && g.request.by === request.by)
+        .filter((g) => JSON.stringify(Object.entries(g.request.fields).sort()) === same)
+        .filter((g) => !g.pending.expiresAt || g.pending.expiresAt > now)
+        .at(-1);
+    return standing?.request.at ?? now;
+}
+/** The digest `requestGate` puts in `fields.proof` for an attachment. */
+export const attachmentDigest = (attachment) => `sha256:${createHash("sha256").update(attachment).digest("hex")}`;
+/**
+ * Run `act` once its request is approved: ask (or read) the request, spend
+ * the approval, act, and record how it ended. `act` returns its output and
+ * the flat facts that go on the finished line. A spend that cannot be pushed
+ * throws before `act` runs, so no approval acts twice. A finished line that
+ * cannot be written is reported as `recorded: false`; the act already ran.
+ */
+export async function gatedStateOp(input, act) {
+    const ledger = input.ledger ?? chantLedger;
+    // The proof's digest is a field of the stored request, so the standing request is matched with it.
+    const fields = input.attachment !== undefined ? { ...input.request.fields, proof: attachmentDigest(input.attachment) } : input.request.fields;
+    const at = input.request.at ?? (await requestedAt(input.op, { ...input.request, fields }, { ...(input.now ? { now: input.now } : {}), ...(input.cwd ? { cwd: input.cwd } : {}), ledger }));
+    const request = { kind: input.request.kind, subject: input.request.subject, by: input.request.by, at, fields };
+    const asked = await ledger.requestGate({
+        op: input.op,
+        request,
+        rules: input.rules,
+        ...(input.description ? { description: input.description } : {}),
+        ...(input.expiry ? { expiry: input.expiry } : {}),
+        ...(input.base ? { base: input.base } : {}),
+        ...(input.attachment !== undefined ? { attachment: input.attachment } : {}),
+        ...(input.cwd ? { cwd: input.cwd } : {}),
+        ...(input.now ? { now: input.now } : {}),
+        ...(input.gates ? { gates: input.gates } : {}),
+    });
+    if (asked.status !== "approved")
+        return asked;
+    const { digest } = asked;
+    const approvedBy = asked.approval.resolvedBy;
+    const held = await input.beforeSpend?.();
+    if (held)
+        return { status: "held", digest, request: asked.request, reason: held };
+    const spent = await ledger.spendGatedRequest({
+        op: input.op,
+        gate: request.subject,
+        digest,
+        approval: asked.approval,
+        ...(input.runId ? { runId: input.runId } : {}),
+        ...(input.commit ? { commit: input.commit } : {}),
+        ...(input.cwd ? { cwd: input.cwd } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+    const finish = async (result, detail) => {
+        try {
+            const f = await ledger.finishGatedRequest({ op: input.op, gate: request.subject, digest, applied: spent.timestamp, result, ...(detail ? { detail } : {}), ...(input.cwd ? { cwd: input.cwd } : {}) });
+            return f.pushed;
+        }
+        catch {
+            return false;
+        }
+    };
+    try {
+        const { output, detail } = await act({ digest, request: asked.request, approvedBy });
+        return { status: "done", digest, request: asked.request, approvedBy, output, recorded: await finish("applied", detail) };
+    }
+    catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        return { status: "failed", digest, request: asked.request, approvedBy, error, recorded: await finish("failed", { error: error.message.slice(0, 400) }) };
+    }
+}
+/** The digest a request binds, for a caller that prints it before it asks. */
+export const stateOpDigest = (op, request) => gatedRequestDigest(op, request);
+const actorOf = (env) => env.GITHUB_ACTOR || env.GITLAB_USER_LOGIN || env.USER || env.USERNAME || "unknown";
+const dirOf = (cwd, input) => input.dir ?? join(cwd ?? process.cwd(), input.root);
+async function gatedRun(op, input, kind, fields, act, attachment) {
+    const cwd = input.cwd ?? process.cwd();
+    const result = await gatedStateOp({ op, request: { kind, subject: input.root, by: input.by ?? actorOf(process.env), fields }, rules: { mode: input.approval ?? "ledger" }, cwd, ...(attachment !== undefined ? { attachment } : {}) }, act);
+    if (result.status === "done")
+        return result.output;
+    if (result.status === "failed")
+        throw result.error;
+    if (result.status === "spent")
+        throw new Error(`${op} ${input.root}: the request ${result.digest} applied already, and a request applies once`);
+    if (result.status === "held")
+        throw new Error(`${op} ${input.root}: ${result.reason}`);
+    throw new StateOpWaitingError(op, input.root, result.digest, result.command);
+}
+/** The plan a gated capability answers: the request's digest is computed when it is asked, so the plan binds the step's facts alone. */
+const factsPlan = (member, facts) => ({ member, planDigest: stateOpDigest("plan", { kind: "facts", subject: member, by: "", at: "", fields: facts }) });
+export const terraformStateUnlockCapability = {
+    kind: "terraform-state-unlock",
+    rollbackPolicy: "none-by-design",
+    targets: { refuse: "a lock release acts on one lock by its ID" },
+    async plan(_ctx, input) {
+        return factsPlan(input.root, { id: input.id, location: input.location });
+    },
+    async run(_ctx, input) {
+        const dir = dirOf(input.cwd, input);
+        const binary = input.binary ?? "terraform";
+        return gatedRun(STATE_OPS.unlock, input, STATE_OP_KINDS.unlock, { location: input.location, id: input.id }, async () => {
+            await initRoot({ root: input.root, binary, dir });
+            await forceUnlockState({ root: input.root, binary, dir, id: input.id });
+            return { output: { root: input.root, id: input.id }, detail: { lock: input.id, location: input.location } };
+        });
+    },
+};
+export const terraformStatePushCapability = {
+    kind: "terraform-state-push",
+    rollbackPolicy: "needs-opt-out",
+    targets: { refuse: "a state push writes whole states" },
+    async plan(_ctx, input) {
+        return factsPlan(input.root, { roots: input.files.map((f) => f.root).join(",") });
+    },
+    async run(_ctx, input) {
+        const binary = input.binary ?? "terraform";
+        return gatedRun(STATE_OPS.migrate, input, STATE_OP_KINDS.migrate, { roots: input.files.map((f) => f.root).join(",") }, async () => {
+            for (const f of input.files)
+                await pushStateFile({ root: f.root, binary, dir: dirOf(input.cwd, f), file: f.file, ...(f.lock !== undefined ? { lock: f.lock } : {}), ...(f.force ? { force: true } : {}) });
+            return { output: { roots: input.files.map((f) => f.root) }, detail: { roots: input.files.length } };
+        }, input.proof);
+    },
+};
+export const terraformCopyCapability = {
+    kind: "terraform-copy",
+    rollbackPolicy: "needs-opt-out",
+    targets: { refuse: "a copy plans the whole root" },
+    async plan(_ctx, input) {
+        const dir = dirOf(input.cwd, input);
+        const planFile = join(dir, input.destroy ? ".chant-copy-destroy.tfplan" : ".chant-copy.tfplan");
+        const read = await planCopy({ root: input.root, binary: input.binary ?? "terraform", dir, backendConfig: input.backendConfig, planFile, ...(input.destroy ? { destroy: true } : {}), ...(input.lockTimeout !== undefined ? { lockTimeout: input.lockTimeout } : {}) });
+        const artifact = { planFile, planDigest: read.planDigest };
+        return { member: input.root, planDigest: read.planDigest, artifact, changeSet: read.part };
+    },
+    async run(ctx, input) {
+        const kept = ctx.plans?.[input.root];
+        const planned = kept && typeof kept.planFile === "string" ? kept : await terraformCopyCapability.plan(ctx, input).then((p) => p.artifact);
+        await applyPlanFile({ root: input.root, binary: input.binary ?? "terraform", dir: dirOf(input.cwd, input), planFile: planned.planFile, ...(input.lockTimeout !== undefined ? { lockTimeout: input.lockTimeout } : {}) });
+        return { root: input.root, planDigest: planned.planDigest };
+    },
+};
+/** The state operations' capabilities, for the plugin's registry. */
+export const terraformStateOpCapabilities = [terraformStateUnlockCapability, terraformStatePushCapability, terraformCopyCapability];

package/dist/state-reads.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Variables read from another root's state (#4545, Atmos reads moved from
+ * terragucci's `atmos.ts`): an Atmos stack that sets a var with
+ * `!terraform.state <component> [<stack>] <output>` plans on the upstream
+ * instance's output, which only the job that holds a credential can read.
+ *
+ * In the `terraform-apply` step a read is `{ var, root, output }`: the var it
+ * sets, the `terraform.roots` entry whose state holds the value (its
+ * directory and workspace come from that entry), and the output followed by
+ * the keys into its value (`.subnets.private` is `["subnets", "private"]`).
+ * The step reads each upstream's `output -json` once and passes the values
+ * as `-var`, under the step's own `vars`, which win. A read whose upstream
+ * has no state, or no such output yet, waits: the root is not planned on a
+ * stand-in, and the wave says which upstream to apply first.
+ */
+/** One var a root reads from another root's state. */
+export interface TerraformStateRead {
+    /** The variable it sets. */
+    var: string;
+    /** The `terraform.roots` entry whose state holds the value. */
+    root: string;
+    /** The output, then the keys into its value. */
+    output: string[];
+}
+/** What filling a root's reads came to. */
+export interface FilledStateReads {
+    /** The values, by var. Complete only when `waiting` and `errors` are empty. */
+    vars: Record<string, unknown>;
+    /** Reads whose upstream has no such value yet: the root waits for these upstreams to apply. */
+    waiting: Array<{
+        read: TerraformStateRead;
+        why: string;
+    }>;
+    /** Upstreams whose state could not be read at all. */
+    errors: string[];
+}
+/** What is wrong with a step's `reads`, empty when nothing is. */
+export declare function stateReadsProblems(reads: unknown): string[];
+/** The value a read names in its upstream's outputs, or undefined when the outputs do not have it. */
+export declare function readOutputValue(outputs: Record<string, unknown>, output: readonly string[]): {
+    value: unknown;
+} | undefined;
+/**
+ * Fill `reads` from each upstream's outputs, read once per upstream through
+ * `outputsOf`, which throws when the state cannot be read.
+ */
+export declare function fillStateReads(reads: readonly TerraformStateRead[], outputsOf: (root: string) => Promise<Record<string, unknown>>): Promise<FilledStateReads>;
+/** Why a root with waiting reads was not planned, naming what to apply first. */
+export declare function waitingReadsReason(waiting: FilledStateReads["waiting"]): string;
+/**
+ * The reads an Atmos instance's edges file lists (`{ reads: [{ var,
+ * upstream, output }] }`, as terragucci's `atmos write` leaves beside each
+ * instance), with each upstream mapped to its `terraform.roots` entry by
+ * `rootOf` (by default the upstream's own path).
+ */
+export declare function atmosStateReads(edges: unknown, rootOf?: (upstream: string) => string): TerraformStateRead[];
+//# sourceMappingURL=state-reads.d.ts.map

package/dist/state-reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-reads.d.ts","sourceRoot":"","sources":["../src/state-reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,+FAA+F;IAC/F,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,sDAAsD;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAkB3D;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAS3H;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoBnK;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAAG,MAAM,CAG/E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAiB,GAAG,kBAAkB,EAAE,CAQrH"}

package/dist/state-reads.js

@@ -0,0 +1,104 @@
+/**
+ * Variables read from another root's state (#4545, Atmos reads moved from
+ * terragucci's `atmos.ts`): an Atmos stack that sets a var with
+ * `!terraform.state <component> [<stack>] <output>` plans on the upstream
+ * instance's output, which only the job that holds a credential can read.
+ *
+ * In the `terraform-apply` step a read is `{ var, root, output }`: the var it
+ * sets, the `terraform.roots` entry whose state holds the value (its
+ * directory and workspace come from that entry), and the output followed by
+ * the keys into its value (`.subnets.private` is `["subnets", "private"]`).
+ * The step reads each upstream's `output -json` once and passes the values
+ * as `-var`, under the step's own `vars`, which win. A read whose upstream
+ * has no state, or no such output yet, waits: the root is not planned on a
+ * stand-in, and the wave says which upstream to apply first.
+ */
+/** What is wrong with a step's `reads`, empty when nothing is. */
+export function stateReadsProblems(reads) {
+    if (reads === undefined)
+        return [];
+    if (!Array.isArray(reads))
+        return ["reads must be a list of { var, root, output }"];
+    const problems = [];
+    const vars = new Set();
+    for (const [i, r] of reads.entries()) {
+        const read = r;
+        if (!read || typeof read !== "object") {
+            problems.push(`reads[${i}] must be { var, root, output }`);
+            continue;
+        }
+        if (typeof read.var !== "string" || read.var === "")
+            problems.push(`reads[${i}].var must name a variable`);
+        else if (vars.has(read.var))
+            problems.push(`reads[${i}] sets ${read.var}, which an earlier read sets too`);
+        else
+            vars.add(read.var);
+        if (typeof read.root !== "string" || read.root === "")
+            problems.push(`reads[${i}].root must name a terraform.roots entry`);
+        if (!Array.isArray(read.output) || read.output.length === 0 || !read.output.every((k) => typeof k === "string" && k !== ""))
+            problems.push(`reads[${i}].output must be the output's name, then any keys into its value`);
+    }
+    return problems;
+}
+/** The value a read names in its upstream's outputs, or undefined when the outputs do not have it. */
+export function readOutputValue(outputs, output) {
+    const [name, ...keys] = output;
+    if (name === undefined || !(name in outputs))
+        return undefined;
+    let v = outputs[name];
+    for (const k of keys) {
+        if (!v || typeof v !== "object" || Array.isArray(v) || !(k in v))
+            return undefined;
+        v = v[k];
+    }
+    return { value: v };
+}
+/**
+ * Fill `reads` from each upstream's outputs, read once per upstream through
+ * `outputsOf`, which throws when the state cannot be read.
+ */
+export async function fillStateReads(reads, outputsOf) {
+    const result = { vars: {}, waiting: [], errors: [] };
+    const cache = new Map();
+    for (const read of reads) {
+        if (!cache.has(read.root))
+            cache.set(read.root, outputsOf(read.root));
+        let outputs;
+        try {
+            outputs = await cache.get(read.root);
+        }
+        catch (err) {
+            result.errors.push(`it reads ${read.var} from ${read.root}, whose state could not be read: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const got = readOutputValue(outputs, read.output);
+        if (!got) {
+            result.waiting.push({ read, why: Object.keys(outputs).length === 0 ? "has no state yet" : `has no output ${read.output.join(".")} yet` });
+            continue;
+        }
+        result.vars[read.var] = got.value;
+    }
+    return result;
+}
+/** Why a root with waiting reads was not planned, naming what to apply first. */
+export function waitingReadsReason(waiting) {
+    const upstreams = [...new Set(waiting.map((w) => w.read.root))].sort();
+    return `not planned: ${waiting.map((w) => `it reads ${w.read.var} from ${w.read.root}, which ${w.why}`).join("; ")}; apply ${upstreams.join(", ")} first`;
+}
+/**
+ * The reads an Atmos instance's edges file lists (`{ reads: [{ var,
+ * upstream, output }] }`, as terragucci's `atmos write` leaves beside each
+ * instance), with each upstream mapped to its `terraform.roots` entry by
+ * `rootOf` (by default the upstream's own path).
+ */
+export function atmosStateReads(edges, rootOf = (u) => u) {
+    const reads = edges?.reads;
+    if (!Array.isArray(reads))
+        return [];
+    return reads.flatMap((r) => {
+        const read = r;
+        if (!read || typeof read.var !== "string" || typeof read.upstream !== "string" || !Array.isArray(read.output) || !read.output.every((k) => typeof k === "string"))
+            return [];
+        return [{ var: read.var, root: rootOf(read.upstream), output: read.output }];
+    });
+}

package/dist/terragrunt/affected.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"affected.d.ts","sourceRoot":"","sources":["../../src/terragrunt/affected.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"affected.d.ts","sourceRoot":"","sources":["../../src/terragrunt/affected.ts"],"names":[],"mappings":"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"}

package/dist/terragrunt/affected.js

@@ -190,7 +190,8 @@ export function terragruntAffected(input) {
         const moduleDirs = terragruntModuleDirs(unit);
         const called = new Map();
         for (const m of moduleDirs) {
-            for (const d of rootWatchPaths(input.dir, { dir: m }))
+            // Terragrunt runs tofu when it is installed, so a module's `.tofu` files count (chant#4457).
+            for (const d of rootWatchPaths(input.dir, { dir: m }, "tofu"))
                 if (!moduleDirs.includes(d) && !called.has(d))
                     called.set(d, m);
         }

package/dist/used-sources.d.ts

@@ -0,0 +1,54 @@
+import { type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { type SourceBinary } from "./registry/source-forms.js";
+import type { RegistryProxy } from "./registry/proxies.js";
+/** One module source or provider address a root uses. */
+export interface UsedSource {
+    kind: "module" | "provider";
+    /** The file it is written in, relative to the project, `/`-separated. */
+    file: string;
+    /**
+     * The block that names it, after the module calls that reach it:
+     * `module.vpc`, `terraform` for a terragrunt.hcl's source,
+     * `required_providers.aws`, or `provider.aws` for an implied one.
+     */
+    block: string;
+    /** The source or address as written (`hashicorp/<name>` for an implied provider). */
+    source: string;
+    /**
+     * The normal form: for a module, the source without its query, normalised
+     * ({@link normalizeModuleSource}); for a provider, `<host>/<namespace>/<type>`
+     * ({@link providerAddress}), or the source as written when it is not an address.
+     */
+    normal: string;
+    /** For an implied provider: the block that implies it. */
+    implied?: string;
+}
+/** A local module call that could not be followed. */
+export interface UnreadSource {
+    file: string;
+    block: string;
+    source: string;
+    why: string;
+}
+export interface UsedSourcesOptions {
+    /** Follow `./` and `../` module calls down the tree. Default true. */
+    followLocal?: boolean;
+    /** The project's top: file paths are relative to it, and a call that leaves it is not followed. Default the root's directory. */
+    project?: string;
+    /** Read only the files this binary reads, and default provider hosts to its registry. Default: every `.tf` and `.tofu` file, Terraform's registry. */
+    binary?: SourceBinary;
+    /** The HCL parser. Default: core's lazily loaded hcl2json. */
+    parser?: Hcl2Json;
+    /** Registry proxies (chant#4606): a source through one gets its upstream's normal form. */
+    proxies?: readonly RegistryProxy[];
+}
+/**
+ * Every module source and provider address the root at `dir` uses, and each
+ * local call that could not be followed. Throws, naming the file, when a
+ * file cannot be parsed, so a check fails loudly instead of checking less.
+ */
+export declare function usedSources(dir: string, options?: UsedSourcesOptions): Promise<{
+    used: UsedSource[];
+    unread: UnreadSource[];
+}>;
+//# sourceMappingURL=used-sources.d.ts.map

package/dist/used-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"used-sources.d.ts","sourceRoot":"","sources":["../src/used-sources.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAElF,OAAO,EAAyE,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACnI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iIAAiI;IACjI,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sJAAsJ;IACtJ,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACpC;AA6FD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAkCxI"}