terramend 0.2.0

package/src/mcp/issueComments.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+import { GetIssueCommentsTool } from "#app/mcp/issueComments";
+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(comments: Record<string, unknown>[]) {
+  const listComments = vi.fn();
+  const paginate = vi.fn(async (_route: unknown, _params: unknown) => comments);
+  const toolState: ToolState = initToolState({ progressComment: undefined });
+  const ctx = {
+    octokit: { paginate, rest: { issues: { listComments } } },
+    repo: { owner: "octo", name: "repo" },
+    toolState,
+    tmpdir: "/tmp",
+    githubInstallationToken: "tok",
+  } as unknown as ToolContext;
+  return { ctx, paginate, listComments, toolState };
+}
+
+describe("GetIssueCommentsTool", () => {
+  it("returns all comments with authors and records the issue number", async () => {
+    const { ctx, paginate, listComments, toolState } = makeCtx([
+      { id: 1, body: "first comment", body_html: "<p>first comment</p>", user: { login: "alice" } },
+      { id: 2, body: null, user: undefined },
+    ]);
+    const result = await runTool(GetIssueCommentsTool(ctx), { issue_number: 7 });
+
+    expect(result.isError).toBeUndefined();
+    expect(toolState.issueNumber).toBe(7);
+    expect(paginate).toHaveBeenCalledWith(
+      listComments,
+      expect.objectContaining({
+        owner: "octo",
+        repo: "repo",
+        issue_number: 7,
+        headers: { accept: "application/vnd.github.full+json" },
+      }),
+    );
+
+    const text = result.content[0].text;
+    expect(text).toContain("count: 2");
+    expect(text).toContain("first comment");
+    expect(text).toContain("alice");
+  });
+
+  it("handles an issue with no comments", async () => {
+    const { ctx } = makeCtx([]);
+    const result = await runTool(GetIssueCommentsTool(ctx), { issue_number: 7 });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("count: 0");
+  });
+
+  it("surfaces pagination failures as tool errors", async () => {
+    const { ctx, paginate } = makeCtx([]);
+    paginate.mockRejectedValueOnce(new Error("rate limited"));
+    const result = await runTool(GetIssueCommentsTool(ctx), { issue_number: 7 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("rate limited");
+  });
+});

package/src/mcp/issueComments.ts

@@ -0,0 +1,48 @@
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import { resolveBodyAssets } from "#app/utils/body";
+
+export const GetIssueComments = type({
+  issue_number: type.number.describe("The issue number to get comments for"),
+});
+
+export function GetIssueCommentsTool(ctx: ToolContext) {
+  return tool({
+    name: "get_issue_comments",
+    description:
+      "Get all comments for a GitHub issue. Returns all comments including the issue body and all subsequent discussion comments. " +
+      "Example: `get_issue_comments({ issue_number: 1234 })`.",
+    parameters: GetIssueComments,
+    execute: execute(async ({ issue_number }) => {
+      // set issue context
+      ctx.toolState.issueNumber = issue_number;
+
+      const comments = await ctx.octokit.paginate(ctx.octokit.rest.issues.listComments, {
+        owner: ctx.repo.owner,
+        repo: ctx.repo.name,
+        issue_number,
+        headers: { accept: "application/vnd.github.full+json" },
+      });
+
+      const processedComments = await Promise.all(
+        comments.map(async (comment) => ({
+          id: comment.id,
+          body: await resolveBodyAssets({
+            body: comment.body,
+            bodyHtml: comment.body_html,
+            tmpdir: ctx.tmpdir,
+            githubToken: ctx.githubInstallationToken,
+          }),
+          user: comment.user?.login,
+        })),
+      );
+
+      return {
+        issue_number,
+        comments: processedComments,
+        count: processedComments.length,
+      };
+    }),
+  });
+}

package/src/mcp/issueEvents.test.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { GetIssueEventsTool } from "#app/mcp/issueEvents";
+import type { ToolContext } from "#app/mcp/server";
+import 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(events: unknown[]): {
+  ctx: ToolContext;
+  toolState: ToolState;
+  paginate: ReturnType<typeof vi.fn>;
+} {
+  const toolState = {} as ToolState;
+  const listEventsForTimeline = { endpoint: "timeline" };
+  const paginate = vi.fn(async (endpoint: unknown) => {
+    expect(endpoint).toBe(listEventsForTimeline);
+    return events;
+  });
+  const ctx = {
+    octokit: { paginate, rest: { issues: { listEventsForTimeline } } },
+    repo: { owner: "octo", name: "repo" },
+    toolState,
+  } as unknown as ToolContext;
+  return { ctx, toolState, paginate };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("GetIssueEventsTool", () => {
+  it("records the issue number on tool state and queries the timeline", async () => {
+    const { ctx, toolState, paginate } = makeCtx([]);
+    const result = await runTool(GetIssueEventsTool(ctx), { issue_number: 17 });
+
+    expect(result.isError).toBeUndefined();
+    expect(toolState.issueNumber).toBe(17);
+    expect(paginate).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ owner: "octo", repo: "repo", issue_number: 17 }),
+    );
+    expect(result.content[0].text).toContain("count: 0");
+  });
+
+  it("filters out events that are not cross_referenced/referenced", async () => {
+    const { ctx } = makeCtx([
+      { event: "labeled", id: 1 },
+      { event: "assigned", id: 2 },
+      { not_an_event: true },
+      { event: 42 },
+    ]);
+    const result = await runTool(GetIssueEventsTool(ctx), { issue_number: 17 });
+
+    expect(result.content[0].text).toContain("events: []");
+    expect(result.content[0].text).toContain("count: 0");
+  });
+
+  it("extracts cross-referenced issues and pull requests with actor fallbacks", async () => {
+    const { ctx } = makeCtx([
+      {
+        event: "cross_referenced",
+        actor: { login: "alice" },
+        created_at: "2026-06-01T00:00:00Z",
+        source: {
+          type: "issue",
+          issue: { number: 12, title: "linked issue", html_url: "https://gh/i/12" },
+        },
+      },
+      {
+        event: "cross_referenced",
+        user: { login: "bob" },
+        source: {
+          type: "issue",
+          pull_request: { number: 34, title: "linked PR", html_url: "https://gh/pr/34" },
+        },
+      },
+      // cross_referenced without a source object — only the base fields survive
+      { event: "cross_referenced", id: 3 },
+    ]);
+    const result = await runTool(GetIssueEventsTool(ctx), { issue_number: 17 });
+
+    const text = result.content[0].text;
+    expect(text).toContain("count: 3");
+    expect(text).toContain("actor: alice");
+    expect(text).toContain("actor: bob");
+    expect(text).toContain("linked issue");
+    expect(text).toContain("https://gh/i/12");
+    expect(text).toContain("linked PR");
+    expect(text).toContain("https://gh/pr/34");
+  });
+
+  it("extracts commit references from referenced events", async () => {
+    const { ctx } = makeCtx([
+      {
+        event: "referenced",
+        id: 99,
+        actor: { login: "carol" },
+        created_at: "2026-06-02T00:00:00Z",
+        commit_id: "abc123",
+        commit_url: "https://gh/commit/abc123",
+      },
+    ]);
+    const result = await runTool(GetIssueEventsTool(ctx), { issue_number: 17 });
+
+    const text = result.content[0].text;
+    expect(text).toContain("count: 1");
+    expect(text).toContain("commit_id");
+    expect(text).toContain("abc123");
+    expect(text).toContain("99");
+    expect(text).toContain("carol");
+  });
+
+  it("keeps a referenced event without commit fields (base fields only)", async () => {
+    const { ctx } = makeCtx([{ event: "referenced", id: 5 }]);
+    const result = await runTool(GetIssueEventsTool(ctx), { issue_number: 17 });
+
+    expect(result.content[0].text).toContain("count: 1");
+    expect(result.content[0].text).toContain("referenced");
+  });
+
+  it("propagates pagination failures as tool errors", async () => {
+    const { ctx, paginate } = makeCtx([]);
+    paginate.mockRejectedValueOnce(new Error("rate limited"));
+    const result = await runTool(GetIssueEventsTool(ctx), { issue_number: 17 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("rate limited");
+  });
+});

package/src/mcp/issueEvents.ts

@@ -0,0 +1,100 @@
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+
+export const GetIssueEvents = type({
+  issue_number: type.number.describe("The issue number to get events for"),
+});
+
+export function GetIssueEventsTool(ctx: ToolContext) {
+  return tool({
+    name: "get_issue_events",
+    description:
+      "Get timeline events for a GitHub issue that aren't reflected in the current state. Returns cross-references to other issues/PRs and commit references. Note: current labels, assignees, state, and milestone are already available via get_issue.",
+    parameters: GetIssueEvents,
+    execute: execute(async ({ issue_number }) => {
+      // set issue context
+      ctx.toolState.issueNumber = issue_number;
+
+      const events = await ctx.octokit.paginate(ctx.octokit.rest.issues.listEventsForTimeline, {
+        owner: ctx.repo.owner,
+        repo: ctx.repo.name,
+        issue_number,
+      });
+
+      // Only include events not reflected in current issue state (get_issue already has labels, assignees, state, etc.)
+      // Keep only relationship/reference events that show connections to other issues/PRs/commits
+      const relevantEventTypes = new Set(["cross_referenced", "referenced"]);
+
+      const parsedEvents = events.flatMap((event) => {
+        // octokit's timeline-event union includes members with `event?:
+        // string`, so `"event" in event` does not narrow it to defined.
+        // require a string before the Set.has() check.
+        if (!("event" in event) || typeof event.event !== "string") return [];
+        if (!relevantEventTypes.has(event.event)) return [];
+
+        const baseEvent: Record<string, any> = {
+          event: event.event,
+        };
+
+        // Common fields
+        if ("id" in event) {
+          baseEvent.id = event.id;
+        }
+        if ("actor" in event && event.actor) {
+          baseEvent.actor = event.actor.login;
+        } else if ("user" in event && event.user) {
+          baseEvent.actor = event.user.login;
+        }
+        if ("created_at" in event) {
+          baseEvent.created_at = event.created_at;
+        }
+
+        // Event-specific data
+        if (event.event === "cross_referenced") {
+          if ("source" in event && event.source) {
+            const source = event.source as {
+              type?: string;
+              issue?: { number: number; title: string; html_url: string };
+              pull_request?: { number: number; title: string; html_url: string };
+            };
+            baseEvent.source = {
+              type: source.type,
+              issue: source.issue
+                ? {
+                    number: source.issue.number,
+                    title: source.issue.title,
+                    html_url: source.issue.html_url,
+                  }
+                : null,
+              pull_request: source.pull_request
+                ? {
+                    number: source.pull_request.number,
+                    title: source.pull_request.title,
+                    html_url: source.pull_request.html_url,
+                  }
+                : null,
+            };
+          }
+        }
+
+        if (event.event === "referenced") {
+          if ("commit_id" in event) {
+            baseEvent.commit_id = event.commit_id;
+          }
+          if ("commit_url" in event) {
+            baseEvent.commit_url = event.commit_url;
+          }
+        }
+
+        return [baseEvent];
+      });
+
+      return {
+        issue_number,
+        events: parsedEvents,
+        count: parsedEvents.length,
+      };
+    }),
+  });
+}

package/src/mcp/issueInfo.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it, vi } from "vitest";
+import { IssueInfoTool } from "#app/mcp/issueInfo";
+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, {});
+}
+
+const fullIssue = {
+  number: 5,
+  html_url: "https://gh/issues/5",
+  title: "Broken pipeline",
+  body: "plain body",
+  body_html: "<p>plain body</p>",
+  state: "open",
+  locked: false,
+  labels: ["bug", { name: "infra" }],
+  assignees: [{ login: "alice" }],
+  user: { login: "bob" },
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-02T00:00:00Z",
+  closed_at: null,
+  comments: 2,
+  milestone: { title: "v1" },
+  pull_request: {
+    url: "https://api/pulls/5",
+    html_url: "https://gh/pull/5",
+    diff_url: "https://gh/pull/5.diff",
+    patch_url: "https://gh/pull/5.patch",
+  },
+};
+
+function makeCtx(issueData: Record<string, unknown>) {
+  const get = vi.fn(async (_p: unknown) => ({ data: issueData }));
+  const toolState: ToolState = initToolState({ progressComment: undefined });
+  const ctx = {
+    octokit: { rest: { issues: { get } } },
+    repo: { owner: "octo", name: "repo" },
+    toolState,
+    tmpdir: "/tmp",
+    githubInstallationToken: "tok",
+  } as unknown as ToolContext;
+  return { ctx, get, toolState };
+}
+
+describe("IssueInfoTool", () => {
+  it("returns issue details and records the issue number in tool state", async () => {
+    const { ctx, get, toolState } = makeCtx(fullIssue);
+    const result = await runTool(IssueInfoTool(ctx), { issue_number: 5 });
+
+    expect(result.isError).toBeUndefined();
+    expect(get).toHaveBeenCalledWith(
+      expect.objectContaining({
+        owner: "octo",
+        repo: "repo",
+        issue_number: 5,
+        headers: { accept: "application/vnd.github.full+json" },
+      }),
+    );
+    expect(toolState.issueNumber).toBe(5);
+
+    const text = result.content[0].text;
+    expect(text).toContain("Broken pipeline");
+    expect(text).toContain("plain body");
+    expect(text).toContain("infra");
+    expect(text).toContain("alice");
+    expect(text).toContain("v1");
+    expect(text).toContain("https://gh/pull/5.diff");
+    expect(text).toContain("get_issue_comments");
+    expect(text).toContain("get_issue_events");
+  });
+
+  it("omits the comments hint and nulls pull_request for a bare issue", async () => {
+    const { ctx } = makeCtx({
+      ...fullIssue,
+      comments: 0,
+      pull_request: undefined,
+      labels: undefined,
+      assignees: undefined,
+      user: null,
+      milestone: undefined,
+    });
+    const result = await runTool(IssueInfoTool(ctx), { issue_number: 5 });
+
+    expect(result.isError).toBeUndefined();
+    const text = result.content[0].text;
+    expect(text).not.toContain("get_issue_comments");
+    expect(text).toContain("get_issue_events");
+    expect(text).toContain("pull_request: null");
+  });
+
+  it("surfaces API failures as tool errors", async () => {
+    const { ctx, get } = makeCtx(fullIssue);
+    get.mockRejectedValueOnce(new Error("API down"));
+    const result = await runTool(IssueInfoTool(ctx), { issue_number: 5 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("API down");
+  });
+});

package/src/mcp/issueInfo.ts

@@ -0,0 +1,72 @@
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import { resolveBodyAssets } from "#app/utils/body";
+
+export const IssueInfo = type({
+  issue_number: type.number.describe("The issue number to fetch"),
+});
+
+export function IssueInfoTool(ctx: ToolContext) {
+  return tool({
+    name: "get_issue",
+    description:
+      "Retrieve GitHub issue information by issue number. " +
+      "Example: `get_issue({ issue_number: 1234 })`.",
+    parameters: IssueInfo,
+    execute: execute(async ({ issue_number }) => {
+      const issue = await ctx.octokit.rest.issues.get({
+        owner: ctx.repo.owner,
+        repo: ctx.repo.name,
+        issue_number,
+        headers: { accept: "application/vnd.github.full+json" },
+      });
+
+      const data = issue.data;
+
+      const body = await resolveBodyAssets({
+        body: data.body,
+        bodyHtml: data.body_html,
+        tmpdir: ctx.tmpdir,
+        githubToken: ctx.githubInstallationToken,
+      });
+
+      // set issue context
+      ctx.toolState.issueNumber = issue_number;
+
+      const hints: string[] = [];
+      if (data.comments > 0) {
+        hints.push("use get_issue_comments to retrieve all comments for this issue");
+      }
+      hints.push(
+        "use get_issue_events to retrieve cross-references and commit references (relationships not reflected in current state)",
+      );
+
+      return {
+        number: data.number,
+        url: data.html_url,
+        title: data.title,
+        body: body,
+        state: data.state,
+        locked: data.locked,
+        labels: data.labels?.map((label) => (typeof label === "string" ? label : label.name)),
+        assignees: data.assignees?.map((assignee) => assignee.login),
+        user: data.user?.login,
+        created_at: data.created_at,
+        updated_at: data.updated_at,
+        closed_at: data.closed_at,
+        comments: data.comments,
+        milestone: data.milestone?.title,
+        pull_request: data.pull_request
+          ? {
+              url: data.pull_request.url,
+              html_url: data.pull_request.html_url,
+              diff_url: data.pull_request.diff_url,
+              patch_url: data.pull_request.patch_url,
+            }
+          : null,
+        hints,
+      };
+    }),
+  });
+}

package/src/mcp/labels.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from "vitest";
+import { AddLabelsTool } from "#app/mcp/labels";
+import type { ToolContext } from "#app/mcp/server";
+
+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() {
+  const addLabels = vi.fn(async (_p: unknown) => ({
+    data: [{ name: "bug" }, { name: "infra" }],
+  }));
+  const ctx = {
+    octokit: { rest: { issues: { addLabels } } },
+    repo: { owner: "octo", name: "repo" },
+  } as unknown as ToolContext;
+  return { ctx, addLabels };
+}
+
+describe("AddLabelsTool", () => {
+  it("adds labels and returns the resulting label set", async () => {
+    const { ctx, addLabels } = makeCtx();
+    const result = await runTool(AddLabelsTool(ctx), {
+      issue_number: 12,
+      labels: ["bug", "infra"],
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(addLabels).toHaveBeenCalledWith({
+      owner: "octo",
+      repo: "repo",
+      issue_number: 12,
+      labels: ["bug", "infra"],
+    });
+    const text = result.content[0].text;
+    expect(text).toContain("success: true");
+    expect(text).toContain("bug");
+    expect(text).toContain("infra");
+  });
+
+  it("surfaces API failures as tool errors", async () => {
+    const { ctx, addLabels } = makeCtx();
+    addLabels.mockRejectedValueOnce(new Error("Label does not exist"));
+    const result = await runTool(AddLabelsTool(ctx), { issue_number: 12, labels: ["nope"] });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Label does not exist");
+  });
+});

package/src/mcp/labels.ts

@@ -0,0 +1,34 @@
+import { type } from "arktype";
+import { assertTargetInScope } from "#app/mcp/scope";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+export const AddLabelsParams = type({
+  issue_number: type.number.describe("the issue or PR number to add labels to"),
+  labels: type.string.array().atLeastLength(1).describe("array of label names to add"),
+});
+
+export function AddLabelsTool(ctx: ToolContext) {
+  return tool({
+    name: "add_labels",
+    description:
+      "Add labels to a GitHub issue or pull request. Only use labels that already exist in the repository.",
+    parameters: AddLabelsParams,
+    execute: execute(async ({ issue_number, labels }) => {
+      assertTargetInScope(ctx, issue_number, "add labels to");
+      const result = await ctx.octokit.rest.issues.addLabels({
+        owner: ctx.repo.owner,
+        repo: ctx.repo.name,
+        issue_number,
+        labels,
+      });
+      log.info(`» added labels [${labels.join(", ")}] to issue #${issue_number}`);
+
+      return {
+        success: true,
+        labels: result.data.map((label) => label.name),
+      };
+    }),
+  });
+}

package/src/mcp/localContext.ts

@@ -0,0 +1,28 @@
+import type { ToolState } from "#app/toolState";
+import type { ResolvedPayload } from "#app/utils/payload";
+
+/**
+ * The cwd-scoped, GitHub-free subset of `ToolContext` that the read-only
+ * Terraform tools depend on. Two providers exist:
+ *
+ *   - the GitHub Action run: the full `ToolContext` (structurally assignable —
+ *     it carries these fields plus the GitHub/auth surface), and
+ *   - `terramend mcp` (the local stdio MCP server): exactly this shape, built
+ *     from CLI flags — no octokit, no tokens, no event payload.
+ *
+ * Keep this interface to fields a LOCAL run can genuinely provide. A tool that
+ * needs more (octokit, push, PR state) belongs on `ToolContext`, not here.
+ */
+export interface LocalToolContext {
+  payload: Pick<
+    ResolvedPayload,
+    | "cwd"
+    | "scanScope"
+    | "severityThreshold"
+    | "autonomyThreshold"
+    | "costIncreaseBlockUsd"
+    | "moduleCatalogue"
+  >;
+  toolState: ToolState;
+  tmpdir: string;
+}