@intentius/chant-lexicon-terraform 0.57.0

package/src/lsp/context.ts

@@ -0,0 +1,349 @@
+/**
+ * Shared parsing for the terraform LSP pair (#2088).
+ *
+ * There is no generated `LexiconIndex` here (see `completions.ts`'s module
+ * doc for why), so both providers work off two different sources instead:
+ *
+ *   - `terraform.roots`, read out of the project's `chant.config.{ts,json}`.
+ *     `chant.config.ts` is project-authored code (`config.ts`'s own doc:
+ *     "where it is evaluated is a security question"), and evaluating it is
+ *     an async, sandboxed operation — `loadChantConfigUpward` — while
+ *     `completionProvider`/`hoverProvider` are synchronous. So this reads the
+ *     file's *text* and extracts the `terraform.roots` object literal with a
+ *     small brace-matching scanner, never `eval`/`import()`. A shape the
+ *     scanner cannot follow (roots built by a loop, spread from a helper)
+ *     yields no roots rather than a wrong guess — the same "reachable or
+ *     nothing" rule the config-loading code documents elsewhere.
+ *   - the option keys a `*.op.ts` author types: `TerraformApplyOpConfig`
+ *     (`composites/terraform-apply-op.ts`) and the four builders' own opts
+ *     (`op/builders.ts`, `op/activities/terraform.ts`). Those are a fixed
+ *     table, not read from any file.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── Root resolution ─────────────────────────────────────────────────────────
+
+export interface ResolvedTerraformRoot {
+  dir?: string;
+  workspace?: string;
+  varFiles?: string[];
+}
+
+/** One `{`/`(`/`[` this scanner has not yet seen the matching closer for. */
+interface Opener {
+  char: "{" | "(" | "[";
+  index: number;
+}
+
+/**
+ * Every unmatched opener in `text`, in nesting order (outermost first),
+ * ignoring anything inside a string or template literal. This is the one
+ * pass every context-detection helper below walks backward over — cheap
+ * enough per keystroke since an `*.op.ts` file and a `chant.config.ts` are
+ * both small.
+ */
+function unmatchedOpeners(text: string): Opener[] {
+  const stack: Opener[] = [];
+  let inString: string | null = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (ch === "\\") {
+        i++;
+      } else if (ch === inString) {
+        inString = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      inString = ch;
+    } else if (ch === "{" || ch === "(" || ch === "[") {
+      stack.push({ char: ch, index: i });
+    } else if (ch === "}" || ch === ")" || ch === "]") {
+      stack.pop();
+    }
+  }
+  return stack;
+}
+
+/**
+ * The `{ ... }` body starting at `text[openIndex] === "{"`, and the index of
+ * its matching `}`. A single forward pass tracking overall nesting depth —
+ * `{`/`(`/`[` all count the same way, which is safe here because the only
+ * question this asks is "where does *this* brace close," never which bracket
+ * kind matched which.
+ */
+function braceBody(text: string, openIndex: number): { body: string; closeIndex: number } | undefined {
+  if (text[openIndex] !== "{") return undefined;
+  let depth = 0;
+  let inString: string | null = null;
+  for (let i = openIndex; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (ch === "\\") i++;
+      else if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      inString = ch;
+    } else if (ch === "{" || ch === "(" || ch === "[") {
+      depth++;
+    } else if (ch === "}" || ch === ")" || ch === "]") {
+      depth--;
+      if (depth === 0) return { body: text.slice(openIndex + 1, i), closeIndex: i };
+    }
+  }
+  return undefined;
+}
+
+/** The `{ ... }` body immediately after the first top-level `key\s*:\s*` in `text`. */
+function findKeyBlock(text: string, key: string): string | undefined {
+  const re = new RegExp(`(?:^|[\\s,{])${key}\\s*:\\s*\\{`, "m");
+  const m = re.exec(text);
+  if (!m) return undefined;
+  const openIndex = m.index + m[0].length - 1;
+  return braceBody(text, openIndex)?.body;
+}
+
+/** One key/value pair per top-level entry of an object-literal body. */
+function parseEntries(objText: string): Map<string, string> {
+  const entries = new Map<string, string>();
+  let i = 0;
+  const len = objText.length;
+  while (i < len) {
+    while (i < len && /[\s,]/.test(objText[i])) i++;
+    if (i >= len) break;
+
+    let key: string | undefined;
+    if (objText[i] === '"' || objText[i] === "'") {
+      const quote = objText[i];
+      let j = i + 1;
+      while (j < len && objText[j] !== quote) j++;
+      key = objText.slice(i + 1, j);
+      i = j + 1;
+    } else {
+      const m = /^[A-Za-z_$][\w$]*/.exec(objText.slice(i));
+      if (!m) break;
+      key = m[0];
+      i += m[0].length;
+    }
+    while (i < len && /\s/.test(objText[i])) i++;
+    if (objText[i] !== ":") break;
+    i++;
+    while (i < len && /\s/.test(objText[i])) i++;
+
+    if (objText[i] === "{") {
+      const block = braceBody(objText, i);
+      if (!block) break;
+      // Stored without the braces: every caller re-parses an object value as
+      // another set of entries (`parseTerraformRoots` does, one root at a
+      // time), and `parseEntries` itself only knows how to walk a flat
+      // `key: value` sequence, not a single `{ ... }`-wrapped one.
+      entries.set(key, block.body);
+      i = block.closeIndex + 1;
+    } else {
+      let depth = 0;
+      let inString: string | null = null;
+      let j = i;
+      while (j < len) {
+        const ch = objText[j];
+        if (inString) {
+          if (ch === "\\") j++;
+          else if (ch === inString) inString = null;
+        } else if (ch === '"' || ch === "'" || ch === "`") {
+          inString = ch;
+        } else if (ch === "[" || ch === "(") {
+          depth++;
+        } else if (ch === "]" || ch === ")") {
+          depth--;
+        } else if (ch === "," && depth === 0) {
+          break;
+        }
+        j++;
+      }
+      entries.set(key, objText.slice(i, j));
+      i = j;
+    }
+  }
+  return entries;
+}
+
+function unquote(raw: string | undefined): string | undefined {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  const m = /^["'`]([\s\S]*)["'`]$/.exec(trimmed);
+  return m ? m[1] : trimmed;
+}
+
+function parseStringArray(raw: string | undefined): string[] | undefined {
+  if (raw === undefined) return undefined;
+  const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+  const values = inner
+    .split(",")
+    .map((s) => unquote(s))
+    .filter((s): s is string => typeof s === "string" && s.length > 0);
+  return values.length > 0 ? values : undefined;
+}
+
+/**
+ * `terraform.roots`, extracted from a `chant.config.ts`/`.json`'s raw text.
+ * Never executes the file. `format` distinguishes the two because JSON's
+ * `roots` value is already a plain object — no brace-matching needed.
+ */
+export function parseTerraformRoots(
+  configText: string,
+  format: "ts" | "json",
+): Record<string, ResolvedTerraformRoot> | undefined {
+  if (format === "json") {
+    try {
+      const parsed = JSON.parse(configText) as { terraform?: { roots?: unknown } };
+      const roots = parsed.terraform?.roots;
+      if (!roots || typeof roots !== "object" || Array.isArray(roots)) return undefined;
+      const result: Record<string, ResolvedTerraformRoot> = {};
+      for (const [name, entry] of Object.entries(roots as Record<string, unknown>)) {
+        const e = (entry ?? {}) as { dir?: unknown; workspace?: unknown; varFiles?: unknown };
+        result[name] = {
+          dir: typeof e.dir === "string" ? e.dir : undefined,
+          workspace: typeof e.workspace === "string" ? e.workspace : undefined,
+          varFiles: Array.isArray(e.varFiles) ? e.varFiles.filter((v): v is string => typeof v === "string") : undefined,
+        };
+      }
+      return Object.keys(result).length > 0 ? result : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  const terraformBlock = findKeyBlock(configText, "terraform");
+  if (terraformBlock === undefined) return undefined;
+  const rootsBlock = findKeyBlock(terraformBlock, "roots");
+  if (rootsBlock === undefined) return undefined;
+
+  const result: Record<string, ResolvedTerraformRoot> = {};
+  for (const [name, body] of parseEntries(rootsBlock)) {
+    const fields = parseEntries(body);
+    result[name] = {
+      dir: unquote(fields.get("dir")),
+      workspace: unquote(fields.get("workspace")),
+      varFiles: parseStringArray(fields.get("varFiles")),
+    };
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function directoryFromUri(uri: string): string | undefined {
+  if (!uri.startsWith("file://")) return undefined;
+  try {
+    return dirname(fileURLToPath(uri));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Walk upward from `startDir` for the nearest `chant.config.{ts,json}`. */
+function findConfigUpward(startDir: string): string | undefined {
+  let dir = startDir;
+  for (let i = 0; i < 32; i++) {
+    const tsPath = join(dir, "chant.config.ts");
+    if (existsSync(tsPath)) return tsPath;
+    const jsonPath = join(dir, "chant.config.json");
+    if (existsSync(jsonPath)) return jsonPath;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/**
+ * `terraform.roots`, resolved from the project config reachable from the
+ * document at `uri`. `undefined` when `uri` is not a `file://` URI, no
+ * `chant.config.*` is reachable by walking up from it, or the namespace
+ * declares no roots — every case where root-name completion has nothing
+ * honest to offer, so callers fall back to the option-key completions
+ * instead of fabricating a root list.
+ */
+export function resolveRootsForUri(uri: string): Record<string, ResolvedTerraformRoot> | undefined {
+  const startDir = directoryFromUri(uri);
+  if (!startDir) return undefined;
+  const configPath = findConfigUpward(startDir);
+  if (!configPath) return undefined;
+  try {
+    const text = readFileSync(configPath, "utf-8");
+    return parseTerraformRoots(text, configPath.endsWith(".json") ? "json" : "ts");
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Call/field context detection ────────────────────────────────────────────
+
+/** Content of the open document up to (and a little past) the cursor line, mirroring core's `lexiconCompletions`. */
+export function contentUpToCursor(content: string, line: number): string {
+  return content.split("\n").slice(0, line + 1).join("\n");
+}
+
+/**
+ * The name of the call whose parenthesized argument list holds the innermost
+ * unmatched `{` before the cursor — `TerraformApplyOp({ ↵ name: "x", ↵ <cursor>`
+ * and `terraformPlan("app", { ↵ <cursor>` both resolve to their call name,
+ * regardless of which positional argument the object is.
+ */
+export function enclosingCallName(text: string): string | undefined {
+  const stack = unmatchedOpeners(text);
+  const top = stack[stack.length - 1];
+  if (!top || top.char !== "{") return undefined;
+  const parent = stack[stack.length - 2];
+  if (!parent || parent.char !== "(") return undefined;
+  let k = parent.index - 1;
+  while (k >= 0 && /\s/.test(text[k])) k--;
+  const end = k + 1;
+  while (k >= 0 && /[\w$]/.test(text[k])) k--;
+  const name = text.slice(k + 1, end);
+  return name.length > 0 ? name : undefined;
+}
+
+/** The `key` immediately before the `{` at `braceIndex`, from `key: {`. */
+function precedingObjectKey(text: string, braceIndex: number): string | undefined {
+  const before = text.slice(0, braceIndex);
+  const m = /(?:^|[\s,{])(["'`]?)([\w$-]+)\1\s*:\s*$/.exec(before);
+  return m?.[2];
+}
+
+/**
+ * The key of the innermost enclosing object literal, regardless of what
+ * encloses *that* — `compensate: { <cursor>` resolves to `"compensate"` even
+ * though the whole thing sits inside `TerraformApplyOp({ ... })`'s own
+ * argument object, which `enclosingKeyPath` would refuse to walk through (a
+ * call anywhere in the chain ends it there).
+ */
+export function innermostObjectKey(text: string): string | undefined {
+  const stack = unmatchedOpeners(text);
+  const top = stack[stack.length - 1];
+  if (!top || top.char !== "{") return undefined;
+  return precedingObjectKey(text, top.index);
+}
+
+/**
+ * The chain of object-literal keys enclosing the cursor, outermost first —
+ * `["terraform", "roots", "app"]` inside `terraform: { roots: { app: { <cursor>` —
+ * for the plain-object contexts (`chant.config.ts`) that `enclosingCallName`
+ * does not cover, since there is no call there at all. A brace with no `key:`
+ * before it (the module's own `export default {`) contributes nothing to the
+ * path rather than ending it — only a `(` anywhere in the chain does, since
+ * `chant.config.ts` builds one object literal and calling anything
+ * mid-declaration is not a shape this needs to follow.
+ */
+export function enclosingKeyPath(text: string): string[] | undefined {
+  const stack = unmatchedOpeners(text);
+  const path: string[] = [];
+  for (const frame of stack) {
+    if (frame.char !== "{") return undefined;
+    const key = precedingObjectKey(text, frame.index);
+    if (key) path.push(key);
+  }
+  return path;
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,82 @@
+/**
+ * LSP hover tests (#2088). Root hover needs a reachable `chant.config.*`,
+ * same as completions — written to a temp directory rather than mocked.
+ */
+
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { HoverContext } from "@intentius/chant/lsp/types";
+import { hover } from "./hover";
+
+function ctx(overrides: Partial<HoverContext>): HoverContext {
+  return {
+    uri: "untitled:Untitled-1",
+    content: "",
+    position: { line: 0, character: 0 },
+    word: "",
+    lineText: "",
+    ...overrides,
+  };
+}
+
+describe("LSP hover", () => {
+  it("returns undefined for an empty context", () => {
+    expect(hover(ctx({}))).toBeUndefined();
+  });
+
+  it("shows a root's dir/workspace/varFiles when the word is quoted next to a known root", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-terraform-lsp-"));
+    try {
+      writeFileSync(
+        join(dir, "chant.config.ts"),
+        `export default { terraform: { roots: { app: { dir: "./terraform/app", workspace: "prod", varFiles: ["prod.tfvars"] } } } };`,
+      );
+      const uri = pathToFileURL(join(dir, "infra.op.ts")).toString();
+      const info = hover(ctx({ uri, word: "app", lineText: 'terraformPlan("app")' }));
+      expect(info?.contents).toContain("app");
+      expect(info?.contents).toContain("./terraform/app");
+      expect(info?.contents).toContain("prod");
+      expect(info?.contents).toContain("prod.tfvars");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not treat a bare identifier as a root reference, even if it matches a root name", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-terraform-lsp-"));
+    try {
+      writeFileSync(join(dir, "chant.config.ts"), `export default { terraform: { roots: { app: { dir: "./tf" } } } };`);
+      const uri = pathToFileURL(join(dir, "infra.op.ts")).toString();
+      const info = hover(ctx({ uri, word: "app", lineText: "const app = 1;" }));
+      expect(info).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns undefined for a quoted word that names no declared root", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-terraform-lsp-"));
+    try {
+      writeFileSync(join(dir, "chant.config.ts"), `export default { terraform: { roots: { app: { dir: "./tf" } } } };`);
+      const uri = pathToFileURL(join(dir, "infra.op.ts")).toString();
+      const info = hover(ctx({ uri, word: "ghost", lineText: 'terraformPlan("ghost")' }));
+      expect(info).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("documents a known option key even with no reachable config", () => {
+    const info = hover(ctx({ word: "gate", lineText: '  gate: "always",' }));
+    expect(info?.contents).toContain("gate");
+    expect(info?.contents).toContain("on-destroy");
+  });
+
+  it("returns undefined for a word that is neither a reachable root nor a known option key", () => {
+    const info = hover(ctx({ word: "somethingElse", lineText: "somethingElse" }));
+    expect(info).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,44 @@
+/**
+ * LSP hover for the terraform lexicon (#2088). See `./completions.ts`'s
+ * module doc for why this reads `chant.config.*` as text rather than a
+ * generated index, and completes/documents the same two things: a
+ * `terraform.roots` name (when the word under the cursor is quoted next to
+ * it, so an ordinary identifier never gets mistaken for a root) and one of
+ * the composite/builder option keys (`./option-keys.ts`), the latter needing
+ * no reachable config at all.
+ */
+
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { resolveRootsForUri } from "./context";
+import { ALL_OPTION_KEYS } from "./option-keys";
+
+/** `"app"` or `'app'` — the word is only a root reference if it sits inside a quote pair on the line. */
+function isQuoted(lineText: string, word: string): boolean {
+  if (!word) return false;
+  return new RegExp(`["']${word}["']`).test(lineText);
+}
+
+function rootHover(uri: string, word: string, lineText: string): HoverInfo | undefined {
+  if (!isQuoted(lineText, word)) return undefined;
+  const roots = resolveRootsForUri(uri);
+  const root = roots?.[word];
+  if (!root) return undefined;
+
+  const lines = [`**${word}**`, "", "terraform root (`terraform.roots." + word + "`)"];
+  if (root.dir) lines.push("", `\`dir\`: \`${root.dir}\``);
+  if (root.workspace) lines.push("", `\`workspace\`: \`${root.workspace}\``);
+  if (root.varFiles?.length) lines.push("", `\`varFiles\`: ${root.varFiles.map((f) => `\`${f}\``).join(", ")}`);
+  return { contents: lines.join("\n") };
+}
+
+function optionKeyHover(word: string): HoverInfo | undefined {
+  const detail = ALL_OPTION_KEYS.get(word);
+  if (!detail) return undefined;
+  return { contents: `**${word}**\n\n${detail}` };
+}
+
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  const word = ctx.word ?? "";
+  if (!word) return undefined;
+  return rootHover(ctx.uri, word, ctx.lineText ?? "") ?? optionKeyHover(word);
+}

package/src/lsp/option-keys.ts

@@ -0,0 +1,106 @@
+/**
+ * The option keys a `*.op.ts` or `chant.config.ts` author types against this
+ * lexicon's config schema (`../config.ts`), its composite
+ * (`../composites/terraform-apply-op.ts`) and its four builders
+ * (`../op/builders.ts`, `../op/activities/terraform.ts`). A fixed table, not
+ * read from any generated registry — there is no upstream schema here (see
+ * `plugin.ts`'s module doc), so this is the same set of fields those files
+ * already document in their own TSDoc, restated once for the editor.
+ */
+
+export interface OptionKey {
+  key: string;
+  detail: string;
+}
+
+/** `TerraformConfig`'s own top-level keys (`terraform: { <here> }`). */
+export const CONFIG_NAMESPACE_KEYS: OptionKey[] = [
+  { key: "binary", detail: '"terraform" | "tofu" — which CLI drives the roots. Default: "terraform".' },
+  { key: "roots", detail: "Named root modules. The name is the entity-key prefix." },
+];
+
+/** `TerraformRootConfig`'s keys — one entry of `terraform.roots.<name>: { <here> }`. */
+export const ROOT_ENTRY_KEYS: OptionKey[] = [
+  { key: "dir", detail: "Root module directory, relative to the project root. Required." },
+  { key: "workspace", detail: "Terraform workspace to select for this root. Omitted means `default`." },
+  { key: "varFiles", detail: "`-var-file` arguments, in order, relative to `dir`." },
+  { key: "backendConfig", detail: "`-backend-config` key/value pairs handed to `init`." },
+];
+
+/** `TerraformApplyOpConfig`'s keys (`TerraformApplyOp({ <here> })`). */
+export const APPLY_OP_KEYS: OptionKey[] = [
+  { key: "name", detail: "Op name (kebab-case). Also the default task queue and gate signal suffix." },
+  { key: "root", detail: "Key into the project's `terraform.roots`." },
+  { key: "planFile", detail: "Plan file written by Plan and consumed by Apply. Default: `chant.tfplan`." },
+  { key: "gate", detail: '"on-destroy" | "always" | "never" — when to emit the approval gate. Default: "on-destroy".' },
+  { key: "signalName", detail: "Gate signal name. Default: `approve-<name>`." },
+  { key: "gateTimeout", detail: "Temporal duration the gate waits before timing out. Default: core's own (48h)." },
+  { key: "gateDescription", detail: "Override the gate description shown to the approver." },
+  { key: "upgrade", detail: "`-upgrade` on the Init step: re-resolve provider and module versions." },
+  { key: "cwd", detail: "Directory each step starts the `chant.config.*` search from." },
+  { key: "compensate", detail: "Saga-style rollback on a failed apply: `true` with no command throws; supply `{ command }`." },
+  { key: "taskQueue", detail: "Override the task queue. Defaults to `name`." },
+];
+
+/** `compensate`'s own shape when it is an object: `compensate: { <here> }`. */
+export const COMPENSATE_KEYS: OptionKey[] = [
+  { key: "command", detail: "Shell command that undoes a failed apply — terraform has no automatic rollback." },
+];
+
+/** Extra opts every builder wrapper accepts alongside its activity's own fields. */
+const STEP_OPTS: OptionKey[] = [
+  { key: "profile", detail: "Activity profile override (defaults are set per builder)." },
+  { key: "id", detail: 'Step id — required for `.out` references, e.g. `plan.out.planFile`.' },
+];
+
+/** `terraformInit(root, { <here> })`'s opts — `TerraformInitArgs` minus `root`, plus step opts. */
+export const INIT_OPTS_KEYS: OptionKey[] = [
+  { key: "upgrade", detail: "`-upgrade`: re-resolve provider and module versions within constraints." },
+  { key: "reconfigure", detail: "`-reconfigure`: ignore any existing backend state and configure afresh." },
+  { key: "cwd", detail: "Directory to start the `chant.config.*` search from." },
+  ...STEP_OPTS,
+];
+
+/** `terraformPlan(root, { <here> })`'s opts — `TerraformPlanArgs` minus `root`, plus step opts. */
+export const PLAN_OPTS_KEYS: OptionKey[] = [
+  { key: "planFile", detail: "Plan file to write, relative to the root directory. Default: `chant.tfplan`." },
+  { key: "destroy", detail: "`-destroy`: plan the removal of everything the root manages." },
+  { key: "cwd", detail: "Directory to start the `chant.config.*` search from." },
+  ...STEP_OPTS,
+];
+
+/** `terraformApply(root, { <here> })`'s opts — `TerraformApplyArgs` minus `root`, plus step opts. */
+export const APPLY_OPTS_KEYS: OptionKey[] = [
+  { key: "planFile", detail: "The saved plan file to apply, relative to the root directory. Required." },
+  { key: "cwd", detail: "Directory to start the `chant.config.*` search from." },
+  ...STEP_OPTS,
+];
+
+/** `terraformShow(root, { <here> })`'s opts — `TerraformShowArgs` minus `root`, plus step opts. */
+export const SHOW_OPTS_KEYS: OptionKey[] = [
+  { key: "planFile", detail: "Show this saved plan file. Omitted, the activity shows current state." },
+  { key: "cwd", detail: "Directory to start the `chant.config.*` search from." },
+  ...STEP_OPTS,
+];
+
+/** Every builder call name mapped to its opts table, for completion inside `(root, { <here> })`. */
+export const BUILDER_OPTS_BY_CALL: Record<string, OptionKey[]> = {
+  terraformInit: INIT_OPTS_KEYS,
+  terraformPlan: PLAN_OPTS_KEYS,
+  terraformApply: APPLY_OPTS_KEYS,
+  terraformShow: SHOW_OPTS_KEYS,
+};
+
+/** Every option key across every table, keyed by name, for hover lookup. Last writer wins on a name shared across tables (`cwd`, `planFile`) — the detail text is the same fact restated per activity, so any one of them is a correct hover. */
+export const ALL_OPTION_KEYS: Map<string, string> = new Map(
+  [
+    ...CONFIG_NAMESPACE_KEYS,
+    ...ROOT_ENTRY_KEYS,
+    ...APPLY_OP_KEYS,
+    ...COMPENSATE_KEYS,
+    ...INIT_OPTS_KEYS,
+    ...PLAN_OPTS_KEYS,
+    ...APPLY_OPTS_KEYS,
+    ...SHOW_OPTS_KEYS,
+  ].map((o) => [o.key, o.detail]),
+);

package/src/op/activities/index.ts

@@ -0,0 +1,48 @@
+/**
+ * terraform Op activities — resolved by the core activity registry when a
+ * project's `chant.config.ts` lists the `terraform` lexicon. `loadActivities`
+ * (`packages/core/src/op/activity-registry.ts`) imports
+ * `@intentius/chant-lexicon-terraform/op/activities` and keys every exported
+ * function by its name, so there is no plugin member to register:
+ *
+ *   - terraformInit — `init` with the root's `backendConfig`.
+ *   - terraformPlan — `plan -detailed-exitcode -out=<planFile>`, plus both
+ *     `show` renders of the written plan.
+ *   - terraformApply — `apply <planFile>`, a saved plan only.
+ *   - terraformShow — state, or a saved plan, as JSON and as text.
+ *
+ * The module is dependency-light on purpose: it shells out to the configured
+ * binary and reads the `terraform` config namespace, and never touches the
+ * lexicon's HCL parse or serializer, so a Temporal worker loads it cheaply.
+ * The pure command and environment builders are exported alongside the
+ * activities because they are what the tests assert on.
+ */
+export {
+  terraformInit,
+  terraformPlan,
+  terraformApply,
+  terraformShow,
+  terraformInitCommand,
+  terraformPlanCommand,
+  terraformApplyCommand,
+  terraformShowCommand,
+  terraformEnvironment,
+  terraformBinary,
+  countPlanChanges,
+  quoteArg,
+  DEFAULT_PLAN_FILE,
+  DEFAULT_TERRAFORM_BINARY,
+} from "./terraform";
+
+export type {
+  TerraformRootArgs,
+  TerraformInitArgs,
+  TerraformPlanArgs,
+  TerraformApplyArgs,
+  TerraformShowArgs,
+  TerraformInitResult,
+  TerraformPlanResult,
+  TerraformApplyResult,
+  TerraformShowResult,
+  PlanChangeCounts,
+} from "./terraform";

package/src/op/activities/registry.test.ts

@@ -0,0 +1,29 @@
+/**
+ * The registry contract (#2086): activities are discovered by convention, not
+ * by a plugin member. `loadActivities` (`packages/core/src/op/
+ * activity-registry.ts`) imports
+ * `@intentius/chant-lexicon-terraform/op/activities` for every configured
+ * lexicon and keys each exported function by name, so the `"./op/activities"`
+ * entry in this lexicon's package.json is load-bearing and this test is what
+ * notices if it goes missing.
+ *
+ * Nothing here runs terraform: resolving a name is importing a module, not
+ * calling it.
+ */
+
+import { describe, test, expect } from "vitest";
+import { loadActivities, resolveActivity } from "@intentius/chant/op";
+
+describe("loadActivities([\"terraform\"]) (#2086)", () => {
+  test("resolves all four activity names", async () => {
+    const activities = await loadActivities(["terraform"]);
+    for (const name of ["terraformInit", "terraformPlan", "terraformApply", "terraformShow"]) {
+      expect(typeof resolveActivity(activities, name)).toBe("function");
+    }
+  });
+
+  test("a project that does not list terraform gets none of them", async () => {
+    const activities = await loadActivities([]);
+    expect(activities.has("terraformApply")).toBe(false);
+  });
+});