terramend 0.2.0

package/src/mcp/policy.ts

@@ -0,0 +1,199 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool, toolOk, toolSkip } from "#app/mcp/shared";
+import { SUBPROCESS_TIMEOUT_MS } from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import { resolveEnv } from "#app/utils/secrets";
+
+/**
+ * Policy-as-code gate (§3.5 OPA/Conftest). An optional, opt-in tool that runs
+ * the operator's own Rego policies against the Terraform plan JSON (or the HCL),
+ * so an org's policy-as-code can gate a remediation/generation the same way the
+ * deterministic scanners do — pairs with §21 (prevent recurrence). Terramend is
+ * an ORCHESTRATOR here, never a redistributor: it invokes the external
+ * `conftest` (OPA) binary as a separate process and consumes its normalized
+ * output. Degrades green — when conftest isn't installed or no policy dir
+ * exists, it returns `ok: false` with a `code` and never fails the run.
+ *
+ * The parsing is pure + unit-tested; the tool just shells out and parses.
+ */
+
+export interface PolicyFailure {
+  /** the policy rule message (the human-readable violation). */
+  msg: string;
+  /** the file conftest evaluated (repo-relative when conftest reported it). */
+  file: string;
+  /** "failure" (a deny) or "warning" (a warn). */
+  level: "failure" | "warning";
+}
+
+export interface PolicyResult {
+  /** true when there were zero failures (warnings don't fail the gate). */
+  passed: boolean;
+  failures: PolicyFailure[];
+  warnings: PolicyFailure[];
+  /** total tests conftest ran (across files), for a confidence signal. */
+  tested: number;
+}
+
+interface ConftestResultEntry {
+  filename?: string;
+  namespace?: string;
+  successes?: number;
+  failures?: { msg?: string }[];
+  warnings?: { msg?: string }[];
+}
+
+/**
+ * Parse `conftest test --output json` output into a normalized PolicyResult.
+ * Conftest emits an array of per-file result objects, each with `failures` /
+ * `warnings` / `successes`. Pure; tolerant of malformed/empty input (returns a
+ * clean pass). A non-empty `failures` anywhere means the gate did NOT pass;
+ * warnings are surfaced but don't fail it.
+ */
+export function parseConftestOutput(stdout: string): PolicyResult {
+  let parsed: ConftestResultEntry[];
+  try {
+    const raw = JSON.parse(stdout || "[]");
+    parsed = Array.isArray(raw) ? raw : [];
+  } catch {
+    return { passed: true, failures: [], warnings: [], tested: 0 };
+  }
+  const failures: PolicyFailure[] = [];
+  const warnings: PolicyFailure[] = [];
+  let tested = 0;
+  for (const entry of parsed) {
+    const file = entry.filename || "(plan)";
+    const fails = entry.failures ?? [];
+    const warns = entry.warnings ?? [];
+    tested += (entry.successes ?? 0) + fails.length + warns.length;
+    for (const f of fails)
+      failures.push({ msg: f.msg || "policy violation", file, level: "failure" });
+    for (const w of warns)
+      warnings.push({ msg: w.msg || "policy warning", file, level: "warning" });
+  }
+  return { passed: failures.length === 0, failures, warnings, tested };
+}
+
+/** the default dirs a repo keeps Rego policies in (checked in order). */
+const DEFAULT_POLICY_DIRS = ["policy", "policies", ".conftest"];
+
+/** resolve the policy dir to use: the explicit arg, else the first default dir
+ * that exists. Returns null when none is found. */
+function resolvePolicyDir(cwd: string, explicit: string | undefined): string | null {
+  if (explicit) {
+    const abs = isAbsolute(explicit) ? explicit : join(cwd, explicit);
+    return existsSync(abs) ? abs : null;
+  }
+  for (const d of DEFAULT_POLICY_DIRS) {
+    const abs = join(cwd, d);
+    if (existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+export const PolicyCheckParams = type({
+  "target?": type.string.describe(
+    "the file conftest evaluates — a terraform plan JSON (preferred; produce it with `terraform show -json plan.tfplan`) or an HCL file. Default: ./plan.json, then ./tfplan.json, in the workspace.",
+  ),
+  "policy_dir?": type.string.describe(
+    "dir holding the Rego policies. Default: the first of ./policy, ./policies, ./.conftest that exists.",
+  ),
+});
+
+export function PolicyCheckTool(ctx: ToolContext) {
+  return tool({
+    name: "policy_check",
+    description:
+      "Run the repo's own policy-as-code (Rego) against the Terraform plan/HCL via the external `conftest` " +
+      "(OPA) binary, so org policy can gate a fix (§3.5). Opt-in and degrades green — returns `ok: false` " +
+      "(never fails the run) when conftest isn't installed or no policy dir is present. On success returns " +
+      "`passed` (false when any policy DENY fired), the `failures` and `warnings` (each with msg + file), and " +
+      "the count `tested`. When `passed` is false, treat it like a failed validate: fix the violation or " +
+      "label the PR needs-human — do NOT push past a policy denial.",
+    parameters: PolicyCheckParams,
+    execute: execute(async ({ target, policy_dir }) => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const policyDir = resolvePolicyDir(cwd, policy_dir);
+      if (!policyDir) {
+        return toolSkip(
+          "no_policy_dir",
+          "no Rego policy dir found (looked for ./policy, ./policies, ./.conftest, or the policy_dir arg) — policy_check is opt-in",
+        );
+      }
+      // resolve the target file: explicit arg, else a conventional plan JSON.
+      let targetFile: string | null = null;
+      if (target) {
+        const abs = isAbsolute(target) ? target : join(cwd, target);
+        targetFile = existsSync(abs) ? abs : null;
+        if (!targetFile) {
+          return toolSkip(
+            "target_not_found",
+            `policy target '${target}' not found in the workspace`,
+          );
+        }
+      } else {
+        for (const candidate of ["plan.json", "tfplan.json"]) {
+          const abs = join(cwd, candidate);
+          if (existsSync(abs)) {
+            targetFile = abs;
+            break;
+          }
+        }
+        if (!targetFile) {
+          return toolSkip(
+            "no_target",
+            "no plan JSON to evaluate — produce one with `terraform show -json plan.tfplan > plan.json`, or pass `target`",
+          );
+        }
+      }
+      const r = spawnSync("conftest", ["test", "--output", "json", "-p", policyDir, targetFile], {
+        cwd,
+        encoding: "utf-8",
+        env: resolveEnv("restricted") as NodeJS.ProcessEnv,
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 64 * 1024 * 1024,
+        // bound a hung conftest (e.g. a policy that pulls a remote bundle).
+        timeout: SUBPROCESS_TIMEOUT_MS,
+      });
+      if (r.error && (r.error as NodeJS.ErrnoException).code === "ENOENT") {
+        return toolSkip(
+          "conftest_not_installed",
+          "conftest (OPA) is not installed — policy_check is opt-in and best-effort; install conftest to enable it",
+        );
+      }
+      // conftest exits non-zero when a policy DENY fires — that's a normal
+      // denial (JSON on stdout), not a tool error. But it ALSO exits non-zero
+      // when it couldn't evaluate at all (bad policy, parse error, no tests) —
+      // there it emits nothing parseable. Distinguish: a non-zero exit that
+      // yielded no evaluated tests AND no failures/warnings is a real error, so
+      // report it as a skip rather than a false PASS. A genuine denial has
+      // failures > 0 and flows through to `passed: false`.
+      const result = parseConftestOutput(r.stdout);
+      const evaluated =
+        result.tested > 0 || result.failures.length > 0 || result.warnings.length > 0;
+      if (r.status !== 0 && !evaluated) {
+        return toolSkip(
+          "conftest_failed",
+          `conftest could not evaluate the target: ${r.stderr.trim().slice(0, 300) || "unknown error"}`,
+        );
+      }
+      log.info(
+        `» policy_check: ${result.passed ? "PASS" : "FAIL"} — ${result.failures.length} failure(s), ${result.warnings.length} warning(s) over ${result.tested} test(s)`,
+      );
+      return toolOk({
+        passed: result.passed,
+        policy_dir: policyDir,
+        target: targetFile,
+        failure_count: result.failures.length,
+        warning_count: result.warnings.length,
+        failures: result.failures,
+        warnings: result.warnings,
+        tested: result.tested,
+      });
+    }),
+  });
+}

package/src/mcp/pr.test.ts

@@ -0,0 +1,387 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { assertUnderPrCap, recordRemediationPrOpened } from "#app/mcp/guardrails";
+import {
+  CreatePullRequestTool,
+  pickBaseBranch,
+  resolveBaseBranch,
+  UpdatePullRequestBodyTool,
+} from "#app/mcp/pr";
+import type { ToolContext } from "#app/mcp/server";
+import type { ToolState } from "#app/toolState";
+import { TERRAMEND_DIVIDER } from "#app/utils/buildTerramendFooter";
+import { patchWorkflowRunFields } from "#app/utils/patchWorkflowRunFields";
+import { $ } from "#app/utils/shell";
+
+vi.mock("#app/utils/shell", () => ({
+  $: vi.fn(() => "feature-branch"),
+}));
+
+vi.mock("#app/mcp/guardrails", () => ({
+  assertUnderPrCap: vi.fn(),
+  recordRemediationPrOpened: vi.fn(),
+}));
+
+vi.mock("#app/utils/patchWorkflowRunFields", () => ({
+  patchWorkflowRunFields: vi.fn(async () => undefined),
+}));
+
+const shellMock = vi.mocked($);
+
+describe("pickBaseBranch (deterministic base: declared → default → main → master → main)", () => {
+  it("an explicit declaration always wins", () => {
+    expect(
+      pickBaseBranch({
+        declared: "release",
+        defaultBranch: "main",
+        mainExists: true,
+        masterExists: true,
+      }),
+    ).toBe("release");
+  });
+
+  it("uses the repository default branch when nothing is declared", () => {
+    expect(pickBaseBranch({ defaultBranch: "master", mainExists: true, masterExists: true })).toBe(
+      "master",
+    );
+  });
+
+  it("prefers main when neither a declaration nor a default branch is known", () => {
+    expect(pickBaseBranch({ mainExists: true, masterExists: true })).toBe("main");
+  });
+
+  it("falls back to master when main does not exist", () => {
+    expect(pickBaseBranch({ mainExists: false, masterExists: true })).toBe("master");
+  });
+
+  it("ultimately defaults to main", () => {
+    expect(pickBaseBranch({ mainExists: false, masterExists: false })).toBe("main");
+  });
+});
+
+describe("resolveBaseBranch (ctx wiring; git not probed when a declaration or default exists)", () => {
+  const ctx = (over: { baseBranch?: string; defaultBranch?: string }): ToolContext =>
+    ({
+      payload: { baseBranch: over.baseBranch },
+      repo: { data: { default_branch: over.defaultBranch } },
+    }) as unknown as ToolContext;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("prefers the explicit base_branch override", () => {
+    expect(resolveBaseBranch(ctx({ baseBranch: "release", defaultBranch: "main" }))).toBe(
+      "release",
+    );
+    expect(shellMock).not.toHaveBeenCalled();
+  });
+
+  it("trims the override", () => {
+    expect(resolveBaseBranch(ctx({ baseBranch: "  release  ", defaultBranch: "main" }))).toBe(
+      "release",
+    );
+  });
+
+  it("uses the repository default branch when no override is set", () => {
+    expect(resolveBaseBranch(ctx({ defaultBranch: "master" }))).toBe("master");
+    expect(shellMock).not.toHaveBeenCalled();
+  });
+
+  it("probes git only in the last-resort case and finds main on the remote ref", () => {
+    shellMock.mockImplementation((_cmd, args) => {
+      const argList = args as string[];
+      if (argList.includes("refs/remotes/origin/main")) return "ok";
+      throw new Error("ref absent");
+    });
+    expect(resolveBaseBranch(ctx({}))).toBe("main");
+  });
+
+  it("falls back to a local master ref when no main exists anywhere", () => {
+    shellMock.mockImplementation((_cmd, args) => {
+      const argList = args as string[];
+      if (argList.includes("refs/heads/master")) return "ok";
+      throw new Error("ref absent");
+    });
+    expect(resolveBaseBranch(ctx({}))).toBe("master");
+  });
+
+  it("defaults to main when neither branch resolves", () => {
+    shellMock.mockImplementation(() => {
+      throw new Error("ref absent");
+    });
+    expect(resolveBaseBranch(ctx({}))).toBe("main");
+  });
+});
+
+// ── the octokit-backed tools ─────────────────────────────────────────────────
+
+type ToolResultShape = { content: [{ type: "text"; text: string }]; isError?: boolean };
+
+async function runTool(t: { execute?: unknown }, params: unknown): Promise<ToolResultShape> {
+  const exec = t.execute as (p: unknown, c: unknown) => Promise<ToolResultShape>;
+  return exec(params, {});
+}
+
+function makeOctokit() {
+  return {
+    rest: {
+      pulls: {
+        update: vi.fn(async (_p: unknown) => ({
+          data: { number: 12, html_url: "https://gh/pr/12" },
+        })),
+        create: vi.fn(async (_p: unknown) => ({
+          data: {
+            id: 7001,
+            number: 12,
+            node_id: "PR_NODE",
+            html_url: "https://gh/pr/12",
+            title: "fix: encrypt bucket",
+            head: { ref: "feature-branch" },
+            base: { ref: "main" },
+          },
+        })),
+        requestReviewers: vi.fn(async (_p: unknown) => ({})),
+      },
+    },
+  };
+}
+
+function makeToolCtx(overrides?: {
+  toolState?: Partial<ToolState>;
+  triggerer?: string;
+  baseBranch?: string;
+  push?: "disabled" | "restricted" | "enabled";
+  eventIssueNumber?: number;
+}): { ctx: ToolContext; octokit: ReturnType<typeof makeOctokit>; toolState: ToolState } {
+  const octokit = makeOctokit();
+  const toolState = { createdTargets: new Set<number>(), ...overrides?.toolState } as ToolState;
+  const event =
+    overrides?.eventIssueNumber === undefined
+      ? { trigger: "unknown" }
+      : { trigger: "pull_request_opened", is_pr: true, issue_number: overrides.eventIssueNumber };
+  const ctx = {
+    octokit,
+    repo: { owner: "octo", name: "repo", data: { default_branch: "main" } },
+    payload: {
+      triggerer: overrides?.triggerer,
+      baseBranch: overrides?.baseBranch,
+      push: overrides?.push,
+      event,
+    },
+    toolState,
+  } as unknown as ToolContext;
+  return { ctx, octokit, toolState };
+}
+
+describe("UpdatePullRequestBodyTool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("updates the PR body with a fresh footer and marks wasUpdated", async () => {
+    const { ctx, octokit, toolState } = makeToolCtx();
+    const result = await runTool(UpdatePullRequestBodyTool(ctx), {
+      pull_number: 12,
+      body: "new description",
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("success: true");
+    expect(octokit.rest.pulls.update).toHaveBeenCalledWith(
+      expect.objectContaining({ owner: "octo", repo: "repo", pull_number: 12 }),
+    );
+    const sent = octokit.rest.pulls.update.mock.calls[0]?.[0] as { body: string };
+    expect(sent.body).toContain("new description");
+    expect(sent.body).toContain(TERRAMEND_DIVIDER);
+    expect(toolState.wasUpdated).toBe(true);
+  });
+
+  it("strips a stale footer before appending a fresh one", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    await runTool(UpdatePullRequestBodyTool(ctx), {
+      pull_number: 12,
+      body: `body text\n\n${TERRAMEND_DIVIDER}\n<sup>stale</sup>`,
+    });
+
+    const sent = octokit.rest.pulls.update.mock.calls[0]?.[0] as { body: string };
+    expect(sent.body.startsWith("body text")).toBe(true);
+    expect(sent.body).not.toContain("stale");
+    expect(sent.body.indexOf(TERRAMEND_DIVIDER)).toBe(sent.body.lastIndexOf(TERRAMEND_DIVIDER));
+  });
+
+  it("repairs a double-escaped body (no real newlines) before sending", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    await runTool(UpdatePullRequestBodyTool(ctx), { pull_number: 12, body: "line1\\nline2" });
+
+    const sent = octokit.rest.pulls.update.mock.calls[0]?.[0] as { body: string };
+    expect(sent.body).toContain("line1\nline2");
+    expect(sent.body).not.toContain("line1\\nline2");
+  });
+
+  it("propagates API failures as tool errors", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    octokit.rest.pulls.update.mockRejectedValueOnce(new Error("API down"));
+    const result = await runTool(UpdatePullRequestBodyTool(ctx), { pull_number: 12, body: "b" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("API down");
+  });
+});
+
+describe("CreatePullRequestTool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    shellMock.mockReturnValue("feature-branch");
+  });
+
+  it("creates the PR from the current branch against the resolved base", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    const result = await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(result.isError).toBeUndefined();
+    expect(assertUnderPrCap).toHaveBeenCalledWith(ctx);
+    expect(octokit.rest.pulls.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        owner: "octo",
+        repo: "repo",
+        head: "feature-branch",
+        base: "main",
+        draft: false,
+      }),
+    );
+    expect(patchWorkflowRunFields).toHaveBeenCalledWith(ctx, { prNodeId: "PR_NODE" });
+    expect(recordRemediationPrOpened).toHaveBeenCalledWith(ctx);
+    const text = result.content[0].text;
+    expect(text).toContain("success: true");
+    expect(text).toContain("number: 12");
+    expect(text).toContain("head: feature-branch");
+    expect(text).toContain("base: main");
+  });
+
+  it("honors an explicit base and the draft flag", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    await runTool(CreatePullRequestTool(ctx), {
+      title: "t",
+      body: "b",
+      base: "release",
+      draft: true,
+    });
+
+    expect(octokit.rest.pulls.create).toHaveBeenCalledWith(
+      expect.objectContaining({ base: "release", draft: true }),
+    );
+  });
+
+  it("requests a review from the triggering user (best-effort)", async () => {
+    const { ctx, octokit } = makeToolCtx({ triggerer: "octocat" });
+    await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(octokit.rest.pulls.requestReviewers).toHaveBeenCalledWith(
+      expect.objectContaining({ pull_number: 12, reviewers: ["octocat"] }),
+    );
+  });
+
+  it("swallows a failed review request and still succeeds", async () => {
+    const { ctx, octokit } = makeToolCtx({ triggerer: "octocat" });
+    octokit.rest.pulls.requestReviewers.mockRejectedValueOnce(new Error("cannot review own PR"));
+    const result = await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("success: true");
+  });
+
+  it("skips the reviewer request without a triggerer", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(octokit.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+  });
+
+  it("skips the workflow-run patch when the PR has no node_id", async () => {
+    const { ctx, octokit } = makeToolCtx();
+    octokit.rest.pulls.create.mockResolvedValueOnce({
+      data: {
+        id: 7001,
+        number: 12,
+        node_id: "",
+        html_url: "https://gh/pr/12",
+        title: "t",
+        head: { ref: "feature-branch" },
+        base: { ref: "main" },
+      },
+    });
+    const result = await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(result.isError).toBeUndefined();
+    expect(patchWorkflowRunFields).not.toHaveBeenCalled();
+  });
+
+  it("stops at the remediation PR cap before touching git or GitHub", async () => {
+    vi.mocked(assertUnderPrCap).mockImplementationOnce(() => {
+      throw new Error("max_prs reached (3)");
+    });
+    const { ctx, octokit } = makeToolCtx();
+    const result = await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("max_prs reached");
+    expect(octokit.rest.pulls.create).not.toHaveBeenCalled();
+    expect(recordRemediationPrOpened).not.toHaveBeenCalled();
+  });
+
+  it("is blocked under push: disabled (read-only access)", async () => {
+    const { ctx, octokit } = makeToolCtx({ push: "disabled" });
+    const result = await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/read-only access/);
+    expect(assertUnderPrCap).not.toHaveBeenCalled();
+    expect(octokit.rest.pulls.create).not.toHaveBeenCalled();
+  });
+});
+
+describe("REST write-tool scope binding", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    shellMock.mockReturnValue("feature-branch");
+  });
+
+  it("update_pull_request_body refuses a PR outside the run's scope", async () => {
+    const { ctx, octokit } = makeToolCtx({ eventIssueNumber: 5 });
+    const result = await runTool(UpdatePullRequestBodyTool(ctx), {
+      pull_number: 6,
+      body: "b",
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/scoped to #5; refusing to update the body of #6/);
+    expect(octokit.rest.pulls.update).not.toHaveBeenCalled();
+  });
+
+  it("update_pull_request_body allows the run's scoped PR", async () => {
+    const { ctx, octokit } = makeToolCtx({ eventIssueNumber: 12 });
+    const result = await runTool(UpdatePullRequestBodyTool(ctx), {
+      pull_number: 12,
+      body: "b",
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(octokit.rest.pulls.update).toHaveBeenCalled();
+  });
+
+  it("update_pull_request_body allows a PR the run just created", async () => {
+    const { ctx, octokit } = makeToolCtx({ eventIssueNumber: 5 });
+    // the run opens PR #12 (create records it as owned)…
+    await runTool(CreatePullRequestTool(ctx), { title: "t", body: "b" });
+    // …so editing #12's body is now in scope even though the trigger was #5.
+    const result = await runTool(UpdatePullRequestBodyTool(ctx), {
+      pull_number: 12,
+      body: "updated",
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(octokit.rest.pulls.update).toHaveBeenCalledWith(
+      expect.objectContaining({ pull_number: 12 }),
+    );
+  });
+});