terramend 0.2.0

package/src/mcp/localServer.test.ts

@@ -0,0 +1,75 @@
+import { existsSync } from "node:fs";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildLocalContext, buildLocalTools } from "#app/mcp/localServer";
+import { log, setLogSink } from "#app/utils/log";
+
+afterEach(() => {
+  setLogSink("actions");
+  vi.restoreAllMocks();
+});
+
+describe("buildLocalTools", () => {
+  it("exposes exactly the read-only terraform tool set — no GitHub/git/PR/shell surface", () => {
+    const ctx = buildLocalContext({ cwd: process.cwd() });
+    const names = buildLocalTools(ctx)
+      .map((t) => t.name)
+      .sort();
+    // append-only review gate: a tool that pushes, comments, or opens PRs must
+    // never appear here. Update deliberately, with the localServer.ts doc rule.
+    expect(names).toEqual([
+      "infracost_diff",
+      "list_modules",
+      "module_extraction_candidates",
+      "read_findings",
+      "terraform_emit_sarif",
+      "terraform_module_graph",
+      "terraform_module_interface",
+      "terraform_module_tests",
+      "terraform_plan",
+      "terraform_provider_schema",
+      "terraform_roots",
+      "terraform_scan",
+      "terraform_validate",
+      "terraform_verify_remediation",
+      "terraform_version_currency",
+    ]);
+  });
+});
+
+describe("buildLocalContext", () => {
+  it("builds a cwd-scoped context with initialized tool state and a real tmpdir", () => {
+    const ctx = buildLocalContext({
+      cwd: "/repo",
+      severityThreshold: "medium",
+      scanScope: "diff",
+      moduleCatalogue: "terraform-aws-modules/vpc/aws ~> 5.0",
+    });
+    expect(ctx.payload).toMatchObject({
+      cwd: "/repo",
+      severityThreshold: "medium",
+      scanScope: "diff",
+      moduleCatalogue: "terraform-aws-modules/vpc/aws ~> 5.0",
+    });
+    expect(ctx.toolState.backgroundProcesses.size).toBe(0);
+    expect(ctx.toolState.usageEntries).toEqual([]);
+    expect(existsSync(ctx.tmpdir)).toBe(true);
+  });
+});
+
+describe("setLogSink", () => {
+  it("routes log output to stderr (stdout must stay clean for stdio JSON-RPC)", () => {
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+
+    setLogSink("stderr");
+    log.info("diagnostic line");
+    log.warning("careful");
+    log.error("broken");
+
+    const stderrText = stderrWrite.mock.calls.map((c) => String(c[0])).join("");
+    expect(stderrText).toContain("diagnostic line");
+    expect(stderrText).toContain("warning: careful");
+    expect(stderrText).toContain("error: broken");
+    expect(stdoutWrite).not.toHaveBeenCalled();
+  });
+});

package/src/mcp/localServer.ts

@@ -0,0 +1,131 @@
+/**
+ * `terramend mcp` — the LOCAL stdio MCP server (P2.1).
+ *
+ * Exposes terramend's read-only Terraform intelligence (scan, validate, verify,
+ * plan, currency, modules, provider schema, roots) to MCP clients — Claude Code,
+ * Cursor, Windsurf — over stdio, scoped to a working directory.
+ *
+ * Security boundary: this surface must stay GITHUB-FREE and WRITE-FREE. It is
+ * built from `LocalToolContext` (no octokit, no tokens, no event payload), so a
+ * tool that pushes, comments, or opens PRs cannot even type-check here. The
+ * one file-writing exception is `terraform_emit_sarif`, which writes a report
+ * the USER asked for into the workspace — not repo state.
+ *
+ * stdout discipline: stdout is the JSON-RPC channel. The caller MUST call
+ * `setLogSink("stderr")` before `startLocalMcpServer` (the `mcp` CLI command
+ * does) so tool diagnostics land on stderr.
+ */
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FastMCP, type Tool } from "fastmcp";
+import { terramendMcpName } from "#app/external";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { ModuleExtractionCandidatesTool } from "#app/mcp/moduleExtraction";
+import {
+  ListModulesTool,
+  TerraformModuleGraphTool,
+  TerraformModuleInterfaceTool,
+} from "#app/mcp/modules";
+import { TerraformModuleTestsTool } from "#app/mcp/moduleTests";
+import { TerraformProviderSchemaTool } from "#app/mcp/providerSchema";
+import { TerraformRootsTool } from "#app/mcp/roots";
+import {
+  InfracostDiffTool,
+  ReadFindingsTool,
+  TerraformEmitSarifTool,
+  TerraformPlanTool,
+  TerraformScanTool,
+  TerraformValidateTool,
+  TerraformVerifyRemediationTool,
+  TerraformVersionCurrencyTool,
+} from "#app/mcp/terraform";
+import { initToolState } from "#app/toolState";
+import { log } from "#app/utils/cli";
+
+export interface LocalMcpOptions {
+  /** absolute workspace directory the tools operate on. */
+  cwd: string;
+  severityThreshold?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+  scanScope?: "full" | "diff" | undefined;
+  /** newline/comma-separated approved module list (same as the action input). */
+  moduleCatalogue?: string | undefined;
+}
+
+/** build the cwd-scoped context the read-only tools run against. */
+export function buildLocalContext(options: LocalMcpOptions): LocalToolContext {
+  return {
+    payload: {
+      cwd: options.cwd,
+      scanScope: options.scanScope,
+      severityThreshold: options.severityThreshold,
+      autonomyThreshold: undefined,
+      costIncreaseBlockUsd: undefined,
+      moduleCatalogue: options.moduleCatalogue,
+    },
+    toolState: initToolState({ progressComment: undefined }),
+    tmpdir: mkdtempSync(join(tmpdir(), "terramend-mcp-")),
+  };
+}
+
+/**
+ * The local tool set. Append-only review rule: anything added here must be
+ * read-only w.r.t. the repo and runnable without GitHub context — the
+ * `localServer.test.ts` snapshot exists to make additions deliberate.
+ */
+export function buildLocalTools(ctx: LocalToolContext): Tool<any, any>[] {
+  return [
+    TerraformScanTool(ctx),
+    TerraformValidateTool(ctx),
+    TerraformVerifyRemediationTool(ctx),
+    TerraformPlanTool(ctx),
+    TerraformVersionCurrencyTool(ctx),
+    InfracostDiffTool(ctx),
+    ReadFindingsTool(ctx),
+    TerraformEmitSarifTool(ctx),
+    ListModulesTool(ctx),
+    TerraformModuleGraphTool(ctx),
+    TerraformModuleInterfaceTool(ctx),
+    TerraformModuleTestsTool(ctx),
+    ModuleExtractionCandidatesTool(ctx),
+    TerraformProviderSchemaTool(ctx),
+    TerraformRootsTool(ctx),
+  ];
+}
+
+/** the bundled CLI version when it looks like semver (esbuild injects
+ * CLI_VERSION at build time); a dev run without it reports 0.0.0. */
+function cliVersion(): `${number}.${number}.${number}` {
+  const raw = process.env.CLI_VERSION;
+  if (raw !== undefined && /^\d+\.\d+\.\d+$/.test(raw)) {
+    return raw as `${number}.${number}.${number}`;
+  }
+  return "0.0.0";
+}
+
+export async function startLocalMcpServer(
+  options: LocalMcpOptions,
+): Promise<{ stop: () => Promise<void> }> {
+  const ctx = buildLocalContext(options);
+  const server = new FastMCP({
+    name: terramendMcpName,
+    version: cliVersion(),
+    instructions:
+      "Read-only Terraform best-practice intelligence for the workspace at " +
+      `${options.cwd}. Start with terraform_scan (findings) or terraform_module_graph ` +
+      "(structure); verify any fix you make with terraform_validate and prove cleared " +
+      "concerns with terraform_verify_remediation. This server never holds cloud or " +
+      "GitHub credentials and cannot push, comment, or open PRs.",
+  });
+  for (const tool of buildLocalTools(ctx)) {
+    server.addTool(tool);
+  }
+  await server.start({ transportType: "stdio" });
+  log.info(`» terramend mcp: stdio server ready (cwd: ${options.cwd})`);
+  return {
+    stop: async () => {
+      await server.stop();
+    },
+  };
+}

package/src/mcp/moduleExtraction.test.ts

@@ -0,0 +1,261 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Unwrap the ToolResult envelope so tests assert on the raw object a tool
+// returns instead of decoding the encoded MCP text content.
+vi.mock("#app/mcp/shared", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("#app/mcp/shared")>();
+  return {
+    ...actual,
+    execute: <T, R>(fn: (params: T) => Promise<R>): ((params: T) => Promise<R>) => fn,
+  };
+});
+
+import type { LocalToolContext } from "#app/mcp/localContext";
+import {
+  clusterResources,
+  findExtractionCandidates,
+  ModuleExtractionCandidatesTool,
+  matchCluster,
+  parseResourceBlocks,
+  serviceKeywords,
+} from "#app/mcp/moduleExtraction";
+
+const tempDirs: string[] = [];
+
+function makeDir(files: Record<string, string> = {}): string {
+  const dir = mkdtempSync(join(tmpdir(), "terramend-extract-"));
+  tempDirs.push(dir);
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(dir, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  }
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const res = (resourceType: string, name: string) => ({ type: resourceType, name });
+
+describe("parseResourceBlocks", () => {
+  it("parses resource headers and ignores nested braces + other block kinds", () => {
+    const hcl = `
+resource "aws_s3_bucket" "logs" {
+  tags = { Name = "logs" }
+}
+data "aws_caller_identity" "me" {}
+module "vpc" { source = "./modules/vpc" }
+resource "aws_s3_bucket_versioning" "logs" {
+  versioning_configuration { status = "Enabled" }
+}
+`;
+    expect(parseResourceBlocks(hcl)).toEqual([
+      res("aws_s3_bucket", "logs"),
+      res("aws_s3_bucket_versioning", "logs"),
+    ]);
+  });
+});
+
+describe("clusterResources", () => {
+  it("clusters by shared name prefix (≥3 members)", () => {
+    const clusters = clusterResources("main.tf", [
+      res("aws_s3_bucket", "logs_bucket"),
+      res("aws_s3_bucket_versioning", "logs_versioning"),
+      res("aws_s3_bucket_public_access_block", "logs_pab"),
+      res("aws_instance", "web"),
+    ]);
+    expect(clusters).toHaveLength(1);
+    expect(clusters[0]).toMatchObject({ file: "main.tf", name_prefix: "logs" });
+    expect(clusters[0]?.resource_types).toEqual([
+      "aws_s3_bucket",
+      "aws_s3_bucket_public_access_block",
+      "aws_s3_bucket_versioning",
+    ]);
+  });
+
+  it("falls back to a whole-file cluster for a cohesive multi-type file", () => {
+    const clusters = clusterResources("net.tf", [
+      res("aws_vpc", "main"),
+      res("aws_subnet", "a"),
+      res("aws_subnet", "b"),
+      res("aws_route_table", "rt"),
+      res("aws_internet_gateway", "igw"),
+    ]);
+    expect(clusters).toHaveLength(1);
+    expect(clusters[0]).toMatchObject({ file: "net.tf", name_prefix: null });
+  });
+
+  it("ignores small files and single-type piles", () => {
+    expect(
+      clusterResources("a.tf", [res("aws_s3_bucket", "x"), res("aws_s3_bucket", "y")]),
+    ).toEqual([]);
+    expect(
+      clusterResources("b.tf", [
+        res("aws_instance", "a1"),
+        res("aws_instance", "b2"),
+        res("aws_instance", "c3"),
+        res("aws_instance", "d4"),
+      ]),
+    ).toEqual([]);
+  });
+});
+
+describe("serviceKeywords / matchCluster", () => {
+  it("derives service keywords without provider prefixes", () => {
+    expect(serviceKeywords("aws_s3_bucket")).toEqual(["s3", "bucket"]);
+    expect(serviceKeywords("google_storage_bucket")).toEqual(["storage", "bucket"]);
+  });
+
+  it("ranks a house-module signature match above a catalogue keyword match", () => {
+    const cluster = {
+      file: "main.tf",
+      name_prefix: "logs",
+      resources: [res("aws_s3_bucket", "logs"), res("aws_s3_bucket_versioning", "logs")],
+      resource_types: ["aws_s3_bucket", "aws_s3_bucket_versioning"],
+    };
+    const candidates = matchCluster(
+      cluster,
+      [
+        {
+          dir: "modules/bucket",
+          resourceTypes: ["aws_s3_bucket", "aws_s3_bucket_versioning"],
+          requiredVariables: ["bucket_name"],
+        },
+      ],
+      [
+        {
+          name: "s3-bucket",
+          source: "terraform-aws-modules/s3-bucket/aws",
+          version: "~> 4.0",
+          kind: "registry",
+        },
+      ],
+    );
+    expect(candidates).toHaveLength(2);
+    expect(candidates[0]).toMatchObject({
+      match: "resource_signature",
+      source: "./modules/bucket",
+      overlap: 1,
+      required_variables: ["bucket_name"],
+    });
+    expect(candidates[1]).toMatchObject({ match: "name_keyword", kind: "registry" });
+  });
+
+  it("drops candidates below the overlap floor", () => {
+    const cluster = {
+      file: "main.tf",
+      name_prefix: null,
+      resources: [res("aws_vpc", "x"), res("aws_subnet", "y"), res("aws_route_table", "z")],
+      resource_types: ["aws_route_table", "aws_subnet", "aws_vpc"],
+    };
+    const candidates = matchCluster(
+      cluster,
+      [{ dir: "modules/bucket", resourceTypes: ["aws_s3_bucket"], requiredVariables: [] }],
+      [],
+    );
+    expect(candidates).toEqual([]);
+  });
+});
+
+const ROOT_TF = `
+resource "aws_s3_bucket" "logs_bucket" { bucket = "x" }
+resource "aws_s3_bucket_versioning" "logs_versioning" {
+  bucket = aws_s3_bucket.logs_bucket.id
+}
+resource "aws_s3_bucket_public_access_block" "logs_pab" {
+  bucket = aws_s3_bucket.logs_bucket.id
+}
+module "existing" { source = "./modules/bucket" }
+`;
+
+const HOUSE_MODULE_TF = `
+variable "bucket_name" { type = string }
+variable "tags" {
+  type    = map(string)
+  default = {}
+}
+resource "aws_s3_bucket" "this" { bucket = var.bucket_name }
+resource "aws_s3_bucket_versioning" "this" { bucket = aws_s3_bucket.this.id }
+resource "aws_s3_bucket_public_access_block" "this" { bucket = aws_s3_bucket.this.id }
+`;
+
+describe("findExtractionCandidates", () => {
+  it("finds a cluster, matches the house module, and never re-extracts module dirs", () => {
+    const cwd = makeDir({
+      "main.tf": ROOT_TF,
+      "modules/bucket/main.tf": HOUSE_MODULE_TF,
+    });
+
+    const found = findExtractionCandidates(cwd, undefined);
+
+    expect(found).toHaveLength(1);
+    // all three resources share the prefix, so the cluster covers the whole file.
+    expect(found[0]?.cluster).toMatchObject({ file: "main.tf", name_prefix: null });
+    expect(found[0]?.candidates[0]).toMatchObject({
+      match: "resource_signature",
+      source: "./modules/bucket",
+      overlap: 1,
+      required_variables: ["bucket_name"],
+    });
+  });
+
+  it("matches catalogue entries by service keyword when no house module fits", () => {
+    const cwd = makeDir({
+      "main.tf": ROOT_TF.replace(`module "existing" { source = "./modules/bucket" }`, ""),
+    });
+
+    const found = findExtractionCandidates(cwd, "terraform-aws-modules/s3-bucket/aws ~> 4.0");
+
+    expect(found).toHaveLength(1);
+    expect(found[0]?.candidates[0]).toMatchObject({
+      match: "name_keyword",
+      source: "terraform-aws-modules/s3-bucket/aws",
+      version: "~> 4.0",
+    });
+  });
+});
+
+describe("ModuleExtractionCandidatesTool", () => {
+  it("returns the ok envelope with clusters and the verify note", async () => {
+    const cwd = makeDir({
+      "main.tf": ROOT_TF,
+      "modules/bucket/main.tf": HOUSE_MODULE_TF,
+    });
+    const ctx = {
+      payload: { cwd },
+      toolState: {},
+      tmpdir: makeDir(),
+    } as unknown as LocalToolContext;
+    const fn = ModuleExtractionCandidatesTool(ctx).execute as (
+      p: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>;
+
+    const result = await fn({});
+
+    expect(result).toMatchObject({ ok: true, cluster_count: 1, matched_count: 1 });
+    expect(String(result.note)).toContain("refactor_safe");
+  });
+
+  it("degrades green on a workspace with nothing to extract", async () => {
+    const cwd = makeDir({ "main.tf": `resource "aws_instance" "web" {}` });
+    const ctx = {
+      payload: { cwd },
+      toolState: {},
+      tmpdir: makeDir(),
+    } as unknown as LocalToolContext;
+    const fn = ModuleExtractionCandidatesTool(ctx).execute as (
+      p: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>;
+
+    const result = await fn({});
+
+    expect(result).toMatchObject({ ok: true, cluster_count: 0, matched_count: 0 });
+  });
+});