@intentius/chant-lexicon-terraform 0.124.44 → 0.124.46

package/dist/op/activities/terraform.js

@@ -39,7 +39,8 @@
  * {@link MIN_CHOUDOUFU_VERSION}.
  */
 import { exec } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { resolve, dirname, join, relative, sep } from "node:path";
 import { loadChantConfigUpward } from "@intentius/chant/config";
@@ -59,7 +60,7 @@ const MAX_BUFFER = 64 * 1024 * 1024;
 export const DEFAULT_PLAN_FILE = "chant.tfplan";
 /** Binary used when the `terraform` namespace records no preference. */
 export const DEFAULT_TERRAFORM_BINARY = "terraform";
-/** Where {@link choudoufuLivePlan} writes GitHub issue #788's JSON document, relative to the root directory. */
+/** Where the {@link choudoufuLivePlan} Op activity writes GitHub issue #788's JSON document, relative to the root directory. */
 export const DEFAULT_LIVE_PLAN_DOCUMENT_FILE = "chant.live-plan.json";
 /**
  * choudoufu below this refuses. v0.12.0 brought `live-plan -json`, `live-ls`
@@ -927,6 +928,133 @@ export async function terraformShow(args, signal) {
         ...(planFile ? countPlanChanges(json) : { adds: 0, changes: 0, destroys: 0 }),
     };
 }
+// ── The plan read (#4358) ───────────────────────────────────────────────────
+/** Prefix of the scratch directory a plan read writes its plan file into, under the OS temp directory. */
+export const PLAN_READ_DIR_PREFIX = "chant-terraform-plan-";
+/** The plan file's name inside that scratch directory. */
+export const PLAN_READ_FILE = "plan.tfplan";
+/**
+ * `terraform plan` for an observation read (#4358): `-input=false -lock=false
+ * -out=<file>`, plus the root's own `-var-file`s.
+ *
+ * `-lock=false` is the point. A read must never take the backend's state lock,
+ * or a teammate's apply that starts while chant is reading would fail on
+ * "Error acquiring the state lock". `-detailed-exitcode` is not passed: the
+ * read wants the document, not the boolean, so exit 0 is the only success.
+ * The `-out` path is always outside the root (see {@link terraformPlanRead}).
+ */
+export function terraformPlanReadCommand(opts) {
+    const parts = [opts.binary, "plan", "-input=false", "-lock=false"];
+    for (const varFile of opts.varFiles ?? [])
+        parts.push(`-var-file=${quoteArg(varFile)}`);
+    parts.push(`-out=${quoteArg(opts.planFile)}`);
+    return parts.join(" ");
+}
+/**
+ * The one line a person runs to initialise a root chant refuses to plan,
+ * with the root's `backendConfig` carried, so it can be pasted as printed.
+ */
+export function terraformInitLine(opts) {
+    const init = terraformInitCommand({
+        binary: opts.binary,
+        ...(opts.backendConfig ? { backendConfig: opts.backendConfig } : {}),
+    });
+    return init.replace(`${opts.binary} init`, `${opts.binary} -chdir=${quoteArg(opts.dir)} init`);
+}
+/** A plan read that did not produce a document. `kind` decides the fallback. */
+export class TerraformPlanReadError extends Error {
+    constructor(kind, message, dir, initLine) {
+        super(message);
+        this.name = "TerraformPlanReadError";
+        this.kind = kind;
+        this.dir = dir;
+        if (initLine !== undefined)
+            this.initLine = initLine;
+    }
+}
+/**
+ * Sort a failed plan's own output into a {@link TerraformPlanReadFailureKind}.
+ * Matched on terraform's and OpenTofu's own error summaries. Order matters:
+ * an S3 backend without credentials says both "backend" and "credentials",
+ * and it is the backend that failed, so the backend patterns are read first.
+ */
+export function classifyPlanReadFailure(output) {
+    if (/Backend initialization required|Inconsistent dependency lock file|Required plugins are not installed|Module not installed|Missing required provider|please run "(terraform|tofu|choudoufu) init"|Run "(terraform|tofu|choudoufu) init"|Backend configuration changed/i.test(output)) {
+        return "not-initialised";
+    }
+    if (/error loading state|Failed to load state|Error refreshing state|Failed to get existing workspaces|error configuring (the )?\S+ backend|Error: Failed to (read|retrieve) state|Error retrieving state|Error acquiring the state lock|state data in S3|NoSuchBucket|failed to (get|read) (remote )?state|Unable to access object|\bbackend\b.*(credential|denied|unauthori[sz]ed|forbidden)/i.test(output)) {
+        return "backend";
+    }
+    return "plan";
+}
+/**
+ * Whether a root has been initialised: `.terraform` (or `TF_DATA_DIR`, when
+ * the environment points elsewhere) exists. A root whose providers or modules
+ * have since changed passes this check and is caught by
+ * {@link classifyPlanReadFailure} on the plan's own error instead.
+ */
+export function rootIsInitialised(dir, env = process.env) {
+    const dataDir = env.TF_DATA_DIR ? resolve(dir, env.TF_DATA_DIR) : join(dir, ".terraform");
+    return existsSync(dataDir);
+}
+/**
+ * Read a saved plan for one root without writing anything in it (#4358):
+ * `plan -input=false -lock=false -out=<tmp>/plan.tfplan` in the root, then
+ * `show -json <tmp>/plan.tfplan`, then remove `<tmp>`.
+ *
+ * Three rules, each a lesson behold already learned reading choudoufu
+ * members (behold `src/choudoufu-plan.ts`):
+ *
+ *   - No lock. `-lock=false` on the plan, always ({@link terraformPlanReadCommand}).
+ *   - Nothing in the root. `<tmp>` is a fresh `mkdtemp` under the OS temp
+ *     directory and is removed in a `finally`, failure or not. `init` is never
+ *     run: an uninitialised root throws a {@link TerraformPlanReadError} of
+ *     kind `"not-initialised"` carrying the line to run.
+ *   - A failure says which kind it is, so the observation can fall back by
+ *     depth ({@link classifyPlanReadFailure}).
+ *
+ * Uses the longInfra profile, like {@link terraformPlan}: a plan refreshes
+ * every resource against its provider.
+ */
+export async function terraformPlanRead(args, signal) {
+    const { binary, root, dir } = await resolveRoot(args, signal);
+    const env = terraformEnvironment(root);
+    const initLine = terraformInitLine({ binary, dir, ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}) });
+    const notInitialised = (detail) => new TerraformPlanReadError("not-initialised", `terraform.roots.${args.root} (${dir}) ${detail}: run \`${initLine}\` first. chant never runs init on a read, since init writes into the root.`, dir, initLine);
+    if (!rootIsInitialised(dir, { ...process.env, ...env }))
+        throw notInitialised("has never been initialised");
+    const planDir = mkdtempSync(join(tmpdir(), PLAN_READ_DIR_PREFIX));
+    const planFile = join(planDir, PLAN_READ_FILE);
+    const command = terraformPlanReadCommand({ binary, planFile, ...(root.varFiles ? { varFiles: root.varFiles } : {}) });
+    try {
+        try {
+            const { stderr } = await run(command, dir, env, signal);
+            // The plan's own stdout is the human render, which this read never
+            // uses; stderr carries warnings worth a human's eye.
+            if (stderr)
+                console.error(stderr);
+        }
+        catch (err) {
+            const failure = err;
+            if (typeof failure.code !== "number")
+                throw err;
+            const output = `${failure.stderr ?? ""}\n${failure.stdout ?? ""}`.replace(/\x1b\[[0-9;]*m/g, "");
+            const kind = classifyPlanReadFailure(output);
+            const line = output
+                .split("\n")
+                .map((l) => l.replace(/^[\s│╷╵]+/, "").trim())
+                .find((l) => /^Error:/.test(l)) ?? `exit ${failure.code}`;
+            if (kind === "not-initialised")
+                throw notInitialised(`needs init (${line})`);
+            throw new TerraformPlanReadError(kind, `${binary} plan failed in ${dir}: ${line}`, dir);
+        }
+        const shown = await run(terraformShowCommand({ binary, json: true, planFile }), dir, env, signal);
+        return { json: JSON.parse(shown.stdout), dir, planDir, command };
+    }
+    finally {
+        rmSync(planDir, { recursive: true, force: true });
+    }
+}
 /**
  * The estate a choudoufu-only activity runs against, in precedence order:
  * `args.estate` when the step names one, then the root's own `estate`
@@ -1003,14 +1131,16 @@ export function liveDocumentFrom(stdout) {
  * the root's environment. The graph command runs in such a scope, so its
  * observation and its prediction see one `live-plan` between them, and the
  * graph's statuses and the prediction's figures are statements about the
- * same read. The document file is still written on every call.
+ * same read. The document is returned, not written: the root is left
+ * byte-for-byte as it was (#4379). A caller that wants the file passes
+ * `documentPath` (relative to the root) and it is written there on request.
  */
 export async function choudoufuLivePlanDocument(args, signal) {
     const resolved = await resolveRoot(args, signal);
     const { binary, dir } = resolved;
     const estate = resolveEstate(args, resolved, "choudoufuLivePlan");
     const env = terraformEnvironment(resolved.root);
-    const documentPath = args.documentPath ?? DEFAULT_LIVE_PLAN_DOCUMENT_FILE;
+    const documentPath = args.documentPath;
     // A root that declares its own estate is run without `-estate`: choudoufu
     // refuses the flag beside a declaration and, since v0.14.0, settles the name
     // from the declaration itself. See {@link choudoufuLivePlanCommand}.
@@ -1049,11 +1179,22 @@ export async function choudoufuLivePlanDocument(args, signal) {
     // the identity on a supported binary. See {@link liveDocumentFrom}.
     const document = liveDocumentFrom(jsonStdout);
     const json = JSON.parse(document);
-    writeFileSync(join(dir, documentPath), document);
-    return { drift, json, dir, documentPath, estate, ...countLivePlanUnowned(json) };
+    if (documentPath !== undefined)
+        writeFileSync(join(dir, documentPath), document);
+    return {
+        drift,
+        json,
+        dir,
+        ...(documentPath === undefined ? {} : { documentPath }),
+        estate,
+        ...countLivePlanUnowned(json),
+    };
 }
 export async function choudoufuLivePlan(args, signal) {
-    const { drift, json, dir, documentPath, estate, ...unowned } = await choudoufuLivePlanDocument(args, signal);
+    // The Op activity is the one caller that wants the file: `documentPath` is a
+    // declared `.out` ref a later step or reviewer opens (#2103), so it asks.
+    const documentPath = args.documentPath ?? DEFAULT_LIVE_PLAN_DOCUMENT_FILE;
+    const { drift, json, dir, estate, ...unowned } = await choudoufuLivePlanDocument({ ...args, documentPath }, signal);
     const resolved = await resolveRoot(args, signal);
     const { binary } = resolved;
     const env = terraformEnvironment(resolved.root);

package/dist/plan-observation.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The plan depth's projection (#4358): a saved plan's `show -json` document,
+ * turned into the attributes an observed terraform block carries.
+ *
+ * The state read (`terraform show -json` over state) says what the last apply
+ * recorded. A plan says what the next apply would do, and four facts exist
+ * only there:
+ *
+ * | plan document | IR attribute |
+ * |---|---|
+ * | `resource_changes[].change.actions` | `planAction`, `planActions` |
+ * | `resource_changes[].change.replace_paths`, `resource_changes[].action_reason` | `planReplacePaths`, `planActionReason` |
+ * | `resource_changes[].change.after_unknown` | `planAfterUnknown` |
+ * | `resource_drift[]`, `relevant_attributes[]` | `planDrift`, `planDriftAction`, `planRelevantAttributes` |
+ *
+ * plus `planChanges`, the attribute-level before and after of each planned
+ * update or replace. `PLAN_ATTRIBUTE_NAMES` lists them for a consumer.
+ *
+ * ## Paths
+ *
+ * Every attribute path is one string: object keys joined with `.`, list
+ * indexes and keys that are not identifiers in brackets, so
+ * `lifecycle_commands[0].read`, `tags["kubernetes.io/role"]`. A `chant search
+ * attr:planReplacePaths=triggers_replace` term matches by substring over that.
+ *
+ * ## Sensitive values never leave this module
+ *
+ * `before_sensitive` and `after_sensitive` are trees parallel to `before` and
+ * `after`: `true` at a node marks that node and everything under it. A value
+ * under a `true` node is replaced with `(sensitive)` before it is put on an
+ * attribute, at any depth, so a sensitive value nested in a map is caught
+ * exactly like a sensitive top-level attribute. Only leaves are ever emitted,
+ * never a whole object, so no unwalked subtree can carry a secret past the
+ * check.
+ *
+ * A flag on either side redacts both sides of that path. On a stock root the
+ * two sides are flagged alike, because state records which paths were
+ * sensitive. On a choudoufu live root (#4371) they are not: prior state is
+ * rebuilt from the account on every run and carries no marks from the
+ * configuration, so an attribute made sensitive by a `sensitive` variable is
+ * flagged on `after` only, while `before` holds the live value, which is the
+ * previous secret. Recorded in `__fixtures__/live-plan-depth/`.
+ *
+ * Flags alone are not enough, as a real plan shows: `terraform_data` copies
+ * `input` to `output`, and the plan flags `input.token` sensitive while
+ * leaving `output.token` unflagged with the same value in it. So every string
+ * found under a sensitive flag anywhere in the document is collected first,
+ * and any emitted value equal to one of them is redacted too. That catches a
+ * copy; it cannot catch a secret a provider transformed (hashed, embedded in a
+ * longer string), and the observation page says so.
+ *
+ * Nothing from `prior_state` is surfaced but each row's `id`, which is the
+ * state read's rule too.
+ */
+/** What stands in for a value flagged sensitive, or equal to one that was. */
+export declare const SENSITIVE_VALUE = "(sensitive)";
+/** OpenTofu's and Terraform's own phrase for a value the plan cannot know yet. */
+export declare const KNOWN_AFTER_APPLY = "(known after apply)";
+/**
+ * Every attribute the plan depth adds to an observed block, beside the state
+ * read's `address`, `root`, `resourceType`, `mode` and `provider`. A block the
+ * plan does not touch carries `planAction: "no-op"` and none of the optional
+ * ones.
+ */
+export declare const PLAN_ATTRIBUTE_NAMES: readonly ["planAction", "planActions", "planActionReason", "planReplacePaths", "planAfterUnknown", "planChanges", "planDrift", "planDriftAction", "planRelevantAttributes"];
+/** One attribute that differs between two sides of a change, at leaf level. */
+export interface PlanValueChange {
+    /** Attribute path, see the module doc. */
+    path: string;
+    /** Before value, or `(sensitive)`. `null` where the side had no value. */
+    before: unknown;
+    /** After value, `(sensitive)`, or `(known after apply)`. */
+    after: unknown;
+    /** The instance this change belongs to, when the block has more than one. */
+    instance?: string;
+    /** On a drift entry: the plan reads this attribute (`relevant_attributes`). */
+    relevant?: boolean;
+}
+/** One `resource_changes[]` entry, projected. */
+export interface PlanInstanceChange {
+    address: string;
+    actions: string[];
+    actionReason?: string;
+    replacePaths: string[];
+    afterUnknown: string[];
+    changes: PlanValueChange[];
+}
+/** One `resource_drift[]` entry, projected. */
+export interface PlanInstanceDrift {
+    address: string;
+    actions: string[];
+    changes: PlanValueChange[];
+}
+/** A plan document, indexed for the plan depth. */
+export interface PlanIndex {
+    /**
+     * `prior_state`, as the document carries it. The reader indexes it exactly
+     * as the state read indexes state, so presence and ownership come from here.
+     */
+    priorState: unknown;
+    /** `resource_changes[]`, by instance address. */
+    changes: Map<string, PlanInstanceChange>;
+    /** `resource_drift[]`, by instance address. */
+    drift: Map<string, PlanInstanceDrift>;
+    /** `relevant_attributes[]`, by instance address: the attribute paths the plan read. */
+    relevant: Map<string, string[]>;
+}
+/** Render one path segment list as a single string. */
+export declare function renderPath(segments: ReadonlyArray<string | number>): string;
+/**
+ * The leaf-level differences between two sides of one change. Exported for
+ * the redaction tests; see the module doc for the rules.
+ */
+export declare function diffChange(change: {
+    before?: unknown;
+    after?: unknown;
+    before_sensitive?: unknown;
+    after_sensitive?: unknown;
+    after_unknown?: unknown;
+}, secrets: ReadonlySet<string>): PlanValueChange[];
+/**
+ * Index a `show -json <planfile>` document. Unknown fields are ignored and a
+ * missing section reads as empty, the same tolerance the state read has.
+ */
+export declare function indexPlan(document: unknown): PlanIndex;
+/**
+ * The block address an instance address belongs to: every instance key
+ * removed, on the resource and on each module call, so `module.a[0].x.y["k"]`
+ * belongs to `module.a.x.y`.
+ */
+export declare function blockAddressOf(instance: string): string;
+/** One action list as one word: `replace` for either order of delete and create. */
+export declare function actionWord(actions: readonly string[]): string;
+/**
+ * The plan attributes of one declared block, aggregated over its instances.
+ * `instances` are the block's instance addresses in `prior_state`; a block in
+ * the plan that has none there is a planned create, which the reader reports
+ * absent and annotates with {@link plannedAttributesFor} instead.
+ */
+export declare function planAttributesFor(address: string, index: PlanIndex): Record<string, unknown>;
+/**
+ * The plan attributes of a block that has no row in `prior_state` (#4372),
+ * or undefined when the plan has no change for it either. The usual case is
+ * a planned create: `planAction: "create"`, `planActions`, and
+ * `planAfterUnknown` naming what stays unknown until apply (its `id` among
+ * them). A data block read during apply comes back as `planAction: "read"`.
+ *
+ * The reader puts these on the observation's `annotations`, not on a
+ * `resources` row, so the block stays absent and `lifecycle plan` still
+ * proposes the create.
+ */
+export declare function plannedAttributesFor(address: string, index: PlanIndex): Record<string, unknown> | undefined;
+//# sourceMappingURL=plan-observation.d.ts.map

package/dist/plan-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-observation.d.ts","sourceRoot":"","sources":["../src/plan-observation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,YAC/B,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,wBAAwB,CAChB,CAAC;AAEX,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACzC,+CAA+C;IAC/C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACtC,uFAAuF;IACvF,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACjC;AAYD,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAQ3E;AA4DD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE;IACN,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,EACD,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,eAAe,EAAE,CAgEnB;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAmEtD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAI7D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6B5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAG3G"}