@intentius/chant-lexicon-terraform 0.57.0

package/README.md

@@ -0,0 +1,53 @@
+# @intentius/chant-lexicon-terraform
+
+Terraform lexicon plugin for [chant](https://github.com/intentius/chant).
+
+Unlike the lexicons that generate typed resource classes from an upstream
+schema, this one reads the HCL an estate already has. Name your root modules in
+`chant.config.ts` and each `.tf` block joins the build as an entity, so the
+post-synth checks and `chant audit` can see the root without anything being
+written back over it.
+
+```ts
+// chant.config.ts
+import type { ChantConfig } from "@intentius/chant/config";
+import "@intentius/chant-lexicon-terraform";
+
+export default {
+  lexicons: ["terraform"],
+  terraform: {
+    binary: "terraform", // or "tofu"
+    roots: {
+      app: { dir: "./terraform", workspace: "prod", varFiles: ["prod.tfvars"] },
+    },
+  },
+} satisfies ChantConfig;
+```
+
+`dir` resolves against the project root, the directory holding
+`chant.config.ts`. A root that does not exist, or a `.tf` the parser refuses, is
+a build warning and no entities for that root, never a failure.
+
+## Getting started
+
+```bash
+# Assemble dist/ (there is no upstream spec to fetch)
+npm run bundle
+
+# Validate the generated artifacts
+just validate
+
+# Generate the docs site
+just docs
+```
+
+## Project structure
+
+- `src/plugin.ts`, the LexiconPlugin, including the `buildRoots()` hook
+- `src/config.ts`, the `terraform` config namespace and its `ChantConfig` augmentation
+- `src/hcl/parse.ts`, one entity per HCL block, from a directory or from `chant audit`'s joined-file form
+- `src/hcl/roots.ts`, the per-root render `buildRoots()` delegates to
+- `src/serializer.ts`, a deliberate no-op: the `.tf` files are the artifact
+- `src/lint/rules/`, source-level lint rules
+- `src/lint/post-synth/`, checks over the parsed roots (TF001 and up)
+- `src/lsp/`, LSP completions and hover

package/dist/codegen/docs-cli.d.ts

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

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

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

package/dist/codegen/docs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function generateDocs(options?: {
+    verbose?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/codegen/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjF"}

package/dist/codegen/generate-cli.d.ts

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

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

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

package/dist/codegen/generate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { GenerateResult } from "@intentius/chant/codegen/generate";
+/** Filename of the generated registry, read back by `../validate.ts`. */
+export declare const LEXICON_JSON_FILENAME = "lexicon-terraform.json";
+export declare function generate(options?: {
+    verbose?: boolean;
+    force?: boolean;
+}): Promise<GenerateResult>;
+/**
+ * Write generated files to the package directory.
+ */
+export declare function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/codegen/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/codegen/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAIxE,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAY9D,wBAAsB,QAAQ,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAgBxG;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAWjF"}

package/dist/codegen/package.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Package the terraform lexicon for distribution.
+ */
+export declare function packageLexicon(options?: {
+    verbose?: boolean;
+    force?: boolean;
+}): Promise<{
+    spec: import("packages/core/src").BundleSpec;
+    stats: {
+        resources: number;
+        properties: number;
+        enums: number;
+        ruleCount: number;
+        skillCount: number;
+    };
+}>;
+//# sourceMappingURL=package.d.ts.map

package/dist/codegen/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/codegen/package.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;;;;;;;;;GAoBpF"}

package/dist/composites/terraform-apply-op.d.ts

@@ -0,0 +1,88 @@
+/**
+ * TerraformApplyOp composite (#2086) — init, plan, approve, apply for one root
+ * module named in `terraform.roots`.
+ *
+ * Authority stays with terraform: chant runs the binary, reads its plan, and
+ * hands the same saved plan to apply. The Apply step never re-plans, because
+ * it takes the Plan step's own `planFile` as a `StepOutputRef` — whatever was
+ * approved is what runs.
+ *
+ * Phases: Init, Plan, Gate, Apply.
+ *
+ * The gate is durable-runtime work, so an Op that emits one needs Temporal;
+ * `packages/core/src/op/local-executor.ts` refuses any Op containing a gate.
+ * `gate: "never"` is what makes the Op runnable with `chant run` locally.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformApplyOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * export const { op } = TerraformApplyOp({ name: "app-apply", root: "app" });
+ * ```
+ */
+import { OpResource } from "@intentius/chant/op";
+/**
+ * When to pause for a human before applying.
+ *
+ * `GateStep` (`packages/core/src/op/types.ts`) carries a signal name, a
+ * timeout and a description, and nothing conditional — so `"on-destroy"`
+ * cannot branch at build time on a count the plan only produces at run time.
+ * The workable v1 is that `"on-destroy"` and `"always"` emit the same Gate
+ * phase, and the approver is told what is at stake instead: the phase reports
+ * the plan's `destroys` count as the `Destroys` search attribute before it
+ * waits, and the gate description says so. A gate that skips itself when the
+ * plan turns out additive is a new step kind, out of scope here.
+ */
+export type TerraformGateMode = "on-destroy" | "always" | "never";
+export interface TerraformApplyOpConfig {
+    /** Op name (kebab-case). Also the default task queue and gate signal suffix. */
+    name: string;
+    /** Key into the project's `terraform.roots`. The root carries dir, workspace, var files and backend config. */
+    root: string;
+    /** Plan file written by Plan and consumed by Apply, relative to the root dir. Default: `chant.tfplan`. */
+    planFile?: string;
+    /**
+     * When to emit the approval gate. Default: `"on-destroy"`. See
+     * {@link TerraformGateMode} for why `"on-destroy"` and `"always"` build the
+     * same phase.
+     */
+    gate?: TerraformGateMode;
+    /** Gate signal name. Default: `approve-<name>`, as `ApplyOp` does. */
+    signalName?: string;
+    /** Temporal duration the gate waits before timing out. Default: core's own (48h). */
+    gateTimeout?: string;
+    /** Override the gate description shown to the approver. */
+    gateDescription?: string;
+    /** `-upgrade` on the Init step: re-resolve provider and module versions. */
+    upgrade?: boolean;
+    /**
+     * Directory each step starts the `chant.config.*` search from, which is
+     * what `terraform.roots` and the root's relative `dir` resolve against.
+     * Default: the running process's cwd, which is the project root under
+     * `chant run`.
+     */
+    cwd?: string;
+    /**
+     * Saga-style rollback on a failed apply, run as an `onFailure` phase.
+     *
+     * Terraform has no automatic rollback: a half-applied plan is undone by
+     * planning and applying the inverse, which is a decision about the estate
+     * rather than something chant can synthesize. So compensation here is
+     * total or refused, the same stance `ApplyOp` takes (`lexicons/temporal/src/
+     * composites/apply-op.ts`) — `true`, or an object with no `command`, throws
+     * when the Op is built, naming the Op, rather than warning at the moment a
+     * rollback is already needed. Supply `compensate: { command: "..." }` with a
+     * rollback of your own, or leave it unset.
+     */
+    compensate?: boolean | {
+        command?: string;
+    };
+    /** Override the task queue. Defaults to `name`. */
+    taskQueue?: string;
+}
+export interface TerraformApplyOpResources {
+    /** Op resource — generates the Init/Plan/[Gate]/Apply workflow. */
+    op: InstanceType<typeof OpResource>;
+}
+export declare function TerraformApplyOp(config: TerraformApplyOpConfig): TerraformApplyOpResources;
+//# sourceMappingURL=terraform-apply-op.d.ts.map

package/dist/composites/terraform-apply-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAA6B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAS5E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAqE1F"}

package/dist/composites/terraform-watch-op.d.ts

@@ -0,0 +1,124 @@
+/**
+ * TerraformWatchOp composite (#2087): drift reporting for one root module,
+ * on a schedule.
+ *
+ * The observe position on the lifecycle dial. `TerraformApplyOp` next door
+ * changes the estate; this one never does: it inits, plans, and reports what
+ * the plan found. `terraform plan -detailed-exitcode` is the whole mechanism.
+ * Exit 0 is "the world matches the configuration", exit 2 is drift, and
+ * `terraformPlan` turns that into the boolean `changed`, which rides out of
+ * the Op as the `Drift` search attribute.
+ *
+ * Phases: Init, Plan, and (for a finding mode that opens something) Report.
+ *
+ * ## Only the human plan is ever posted
+ *
+ * `terraformPlan` returns two renders of the same plan: `json`, from
+ * `terraform show -json`, and `text`, from `terraform show -no-color`. The
+ * JSON one carries every resource attribute value the plan touches, including
+ * provider credentials that no `sensitive` marking covers, because
+ * `sensitive_values` describes the configuration's own declarations rather
+ * than everything a provider puts in a plan. So the issue and pull-request
+ * modes reference `plan.out.text` and nothing else. There is no option to
+ * post the JSON, and `terraform-watch-op.test.ts` asserts no reference to it
+ * reaches the finding step.
+ *
+ * ## Findings reuse `reconcilePr`
+ *
+ * `issue` and `pull-request` call the temporal lexicon's `reconcilePr`
+ * activity, the one place in chant that shells to `gh issue create` /
+ * `gh pr create`, rather than growing a second copy of those calls here.
+ * That activity built its own change-set summary and had no way to be handed
+ * one, so #2087 added a single field to it (`ReconcilePrArgs.body`), which is
+ * what carries the `-no-color` plan through. Note that the pull-request mode
+ * of `reconcilePr` regenerates chant TypeScript via `chant import`; a
+ * terraform-native regeneration of HCL from live state is #2089, so until
+ * then `findingMode: "issue"` is the mode with an end-to-end answer and
+ * `"pull-request"` opens a PR whose body is the plan.
+ *
+ * ## The schedule
+ *
+ * A cron makes this a `{ op, schedule }` pair, the shape
+ * `lexicons/temporal/src/composites/workflow-audit-op.ts` and
+ * `reconcile-op.ts` return. The schedule resource is `Temporal::Schedule`,
+ * built here through core's own `createResource` rather than imported from
+ * `@intentius/chant-lexicon-temporal`: no lexicon in this repo imports
+ * another lexicon's package at runtime, and a static import would mean a
+ * project that installs terraform and runs `chant run` on the local executor
+ * could not load `@intentius/chant-lexicon-terraform` at all without also
+ * installing temporal. The declarable is the same one temporal's
+ * `TemporalSchedule` produces (`createResource("Temporal::Schedule",
+ * "temporal", {})`, `lexicons/temporal/src/resources.ts`), so temporal's
+ * serializer renders it unchanged when a project has both.
+ *
+ * A project with no Temporal at all runs the same Op on a CI cron instead:
+ * `generateOpsPipeline` against the github lexicon turns the Op plus its cron
+ * into a workflow. `examples/scheduled-watch/` is that recipe.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformWatchOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * // one-shot, local executor: chant run app-watch
+ * export const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
+ *
+ * // nightly, opening an issue when the plan is non-empty
+ * export const { op, schedule } = TerraformWatchOp({
+ *   name: "app-watch",
+ *   root: "app",
+ *   schedule: "0 6 * * *",
+ *   findingMode: "issue",
+ * });
+ * ```
+ */
+import { OpResource } from "@intentius/chant/op";
+import type { Declarable } from "@intentius/chant/declarable";
+/**
+ * What to do with a non-empty plan. A subset of core's `OpFindingMode`
+ * (`packages/core/src/lexicon.ts`): `merge-request` is GitLab's spelling of
+ * `pull-request` and is produced by the CI generator, not chosen here.
+ */
+export type TerraformFindingMode = "report" | "issue" | "pull-request";
+export interface TerraformWatchOpConfig {
+    /** Op name (kebab-case). Also the default task queue and schedule id base. */
+    name: string;
+    /** Key into the project's `terraform.roots`. The root carries dir, workspace, var files and backend config. */
+    root: string;
+    /**
+     * Cron expression. When set, a `Temporal::Schedule` is returned alongside
+     * the Op; omit for one-shot `chant run` on the local executor, or for a CI
+     * cron built by `generateOpsPipeline`.
+     */
+    schedule?: string;
+    /**
+     * What to do when the plan proposes changes. Default: `"report"`, which
+     * opens nothing. The `Drift` search attribute and the run's own log are
+     * the report.
+     */
+    findingMode?: TerraformFindingMode;
+    /** Plan file the Plan step writes, relative to the root dir. Default: `chant.tfplan`. */
+    planFile?: string;
+    /** `-upgrade` on the Init step: re-resolve provider and module versions. */
+    upgrade?: boolean;
+    /**
+     * Directory each step starts the `chant.config.*` search from, which is
+     * what `terraform.roots` and the root's relative `dir` resolve against.
+     * Default: the running process's cwd, which is the project root under
+     * `chant run`. Same field, same meaning, as `TerraformApplyOpConfig.cwd`.
+     */
+    cwd?: string;
+    /** Issue / PR title. Default: `Terraform drift in root "<root>"`. */
+    title?: string;
+    /** Branch the pull-request mode opens from. Default: `reconcilePr`'s own. */
+    branch?: string;
+    /** Override the task queue. Defaults to `name`. */
+    taskQueue?: string;
+}
+export interface TerraformWatchOpResources {
+    /** Op resource. Generates the Init/Plan/[Report] workflow. */
+    op: InstanceType<typeof OpResource>;
+    /** `Temporal::Schedule`, present only when `schedule` was given. */
+    schedule?: Declarable;
+}
+export declare function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatchOpResources;
+//# sourceMappingURL=terraform-watch-op.d.ts.map

package/dist/composites/terraform-watch-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terraform-watch-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-watch-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,EAAa,UAAU,EAAqB,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,GAAG,cAAc,CAAC;AAcvE,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CA6D1F"}

package/dist/config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The `terraform` namespace in `chant.config.ts` (#1344).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-terraform";  // brings the `terraform` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["terraform"],
+ *   terraform: {
+ *     binary: "tofu",
+ *     roots: {
+ *       app: { dir: "./terraform/app", workspace: "prod", varFiles: ["prod.tfvars"] },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * One schema, three consumers: core validates the namespace against it at load,
+ * the type below is derived from it, and that derived type is what augments
+ * `ChantConfig`, so an unknown key fails at build time and at compile time for
+ * the same reason, rather than being silently ignored at both.
+ */
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+/**
+ * One Terraform root module chant reads. `dir` is the only required field:
+ * everything else names how the root is invoked rather than what it declares.
+ *
+ * `strictObject`, not `object`. Core applies `.strict()` to the top level of a
+ * declared namespace itself, but nested objects are the lexicon's own to make
+ * strict, and a root entry is exactly where a typo (`varfiles`) would
+ * otherwise land silently.
+ */
+export declare const terraformRootSchema: z.ZodObject<{
+    /** Root module directory, relative to the project root (where `chant.config.*` lives). */
+    dir: z.ZodString;
+    /** Terraform workspace to select for this root. Omitted means `default`. */
+    workspace: z.ZodOptional<z.ZodString>;
+    /** `-var-file` arguments, in order, relative to `dir`. */
+    varFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** `-backend-config` key/value pairs handed to `init`. */
+    backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export declare const terraformConfigSchema: z.ZodObject<{
+    /**
+     * Which CLI drives the roots. The two are wire-compatible for everything
+     * this lexicon does, so the choice is recorded rather than inferred.
+     */
+    binary: z.ZodOptional<z.ZodEnum<{
+        terraform: "terraform";
+        tofu: "tofu";
+    }>>;
+    /** Named root modules. The name is the entity-key prefix, so keep it stable. */
+    roots: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Root module directory, relative to the project root (where `chant.config.*` lives). */
+        dir: z.ZodString;
+        /** Terraform workspace to select for this root. Omitted means `default`. */
+        workspace: z.ZodOptional<z.ZodString>;
+        /** `-var-file` arguments, in order, relative to `dir`. */
+        varFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** `-backend-config` key/value pairs handed to `init`. */
+        backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TerraformRootConfig = z.infer<typeof terraformRootSchema>;
+export type TerraformConfig = z.infer<typeof terraformConfigSchema>;
+declare module "@intentius/chant/config" {
+    interface ChantConfig {
+        terraform?: TerraformConfig;
+    }
+}
+/**
+ * Compile-time proof that the augmentation above reaches `ChantConfig` (#1344).
+ *
+ * Without it this line is `Property 'terraform' does not exist on type
+ * 'ChantConfig'`, which is exactly the error a user's `chant.config.ts` gets.
+ * It lives here rather than in a test because the root tsconfig excludes test
+ * files from typechecking, so a compile-time claim asserted in one is checked
+ * by nothing.
+ */
+export type TerraformConfigNamespace = NonNullable<ChantConfig["terraform"]>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,0DAA0D;;kBAE1D,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;OAGG;;;;;IAEH,gFAAgF;;QAhBhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,0DAA0D;;;kBAY1D,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}

package/dist/describe-resources.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Live observation for declared terraform entities (#2087).
+ *
+ * `buildRoots()` turns each configured root module into one entity per HCL
+ * block, keyed `<root>/<address>` (`./hcl/parse.ts`). This reader answers the
+ * lifecycle question for those entities by running `terraform show -json` over
+ * the root's current state and matching addresses.
+ *
+ * ## The state file is the ownership answer
+ *
+ * Every other lexicon in chant stamps a tag or a label at synthesis and reads
+ * it back off the live resource. Terraform stamps nothing, and there is
+ * nowhere to stamp: a resource's provider-side tags are the practitioner's
+ * own, and writing chant's marker into them would edit an estate this lexicon
+ * promises never to write. What terraform has instead is the thing chant
+ * elsewhere refuses to host, a trusted state file that already records
+ * exactly which addresses this configuration manages.
+ *
+ * So the answer here is state membership. An address `terraform show -json`
+ * returns is `owned`; anything else is `unknown`. Concretely that makes a
+ * declared `module` block `unknown`: the state carries the module's
+ * resources, never a row for the block itself, so chant can see the block is
+ * live without the state ever saying that block is managed. `unknown` never
+ * escalates to a delete, which is the correct posture for a thing chant did
+ * not read a verdict for.
+ *
+ * That places terraform on the trusted-state-file row of the third axis in
+ * docs/src/content/docs/concepts/lifecycle-models.mdx, where chant elsewhere
+ * sits on the live-marker row. `docs/pages/observation.mdx` is the reader's
+ * version of this paragraph.
+ *
+ * ## What is readable at all
+ *
+ * `values.root_module.resources[]` (and, recursively, `child_modules[]`)
+ * carries `resource` and `data` blocks. A `terraform`, `provider`, `variable`,
+ * `output` or `locals` block has no row there and reads `unsupported-kind`.
+ * That is honest, not a gap to close by inventing an address for something
+ * that has none.
+ *
+ * ## Tri-state (#1089)
+ *
+ * A root whose `init` or `show` fails reports EVERY entity declared in that
+ * root as not-observed with reason `read-failed` and the root named, never
+ * absent. A failed read must never render as a list of creates. Roots are
+ * read independently and merged (`mergeObservations`), so one broken backend
+ * does not un-observe a root that answered.
+ *
+ * ## Nothing from `values` is surfaced
+ *
+ * A state row's `values` are the resource's full attribute set, secrets
+ * included, and `sensitive_values` describes only what the configuration
+ * declared sensitive. So the attributes reported here are the row's identity
+ * (address, type, mode, provider, root) and nothing from `values` except the
+ * `id`, which is the physical id every observation carries.
+ */
+import type { DescribeResourcesResult } from "@intentius/chant/lexicon";
+import { terraformInit, terraformShow } from "./op/activities/terraform.js";
+export { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
+/** One row out of `values.root_module.resources[]`, at any module depth. */
+export interface StateResourceRow {
+    /** Fully qualified terraform address, `module.<name>.` prefixes included. */
+    address: string;
+    /** `managed` for a `resource` block, `data` for a `data` block. */
+    mode?: string;
+    /** Resource type, e.g. `null_resource`. */
+    type?: string;
+    /** Provider that owns the row, e.g. `registry.terraform.io/hashicorp/null`. */
+    providerName?: string;
+    /** `values.id`, when the row carries a string id. Nothing else from `values` is read. */
+    id?: string;
+}
+/** What one root's state read produced. */
+export interface StateIndex {
+    /** Every resource/data row, keyed by fully qualified address. */
+    rows: Map<string, StateResourceRow>;
+    /** Every `module.<name>` address the state carries a child module for, at any depth. */
+    modules: Set<string>;
+}
+/**
+ * Index a `terraform show -json` document by address.
+ *
+ * Terraform already writes fully qualified addresses inside `child_modules`
+ * (`module.cdn.null_resource.edge`, as `src/__fixtures__/show-state.json`
+ * records), so the module prefix is applied only when a row's own address is
+ * missing it. Belt and braces for an older `format_version`, never a second
+ * `module.cdn.` on top of the first.
+ */
+export declare function indexStateResources(showJson: unknown): StateIndex;
+/**
+ * The ownership verdict for one declared address: `owned` when the state
+ * carries a row for it, `unknown` otherwise. Exported because it is the whole
+ * of terraform's ownership channel, and a channel with one rule deserves one
+ * function to point at.
+ */
+export declare function classifyStateOwnership(address: string, index: StateIndex): "owned" | "unknown";
+/** The activity pair this reader drives. Injectable so tests never run terraform. */
+export interface TerraformReadDeps {
+    init: typeof terraformInit;
+    show: typeof terraformShow;
+}
+export interface DescribeResourcesOptions {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    /**
+     * Restrict to state-backed entities (#1348). A withheld entity is
+     * `filtered`, never a silent drop into `absent`: a live module block still
+     * exists, chant just has no state row saying it is managed.
+     */
+    owned?: boolean;
+    /**
+     * Directory the activities start the `chant.config.*` search from. Default:
+     * the running process's cwd. Same meaning as `TerraformWatchOpConfig.cwd`.
+     */
+    cwd?: string;
+}
+/**
+ * Observe every declared terraform entity, one `init` + `show` per configured
+ * root. Roots are read independently, so a broken backend on one never
+ * un-observes another (`mergeObservations`).
+ */
+export declare function describeResources(options: DescribeResourcesOptions, deps?: TerraformReadDeps): Promise<DescribeResourcesResult>;
+//# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAUxE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAMzE,OAAO,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AAEnE,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACpC,wFAAwF;IACxF,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACtB;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CA6BjE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAE9F;AASD,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,aAAa,CAAC;IAC3B,IAAI,EAAE,OAAO,aAAa,CAAC;CAC5B;AA+GD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,iBAA6B,GAClC,OAAO,CAAC,uBAAuB,CAAC,CAgDlC"}

package/dist/generated/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/generated/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC"}