infraweaver 0.1.0

package/src/mcp/issue.ts

@@ -0,0 +1,74 @@
+import { type } from "arktype";
+import type { GitHubWriteToolContext } from "#app/mcp/capabilityContext";
+import { recordCreatedTarget } from "#app/mcp/scope";
+import { execute, tool } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+import { fixDoubleEscapedString } from "#app/utils/fixDoubleEscapedString";
+import { patchWorkflowRunFields } from "#app/utils/patchWorkflowRunFields";
+
+export const Issue = type({
+  title: type.string.describe("the title of the issue"),
+  body: type.string.describe("the body content of the issue"),
+  labels: type.string
+    .array()
+    .describe("optional array of label names to apply to the issue")
+    .optional(),
+  assignees: type.string
+    .array()
+    .describe("optional array of usernames to assign to the issue")
+    .optional(),
+});
+
+export function IssueTool(ctx: GitHubWriteToolContext) {
+  return tool({
+    mutates: true,
+    name: "create_issue",
+    description: "Create a new GitHub issue",
+    parameters: Issue,
+    execute: execute(async (params) => {
+      // permission gate: creating an issue is a repo write. `push: disabled`
+      // means read-only access, so block it (matches create_pull_request /
+      // push_branch) — an injected or read-only-intended agent must not be able
+      // to file issues.
+      if (ctx.payload.push === "disabled") {
+        throw new Error(
+          "Creating an issue is disabled. This repository is configured for read-only access (push: disabled).",
+        );
+      }
+
+      const result = await ctx.octokit.rest.issues.create({
+        owner: ctx.repo.owner,
+        repo: ctx.repo.name,
+        title: params.title,
+        body: fixDoubleEscapedString(params.body),
+        labels: params.labels ?? [],
+        assignees: params.assignees ?? [],
+      });
+
+      log.info(`» created issue #${result.data.number} (id ${result.data.id})`);
+
+      // record so a later comment on / label of THIS issue passes the scope guard.
+      recordCreatedTarget(ctx, result.data.number);
+
+      const nodeId = result.data.node_id;
+      if (typeof nodeId === "string" && nodeId.length > 0) {
+        await patchWorkflowRunFields(ctx, {
+          issueNodeId: nodeId,
+        });
+      }
+
+      return {
+        success: true,
+        issueId: result.data.id,
+        number: result.data.number,
+        url: result.data.html_url,
+        title: result.data.title,
+        state: result.data.state,
+        labels: result.data.labels?.map((label) =>
+          typeof label === "string" ? label : label.name,
+        ),
+        assignees: result.data.assignees?.map((assignee) => assignee.login),
+      };
+    }),
+  });
+}

package/src/mcp/issueComments.ts

@@ -0,0 +1,48 @@
+import { type } from "arktype";
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+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: GitHubToolContext) {
+  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.ts

@@ -0,0 +1,100 @@
+import { type } from "arktype";
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+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: GitHubToolContext) {
+  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.ts

@@ -0,0 +1,72 @@
+import { type } from "arktype";
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+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: GitHubToolContext) {
+  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.ts

@@ -0,0 +1,35 @@
+import { type } from "arktype";
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+import { assertTargetInScope } from "#app/mcp/scope";
+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: GitHubToolContext) {
+  return tool({
+    mutates: true,
+    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,65 @@
+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
+ *   - `infraweaver 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"
+    // multi-language Assess scope: which IaC languages the READ-ONLY surfaces
+    // (Assess / SARIF / evidence) report on ("auto" | "terraform" | comma list).
+    // The fix loop stays Terraform-first regardless of this.
+    | "iacLanguages"
+    | "severityThreshold"
+    | "grouping"
+    | "autonomyThreshold"
+    | "costIncreaseBlockUsd"
+    | "moduleCatalogue"
+    // resource addresses the operator allows to be destroyed/replaced. Read by
+    // terraform_plan (read-only) to surface, at plan time, whether a stateful
+    // destroy/replace WOULD be blocked at push — moving the allow_replace gate
+    // earlier so a committing mode abandons before a wasted commit/push.
+    | "allowReplace"
+    // the unified tool selection + module-fetch/registry credentials are honoured
+    // on the local stdio MCP server too (read-only scans + private-module init).
+    | "toolsEnabled"
+    // per-scanner egress policy (supply-chain 0.2) — honoured wherever the
+    // scanners run, so a local session gets the same bounded-egress toolchain.
+    | "toolsNetwork"
+    | "gitleaks"
+    | "terratest"
+    | "docs"
+    | "terraformMcp"
+    | "moduleFetchToken"
+    | "moduleFetchSshKey"
+    | "registryToken"
+    | "registryHost"
+    | "opentofuMcp"
+    // §5.12 reusable proven-fix memory: capture proven transformations + offer
+    // them as priors (via the read-only terraform_fix_memory tool). Honoured on
+    // the local stdio MCP server too, so a CLI/IDE session benefits from a
+    // committed `.infraweaver.fix-memory.json`.
+    | "fixMemory"
+  >;
+  toolState: ToolState;
+  tmpdir: string;
+  /** resolved upstream model specifier driving this run's agent (e.g.
+   * "anthropic/claude-opus-4-8"). The Action's full `ToolContext` carries it
+   * (structurally assignable); a local `infraweaver mcp` session has no agent of
+   * its own, so it is absent there. Read by `terraform_emit_evidence` for the
+   * bundle's PROVENANCE block (A.3) — recording WHO produced the evidence, not
+   * just what was found. */
+  resolvedModel?: string | undefined;
+}

package/src/mcp/localServer.ts

@@ -0,0 +1,217 @@
+/**
+ * `infraweaver mcp` — the LOCAL stdio MCP server.
+ *
+ * Exposes infraweaver'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 { PRODUCT_SLUG } from "#app/brand";
+import { infraweaverMcpName } from "#app/external";
+import { TerraformAssessTool } from "#app/mcp/assess";
+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 {
+  DetectPlanDriftTool,
+  InfracostDiffTool,
+  IngestExternalFindingsTool,
+  NormalizationCandidatesTool,
+  ReadFindingsTool,
+  TerraformEmitCostTool,
+  TerraformEmitEvidenceTool,
+  TerraformEmitOscalTool,
+  TerraformEmitSarifTool,
+  TerraformEmitVexTool,
+  TerraformEquivalenceCheckTool,
+  TerraformFixMemoryTool,
+  TerraformGenerateMovedTool,
+  TerraformModuleDocsTool,
+  TerraformModuleLookupTool,
+  TerraformModuleSearchTool,
+  TerraformPlanTool,
+  TerraformProviderUpgradeTool,
+  TerraformQueryInventoryTool,
+  TerraformScanTool,
+  TerraformValidateTool,
+  TerraformVerifyRemediationTool,
+  TerraformVersionCurrencyTool,
+} from "#app/mcp/terraform";
+import { parseToolsNetwork } from "#app/mcp/terraform/scannerEgress";
+import { initToolState } from "#app/toolState";
+import { log } from "#app/utils/cli";
+import { parseToolSelection } from "#app/utils/toolSelection";
+
+export interface LocalMcpOptions {
+  /** absolute workspace directory the tools operate on. */
+  cwd: string;
+  severityThreshold?:
+    | "critical"
+    | "high"
+    | "medium"
+    | "low"
+    | "info"
+    | undefined;
+  scanScope?: "full" | "diff" | undefined;
+  /** multi-language Assess scope ("auto" | "terraform" | comma list); undefined → "auto". */
+  iacLanguages?: string | undefined;
+  /** default remediation grouping ("file" | "rule"); undefined → "file". */
+  grouping?: "file" | "rule" | undefined;
+  /** newline/comma-separated approved module list (same as the action input). */
+  moduleCatalogue?: string | undefined;
+  /** the unified tool-selection list (same syntax as the action input). */
+  toolsEnabled?: string | undefined;
+  /** per-scanner egress policy (same syntax as the `tools_network` input). */
+  toolsNetwork?: string | undefined;
+  /** scoped token to fetch private cross-repo `git::` modules at init. */
+  moduleFetchToken?: string | undefined;
+  /** SSH/deploy key for `git::ssh://…` cross-repo modules (the SSH counterpart). */
+  moduleFetchSshKey?: string | undefined;
+  /** scoped bearer token to fetch a private Terraform REGISTRY module at init. */
+  registryToken?: string | undefined;
+  /** host(s) the registry token authorises (default: app.terraform.io). */
+  registryHost?: 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,
+      iacLanguages: options.iacLanguages,
+      severityThreshold: options.severityThreshold,
+      grouping: options.grouping,
+      autonomyThreshold: undefined,
+      costIncreaseBlockUsd: undefined,
+      // a local `infraweaver mcp` run has no PR/push surface, so the
+      // allow_replace gate never engages — terraform_plan reports
+      // blocked_destructive informationally with push_will_block: false.
+      allowReplace: undefined,
+      moduleCatalogue: options.moduleCatalogue,
+      toolsEnabled: parseToolSelection(options.toolsEnabled),
+      toolsNetwork: options.toolsNetwork
+        ? parseToolsNetwork(options.toolsNetwork)
+        : undefined,
+      gitleaks: false,
+      terratest: false,
+      // a local `infraweaver mcp` user invoking terraform_module_docs has asked
+      // for the README write (same rationale as the emit_sarif exception), and
+      // there is no push surface here for the allow-list to gate.
+      docs: true,
+      terraformMcp: false,
+      opentofuMcp: false,
+      // read-only offer surface: terraform_fix_memory reads a committed
+      // `.infraweaver.fix-memory.json` so a local CLI/IDE session gets the same
+      // proven priors a Cloud-connected run does. Capture (the write side) only
+      // happens on the full Action run, so enabling it here is offer-only.
+      fixMemory: true,
+      moduleFetchToken: options.moduleFetchToken,
+      moduleFetchSshKey: options.moduleFetchSshKey,
+      registryToken: options.registryToken,
+      registryHost: options.registryHost,
+    },
+    toolState: initToolState({ progressComment: undefined }),
+    tmpdir: mkdtempSync(join(tmpdir(), `${PRODUCT_SLUG}-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),
+    TerraformAssessTool(ctx),
+    TerraformValidateTool(ctx),
+    TerraformVerifyRemediationTool(ctx),
+    TerraformFixMemoryTool(ctx),
+    TerraformPlanTool(ctx),
+    TerraformProviderUpgradeTool(ctx),
+    TerraformVersionCurrencyTool(ctx),
+    TerraformModuleLookupTool(ctx),
+    TerraformModuleSearchTool(ctx),
+    InfracostDiffTool(ctx),
+    ReadFindingsTool(ctx),
+    IngestExternalFindingsTool(ctx),
+    DetectPlanDriftTool(ctx),
+    TerraformEmitSarifTool(ctx),
+    TerraformEmitEvidenceTool(ctx),
+    TerraformEmitOscalTool(ctx),
+    TerraformEmitVexTool(ctx),
+    TerraformEmitCostTool(ctx),
+    ListModulesTool(ctx),
+    TerraformModuleGraphTool(ctx),
+    TerraformModuleInterfaceTool(ctx),
+    TerraformModuleTestsTool(ctx),
+    ModuleExtractionCandidatesTool(ctx),
+    NormalizationCandidatesTool(ctx),
+    TerraformQueryInventoryTool(ctx),
+    TerraformEquivalenceCheckTool(ctx),
+    TerraformGenerateMovedTool(ctx),
+    TerraformModuleDocsTool(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: infraweaverMcpName,
+    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. Use terraform_module_lookup / " +
+      "terraform_module_search to read or find published registry modules (and their real " +
+      "inputs/outputs) before wiring a module block. 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(`» ${PRODUCT_SLUG} mcp: stdio server ready (cwd: ${options.cwd})`);
+  return {
+    stop: async () => {
+      await server.stop();
+    },
+  };
+}