terramend 0.2.0

package/src/mcp/output.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { SetOutputTool } from "#app/mcp/output";
+import type { ToolContext } from "#app/mcp/server";
+import { initToolState, type ToolState } from "#app/toolState";
+
+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 makeCtx(): { ctx: ToolContext; toolState: ToolState } {
+  const toolState = initToolState({ progressComment: undefined });
+  const ctx = { toolState } as unknown as ToolContext;
+  return { ctx, toolState };
+}
+
+type StandardValidate = {
+  "~standard": {
+    vendor: string;
+    jsonSchema: { input: () => Record<string, unknown>; output: () => Record<string, unknown> };
+    validate: (input: unknown) => {
+      value?: unknown;
+      issues?: { message: string; path: string[] }[];
+    };
+  };
+};
+
+const objectSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "object",
+  properties: { foo: { type: "string" } },
+  required: ["foo"],
+  additionalProperties: false,
+};
+
+describe("SetOutputTool (string output)", () => {
+  it("stores the raw value on tool state", async () => {
+    const { ctx, toolState } = makeCtx();
+    const result = await runTool(SetOutputTool(ctx), { value: "hello world" });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("success: true");
+    expect(toolState.output).toBe("hello world");
+  });
+});
+
+describe("SetOutputTool (structured output schema)", () => {
+  it("stores the params serialized as JSON", async () => {
+    const { ctx, toolState } = makeCtx();
+    const result = await runTool(SetOutputTool(ctx, objectSchema), { foo: "bar" });
+
+    expect(result.isError).toBeUndefined();
+    expect(toolState.output).toBe(JSON.stringify({ foo: "bar" }));
+  });
+
+  it("exposes the JSON schema (minus $schema) through the standard-schema surface", () => {
+    const { ctx } = makeCtx();
+    const tool = SetOutputTool(ctx, objectSchema);
+    const std = (tool.parameters as unknown as StandardValidate)["~standard"];
+
+    expect(std.vendor).toBe("json-schema");
+    expect(std.jsonSchema.input()).not.toHaveProperty("$schema");
+    expect(std.jsonSchema.output()).toMatchObject({ type: "object" });
+  });
+
+  it("validates conforming input", () => {
+    const { ctx } = makeCtx();
+    const tool = SetOutputTool(ctx, objectSchema);
+    const std = (tool.parameters as unknown as StandardValidate)["~standard"];
+
+    expect(std.validate({ foo: "ok" })).toEqual({ value: { foo: "ok" } });
+  });
+
+  it("reports root-level validation failures with a '/' path", () => {
+    const { ctx } = makeCtx();
+    const tool = SetOutputTool(ctx, objectSchema);
+    const std = (tool.parameters as unknown as StandardValidate)["~standard"];
+
+    const result = std.validate(42);
+    expect(result.value).toBeUndefined();
+    expect(result.issues?.[0]?.message).toMatch(/^\/: must be object/);
+    expect(result.issues?.[0]?.path).toEqual([]);
+  });
+
+  it("reports nested validation failures with the instance path", () => {
+    const { ctx } = makeCtx();
+    const tool = SetOutputTool(ctx, objectSchema);
+    const std = (tool.parameters as unknown as StandardValidate)["~standard"];
+
+    const result = std.validate({ foo: 42 });
+    expect(result.issues?.[0]?.message).toMatch(/\/foo: must be string/);
+    expect(result.issues?.[0]?.path).toEqual(["foo"]);
+  });
+});

package/src/mcp/output.ts

@@ -0,0 +1,70 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+import { Ajv } from "ajv";
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+
+export const SetOutputParams = type({
+  value: type.string.describe("the output value to expose as a GitHub Action output"),
+});
+
+type JsonSchema = Record<string, unknown>;
+
+function jsonSchemaToStandardSchema({
+  $schema: _,
+  ...jsonSchema
+}: JsonSchema): StandardJSONSchemaV1<any> & StandardSchemaV1<any> {
+  const ajv = new Ajv();
+  const validate = ajv.compile(jsonSchema);
+
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "json-schema",
+      jsonSchema: {
+        input: () => jsonSchema,
+        output: () => jsonSchema,
+      },
+      validate(input: unknown) {
+        if (validate(input)) {
+          return { value: input };
+        }
+        return {
+          issues: (validate.errors ?? []).map((err) => ({
+            message: `${err.instancePath || "/"}: ${err.message ?? "validation error"}`,
+            path: err.instancePath ? err.instancePath.split("/").filter(Boolean) : [],
+          })),
+        };
+      },
+    },
+  };
+}
+
+function storeOutput(ctx: ToolContext, value: string) {
+  ctx.toolState.output = value;
+  return { success: true };
+}
+
+export function SetOutputTool(ctx: ToolContext, outputSchema?: JsonSchema) {
+  if (outputSchema) {
+    return tool({
+      name: "set_output",
+      description:
+        "Set the structured action output. You MUST call this tool before finishing — the output is required. Pass the output object directly as the tool arguments (no wrapping needed).",
+      parameters: jsonSchemaToStandardSchema(outputSchema),
+      execute: execute(async (params) => {
+        return storeOutput(ctx, JSON.stringify(params));
+      }),
+    });
+  }
+
+  return tool({
+    name: "set_output",
+    description:
+      "Set the action output. Exposes the value as the 'result' GitHub Action output for downstream workflow steps. Do NOT use this for progress reporting — use report_progress instead.",
+    parameters: SetOutputParams,
+    execute: execute(async (params) => {
+      return storeOutput(ctx, params.value);
+    }),
+  });
+}

package/src/mcp/pathSafety.test.ts

@@ -0,0 +1,44 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+
+// `resolve("workspace-root")` yields an absolute path under the test cwd, so the
+// assertions are drive-correct on Windows and POSIX alike.
+const base = resolve("workspace-root");
+
+describe("resolveWithinCwd", () => {
+  it("allows a relative child path", () => {
+    expect(resolveWithinCwd(base, "findings.json")).toBe(resolve(base, "findings.json"));
+  });
+
+  it("allows a nested relative child path", () => {
+    expect(resolveWithinCwd(base, "reports/out.sarif")).toBe(resolve(base, "reports/out.sarif"));
+  });
+
+  it("allows the workspace root itself", () => {
+    expect(resolveWithinCwd(base, ".")).toBe(base);
+  });
+
+  it("allows traversal that resolves back inside the workspace", () => {
+    expect(resolveWithinCwd(base, "a/../b.json")).toBe(resolve(base, "b.json"));
+  });
+
+  it("allows an absolute path that is inside the workspace", () => {
+    const inside = resolve(base, "deep/x.json");
+    expect(resolveWithinCwd(base, inside)).toBe(inside);
+  });
+
+  it("rejects parent traversal", () => {
+    expect(() => resolveWithinCwd(base, "../escape")).toThrow(/escapes the workspace/);
+  });
+
+  it("rejects deep traversal that resolves outside", () => {
+    expect(() => resolveWithinCwd(base, "a/../../escape")).toThrow(/escapes the workspace/);
+  });
+
+  it("rejects an absolute path outside the workspace", () => {
+    expect(() => resolveWithinCwd(base, resolve(base, "../sibling/x"))).toThrow(
+      /escapes the workspace/,
+    );
+  });
+});

package/src/mcp/pathSafety.ts

@@ -0,0 +1,28 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+/**
+ * Resolve an agent-supplied path against `cwd` and confine it to that workspace.
+ *
+ * Returns the absolute path when it stays inside `cwd`; throws otherwise. Blocks
+ * both `..` traversal and absolute paths that point outside `cwd` (including a
+ * different drive on Windows, where `relative` returns an absolute path).
+ *
+ * Terramend treats the agent as semi-trusted (attacker-controlled PR content can
+ * prompt-inject it), so any tool that reads or writes a file path the agent
+ * controls — read_findings, terraform_emit_sarif, terraform_module_interface —
+ * must confine that path to the workspace. Without it the agent has an arbitrary
+ * file read (findings) or write (SARIF) primitive on the runner.
+ */
+export function resolveWithinCwd(cwd: string, userPath: string): string {
+  const base = resolve(cwd);
+  const target = resolve(base, userPath);
+  const rel = relative(base, target);
+  // rel === "" means target IS the workspace root; a child path neither starts
+  // with ".." nor is absolute. Anything else escaped the workspace.
+  if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) {
+    return target;
+  }
+  throw new Error(
+    `path '${userPath}' escapes the workspace; only paths inside the working directory are allowed.`,
+  );
+}

package/src/mcp/policy.test.ts

@@ -0,0 +1,282 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PolicyCheckTool, parseConftestOutput } from "#app/mcp/policy";
+import type { ToolContext } from "#app/mcp/server";
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return { ...actual, default: actual, existsSync: vi.fn(() => false) };
+});
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, default: actual, spawnSync: vi.fn() };
+});
+
+vi.mock("#app/utils/secrets", () => ({
+  resolveEnv: vi.fn(() => ({})),
+}));
+
+const existsSyncMock = vi.mocked(existsSync);
+const spawnSyncMock = vi.mocked(spawnSync);
+
+describe("parseConftestOutput", () => {
+  it("returns a clean pass for empty/malformed input", () => {
+    expect(parseConftestOutput("")).toEqual({
+      passed: true,
+      failures: [],
+      warnings: [],
+      tested: 0,
+    });
+    expect(parseConftestOutput("not json")).toEqual({
+      passed: true,
+      failures: [],
+      warnings: [],
+      tested: 0,
+    });
+    expect(parseConftestOutput("{}")).toEqual({
+      passed: true,
+      failures: [],
+      warnings: [],
+      tested: 0,
+    });
+  });
+
+  it("counts successes and reports zero failures as passed", () => {
+    const out = parseConftestOutput(
+      JSON.stringify([
+        { filename: "plan.json", namespace: "main", successes: 3, failures: [], warnings: [] },
+      ]),
+    );
+    expect(out.passed).toBe(true);
+    expect(out.tested).toBe(3);
+    expect(out.failures).toHaveLength(0);
+  });
+
+  it("captures failures with file + level and fails the gate", () => {
+    const out = parseConftestOutput(
+      JSON.stringify([
+        {
+          filename: "plan.json",
+          successes: 1,
+          failures: [{ msg: "S3 bucket must be encrypted" }],
+          warnings: [{ msg: "consider tagging" }],
+        },
+      ]),
+    );
+    expect(out.passed).toBe(false);
+    expect(out.failures).toEqual([
+      { msg: "S3 bucket must be encrypted", file: "plan.json", level: "failure" },
+    ]);
+    expect(out.warnings).toEqual([
+      { msg: "consider tagging", file: "plan.json", level: "warning" },
+    ]);
+    // 1 success + 1 failure + 1 warning
+    expect(out.tested).toBe(3);
+  });
+
+  it("warnings alone do not fail the gate", () => {
+    const out = parseConftestOutput(
+      JSON.stringify([{ filename: "plan.json", warnings: [{ msg: "w" }] }]),
+    );
+    expect(out.passed).toBe(true);
+    expect(out.warnings).toHaveLength(1);
+  });
+
+  it("aggregates failures across multiple files", () => {
+    const out = parseConftestOutput(
+      JSON.stringify([
+        { filename: "a.json", failures: [{ msg: "x" }] },
+        { filename: "b.json", failures: [{ msg: "y" }] },
+      ]),
+    );
+    expect(out.passed).toBe(false);
+    expect(out.failures.map((f) => f.file)).toEqual(["a.json", "b.json"]);
+  });
+
+  it("defaults a missing failure message and filename", () => {
+    const out = parseConftestOutput(JSON.stringify([{ failures: [{}] }]));
+    expect(out.failures[0]).toEqual({ msg: "policy violation", file: "(plan)", level: "failure" });
+  });
+
+  it("defaults a missing warning message", () => {
+    const out = parseConftestOutput(JSON.stringify([{ warnings: [{}] }]));
+    expect(out.warnings[0]).toEqual({ msg: "policy warning", file: "(plan)", level: "warning" });
+  });
+});
+
+// ── PolicyCheckTool (the shell-out wrapper around the pure parser) ────────────
+
+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, {});
+}
+
+const CWD = join(path("ws"), "repo");
+
+function path(...segs: string[]): string {
+  return join("/", ...segs);
+}
+
+function makeCtx(cwd: string | undefined = CWD): ToolContext {
+  return { payload: { cwd } } as unknown as ToolContext;
+}
+
+/** existsSync only returns true for the given absolute paths. */
+function filesExist(...paths: string[]): void {
+  existsSyncMock.mockImplementation((p) => paths.includes(String(p)));
+}
+
+function spawnResult(over: Partial<ReturnType<typeof spawnSync>>): ReturnType<typeof spawnSync> {
+  return {
+    pid: 1,
+    output: [],
+    stdout: "[]",
+    stderr: "",
+    status: 0,
+    signal: null,
+    error: undefined,
+    ...over,
+  } as unknown as ReturnType<typeof spawnSync>;
+}
+
+describe("PolicyCheckTool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    existsSyncMock.mockReturnValue(false);
+  });
+
+  it("skips with no_policy_dir when no default policy dir exists", async () => {
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("ok: false");
+    expect(result.content[0].text).toContain("code: no_policy_dir");
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+
+  it("skips with no_policy_dir when the explicit policy_dir is missing", async () => {
+    const result = await runTool(PolicyCheckTool(makeCtx()), { policy_dir: "rego" });
+
+    expect(result.content[0].text).toContain("code: no_policy_dir");
+    expect(existsSyncMock).toHaveBeenCalledWith(join(CWD, "rego"));
+  });
+
+  it("skips with target_not_found when the explicit target does not exist", async () => {
+    filesExist(join(CWD, "policy"));
+    const result = await runTool(PolicyCheckTool(makeCtx()), { target: "missing.json" });
+
+    expect(result.content[0].text).toContain("code: target_not_found");
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+
+  it("skips with no_target when no conventional plan JSON exists", async () => {
+    filesExist(join(CWD, "policies"));
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    expect(result.content[0].text).toContain("code: no_target");
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+
+  it("skips with conftest_not_installed on a spawn ENOENT", async () => {
+    filesExist(join(CWD, "policy"), join(CWD, "plan.json"));
+    const enoent = Object.assign(new Error("spawn conftest ENOENT"), { code: "ENOENT" });
+    spawnSyncMock.mockReturnValue(spawnResult({ error: enoent }));
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    expect(result.content[0].text).toContain("code: conftest_not_installed");
+  });
+
+  it("skips with conftest_failed when a non-zero exit evaluated nothing", async () => {
+    filesExist(join(CWD, "policy"), join(CWD, "plan.json"));
+    spawnSyncMock.mockReturnValue(
+      spawnResult({ status: 1, stdout: "", stderr: "rego_parse_error: unexpected token" }),
+    );
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    expect(result.content[0].text).toContain("code: conftest_failed");
+    expect(result.content[0].text).toContain("rego_parse_error");
+  });
+
+  it("reports an unknown error when conftest fails without stderr", async () => {
+    filesExist(join(CWD, "policy"), join(CWD, "plan.json"));
+    spawnSyncMock.mockReturnValue(spawnResult({ status: 2, stdout: "", stderr: "   " }));
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    expect(result.content[0].text).toContain("unknown error");
+  });
+
+  it("passes a clean evaluation and reports the resolved dir + target", async () => {
+    filesExist(join(CWD, "policy"), join(CWD, "plan.json"));
+    spawnSyncMock.mockReturnValue(
+      spawnResult({ stdout: JSON.stringify([{ filename: "plan.json", successes: 4 }]) }),
+    );
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    const text = result.content[0].text;
+    expect(text).toContain("ok: true");
+    expect(text).toContain("passed: true");
+    expect(text).toContain("tested: 4");
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      "conftest",
+      ["test", "--output", "json", "-p", join(CWD, "policy"), join(CWD, "plan.json")],
+      expect.objectContaining({ cwd: CWD }),
+    );
+  });
+
+  it("flows a genuine denial (non-zero exit WITH failures) through to passed: false", async () => {
+    filesExist(join(CWD, "policy"), join(CWD, "plan.json"));
+    spawnSyncMock.mockReturnValue(
+      spawnResult({
+        status: 1,
+        stdout: JSON.stringify([
+          { filename: "plan.json", failures: [{ msg: "bucket must be encrypted" }] },
+        ]),
+      }),
+    );
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    const text = result.content[0].text;
+    expect(text).toContain("ok: true");
+    expect(text).toContain("passed: false");
+    expect(text).toContain("failure_count: 1");
+    expect(text).toContain("bucket must be encrypted");
+  });
+
+  it("falls back through the default policy dirs in order", async () => {
+    filesExist(join(CWD, ".conftest"), join(CWD, "tfplan.json"));
+    spawnSyncMock.mockReturnValue(spawnResult({ stdout: "[]" }));
+    const result = await runTool(PolicyCheckTool(makeCtx()), {});
+
+    expect(result.content[0].text).toContain("ok: true");
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      "conftest",
+      expect.arrayContaining([join(CWD, ".conftest"), join(CWD, "tfplan.json")]),
+      expect.anything(),
+    );
+  });
+
+  it("accepts absolute policy_dir and target paths and a default cwd", async () => {
+    const absPolicy = join(path("abs"), "rego");
+    const absTarget = join(path("abs"), "plan.json");
+    expect(isAbsolute(absPolicy)).toBe(true);
+    filesExist(absPolicy, absTarget);
+    spawnSyncMock.mockReturnValue(spawnResult({ stdout: "[]" }));
+    const noCwdCtx = { payload: {} } as unknown as ToolContext;
+    const result = await runTool(PolicyCheckTool(noCwdCtx), {
+      policy_dir: absPolicy,
+      target: absTarget,
+    });
+
+    expect(result.content[0].text).toContain("ok: true");
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      "conftest",
+      ["test", "--output", "json", "-p", absPolicy, absTarget],
+      expect.objectContaining({ cwd: process.cwd() }),
+    );
+  });
+});