terramend 0.2.0

package/src/mcp/roots.test.ts

@@ -0,0 +1,175 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  detectEnvironmentTwins,
+  discoverTerraformRoots,
+  isRootModuleHcl,
+  TerraformRootsTool,
+} from "#app/mcp/roots";
+import type { ToolContext } from "#app/mcp/server";
+
+describe("isRootModuleHcl", () => {
+  it("detects a provider configuration block (root)", () => {
+    expect(isRootModuleHcl('provider "aws" {\n  region = "eu-west-2"\n}')).toEqual({
+      hasBackend: false,
+      hasProviderConfig: true,
+    });
+  });
+
+  it("detects a backend block (root)", () => {
+    expect(isRootModuleHcl('terraform {\n  backend "s3" {}\n}').hasBackend).toBe(true);
+  });
+
+  it("does NOT treat a child module's required_providers as a root", () => {
+    const moduleHcl = `terraform {
+      required_providers {
+        aws = { source = "hashicorp/aws", version = ">= 5.0" }
+      }
+    }`;
+    expect(isRootModuleHcl(moduleHcl)).toEqual({ hasBackend: false, hasProviderConfig: false });
+  });
+});
+
+describe("discoverTerraformRoots (multi-root, hepcare layout)", () => {
+  let root: string;
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), "tf-roots-"));
+    // root #1: terraform/ with backend + provider config
+    mkdirSync(join(root, "terraform"), { recursive: true });
+    writeFileSync(
+      join(root, "terraform", "providers.tf"),
+      'terraform {\n  backend "s3" {}\n}\nprovider "aws" {\n  region = "eu-west-2"\n}',
+    );
+    writeFileSync(join(root, "terraform", "main.tf"), 'resource "aws_s3_bucket" "b" {}');
+    // root #2: terraform/core/ with a provider config
+    mkdirSync(join(root, "terraform", "core"), { recursive: true });
+    writeFileSync(join(root, "terraform", "core", "providers.tf"), 'provider "aws" {}');
+    // child module: terraform/modules/x — only required_providers (NOT a root)
+    mkdirSync(join(root, "terraform", "modules", "x"), { recursive: true });
+    writeFileSync(
+      join(root, "terraform", "modules", "x", "versions.tf"),
+      'terraform {\n  required_providers {\n    aws = { source = "hashicorp/aws" }\n  }\n}',
+    );
+  });
+
+  afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+  it("finds the two roots and excludes the child module", () => {
+    const roots = discoverTerraformRoots(root);
+    expect(roots.map((r) => r.dir)).toEqual(["terraform", "terraform/core"]);
+    expect(roots[0]).toMatchObject({ hasBackend: true, hasProviderConfig: true });
+    expect(roots[1]).toMatchObject({ hasBackend: false, hasProviderConfig: true });
+    expect(roots.some((r) => r.dir.includes("modules"))).toBe(false);
+  });
+
+  it("returns empty when no provider/backend is configured anywhere", () => {
+    const empty = mkdtempSync(join(tmpdir(), "tf-noroot-"));
+    writeFileSync(join(empty, "main.tf"), 'resource "aws_s3_bucket" "b" {}');
+    expect(discoverTerraformRoots(empty)).toEqual([]);
+    rmSync(empty, { recursive: true, force: true });
+  });
+});
+
+describe("detectEnvironmentTwins (§22)", () => {
+  it("groups dev/staging/prod stacks that differ only by an env segment", () => {
+    const twins = detectEnvironmentTwins([
+      "environments/dev",
+      "environments/staging",
+      "environments/prod",
+    ]);
+    expect(twins).toHaveLength(1);
+    expect(twins[0]!.pattern).toBe("environments/{env}");
+    expect(twins[0]!.members.map((m) => m.environment)).toEqual(["dev", "prod", "staging"]);
+  });
+
+  it("matches the LAST env segment so nested paths key correctly", () => {
+    const twins = detectEnvironmentTwins(["infra/prod/network", "infra/dev/network"]);
+    expect(twins[0]!.pattern).toBe("infra/{env}/network");
+    expect(twins[0]!.members.map((m) => m.environment)).toEqual(["dev", "prod"]);
+  });
+
+  it("detects per-region twins", () => {
+    const twins = detectEnvironmentTwins(["stacks/eu-west-2", "stacks/eu-west-1"]);
+    expect(twins[0]!.pattern).toBe("stacks/{env}");
+    expect(twins[0]!.members.map((m) => m.environment)).toEqual(["eu-west-1", "eu-west-2"]);
+  });
+
+  it("matches a <env>.tfvars filename", () => {
+    const twins = detectEnvironmentTwins(["env/dev.tfvars", "env/prod.tfvars"]);
+    expect(twins[0]!.pattern).toBe("env/{env}.tfvars");
+    expect(twins[0]!.members.map((m) => m.environment)).toEqual(["dev", "prod"]);
+  });
+
+  it("does NOT group a single environment (needs ≥2 distinct)", () => {
+    expect(detectEnvironmentTwins(["environments/prod"])).toEqual([]);
+    // same env twice → still one distinct → not a twin set.
+    expect(detectEnvironmentTwins(["a/prod", "a/prod"])).toEqual([]);
+  });
+
+  it("ignores paths with no env/region segment", () => {
+    expect(detectEnvironmentTwins(["modules/vpc", "modules/s3"])).toEqual([]);
+  });
+});
+
+describe("TerraformRootsTool", () => {
+  async function runRootsTool(cwd: string): Promise<string> {
+    const tool = TerraformRootsTool({ payload: { cwd } } as unknown as ToolContext);
+    const exec = tool.execute as (
+      p: unknown,
+      c: unknown,
+    ) => Promise<{ content: [{ type: "text"; text: string }] }>;
+    const result = await exec({}, {});
+    return result.content[0].text;
+  }
+
+  let multiRoot: string;
+  let twinRoot: string;
+  let singleRoot: string;
+
+  beforeAll(() => {
+    multiRoot = mkdtempSync(join(tmpdir(), "tf-rootstool-"));
+    mkdirSync(join(multiRoot, "core"), { recursive: true });
+    writeFileSync(join(multiRoot, "main.tf"), 'provider "aws" {}');
+    writeFileSync(join(multiRoot, "core", "main.tf"), 'terraform {\n  backend "s3" {}\n}');
+
+    twinRoot = mkdtempSync(join(tmpdir(), "tf-rootstwin-"));
+    for (const env of ["dev", "prod"]) {
+      mkdirSync(join(twinRoot, "stacks", env), { recursive: true });
+      writeFileSync(join(twinRoot, "stacks", env, "main.tf"), 'provider "aws" {}');
+    }
+
+    singleRoot = mkdtempSync(join(tmpdir(), "tf-rootsone-"));
+    writeFileSync(join(singleRoot, "main.tf"), 'provider "aws" {}');
+  });
+
+  afterAll(() => {
+    rmSync(multiRoot, { recursive: true, force: true });
+    rmSync(twinRoot, { recursive: true, force: true });
+    rmSync(singleRoot, { recursive: true, force: true });
+  });
+
+  it("reports multiple roots with the per-root flags and the multi-root note", async () => {
+    const text = await runRootsTool(multiRoot);
+    expect(text).toContain("root_count: 2");
+    expect(text).toContain("has_backend");
+    expect(text).toContain("has_provider_config");
+    expect(text).toContain("Multiple roots");
+    expect(text).toContain("environment_twins: []");
+  });
+
+  it("reports environment twins among parallel stacks", async () => {
+    const text = await runRootsTool(twinRoot);
+    expect(text).toContain("root_count: 2");
+    expect(text).toContain("stacks/{env}");
+    expect(text).toContain("Detected environment twins");
+  });
+
+  it("reports a single root with the single-root note", async () => {
+    const text = await runRootsTool(singleRoot);
+    expect(text).toContain("root_count: 1");
+    expect(text).toContain("Single root (or none detected)");
+  });
+});

package/src/mcp/roots.ts

@@ -0,0 +1,217 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { walkTfFiles } from "#app/mcp/modules";
+import { execute, tool } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+/**
+ * Multi-root awareness. A repo can hold SEVERAL Terraform root modules — the
+ * dirs you'd run `terraform init/plan/apply` in — not one. hepcare, for example,
+ * has `terraform/` AND `terraform/core/`, plus a child module under
+ * `terraform/modules/`. The scanners run recursively, but plan/validate assume a
+ * single `cwd`; this surfaces the roots so a run can act per-root.
+ *
+ * Heuristic (validated against real repos): a ROOT is a dir whose `*.tf`
+ * declares a PROVIDER CONFIGURATION (`provider "<name>" { … }`) or a BACKEND
+ * (`backend "<type>" { … }`). A CHILD MODULE never configures a provider or a
+ * backend (it only declares `required_providers`), so this cleanly separates the
+ * two. Pure parsing + a single fs walk; no subprocess.
+ */
+
+export interface TerraformRoot {
+  /** repo-relative dir (POSIX); "" for the top-level. */
+  dir: string;
+  hasBackend: boolean;
+  hasProviderConfig: boolean;
+  tfFileCount: number;
+}
+
+// a provider CONFIGURATION block — `provider "aws" {`. Distinct from a
+// `required_providers` block (which child modules also have). The negative
+// lookbehind avoids matching `required_providers`.
+const PROVIDER_CONFIG = /(?:^|\n)\s*provider\s+"[^"]+"\s*\{/;
+const BACKEND_BLOCK = /(?:^|\n)\s*backend\s+"[^"]+"\s*\{/;
+
+/** detect whether some concatenated HCL marks a root module. */
+export function isRootModuleHcl(hcl: string): { hasBackend: boolean; hasProviderConfig: boolean } {
+  return {
+    hasBackend: BACKEND_BLOCK.test(hcl),
+    hasProviderConfig: PROVIDER_CONFIG.test(hcl),
+  };
+}
+
+/** the directory of a repo-relative file path ("" for a top-level file). */
+function dirOf(file: string): string {
+  const i = file.lastIndexOf("/");
+  return i === -1 ? "" : file.slice(0, i);
+}
+
+/**
+ * Discover the Terraform root modules under `cwd`. Walks `*.tf` recursively
+ * (skipping cache/VCS dirs via walkTfFiles), groups by directory, and keeps the
+ * dirs that configure a provider or a backend. Sorted by dir. An empty result
+ * means no obvious root was found — the caller falls back to scanning `cwd`
+ * itself as a single root.
+ */
+export function discoverTerraformRoots(cwd: string): TerraformRoot[] {
+  const byDir = new Map<string, { files: string[]; hcl: string }>();
+  for (const f of walkTfFiles(cwd)) {
+    const dir = dirOf(f);
+    const entry = byDir.get(dir) ?? { files: [], hcl: "" };
+    entry.files.push(f);
+    try {
+      entry.hcl += `${readFileSync(join(cwd, f), "utf8")}\n`;
+    } catch {
+      /* skip unreadable */
+    }
+    byDir.set(dir, entry);
+  }
+  const roots: TerraformRoot[] = [];
+  for (const [dir, entry] of byDir) {
+    const { hasBackend, hasProviderConfig } = isRootModuleHcl(entry.hcl);
+    if (hasBackend || hasProviderConfig) {
+      roots.push({ dir, hasBackend, hasProviderConfig, tfFileCount: entry.files.length });
+    }
+  }
+  return roots.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+
+// --- §22 environment / region fan-out --------------------------------------
+
+// tokens that mark an environment twin when they appear as a whole path segment
+// or a `<token>.tfvars` filename. Lowercased; matched exactly against a segment.
+const ENV_TOKENS = new Set([
+  "dev",
+  "develop",
+  "development",
+  "stg",
+  "stage",
+  "staging",
+  "prod",
+  "prd",
+  "production",
+  "test",
+  "testing",
+  "qa",
+  "uat",
+  "sandbox",
+  "sbx",
+  "preprod",
+  "pre-prod",
+  "preproduction",
+  "demo",
+  "nonprod",
+  "non-prod",
+]);
+
+// AWS-style region segment, e.g. `eu-west-2`, `eu-west-1` — the other common
+// fan-out axis (the same stack replicated per region).
+const REGION_RE = /^[a-z]{2}-[a-z]+-\d$/;
+
+export interface EnvironmentTwinGroup {
+  /** the shared path shape with the env/region segment replaced by `{env}`. */
+  pattern: string;
+  /** the matched twins: each a dir + the environment/region token it carries. */
+  members: { dir: string; environment: string }[];
+}
+
+/**
+ * Detect environment/region TWINS among a set of repo-relative paths (root dirs
+ * and/or `*.tfvars` files): parallel stacks that differ only by an environment
+ * (`dev`/`staging`/`prod`/…) or region (`eu-west-2`) segment. A fix applied to
+ * one should usually be offered for its twins too (§22 — backport / fan-out).
+ *
+ * For each path, finds the LAST segment that is an env token or a region (a
+ * `<env>.tfvars` file counts via its basename), replaces it with `{env}` to form
+ * a pattern, and groups by that pattern. Only groups with ≥2 DISTINCT
+ * environments are returned (a single match isn't a twin set). Pure +
+ * deterministic (sorted).
+ */
+export function detectEnvironmentTwins(paths: string[]): EnvironmentTwinGroup[] {
+  const byPattern = new Map<string, Map<string, string>>(); // pattern → env → dir
+  for (const raw of paths) {
+    const path = raw.replace(/\\/g, "/").replace(/^\.\//, "");
+    const segments = path.split("/").filter(Boolean);
+    // a `<env>.tfvars` filename: treat the basename (sans .tfvars) as a segment.
+    const last = segments[segments.length - 1] ?? "";
+    if (last.endsWith(".tfvars")) {
+      segments[segments.length - 1] = last.slice(0, -".tfvars".length);
+    }
+    // find the LAST env/region segment (so `infra/prod/network` keys on `prod`).
+    let idx = -1;
+    let token = "";
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const seg = segments[i]!.toLowerCase();
+      if (ENV_TOKENS.has(seg) || REGION_RE.test(seg)) {
+        idx = i;
+        token = seg;
+        break;
+      }
+    }
+    if (idx === -1) continue;
+    const patternSegs = [...segments];
+    patternSegs[idx] = "{env}";
+    const pattern = patternSegs.join("/") + (last.endsWith(".tfvars") ? ".tfvars" : "");
+    const map = byPattern.get(pattern) ?? new Map<string, string>();
+    if (!map.has(token)) map.set(token, path);
+    byPattern.set(pattern, map);
+  }
+  const groups: EnvironmentTwinGroup[] = [];
+  for (const [pattern, envMap] of byPattern) {
+    if (envMap.size < 2) continue;
+    const members = [...envMap.entries()]
+      .map(([environment, dir]) => ({ dir, environment }))
+      .sort((a, b) => a.environment.localeCompare(b.environment));
+    groups.push({ pattern, members });
+  }
+  return groups.sort((a, b) => a.pattern.localeCompare(b.pattern));
+}
+
+export const TerraformRootsParams = type({});
+
+export function TerraformRootsTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_roots",
+    description:
+      "Discover the Terraform ROOT modules in the repo — the dirs you'd run `terraform init/plan/apply` in " +
+      "(they configure a `provider` or a `backend`), as opposed to child modules under `modules/`. A repo " +
+      "can have several (e.g. `terraform/` and `terraform/core/`). `terraform_scan` already scans the whole " +
+      "tree, but `terraform_plan`/`terraform_validate` act on one dir — run them once PER ROOT (set the " +
+      "`cwd` accordingly) when there is more than one, so each root's real-world effect is checked. Returns " +
+      "an empty list when no root is detected (then treat the scan `cwd` as the single root).",
+    parameters: TerraformRootsParams,
+    execute: execute(async () => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const roots = discoverTerraformRoots(cwd);
+      // §22 — parallel per-environment/region stacks among the roots; a fix to
+      // one twin should usually be offered for the others.
+      const twins = detectEnvironmentTwins(roots.map((r) => r.dir).filter(Boolean));
+      log.info(
+        `» terraform_roots: ${roots.length} root(s) [${roots.map((r) => r.dir || ".").join(", ")}]` +
+          (twins.length ? `, ${twins.length} env-twin group(s)` : ""),
+      );
+      return {
+        ok: true,
+        root_count: roots.length,
+        roots: roots.map((r) => ({
+          dir: r.dir || ".",
+          has_backend: r.hasBackend,
+          has_provider_config: r.hasProviderConfig,
+          tf_file_count: r.tfFileCount,
+        })),
+        // §22 — environment/region twin groups (≥2 stacks differing only by an
+        // env/region segment). Empty when there are none.
+        environment_twins: twins,
+        note:
+          roots.length > 1
+            ? "Multiple roots — terraform_plan/terraform_validate run per root automatically. " +
+              (twins.length
+                ? "Detected environment twins: a fix to one stack should usually be offered for its twins (§22)."
+                : "")
+            : "Single root (or none detected) — the scan cwd is the root.",
+      };
+    }),
+  });
+}

package/src/mcp/scope.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { assertTargetInScope, isTargetInScope, recordCreatedTarget } from "#app/mcp/scope";
+import type { ToolContext } from "#app/mcp/server";
+
+function makeCtx(opts: { issueNumber?: number; created?: number[] } = {}): ToolContext {
+  const event =
+    opts.issueNumber === undefined
+      ? { trigger: "unknown" }
+      : { trigger: "pull_request_opened", issue_number: opts.issueNumber, is_pr: true };
+  return {
+    payload: { event },
+    toolState: { createdTargets: new Set<number>(opts.created ?? []) },
+  } as unknown as ToolContext;
+}
+
+describe("scope guard", () => {
+  it("allows any target on standalone runs (no triggering issue/PR)", () => {
+    const ctx = makeCtx({});
+    expect(isTargetInScope(ctx, 999)).toBe(true);
+    expect(() => assertTargetInScope(ctx, 999, "comment on")).not.toThrow();
+  });
+
+  it("allows the run's triggering issue/PR", () => {
+    expect(isTargetInScope(makeCtx({ issueNumber: 5 }), 5)).toBe(true);
+  });
+
+  it("blocks a different issue/PR in the same repo", () => {
+    const ctx = makeCtx({ issueNumber: 5 });
+    expect(isTargetInScope(ctx, 6)).toBe(false);
+    expect(() => assertTargetInScope(ctx, 6, "comment on")).toThrow(
+      /scoped to #5; refusing to comment on #6/,
+    );
+  });
+
+  it("allows a PR/issue the run created", () => {
+    expect(isTargetInScope(makeCtx({ issueNumber: 5, created: [50] }), 50)).toBe(true);
+  });
+
+  it("recordCreatedTarget widens scope to the new target", () => {
+    const ctx = makeCtx({ issueNumber: 5 });
+    expect(isTargetInScope(ctx, 77)).toBe(false);
+    recordCreatedTarget(ctx, 77);
+    expect(isTargetInScope(ctx, 77)).toBe(true);
+  });
+
+  it("recordCreatedTarget initializes the set when absent", () => {
+    const ctx = {
+      payload: { event: { trigger: "issues_opened", issue_number: 1 } },
+      toolState: {},
+    } as unknown as ToolContext;
+    recordCreatedTarget(ctx, 42);
+    expect(isTargetInScope(ctx, 42)).toBe(true);
+  });
+
+  it("degrades to a no-op when payload/event is missing (defensive)", () => {
+    const ctx = { toolState: {} } as unknown as ToolContext;
+    expect(isTargetInScope(ctx, 123)).toBe(true);
+  });
+});

package/src/mcp/scope.ts

@@ -0,0 +1,65 @@
+import type { ToolContext } from "#app/mcp/server";
+
+/**
+ * Bind the GitHub REST write tools to the issue/PR the run is scoped to.
+ *
+ * Terramend's threat model treats the agent as semi-trusted: attacker-controlled
+ * PR/issue content can prompt-inject it. The git tools already refuse to act on a
+ * PR the run was not triggered against (the cross-PR clobber guard in
+ * `mcp/git.ts`). These helpers extend the same scoping to the REST write tools
+ * (comment, review, labels, PR-body update, review reply, thread resolve) so an
+ * injected agent cannot comment on / approve / label an UNRELATED issue or PR in
+ * the same repo. The installation token already prevents cross-REPO writes; this
+ * closes the remaining cross-issue/PR-within-the-repo gap.
+ *
+ * In scope = the triggering issue/PR (`event.issue_number`) OR a PR/issue THIS
+ * run created (`create_pull_request` / `create_issue`, recorded via
+ * `recordCreatedTarget`). A merely checked-out PR is NOT in scope: `checkout_pr`
+ * is agent-controlled, so letting it widen write scope would defeat the guard.
+ *
+ * Standalone runs (workflow_dispatch / CLI: `event.trigger === "unknown"`) carry
+ * no triggering issue/PR and therefore no injection surface — there is nothing to
+ * bind to, so the guard is a no-op and the operator-supplied target is honored.
+ */
+
+/** the PR/issue this run was triggered against, or undefined for standalone runs. */
+function scopedTarget(ctx: ToolContext): number | undefined {
+  // optional chain: production always sets `payload.event` (resolvePayload
+  // defaults event to {trigger:"unknown"}), but degrade to "no scope" if it's
+  // somehow absent rather than throwing from a guard.
+  return ctx.payload?.event?.issue_number;
+}
+
+/**
+ * Record a PR/issue this run created so later body edits / comments / reviews on
+ * it pass {@link assertTargetInScope}. Call after a successful
+ * `create_pull_request` / `create_issue`.
+ */
+export function recordCreatedTarget(ctx: ToolContext, target: number): void {
+  ctx.toolState.createdTargets ??= new Set();
+  ctx.toolState.createdTargets.add(target);
+}
+
+/** true when `target` is the run's triggering issue/PR or one it created. */
+export function isTargetInScope(ctx: ToolContext, target: number): boolean {
+  const scoped = scopedTarget(ctx);
+  // standalone run — no triggering issue/PR to bind to (no injection surface).
+  if (scoped === undefined) return true;
+  if (target === scoped) return true;
+  return ctx.toolState.createdTargets?.has(target) ?? false;
+}
+
+/**
+ * Throw if `target` is neither the run's triggering issue/PR nor one it created.
+ * `action` is a short verb phrase used in the error (e.g. "comment on",
+ * "submit a review on", "add labels to").
+ */
+export function assertTargetInScope(ctx: ToolContext, target: number, action: string): void {
+  if (isTargetInScope(ctx, target)) return;
+  const scoped = scopedTarget(ctx);
+  throw new Error(
+    `blocked: this run is scoped to #${scoped}; refusing to ${action} #${target}. ` +
+      `terramend only writes to the issue/PR that triggered the run (or one it opened during the run). ` +
+      `if acting on #${target} is intended, trigger a run against #${target}.`,
+  );
+}