@intentius/chant-lexicon-terraform 0.57.0

package/dist/op/activities/terraform.d.ts

@@ -0,0 +1,213 @@
+/**
+ * terraform Op activities (#2086) — init, plan, apply and show against a root
+ * module named in the project's `terraform.roots` config namespace (#2083).
+ *
+ * Shaped after `lexicons/k3s/src/op/activities/k3s.ts`: `promisify(exec)` with
+ * the caller's `AbortSignal` forwarded so a local timeout or Ctrl-C kills the
+ * child, `safeHeartbeat` on an interval around the long calls, and every
+ * command and environment string produced by a pure exported function so a
+ * test can assert on it without running terraform.
+ *
+ * Two invariants hold for every call:
+ *
+ *   - `TF_IN_AUTOMATION=1` is in the environment, which is what tells terraform
+ *     it is not talking to a person.
+ *   - `-input=false` is on every command that accepts it, so a missing variable
+ *     fails the step instead of blocking on a prompt nobody will answer.
+ *     `terraform show` is the one command that does not accept the flag
+ *     (terraform answers `flag provided but not defined: -input`), so it
+ *     carries the environment variable alone.
+ *
+ * `terraformApply` takes a saved plan file and nothing else. A bare apply
+ * re-plans at apply time, which is exactly the gap an approval gate exists to
+ * close, so it is refused rather than offered.
+ */
+import type { TerraformConfig, TerraformRootConfig } from "../../config.js";
+/** Plan file written into the root directory when a step names none. */
+export declare const DEFAULT_PLAN_FILE = "chant.tfplan";
+/** Binary used when the `terraform` namespace records no preference. */
+export declare const DEFAULT_TERRAFORM_BINARY = "terraform";
+/** Fields every activity here takes: which root, and where the project is. */
+export interface TerraformRootArgs {
+    /**
+     * Key into `terraform.roots`. Not a directory — the directory, workspace,
+     * var files and backend config all come from the named entry, so an Op step
+     * cannot drift from what the project declared.
+     */
+    root: string;
+    /**
+     * Directory to start the `chant.config.*` search from. Default:
+     * `process.cwd()`, which is the project root under `chant run`.
+     */
+    cwd?: string;
+}
+export interface TerraformInitArgs extends TerraformRootArgs {
+    /** `-upgrade`: re-resolve provider and module versions within constraints. */
+    upgrade?: boolean;
+    /** `-reconfigure`: ignore any existing backend state and configure afresh. */
+    reconfigure?: boolean;
+}
+export interface TerraformPlanArgs extends TerraformRootArgs {
+    /** Plan file to write, relative to the root directory. Default: {@link DEFAULT_PLAN_FILE}. */
+    planFile?: string;
+    /** `-destroy`: plan the removal of everything the root manages. */
+    destroy?: boolean;
+}
+export interface TerraformApplyArgs extends TerraformRootArgs {
+    /**
+     * The saved plan file to apply, relative to the root directory — normally
+     * `plan.out.planFile`, the Plan step's own output. Required: this activity
+     * has no bare-apply mode.
+     */
+    planFile: string;
+}
+export interface TerraformShowArgs extends TerraformRootArgs {
+    /** Show this saved plan file. Omitted, the activity shows current state. */
+    planFile?: string;
+}
+/** What {@link terraformInit} resolved. */
+export interface TerraformInitResult {
+    /** Absolute path of the root module directory that was initialized. */
+    dir: string;
+    /** Workspace the run selected via `TF_WORKSPACE`, when the root names one. */
+    workspace?: string;
+}
+/** Counts projected out of a plan's `resource_changes`. */
+export interface PlanChangeCounts {
+    /** Resources to create. A replace counts here and in `destroys`, as terraform's own summary does. */
+    adds: number;
+    /** Resources to update in place. */
+    changes: number;
+    /** Resources to destroy. This is the number an approval gate exists for. */
+    destroys: number;
+}
+/** What {@link terraformPlan} resolved. Carries the plan itself, so no later step re-plans. */
+export interface TerraformPlanResult extends PlanChangeCounts {
+    /** `true` when terraform reported exit 2 under `-detailed-exitcode`: the plan proposes changes. */
+    changed: boolean;
+    /** The written plan file, relative to `dir` — hand this straight to {@link terraformApply}. */
+    planFile: string;
+    /** Absolute path of the root module directory. */
+    dir: string;
+    /** `terraform show -json <planFile>`, parsed. */
+    json: unknown;
+    /** `terraform show -no-color <planFile>` — the human-readable plan. */
+    text: string;
+}
+/** What {@link terraformApply} resolved. */
+export interface TerraformApplyResult {
+    /** The plan file that was applied. */
+    planFile: string;
+    /** Absolute path of the root module directory. */
+    dir: string;
+    /** Always `true` on success; the activity throws otherwise. */
+    applied: boolean;
+}
+/** What {@link terraformShow} resolved. */
+export interface TerraformShowResult extends PlanChangeCounts {
+    /** Whether the output describes a saved plan or current state. */
+    source: "plan" | "state";
+    /** The `-json` output, parsed. */
+    json: unknown;
+    /** The `-no-color` output. */
+    text: string;
+    /** Absolute path of the root module directory. */
+    dir: string;
+    /** Present when `source` is `"plan"`. */
+    planFile?: string;
+}
+/**
+ * Quote a command-line argument for the shell `exec` runs it through, leaving
+ * ordinary paths and `key=value` pairs untouched so command strings stay
+ * readable in logs and in tests.
+ */
+export declare function quoteArg(value: string): string;
+/** Which CLI drives the roots: `terraform.binary`, defaulting to `terraform`. */
+export declare function terraformBinary(config?: TerraformConfig): string;
+/**
+ * Environment for every invocation. `TF_IN_AUTOMATION` suppresses the
+ * "run terraform apply next" hand-holding and is terraform's own signal that
+ * no human is watching; `TF_WORKSPACE` is how a workspace gets selected
+ * without a separate `terraform workspace select` round-trip.
+ */
+export declare function terraformEnvironment(root?: Pick<TerraformRootConfig, "workspace">): Record<string, string>;
+/** `terraform init`, with the root's `backendConfig` as `-backend-config=k=v` flags. */
+export declare function terraformInitCommand(opts: {
+    binary: string;
+    backendConfig?: Record<string, string>;
+    upgrade?: boolean;
+    reconfigure?: boolean;
+}): string;
+/**
+ * `terraform plan`. `-detailed-exitcode` is what makes the run answerable:
+ * 0 means no changes, 2 means changes, and anything else is a failure. See
+ * {@link terraformPlan}.
+ */
+export declare function terraformPlanCommand(opts: {
+    binary: string;
+    planFile: string;
+    varFiles?: string[];
+    destroy?: boolean;
+}): string;
+/** `terraform apply <planFile>` — a saved plan, never a bare apply. */
+export declare function terraformApplyCommand(opts: {
+    binary: string;
+    planFile: string;
+}): string;
+/**
+ * `terraform show`. The one command here that takes no `-input` flag
+ * (terraform answers `flag provided but not defined: -input`), so automation
+ * rests on `TF_IN_AUTOMATION` alone. Show reads an artifact and prompts for
+ * nothing in the first place.
+ */
+export declare function terraformShowCommand(opts: {
+    binary: string;
+    json: boolean;
+    planFile?: string;
+}): string;
+/**
+ * Project a plan's `resource_changes` into add/change/destroy counts, the same
+ * three terraform prints at the end of a plan. A replace (`["delete","create"]`)
+ * counts as one add and one destroy, exactly as terraform reports it.
+ */
+export declare function countPlanChanges(planJson: unknown): PlanChangeCounts;
+/**
+ * `terraform init` in the named root, with the root's `backendConfig` supplied
+ * as `-backend-config` flags. Uses the longInfra profile: init downloads
+ * providers and modules, a network call of unpredictable size.
+ */
+export declare function terraformInit(args: TerraformInitArgs, signal?: AbortSignal): Promise<TerraformInitResult>;
+/**
+ * `terraform plan -detailed-exitcode -out=<planFile>` in the named root, then
+ * `terraform show` over the written plan in both `-json` and `-no-color` form.
+ *
+ * The exit code is the answer, not an error condition: 0 is a plan with no
+ * changes, 2 is a plan with changes, and anything else, 1 included, is a
+ * failure thrown with terraform's own stderr attached. Both `show` renders
+ * come back with the result, so a gate, a report or an apply downstream reads
+ * the plan that ran instead of planning again against a moved world.
+ *
+ * Uses the longInfra profile: plan refreshes every resource against its
+ * provider.
+ */
+export declare function terraformPlan(args: TerraformPlanArgs, signal?: AbortSignal): Promise<TerraformPlanResult>;
+/**
+ * `terraform apply <planFile>` in the named root. A saved plan only: without
+ * one, apply re-plans at apply time and acts on something no gate ever saw,
+ * so a missing `planFile` is refused here rather than quietly widened into a
+ * bare apply.
+ *
+ * Uses the longInfra profile.
+ */
+export declare function terraformApply(args: TerraformApplyArgs, signal?: AbortSignal): Promise<TerraformApplyResult>;
+/**
+ * `terraform show` over current state, or over a saved plan when `planFile` is
+ * given. Returns the parsed `-json` output and the `-no-color` render, plus
+ * the add/change/destroy counts when the subject is a plan. State has no
+ * change set, so for state the three counts are zero.
+ *
+ * Uses the fastIdempotent profile: show reads an artifact and calls no
+ * provider.
+ */
+export declare function terraformShow(args: TerraformShowArgs, signal?: AbortSignal): Promise<TerraformShowResult>;
+//# sourceMappingURL=terraform.d.ts.map

package/dist/op/activities/terraform.d.ts.map

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

package/dist/op/builders.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities, copied from
+ * `lexicons/k3s/src/op/builders.ts` (chant #1288 Stage 2). `opts`'s type in
+ * each wrapper below IS the activity's own `*Args` interface, via
+ * `Omit`/`WithStepRefs`, never restated: rename a field on the activity and
+ * the builder's callers stop compiling.
+ *
+ * The `root` key is positional in every wrapper, because naming the root is
+ * the one thing a terraform step cannot be authored without.
+ *
+ * `id` routes to the step's `id` field rather than into `args`. That matters
+ * here more than anywhere else in the lexicon: `.out` throws without an id
+ * (`packages/core/src/op/builders.ts`), and `.out` is how an Apply step names
+ * the Plan step's `planFile` as a `StepOutputRef` instead of guessing the
+ * path a second time.
+ */
+import { type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
+import type { TerraformInitArgs, TerraformPlanArgs, TerraformApplyArgs, TerraformShowArgs } from "./activities/terraform.js";
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = {
+    profile?: ActivityStep["profile"];
+    id?: string;
+};
+/**
+ * `terraform init` in the named root — the fully typed twin of the
+ * `terraformInit` activity. `opts` is {@link TerraformInitArgs} itself, minus
+ * the positional `root`. Defaults to the `longInfra` profile: init downloads
+ * providers.
+ */
+export declare const terraformInit: (root: string, opts?: WithStepRefs<Omit<TerraformInitArgs, "root">> & StepOpts) => NamedActivityStep;
+/**
+ * `terraform plan` in the named root, writing a saved plan. `opts` is
+ * {@link TerraformPlanArgs} itself, minus the positional `root`. Defaults to
+ * the `longInfra` profile: plan refreshes every resource against its provider.
+ *
+ * Give this step an `id` when a later step applies its plan — `plan.out.planFile`
+ * is the reference an Apply step takes.
+ */
+export declare const terraformPlan: (root: string, opts?: WithStepRefs<Omit<TerraformPlanArgs, "root">> & StepOpts) => NamedActivityStep;
+/**
+ * `terraform apply <planFile>` in the named root — the fully typed twin of the
+ * `terraformApply` activity. `opts` is {@link TerraformApplyArgs} itself,
+ * minus the positional `root`, so `planFile` stays required at the call site
+ * and the activity's bare-apply refusal is a compile error rather than a
+ * runtime one. Defaults to the `longInfra` profile.
+ */
+export declare const terraformApply: (root: string, opts: WithStepRefs<Omit<TerraformApplyArgs, "root">> & StepOpts) => NamedActivityStep;
+/**
+ * `terraform show` in the named root, over state or over a saved plan. `opts`
+ * is {@link TerraformShowArgs} itself, minus the positional `root`. Defaults
+ * to the `fastIdempotent` profile: show reads an artifact and calls no
+ * provider.
+ */
+export declare const terraformShow: (root: string, opts?: WithStepRefs<Omit<TerraformShowArgs, "root">> & StepOpts) => NamedActivityStep;
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,kFAAkF;AAClF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,OAAO,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,OAAO,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,MAAM,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,OAAO,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC"}

package/dist/package-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=package-cli.d.ts.map

package/dist/package-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-cli.d.ts","sourceRoot":"","sources":["../src/package-cli.ts"],"names":[],"mappings":""}

package/dist/plugin.d.ts

@@ -0,0 +1,11 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+/**
+ * terraform lexicon plugin.
+ *
+ * There is no upstream schema to pin here: Terraform's resource surface lives
+ * in provider registries, one schema per provider, and this lexicon reads the
+ * HCL an estate already has rather than generating types for it. So `spec/`
+ * and `codegen/` stay near-empty and there is no `upstreamPin`.
+ */
+export declare const terraformPlugin: LexiconPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAwB9D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,aA4H7B,CAAC"}

package/dist/rules/plan-before-apply.ts

@@ -0,0 +1,143 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * TF101: terraformApply's planFile must reference a preceding terraformPlan step.
+ *
+ * Applying a plan file chosen by a string means the applied plan can be
+ * stale, hand-edited, or simply the wrong one — the entire point of the
+ * plan/apply split (review exactly what will change, then apply exactly
+ * that) is defeated the moment the path is spelled out in source instead of
+ * carried forward from the `terraformPlan` step that produced it.
+ *
+ * The two builders this rule is written against (`terraformPlan`,
+ * `terraformApply`) don't exist yet (#2086 ships them in parallel), so this
+ * matches purely on callee identifier name — same posture as
+ * `lexicons/k3s/src/lint/rules/token-literal.ts`.
+ *
+ * Accepts exactly the two authoring forms that produce a genuine step-output
+ * reference (`packages/core/src/op/step-output-ref.ts`):
+ *   - `stepOutput(<ident>, "planFile")`
+ *   - `<ident>.out.planFile`
+ * where `<ident>` is bound (`const <ident> = terraformPlan(...)`) in the same
+ * file. Flags a string literal, a template literal, or one of the two
+ * accepted reference forms pointing at an identifier that resolves to
+ * something other than a `terraformPlan` call. When `<ident>` cannot be
+ * resolved at all (not declared anywhere in the file), this rule stays
+ * silent — the same deliberately shallow "bail rather than guess" posture
+ * `validateStepOutputRefs` takes, since the runtime brand on a real
+ * `StepOutputRef` is invisible to a source-level AST match.
+ */
+export const planBeforeApplyRule: LintRule = {
+  id: "TF101",
+  severity: "error",
+  category: "correctness",
+  description: "terraformApply's planFile must reference a preceding terraformPlan step",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    /** Identifier name bound to a `terraformPlan(...)` call, to whether it truly is one. */
+    const bindings = new Map<string, boolean>();
+
+    const calleeName = (expr: ts.Expression): string | undefined =>
+      ts.isIdentifier(expr) ? expr.text : ts.isPropertyAccessExpression(expr) ? expr.name.text : undefined;
+
+    const collectBindings = (node: ts.Node) => {
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+        const init = node.initializer;
+        if (ts.isCallExpression(init) || ts.isNewExpression(init)) {
+          bindings.set(node.name.text, calleeName(init.expression) === "terraformPlan");
+        }
+      }
+      ts.forEachChild(node, collectBindings);
+    };
+    collectBindings(source);
+
+    const flag = (node: ts.Node, message: string) => {
+      const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+      diagnostics.push({
+        ruleId: "TF101",
+        severity: "error",
+        message,
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+      });
+    };
+
+    /**
+     * `stepOutput(<ident>, "planFile")` or `<ident>.out.planFile`, returning
+     * the referenced identifier's name, or `undefined` if `initializer`
+     * isn't one of those two shapes.
+     */
+    const referencedIdent = (initializer: ts.Expression): string | undefined => {
+      if (ts.isCallExpression(initializer) && calleeName(initializer.expression) === "stepOutput") {
+        const arg = initializer.arguments[0];
+        return arg && ts.isIdentifier(arg) ? arg.text : undefined;
+      }
+      if (
+        ts.isPropertyAccessExpression(initializer) &&
+        initializer.name.text === "planFile" &&
+        ts.isPropertyAccessExpression(initializer.expression) &&
+        initializer.expression.name.text === "out" &&
+        ts.isIdentifier(initializer.expression.expression)
+      ) {
+        return initializer.expression.expression.text;
+      }
+      return undefined;
+    };
+
+    const checkPlanFile = (obj: ts.ObjectLiteralExpression) => {
+      for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const name = ts.isIdentifier(prop.name)
+          ? prop.name.text
+          : ts.isStringLiteral(prop.name)
+            ? prop.name.text
+            : undefined;
+        if (name !== "planFile") continue;
+
+        const value = prop.initializer;
+        if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value) || ts.isTemplateExpression(value)) {
+          flag(
+            value,
+            "`planFile` is a literal path in source. Pass the preceding `terraformPlan` step's output " +
+              '(`stepOutput(plan, "planFile")` or `plan.out.planFile`), not a hardcoded path.',
+          );
+          continue;
+        }
+
+        const ident = referencedIdent(value);
+        if (ident === undefined) continue; // not one of the two accepted forms — out of this rule's reach
+        const isPlan = bindings.get(ident);
+        if (isPlan === false) {
+          flag(
+            value,
+            `\`planFile\` references "${ident}", which is not bound to a \`terraformPlan(...)\` call. ` +
+              "Apply only a plan this Op itself produced.",
+          );
+        }
+        // isPlan === true: paired correctly.
+        // isPlan === undefined: `ident` isn't declared anywhere in this file — cannot resolve
+        // statically, so stay silent rather than guess.
+      }
+    };
+
+    const visit = (node: ts.Node) => {
+      if (ts.isCallExpression(node) && calleeName(node.expression) === "terraformApply") {
+        // The options object may be the first argument (`terraformApply({ planFile })`)
+        // or follow a positional one (`terraformApply("app", { planFile })`, the
+        // k3s-shaped builder signature); inspect every object-literal argument.
+        for (const arg of node.arguments) {
+          if (ts.isObjectLiteralExpression(arg)) checkPlanFile(arg);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/dist/rules/tf001.ts

@@ -0,0 +1,66 @@
+/**
+ * TF001: a root module keeps its state on local disk.
+ *
+ * A `terraform` block with no `backend "<type>"` and no `cloud {}` falls back
+ * to the local backend, which puts `terraform.tfstate` in the working
+ * directory. That file holds every attribute of every managed resource,
+ * secrets included, and it is not shared, not locked, and not versioned. The
+ * first apply from a second machine or a CI runner starts from an empty state
+ * and proposes to create the estate again.
+ *
+ * One diagnostic per root, fired from the root's `terraform` block. A root
+ * with no `terraform` block at all is not flagged: it declares no version
+ * constraints either, and the missing block is a different finding.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { TERRAFORM_TYPE, type BlockBody } from "../../hcl/parse";
+
+/** `backend`/`cloud` are blocks, so hcl2json encodes them as a value under the key. */
+function hasBlock(body: BlockBody, key: string): boolean {
+  const value = body[key];
+  if (value === undefined || value === null) return false;
+  if (Array.isArray(value)) return value.length > 0;
+  return typeof value === "object" ? Object.keys(value as object).length > 0 : true;
+}
+
+export const tf001: PostSynthCheck = {
+  id: "TF001",
+  description: "Root module declares no remote backend",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    /** Root name to the entity key of the first `terraform` block seen for it. */
+    const flagged = new Set<string>();
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== TERRAFORM_TYPE) continue;
+      if (!isResourceDeclarable(entity)) continue;
+      const props = entity.props as { root?: unknown; body?: unknown };
+      const root = typeof props.root === "string" ? props.root : "";
+      if (flagged.has(root)) continue;
+
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      if (hasBlock(body, "backend") || hasBlock(body, "cloud")) continue;
+
+      flagged.add(root);
+      diagnostics.push({
+        checkId: "TF001",
+        severity: "warning",
+        message:
+          `Root module "${root}" declares no remote backend. State falls back to a local ` +
+          "terraform.tfstate, which is unshared, unlocked and holds every resource attribute in " +
+          'plaintext. Add a `backend "<type>"` or a `cloud {}` block to the terraform block.',
+        entity: name,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/serializer.d.ts

@@ -0,0 +1,19 @@
+import type { Serializer } from "@intentius/chant";
+/**
+ * terraform serializer.
+ *
+ * A stub, deliberately. The entities this lexicon carries come from `.tf`
+ * files that already exist on disk (`buildRoots()` parses the roots named in
+ * `terraform.roots`), so there is nothing for chant to write back: emitting
+ * HCL here would put a second, generated copy of the estate beside the
+ * authored one. The lexicon's value is what the entities let the rest of
+ * chant do with the root (post-synth checks, `chant audit`, the Op surface),
+ * not a rendered artifact.
+ *
+ * `name` and `rulePrefix` are the two members the `Serializer` contract
+ * requires, and both are load-bearing: `name` is the key `build()` files this
+ * lexicon's output under, and `rulePrefix` is what every `TF*` id is checked
+ * against.
+ */
+export declare const terraformSerializer: Serializer;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAOjC,CAAC"}

package/dist/skills/chant-terraform.md

@@ -0,0 +1,92 @@
+---
+skill: chant-terraform
+description: Read an existing Terraform root module into chant's build and audit, and drive it with the init/plan/apply Ops
+user-invocable: true
+---
+
+# Terraform as an Existing Estate
+
+## What this lexicon covers
+
+There is no generated resource surface here, and nothing is written back over the HCL. Terraform's own `.tf` files stay the only source of truth, and `terraform apply` keeps working exactly as before. What chant adds is: one entity per HCL block, read at build time, so the post-synth checks and `chant audit` have something to see; and Op activities that drive `init`/`plan`/`apply`/`show` against a saved plan.
+
+## Naming your roots
+
+Add the `terraform` namespace to `chant.config.ts`. Importing the package brings the key into `ChantConfig`.
+
+```ts
+import type { ChantConfig } from "@intentius/chant/config";
+import "@intentius/chant-lexicon-terraform";
+
+export default {
+  lexicons: ["terraform"],
+  terraform: {
+    binary: "terraform", // or "tofu" — the two are wire-compatible for everything this lexicon does
+    roots: {
+      app: { dir: "./terraform/app", workspace: "prod", varFiles: ["prod.tfvars"] },
+    },
+  },
+} satisfies ChantConfig;
+```
+
+`dir` is the only required field, resolved against the project root (where `chant.config.ts` lives), not against the cwd a step happens to run from. The root's name (`app` above) is the entity-key prefix and the string every Op step and builder takes as `root` — keep it stable once other declarations reference it.
+
+## What a build produces
+
+Every block of every configured root becomes one entity, keyed `<root>/<address>`: `terraform { }` -> `Terraform::Terraform`, `provider "x" {}` -> `Terraform::Provider`, `resource "x" "y" {}` -> `Terraform::Resource`, `data "x" "y" {}` -> `Terraform::Data`, `module "x" {}` -> `Terraform::Module`, `variable "x" {}` -> `Terraform::Variable`, `output "x" {}` -> `Terraform::Output`, `locals {}` -> `Terraform::Locals`. Each carries `props.address`, `props.body` (the block, verbatim), `props.file` and `props.root`. A root whose `dir` doesn't exist, or whose HCL the parser refuses, warns and contributes no entities — the rest of the build is unaffected.
+
+## The one thing to check before anything else
+
+`TF001` fires once per root whose `terraform` block declares neither a `backend "<type>"` nor a `cloud {}`. That root's state is a local `terraform.tfstate`: unshared, unlocked, holding every resource attribute in plaintext. Add a real backend before anything else touches this root:
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket = "acme-tfstate"
+    key    = "app/terraform.tfstate"
+    region = "us-east-1"
+  }
+}
+```
+
+`TF101` is the second rule, and it's about the Ops below: a `terraformApply` step's `planFile` must reference the output of a preceding `terraformPlan` step (`plan.out.planFile`), never a literal path. Applying an unreviewed plan, or a plan somebody hand-edited on disk, is exactly what a saved-plan discipline exists to prevent.
+
+## Driving a root with an Op
+
+`TerraformApplyOp` is Init, Plan, an optional approval Gate, then Apply — Init and Plan on the `longInfra` profile, the Gate's `show` step on `fastIdempotent`:
+
+```ts
+import { TerraformApplyOp } from "@intentius/chant-lexicon-terraform";
+
+export const { op } = TerraformApplyOp({
+  name: "app-apply",
+  root: "app",
+  gate: "on-destroy", // default — "always" gates every apply, "never" drops the Gate phase entirely
+});
+```
+
+`gate: "never"` is what makes the Op runnable under the local executor (`chant run`); any other mode emits a Gate phase, and a gate is durable-runtime work the local executor refuses. The Gate phase always shows the saved plan first and reports its `destroys` count as a `Destroys` search attribute, because `GateStep` carries no condition to branch on at build time — the approver sees what's at stake before approving, rather than the Op deciding for them.
+
+Terraform has no automatic rollback, so `compensate: true` with no command throws at build time, naming the Op, rather than warning once an apply has already half-run:
+
+```ts
+export const { op } = TerraformApplyOp({
+  name: "app-apply-gated",
+  root: "app",
+  gate: "always",
+  compensate: { command: "terraform destroy -auto-approve" },
+});
+```
+
+Reach for the four builders directly (`terraformInit`, `terraformPlan`, `terraformApply`, `terraformShow`) when a phase shape other than Init/Plan/Gate/Apply is needed — `plan.out.planFile` is how a later step references an earlier Plan step's saved output, and it only resolves when the Plan step carries an `id`.
+
+## Where a running estate's ownership answer lives
+
+Terraform's own state file is the ownership answer for what it manages — this lexicon doesn't add a second one. See the lexicon's "Live Observation" doc page for how a scheduled watch reads that state.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| TF001 | error (post-synth) | root module declares no remote backend |
+| TF101 | error | `terraformApply`'s `planFile` isn't a preceding `terraformPlan` step's output |

package/dist/state-ownership.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Terraform's ownership channel (#2087): the state file.
+ *
+ * Its own module, and a tiny one, for the same reason cedar's
+ * `src/avp/ownership.ts` is: `plugin.ts` declares `ownershipChannel` eagerly
+ * while `describeResources` is behind a dynamic import, so the keys cannot
+ * live in the reader without dragging the reader (and `node:child_process`
+ * with it) into every plugin load.
+ *
+ * The design record is the module doc of `./describe-resources.ts` and the
+ * reader-facing version is `docs/pages/observation.mdx`. The short form:
+ * chant elsewhere answers "is this mine?" from a marker it stamped onto the
+ * live resource; terraform answers it from the state file, which already
+ * records exactly which addresses a configuration manages. Nothing is ever
+ * stamped, so nothing is ever written back over an estate's own tags.
+ */
+import type { ChannelKeys } from "@intentius/chant/ownership";
+/**
+ * Where the verdict is read from, rather than what is written.
+ *
+ * {@link ChannelKeys} names tag or label keys everywhere else, because
+ * everywhere else the marker is a key/value pair on the resource. These three
+ * name the state file, the configured root that owns that state, and the
+ * workspace the root selects.
+ */
+export declare const TERRAFORM_STATE_OWNERSHIP_KEYS: ChannelKeys;
+//# sourceMappingURL=state-ownership.d.ts.map