infraweaver 0.1.0

package/src/mcp/roots.ts

@@ -0,0 +1,217 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { walkTfFiles } from "#app/mcp/modules";
+import { execute, tool } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+/**
+ * Multi-root awareness. A repo can hold SEVERAL Terraform root modules — the
+ * dirs you'd run `terraform init/plan/apply` in — not one. hepcare, for example,
+ * has `terraform/` AND `terraform/core/`, plus a child module under
+ * `terraform/modules/`. The scanners run recursively, but plan/validate assume a
+ * single `cwd`; this surfaces the roots so a run can act per-root.
+ *
+ * Heuristic (validated against real repos): a ROOT is a dir whose `*.tf`
+ * declares a PROVIDER CONFIGURATION (`provider "<name>" { … }`) or a BACKEND
+ * (`backend "<type>" { … }`). A CHILD MODULE never configures a provider or a
+ * backend (it only declares `required_providers`), so this cleanly separates the
+ * two. Pure parsing + a single fs walk; no subprocess.
+ */
+
+export interface TerraformRoot {
+  /** repo-relative dir (POSIX); "" for the top-level. */
+  dir: string;
+  hasBackend: boolean;
+  hasProviderConfig: boolean;
+  tfFileCount: number;
+}
+
+// a provider CONFIGURATION block — `provider "aws" {`. Distinct from a
+// `required_providers` block (which child modules also have). The negative
+// lookbehind avoids matching `required_providers`.
+const PROVIDER_CONFIG = /(?:^|\n)\s*provider\s+"[^"]+"\s*\{/;
+const BACKEND_BLOCK = /(?:^|\n)\s*backend\s+"[^"]+"\s*\{/;
+
+/** detect whether some concatenated HCL marks a root module. */
+export function isRootModuleHcl(hcl: string): { hasBackend: boolean; hasProviderConfig: boolean } {
+  return {
+    hasBackend: BACKEND_BLOCK.test(hcl),
+    hasProviderConfig: PROVIDER_CONFIG.test(hcl),
+  };
+}
+
+/** the directory of a repo-relative file path ("" for a top-level file). */
+function dirOf(file: string): string {
+  const i = file.lastIndexOf("/");
+  return i === -1 ? "" : file.slice(0, i);
+}
+
+/**
+ * Discover the Terraform root modules under `cwd`. Walks `*.tf` recursively
+ * (skipping cache/VCS dirs via walkTfFiles), groups by directory, and keeps the
+ * dirs that configure a provider or a backend. Sorted by dir. An empty result
+ * means no obvious root was found — the caller falls back to scanning `cwd`
+ * itself as a single root.
+ */
+export function discoverTerraformRoots(cwd: string): TerraformRoot[] {
+  const byDir = new Map<string, { files: string[]; hcl: string }>();
+  for (const f of walkTfFiles(cwd)) {
+    const dir = dirOf(f);
+    const entry = byDir.get(dir) ?? { files: [], hcl: "" };
+    entry.files.push(f);
+    try {
+      entry.hcl += `${readFileSync(join(cwd, f), "utf8")}\n`;
+    } catch {
+      /* skip unreadable */
+    }
+    byDir.set(dir, entry);
+  }
+  const roots: TerraformRoot[] = [];
+  for (const [dir, entry] of byDir) {
+    const { hasBackend, hasProviderConfig } = isRootModuleHcl(entry.hcl);
+    if (hasBackend || hasProviderConfig) {
+      roots.push({ dir, hasBackend, hasProviderConfig, tfFileCount: entry.files.length });
+    }
+  }
+  return roots.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+
+// --- environment / region fan-out --------------------------------------
+
+// tokens that mark an environment twin when they appear as a whole path segment
+// or a `<token>.tfvars` filename. Lowercased; matched exactly against a segment.
+const ENV_TOKENS = new Set([
+  "dev",
+  "develop",
+  "development",
+  "stg",
+  "stage",
+  "staging",
+  "prod",
+  "prd",
+  "production",
+  "test",
+  "testing",
+  "qa",
+  "uat",
+  "sandbox",
+  "sbx",
+  "preprod",
+  "pre-prod",
+  "preproduction",
+  "demo",
+  "nonprod",
+  "non-prod",
+]);
+
+// AWS-style region segment, e.g. `eu-west-2`, `eu-west-1` — the other common
+// fan-out axis (the same stack replicated per region).
+const REGION_RE = /^[a-z]{2}-[a-z]+-\d$/;
+
+export interface EnvironmentTwinGroup {
+  /** the shared path shape with the env/region segment replaced by `{env}`. */
+  pattern: string;
+  /** the matched twins: each a dir + the environment/region token it carries. */
+  members: { dir: string; environment: string }[];
+}
+
+/**
+ * Detect environment/region TWINS among a set of repo-relative paths (root dirs
+ * and/or `*.tfvars` files): parallel stacks that differ only by an environment
+ * (`dev`/`staging`/`prod`/…) or region (`eu-west-2`) segment. A fix applied to
+ * one should usually be offered for its twins too (backport / fan-out).
+ *
+ * For each path, finds the LAST segment that is an env token or a region (a
+ * `<env>.tfvars` file counts via its basename), replaces it with `{env}` to form
+ * a pattern, and groups by that pattern. Only groups with ≥2 DISTINCT
+ * environments are returned (a single match isn't a twin set). Pure +
+ * deterministic (sorted).
+ */
+export function detectEnvironmentTwins(paths: string[]): EnvironmentTwinGroup[] {
+  const byPattern = new Map<string, Map<string, string>>(); // pattern → env → dir
+  for (const raw of paths) {
+    const path = raw.replace(/\\/g, "/").replace(/^\.\//, "");
+    const segments = path.split("/").filter(Boolean);
+    // a `<env>.tfvars` filename: treat the basename (sans .tfvars) as a segment.
+    const last = segments[segments.length - 1] ?? "";
+    if (last.endsWith(".tfvars")) {
+      segments[segments.length - 1] = last.slice(0, -".tfvars".length);
+    }
+    // find the LAST env/region segment (so `infra/prod/network` keys on `prod`).
+    let idx = -1;
+    let token = "";
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const seg = segments[i]!.toLowerCase();
+      if (ENV_TOKENS.has(seg) || REGION_RE.test(seg)) {
+        idx = i;
+        token = seg;
+        break;
+      }
+    }
+    if (idx === -1) continue;
+    const patternSegs = [...segments];
+    patternSegs[idx] = "{env}";
+    const pattern = patternSegs.join("/") + (last.endsWith(".tfvars") ? ".tfvars" : "");
+    const map = byPattern.get(pattern) ?? new Map<string, string>();
+    if (!map.has(token)) map.set(token, path);
+    byPattern.set(pattern, map);
+  }
+  const groups: EnvironmentTwinGroup[] = [];
+  for (const [pattern, envMap] of byPattern) {
+    if (envMap.size < 2) continue;
+    const members = [...envMap.entries()]
+      .map(([environment, dir]) => ({ dir, environment }))
+      .sort((a, b) => a.environment.localeCompare(b.environment));
+    groups.push({ pattern, members });
+  }
+  return groups.sort((a, b) => a.pattern.localeCompare(b.pattern));
+}
+
+export const TerraformRootsParams = type({});
+
+export function TerraformRootsTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_roots",
+    description:
+      "Discover the Terraform ROOT modules in the repo — the dirs you'd run `terraform init/plan/apply` in " +
+      "(they configure a `provider` or a `backend`), as opposed to child modules under `modules/`. A repo " +
+      "can have several (e.g. `terraform/` and `terraform/core/`). `terraform_scan` already scans the whole " +
+      "tree, but `terraform_plan`/`terraform_validate` act on one dir — run them once PER ROOT (set the " +
+      "`cwd` accordingly) when there is more than one, so each root's real-world effect is checked. Returns " +
+      "an empty list when no root is detected (then treat the scan `cwd` as the single root).",
+    parameters: TerraformRootsParams,
+    execute: execute(async () => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const roots = discoverTerraformRoots(cwd);
+      // parallel per-environment/region stacks among the roots; a fix to
+      // one twin should usually be offered for the others.
+      const twins = detectEnvironmentTwins(roots.map((r) => r.dir).filter(Boolean));
+      log.info(
+        `» terraform_roots: ${roots.length} root(s) [${roots.map((r) => r.dir || ".").join(", ")}]` +
+          (twins.length ? `, ${twins.length} env-twin group(s)` : ""),
+      );
+      return {
+        ok: true,
+        root_count: roots.length,
+        roots: roots.map((r) => ({
+          dir: r.dir || ".",
+          has_backend: r.hasBackend,
+          has_provider_config: r.hasProviderConfig,
+          tf_file_count: r.tfFileCount,
+        })),
+        // environment/region twin groups (≥2 stacks differing only by an
+        // env/region segment). Empty when there are none.
+        environment_twins: twins,
+        note:
+          roots.length > 1
+            ? "Multiple roots — terraform_plan/terraform_validate run per root automatically. " +
+              (twins.length
+                ? "Detected environment twins: a fix to one stack should usually be offered for its twins."
+                : "")
+            : "Single root (or none detected) — the scan cwd is the root.",
+      };
+    }),
+  });
+}

package/src/mcp/scope.ts

@@ -0,0 +1,82 @@
+import { PRODUCT_SLUG } from "#app/brand";
+import type { ToolState } from "#app/toolState";
+import type { ResolvedPayload } from "#app/utils/payload";
+
+/**
+ * The slice of the run these scope guards read: the triggering event (for the
+ * scoped issue/PR) and the created-target set. Both `GitHubToolContext` and the
+ * combined GitHub write context satisfy it — the guards need no octokit of their
+ * own.
+ */
+export interface ScopeContext {
+  payload: ResolvedPayload;
+  toolState: ToolState;
+}
+
+/**
+ * Bind the GitHub REST write tools to the issue/PR the run is scoped to.
+ *
+ * Infraweaver's threat model treats the agent as semi-trusted: attacker-controlled
+ * PR/issue content can prompt-inject it. The git tools already refuse to act on a
+ * PR the run was not triggered against (the cross-PR clobber guard in
+ * `mcp/git.ts`). These helpers extend the same scoping to the REST write tools
+ * (comment, review, labels, PR-body update, review reply, thread resolve) so an
+ * injected agent cannot comment on / approve / label an UNRELATED issue or PR in
+ * the same repo. The installation token already prevents cross-REPO writes; this
+ * closes the remaining cross-issue/PR-within-the-repo gap.
+ *
+ * In scope = the triggering issue/PR (`event.issue_number`) OR a PR/issue THIS
+ * run created (`create_pull_request` / `create_issue`, recorded via
+ * `recordCreatedTarget`). A merely checked-out PR is NOT in scope: `checkout_pr`
+ * is agent-controlled, so letting it widen write scope would defeat the guard.
+ *
+ * Standalone runs (workflow_dispatch / CLI: `event.trigger === "unknown"`) carry
+ * no triggering issue/PR and therefore no injection surface — there is nothing to
+ * bind to, so the guard is a no-op and the operator-supplied target is honored.
+ */
+
+/** the PR/issue this run was triggered against, or undefined for standalone runs. */
+function scopedTarget(ctx: ScopeContext): number | undefined {
+  // optional chain: production always sets `payload.event` (resolvePayload
+  // defaults event to {trigger:"unknown"}), but degrade to "no scope" if it's
+  // somehow absent rather than throwing from a guard.
+  return ctx.payload?.event?.issue_number;
+}
+
+/**
+ * Record a PR/issue this run created so later body edits / comments / reviews on
+ * it pass {@link assertTargetInScope}. Call after a successful
+ * `create_pull_request` / `create_issue`.
+ */
+export function recordCreatedTarget(ctx: ScopeContext, target: number): void {
+  ctx.toolState.createdTargets ??= new Set();
+  ctx.toolState.createdTargets.add(target);
+}
+
+/** true when `target` is the run's triggering issue/PR or one it created. */
+export function isTargetInScope(ctx: ScopeContext, target: number): boolean {
+  const scoped = scopedTarget(ctx);
+  // standalone run — no triggering issue/PR to bind to (no injection surface).
+  if (scoped === undefined) return true;
+  if (target === scoped) return true;
+  return ctx.toolState.createdTargets?.has(target) ?? false;
+}
+
+/**
+ * Throw if `target` is neither the run's triggering issue/PR nor one it created.
+ * `action` is a short verb phrase used in the error (e.g. "comment on",
+ * "submit a review on", "add labels to").
+ */
+export function assertTargetInScope(
+  ctx: ScopeContext,
+  target: number,
+  action: string,
+): void {
+  if (isTargetInScope(ctx, target)) return;
+  const scoped = scopedTarget(ctx);
+  throw new Error(
+    `blocked: this run is scoped to #${scoped}; refusing to ${action} #${target}. ` +
+      `${PRODUCT_SLUG} only writes to the issue/PR that triggered the run (or one it opened during the run). ` +
+      `if acting on #${target} is intended, trigger a run against #${target}.`,
+  );
+}

package/src/mcp/selectMode.ts

@@ -0,0 +1,207 @@
+import { type } from "arktype";
+import { refreshWritePolicy } from "#app/agents/writePolicy";
+import { formatMcpToolRef } from "#app/external";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import type { Mode } from "#app/modes";
+import { cloudRequest } from "#app/utils/cloudClient";
+
+export const SelectModeParams = type({
+  mode: type.string.describe(
+    "the name of the mode to select (e.g., 'Build', 'Plan', 'Review', 'IncrementalReview', 'Fix', 'AddressReviews', 'Task', 'ResolveConflicts')",
+  ),
+  "issue_number?": type("number").describe(
+    "optional issue number; when provided with Plan mode, used to look up an existing plan comment for this issue (edit vs create)",
+  ),
+});
+
+function resolveMode(modes: Mode[], modeName: string): Mode | null {
+  return (
+    modes.find((m) => m.name.toLowerCase() === modeName.toLowerCase()) ?? null
+  );
+}
+
+function buildModeOverrides(
+  t: (name: string) => string,
+): Record<string, string> {
+  return {
+    PlanEdit: `### Checklist (editing existing plan)
+
+An existing plan comment was found for this issue. Update that comment with the revised plan — do not create a new plan comment.
+
+1. **task list**: create your task list for this run as your first action.
+2. Use \`previousPlanBody\` from this response as the plan to revise; do not call \`get_issue\` or \`get_issue_comments\`.
+3. Revise the plan based on the user's request:
+   - incorporate the current plan (\`previousPlanBody\`) and the user's revision request
+   - gather relevant codebase context (file paths, architecture notes from AGENTS.md)
+   - produce a structured plan with clear milestones
+4. Call \`${t("report_progress")}\` with the full revised plan text and \`{ target_plan_comment: true }\` so it updates the existing plan comment (not the progress comment).
+5. Then post a short note to the progress comment (e.g. "Plan has been updated in the comment above.") via \`${t("report_progress")}\` so it is not left as "Leaping...".`,
+  };
+}
+
+type OrchestratorGuidance = {
+  modeName: string;
+  description: string;
+  orchestratorGuidance: string;
+};
+
+// IncrementalReview and TerraformCodeReview inherit Review's user instructions
+// (the org review_instructions + fp_filtering_instructions land on the "Review"
+// key), Fix inherits Build's. Without TerraformCodeReview here its FP addendum
+// never reaches the mode, so its FINDING_VERIFICATION_PASS asks the orchestrator
+// to include a `### Finding precedents — org addendum` section that doesn't exist.
+const modeInstructionParent: Record<string, string> = {
+  IncrementalReview: "Review",
+  TerraformCodeReview: "Review",
+  Fix: "Build",
+};
+
+function buildOrchestratorGuidance(
+  ctx: ToolContext,
+  mode: Mode,
+  overrideGuidance?: string,
+): OrchestratorGuidance {
+  const hardcoded = overrideGuidance ?? mode.prompt ?? "";
+  const lookupKey = modeInstructionParent[mode.name] ?? mode.name;
+  const userInstructions = ctx.modeInstructions[lookupKey] ?? "";
+  const guidance = [hardcoded, userInstructions].filter(Boolean).join("\n\n");
+  return {
+    modeName: mode.name,
+    description: mode.description,
+    orchestratorGuidance: guidance,
+  };
+}
+
+// matches the API response for /repo/[owner]/[repo]/issue/[issueNumber]/plan-comment
+export type PlanCommentResponsePayload =
+  | { error: string }
+  | { commentId: number; body: string };
+
+// IMPORTANT: this route authenticates via GitHub installation token (getEnrichedRepo),
+// NOT the Infraweaver API JWT (ctx.apiToken). use ctx.githubInstallationToken here.
+// see wiki/api-auth.md for the two auth patterns.
+async function fetchExistingPlanComment(
+  ctx: ToolContext,
+  issueNumber: number,
+): Promise<Extract<PlanCommentResponsePayload, { commentId: number }> | null> {
+  if (!ctx.githubInstallationToken) return null;
+  try {
+    const response = await cloudRequest({
+      path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/issue/${issueNumber}/plan-comment`,
+      method: "GET",
+      credential: ctx.githubInstallationToken,
+      timeoutMs: 10_000,
+    });
+    const data = (await response.json()) as PlanCommentResponsePayload;
+    return response.ok && "commentId" in data ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+const SUMMARY_MODES = new Set(["Review", "IncrementalReview", "Task"]);
+
+/** modes that gain the PR summary edit step when toolState.summaryFilePath is set.
+ *
+ * NOTE: this snapshot is an internal artifact consumed by future agent runs. it is
+ * deliberately NOT shaped by user-supplied summary instructions — those would warp
+ * the durable agent context. user-facing summarization (e.g. the review body's
+ * "Reviewed changes" section) is governed by review-mode prompts and review
+ * instructions, separately from this snapshot. */
+function buildSummaryAddendum(
+  t: (name: string) => string,
+  ctx: ToolContext,
+): string {
+  const filePath = ctx.toolState.summaryFilePath;
+  if (!filePath) return "";
+  return `### PR summary snapshot — required step
+
+A rolling PR summary lives at \`${filePath}\`. It is your durable cross-run agent context — a functional summary of what this PR does, the subsystems and files it touches, the material behavior of its changes, and any risks or open questions worth carrying forward. It is NOT a chronological log of past review runs; commit-level history can already be reconstructed from \`${t("list_pull_request_reviews")}\`.
+
+How to use it:
+
+- read \`${filePath}\` at the START of the run, alongside the diff. it represents what previous agent runs already understood about this PR — absorb it before picking lenses or crafting subagent dispatch prompts. if it's a fresh seed (file is one or two lines), this is a first review and you'll be filling it in from the diff.
+- let the snapshot inform triage and dispatch. when it already tracks a risk, your lens prompts to subagents are stronger when they reference that context (e.g. "the JSDoc explicitly scopes to code points — do not flag grapheme-cluster issues" if the snapshot already documents that contract). when something the snapshot tracks is now resolved by new commits, note that. when new commits introduce something the snapshot doesn't yet describe, that's exactly where your fan-out should focus.
+- update the file in place to reflect the PR's CURRENT state. revise stale claims, drop resolved risks, add new behavior or risks. accuracy over breadth — every claim must be grounded in the diff. write for the next agent run, not for a human.
+- structure however serves THIS PR. there is no required section template. a refactor might organize by renamed export and call-site impact; a feature by capability; a billing change by money path. a compact note of which commit ranges have been reviewed should always be present so future runs scope correctly, but the rest is your call. when the structure works across runs, keep it stable so range-diffs are clean; when the PR's character changes (e.g. scope expands), reshape.
+
+Do NOT call \`${t("create_issue_comment")}\` for the summary — the server reads this file at end-of-run and persists it. The file edit is mandatory regardless of whether a review is submitted; the snapshot feeds the next run.`;
+}
+
+export function SelectModeTool(ctx: ToolContext) {
+  const t = (name: string) => formatMcpToolRef(ctx.agentId, name);
+  const overrides = buildModeOverrides(t);
+
+  return tool({
+    mutates: true,
+    name: "select_mode",
+    description:
+      "Select a mode and receive step-by-step guidance on how to handle the task. Call this to understand the best workflow for the current mode. " +
+      'Example: `select_mode({ mode: "Review" })` or `select_mode({ mode: "Plan", issue_number: 1234 })`.',
+    parameters: SelectModeParams,
+    execute: execute(async (params) => {
+      if (ctx.toolState.selectedMode) {
+        return {
+          error: `mode already selected: "${ctx.toolState.selectedMode}". mode selection is final and cannot be changed. complete your current workflow within this mode.`,
+        };
+      }
+
+      const modeName = params.mode;
+
+      const selectedMode = resolveMode(ctx.modes, modeName);
+
+      if (!selectedMode) {
+        const availableModes = ctx.modes.map((m) => m.name).join(", ");
+        return {
+          error: `mode "${modeName}" not found. available modes: ${availableModes}`,
+          availableModes: ctx.modes.map((m) => ({
+            name: m.name,
+            description: m.description,
+          })),
+        };
+      }
+
+      ctx.toolState.selectedMode = selectedMode.name;
+      // publish the write-time path policy for the agent gates. mode selection
+      // is final (see the guard above), so this runs exactly once per run — and
+      // it must run HERE rather than at agent launch, because an auto-selected
+      // mode isn't known until this point.
+      refreshWritePolicy(ctx);
+
+      if (selectedMode.name === "Plan") {
+        const issueNumber =
+          params.issue_number ?? ctx.payload.event.issue_number;
+        if (issueNumber !== undefined) {
+          const existing = await fetchExistingPlanComment(ctx, issueNumber);
+          if (existing !== null) {
+            ctx.toolState.existingPlanCommentId = existing.commentId;
+            ctx.toolState.previousPlanBody = existing.body;
+            return {
+              ...buildOrchestratorGuidance(
+                ctx,
+                selectedMode,
+                overrides.PlanEdit,
+              ),
+              previousPlanBody: existing.body,
+            };
+          }
+        }
+      }
+
+      const summaryAddendum = SUMMARY_MODES.has(selectedMode.name)
+        ? buildSummaryAddendum(t, ctx)
+        : "";
+
+      const base = buildOrchestratorGuidance(ctx, selectedMode);
+      if (summaryAddendum.length > 0) {
+        return {
+          ...base,
+          orchestratorGuidance: `${base.orchestratorGuidance}\n\n${summaryAddendum}`,
+          summaryFilePath: ctx.toolState.summaryFilePath,
+        };
+      }
+      return base;
+    }),
+  });
+}