@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/tools/graft-diff.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { graftDiff } from "../../operations/graft-diff.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { evaluateMcpRefusal } from "../policy.js";
 
 export const graftDiffTool: ToolDefinition = {
   name: "graft_diff",
@@ -9,16 +10,26 @@ export const graftDiffTool: ToolDefinition = {
     "changed symbols per file \u2014 not line hunks. Defaults to working " +
     "tree vs HEAD.",
   schema: { base: z.string().optional(), head: z.string().optional(), path: z.string().optional() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
-      const result = graftDiff({
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const head = args["head"] as string | undefined;
+      const result = await graftDiff({
         cwd: ctx.projectRoot,
         fs: ctx.fs,
+        git: ctx.git,
+        resolveWorkingTreePath: (filePath) => ctx.resolvePath(filePath),
         base: args["base"] as string | undefined,
-        head: args["head"] as string | undefined,
+        head,
         path: args["path"] as string | undefined,
+        refusalCheck: (filePath, actual) => evaluateMcpRefusal(ctx, filePath, actual),
+      });
+      ctx.recordFootprint({
+        paths: (result.files as readonly { path: string }[]).map((f) => f.path),
+      });
+      return ctx.respond("graft_diff", {
+        ...result,
+        layer: head === undefined ? "workspace_overlay" : "ref_view",
       });
-      return ctx.respond("graft_diff", result);
     };
   },
 };

package/src/mcp/tools/map-collector.ts

@@ -0,0 +1,338 @@
+// ---------------------------------------------------------------------------
+// Structural map collector — models and collection logic for graft_map
+// ---------------------------------------------------------------------------
+
+import * as path from "node:path";
+import { extractOutline } from "../../parser/outline.js";
+import { detectLang } from "../../parser/lang.js";
+import type { FileSystem } from "../../ports/filesystem.js";
+import type { GitClient } from "../../ports/git.js";
+import { GitFileQuery, listGitFiles } from "./git-files.js";
+import type { McpPolicyRefusal } from "../policy.js";
+import { collectSymbols, normalizeRepoPath } from "./precision.js";
+
+// ---------------------------------------------------------------------------
+// Request model
+// ---------------------------------------------------------------------------
+
+export class StructuralMapRequest {
+  readonly directory: string;
+  readonly depth: number | null;
+  readonly summary: boolean;
+
+  constructor(args: Record<string, unknown>, projectRoot: string) {
+    const rawPath = args["path"];
+    const rawDepth = args["depth"];
+    const rawSummary = args["summary"];
+    if (rawPath !== undefined && typeof rawPath !== "string") {
+      throw new Error("StructuralMapRequest: path must be a string when provided");
+    }
+    let depth: number | null = null;
+    if (rawDepth !== undefined) {
+      if (typeof rawDepth !== "number" || !Number.isInteger(rawDepth) || rawDepth < 0) {
+        throw new Error("StructuralMapRequest: depth must be a non-negative integer when provided");
+      }
+      depth = rawDepth;
+    }
+    if (rawSummary !== undefined && typeof rawSummary !== "boolean") {
+      throw new Error("StructuralMapRequest: summary must be a boolean when provided");
+    }
+    this.directory = rawPath !== undefined && rawPath.trim().length > 0
+      ? normalizeRepoPath(projectRoot, rawPath)
+      : ".";
+    this.depth = depth;
+    this.summary = rawSummary === true;
+    Object.freeze(this);
+  }
+
+  toGitFileQuery(projectRoot: string): GitFileQuery {
+    return GitFileQuery.project(projectRoot, this.directory === "." ? "" : this.directory);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Result models
+// ---------------------------------------------------------------------------
+
+export class StructuralMapSymbol {
+  readonly name: string;
+  readonly kind: string;
+  readonly signature?: string;
+  readonly exported: boolean;
+  readonly startLine?: number;
+  readonly endLine?: number;
+
+  constructor(opts: {
+    name: string;
+    kind: string;
+    signature?: string;
+    exported: boolean;
+    startLine?: number;
+    endLine?: number;
+  }) {
+    this.name = opts.name;
+    this.kind = opts.kind;
+    this.exported = opts.exported;
+    if (opts.signature !== undefined) this.signature = opts.signature;
+    if (opts.startLine !== undefined) this.startLine = opts.startLine;
+    if (opts.endLine !== undefined) this.endLine = opts.endLine;
+    Object.freeze(this);
+  }
+}
+
+export class StructuralMapFile {
+  readonly path: string;
+  readonly lang: string;
+  readonly symbolCount: number;
+  readonly summaryOnly: boolean;
+  readonly symbols?: readonly StructuralMapSymbol[];
+
+  constructor(opts: {
+    path: string;
+    lang: string;
+    symbolCount: number;
+    summaryOnly: boolean;
+    symbols?: readonly StructuralMapSymbol[];
+  }) {
+    this.path = opts.path;
+    this.lang = opts.lang;
+    this.symbolCount = opts.symbolCount;
+    this.summaryOnly = opts.summaryOnly;
+    if (opts.symbols !== undefined) {
+      this.symbols = Object.freeze([...opts.symbols]);
+    }
+    Object.freeze(this);
+  }
+}
+
+export class StructuralMapDirectory {
+  readonly path: string;
+  readonly fileCount: number;
+  readonly symbolCount: number;
+  readonly childDirectoryCount: number;
+  readonly summaryOnly: true;
+
+  constructor(opts: {
+    path: string;
+    fileCount: number;
+    symbolCount: number;
+    childDirectoryCount: number;
+  }) {
+    this.path = opts.path;
+    this.fileCount = opts.fileCount;
+    this.symbolCount = opts.symbolCount;
+    this.childDirectoryCount = opts.childDirectoryCount;
+    this.summaryOnly = true;
+    Object.freeze(this);
+  }
+}
+
+export class StructuralMapMode {
+  readonly depth: number | null;
+  readonly summary: boolean;
+
+  constructor(opts: {
+    depth: number | null;
+    summary: boolean;
+  }) {
+    this.depth = opts.depth;
+    this.summary = opts.summary;
+    Object.freeze(this);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Directory accumulation
+// ---------------------------------------------------------------------------
+
+class StructuralMapDirectoryAccumulator {
+  fileCount = 0;
+  symbolCount = 0;
+  readonly childDirectories = new Set<string>();
+
+  add(symbolCount: number, childDirectory: string | null): void {
+    this.fileCount += 1;
+    this.symbolCount += symbolCount;
+    if (childDirectory !== null) {
+      this.childDirectories.add(childDirectory);
+    }
+  }
+
+  toDirectory(pathname: string): StructuralMapDirectory {
+    return new StructuralMapDirectory({
+      path: pathname,
+      fileCount: this.fileCount,
+      symbolCount: this.symbolCount,
+      childDirectoryCount: this.childDirectories.size,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function relativeDirectorySegments(scopeDir: string, filePath: string): string[] {
+  const relativeFilePath = scopeDir === "." ? filePath : path.posix.relative(scopeDir, filePath);
+  const relativeDirPath = path.posix.dirname(relativeFilePath);
+  return relativeDirPath === "." ? [] : relativeDirPath.split("/").filter((segment) => segment.length > 0);
+}
+
+function summarizedDirectoryPath(scopeDir: string, filePath: string, depth: number | null): string | null {
+  if (depth === null) return null;
+  const segments = relativeDirectorySegments(scopeDir, filePath);
+  if (segments.length <= depth) return null;
+  const summarySegments = segments.slice(0, depth + 1);
+  return scopeDir === "." ? summarySegments.join("/") : path.posix.join(scopeDir, ...summarySegments);
+}
+
+function summarizedChildDirectory(scopeDir: string, filePath: string, depth: number): string | null {
+  const segments = relativeDirectorySegments(scopeDir, filePath);
+  if (segments.length <= depth + 1) return null;
+  return segments[depth + 1] ?? null;
+}
+
+function getOrCreateDirectoryAccumulator(
+  accumulators: Map<string, StructuralMapDirectoryAccumulator>,
+  pathname: string,
+): StructuralMapDirectoryAccumulator {
+  const existing = accumulators.get(pathname);
+  if (existing !== undefined) return existing;
+  const created = new StructuralMapDirectoryAccumulator();
+  accumulators.set(pathname, created);
+  return created;
+}
+
+function buildStructuralMapFile(opts: {
+  path: string;
+  lang: string;
+  symbols: readonly StructuralMapSymbol[];
+  summaryOnly: boolean;
+}): StructuralMapFile {
+  return new StructuralMapFile({
+    path: opts.path,
+    lang: opts.lang,
+    symbolCount: opts.symbols.length,
+    summaryOnly: opts.summaryOnly,
+    ...(opts.summaryOnly ? {} : { symbols: opts.symbols }),
+  });
+}
+
+function sortByPath<T extends { path: string }>(entries: readonly T[]): T[] {
+  return [...entries].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function buildSummary(opts: {
+  returnedFileCount: number;
+  totalSymbolCount: number;
+  summarizedDirectoryCount: number;
+  depth: number | null;
+  summary: boolean;
+}): string {
+  if (opts.depth === null && !opts.summary && opts.summarizedDirectoryCount === 0) {
+    return `${String(opts.returnedFileCount)} files, ${String(opts.totalSymbolCount)} symbols`;
+  }
+
+  const parts = [
+    `${String(opts.returnedFileCount)} files returned`,
+    `${String(opts.totalSymbolCount)} total symbols`,
+  ];
+  if (opts.summarizedDirectoryCount > 0) {
+    parts.push(`${String(opts.summarizedDirectoryCount)} summarized directories`);
+  }
+  if (opts.depth !== null) {
+    parts.push(`depth=${String(opts.depth)}`);
+  }
+  if (opts.summary) {
+    parts.push("summary mode");
+  }
+  return parts.join(", ");
+}
+
+// ---------------------------------------------------------------------------
+// Collection orchestration
+// ---------------------------------------------------------------------------
+
+export interface StructuralMapCollectionResult {
+  readonly files: StructuralMapFile[];
+  readonly directories: StructuralMapDirectory[];
+  readonly refused: McpPolicyRefusal[];
+  readonly totalSymbols: number;
+}
+
+export async function collectStructuralMap(
+  request: StructuralMapRequest,
+  opts: {
+    readonly projectRoot: string;
+    readonly fs: FileSystem;
+    readonly git: GitClient;
+    readonly refusalCheck: (filePath: string, actual: { lines: number; bytes: number }) => McpPolicyRefusal | null;
+  },
+): Promise<StructuralMapCollectionResult> {
+  const filePaths = (await listGitFiles(request.toGitFileQuery(opts.projectRoot), opts.git)).paths;
+  const files: StructuralMapFile[] = [];
+  const directories = new Map<string, StructuralMapDirectoryAccumulator>();
+  const refused: McpPolicyRefusal[] = [];
+  let totalSymbols = 0;
+
+  for (const filePath of filePaths) {
+    let content: string;
+    try {
+      content = await opts.fs.readFile(path.join(opts.projectRoot, filePath), "utf-8");
+    } catch {
+      continue;
+    }
+
+    const actual = {
+      lines: content.split("\n").length,
+      bytes: Buffer.byteLength(content),
+    };
+    const refusal = opts.refusalCheck(filePath, actual);
+    if (refusal !== null) {
+      refused.push(refusal);
+      continue;
+    }
+
+    const lang = detectLang(filePath);
+    if (lang === null) continue;
+
+    const result = extractOutline(content, lang);
+    const symbols = collectSymbols(result.entries, filePath, result.jumpTable ?? []).map((symbol) =>
+      new StructuralMapSymbol({
+        name: symbol.name,
+        kind: symbol.kind,
+        exported: symbol.exported,
+        ...(symbol.signature !== undefined ? { signature: symbol.signature } : {}),
+        ...(symbol.startLine !== undefined ? { startLine: symbol.startLine } : {}),
+        ...(symbol.endLine !== undefined ? { endLine: symbol.endLine } : {}),
+      })
+    );
+    totalSymbols += symbols.length;
+
+    const clippedDirectoryPath = summarizedDirectoryPath(request.directory, filePath, request.depth);
+    if (clippedDirectoryPath !== null && request.depth !== null) {
+      const accumulator = getOrCreateDirectoryAccumulator(directories, clippedDirectoryPath);
+      accumulator.add(
+        symbols.length,
+        summarizedChildDirectory(request.directory, filePath, request.depth),
+      );
+      continue;
+    }
+
+    files.push(buildStructuralMapFile({
+      path: filePath,
+      lang,
+      symbols,
+      summaryOnly: request.summary,
+    }));
+  }
+
+  return {
+    files: sortByPath(files),
+    directories: sortByPath(
+      [...directories.entries()].map(([pathname, accumulator]) => accumulator.toDirectory(pathname)),
+    ),
+    refused,
+    totalSymbols,
+  };
+}

package/src/mcp/tools/map.ts

@@ -2,27 +2,76 @@ import * as path from "node:path";
 import { z } from "zod";
 import { extractOutline } from "../../parser/outline.js";
 import { detectLang } from "../../parser/lang.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
-import { execFileSync } from "node:child_process";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { GitFileQuery, listGitFiles } from "./git-files.js";
+import { evaluateMcpRefusal, type McpPolicyRefusal } from "../policy.js";
+import { collectSymbols, normalizeRepoPath } from "./precision.js";
 
-interface FileEntry {
+/** Maximum files before auto-truncation to summary-only mode. */
+export const MAX_MAP_FILES = 100;
+
+/** Maximum response bytes before auto-truncation to summary-only mode. */
+export const MAX_MAP_BYTES = 50_000;
+
+class StructuralMapRequest {
+  readonly directory: string;
+
+  constructor(args: Record<string, unknown>, projectRoot: string) {
+    const rawPath = args["path"];
+    if (rawPath !== undefined && typeof rawPath !== "string") {
+      throw new Error("StructuralMapRequest: path must be a string when provided");
+    }
+    this.directory = rawPath !== undefined && rawPath.trim().length > 0
+      ? normalizeRepoPath(projectRoot, rawPath)
+      : ".";
+    Object.freeze(this);
+  }
+
+  toGitFileQuery(projectRoot: string): GitFileQuery {
+    return GitFileQuery.project(projectRoot, this.directory === "." ? "" : this.directory);
+  }
+}
+
+class StructuralMapSymbol {
+  readonly name: string;
+  readonly kind: string;
+  readonly signature?: string;
+  readonly exported: boolean;
+  readonly startLine?: number;
+  readonly endLine?: number;
+
+  constructor(opts: {
+    name: string;
+    kind: string;
+    signature?: string;
+    exported: boolean;
+    startLine?: number;
+    endLine?: number;
+  }) {
+    this.name = opts.name;
+    this.kind = opts.kind;
+    this.exported = opts.exported;
+    if (opts.signature !== undefined) this.signature = opts.signature;
+    if (opts.startLine !== undefined) this.startLine = opts.startLine;
+    if (opts.endLine !== undefined) this.endLine = opts.endLine;
+    Object.freeze(this);
+  }
+}
+
+class StructuralMapFile {
   path: string;
   lang: string;
-  symbols: { name: string; kind: string; signature?: string | undefined; exported: boolean; startLine?: number | undefined; endLine?: number | undefined }[];
-}
+  symbols: readonly StructuralMapSymbol[];
 
-/**
- * List files in a directory (git ls-files for tracked files).
- */
-function listFiles(dirPath: string, cwd: string): string[] {
-  try {
-    const args = dirPath.length > 0
-      ? ["ls-files", "--", dirPath]
-      : ["ls-files"];
-    return execFileSync("git", args, { cwd, encoding: "utf-8" })
-      .trim().split("\n").filter((l) => l.length > 0);
-  } catch {
-    return [];
+  constructor(opts: {
+    path: string;
+    lang: string;
+    symbols: readonly StructuralMapSymbol[];
+  }) {
+    this.path = opts.path;
+    this.lang = opts.lang;
+    this.symbols = Object.freeze([...opts.symbols]);
+    Object.freeze(this);
   }
 }
 
@@ -35,46 +84,100 @@ export const mapTool: ToolDefinition = {
   schema: {
     path: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
-      const dirPath = (args["path"] as string | undefined) ?? "";
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const request = new StructuralMapRequest(args, ctx.projectRoot);
 
-      const filePaths = listFiles(dirPath, ctx.projectRoot);
-      const files: FileEntry[] = [];
+      // Budget gate: if the session budget is exhausted, return summary-only.
+      const budget = ctx.governor.getBudget();
+      if (budget !== null && budget.remaining <= 0) {
+        const filePaths = (await listGitFiles(request.toGitFileQuery(ctx.projectRoot), ctx.git)).paths;
+        return ctx.respond("graft_map", {
+          directory: request.directory,
+          files: [],
+          summary: `${String(filePaths.length)} files (budget exhausted — summary only)`,
+          truncated: true,
+          truncatedReason: "BUDGET_EXHAUSTED",
+        });
+      }
 
-      for (const filePath of filePaths) {
-        const lang = detectLang(filePath);
-        if (lang === null) continue;
+      const filePaths = (await listGitFiles(request.toGitFileQuery(ctx.projectRoot), ctx.git)).paths;
+      const files: StructuralMapFile[] = [];
+      const refused: McpPolicyRefusal[] = [];
 
+      for (const filePath of filePaths) {
         let content: string;
         try {
-          content = ctx.fs.readFileSync(path.join(ctx.projectRoot, filePath), "utf-8");
+          content = await ctx.fs.readFile(path.join(ctx.projectRoot, filePath), "utf-8");
         } catch {
           continue;
         }
 
+        const actual = {
+          lines: content.split("\n").length,
+          bytes: Buffer.byteLength(content),
+        };
+        const refusal = evaluateMcpRefusal(ctx, filePath, actual);
+        if (refusal !== null) {
+          refused.push(refusal);
+          continue;
+        }
+
+        const lang = detectLang(filePath);
+        if (lang === null) continue;
+
         const result = extractOutline(content, lang);
-        const symbols: FileEntry["symbols"] = result.entries.map((entry) => {
-          const jump = result.jumpTable?.find((j) => j.symbol === entry.name);
-          return {
-            name: entry.name,
-            kind: entry.kind,
-            signature: entry.signature,
-            exported: entry.exported,
-            startLine: jump?.start,
-            endLine: jump?.end,
-          };
-        });
+        const symbols = collectSymbols(result.entries, filePath, result.jumpTable ?? []).map((symbol) =>
+          new StructuralMapSymbol({
+            name: symbol.name,
+            kind: symbol.kind,
+            exported: symbol.exported,
+            ...(symbol.signature !== undefined ? { signature: symbol.signature } : {}),
+            ...(symbol.startLine !== undefined ? { startLine: symbol.startLine } : {}),
+            ...(symbol.endLine !== undefined ? { endLine: symbol.endLine } : {}),
+          })
+        );
 
-        files.push({ path: filePath, lang, symbols });
+        files.push(new StructuralMapFile({ path: filePath, lang, symbols }));
       }
 
       files.sort((a, b) => a.path.localeCompare(b.path));
+      const totalFiles = files.length;
       const totalSymbols = files.reduce((n, f) => n + f.symbols.length, 0);
 
+      // Size gate: if the result exceeds limits, switch to summary-only.
+      const serialized = JSON.stringify(files);
+      const responseBytes = Buffer.byteLength(serialized);
+
+      if (totalFiles > MAX_MAP_FILES || responseBytes > MAX_MAP_BYTES) {
+        // Build per-language file counts for the summary.
+        const langCounts = new Map<string, number>();
+        for (const f of files) {
+          langCounts.set(f.lang, (langCounts.get(f.lang) ?? 0) + 1);
+        }
+        const langBreakdown = [...langCounts.entries()]
+          .sort((a, b) => b[1] - a[1])
+          .map(([lang, count]) => `${lang}: ${String(count)}`)
+          .join(", ");
+
+        return ctx.respond("graft_map", {
+          directory: request.directory,
+          files: [],
+          ...(refused.length > 0 ? { refused } : {}),
+          summary: `${String(totalFiles)} files, ${String(totalSymbols)} symbols (${langBreakdown})`,
+          truncated: true,
+          truncatedReason: "OUTPUT_LIMIT",
+          next: [
+            "Narrow the path argument to a specific subdirectory",
+            `Current: ${String(totalFiles)} files, ${String(Math.round(responseBytes / 1024))}KB — limit: ${String(MAX_MAP_FILES)} files / ${String(Math.round(MAX_MAP_BYTES / 1024))}KB`,
+          ],
+        });
+      }
+
       return ctx.respond("graft_map", {
-        directory: dirPath.length > 0 ? dirPath : ".",
+        directory: request.directory,
         files,
+        ...(refused.length > 0 ? { refused } : {}),
         summary: `${String(files.length)} files, ${String(totalSymbols)} symbols`,
       });
     };

package/src/mcp/tools/monitor-pause.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const monitorPauseTool: ToolDefinition = {
+  name: "monitor_pause",
+  description:
+    "Pause the repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("monitor_pause", { ...await ctx.pauseMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/monitor-resume.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const monitorResumeTool: ToolDefinition = {
+  name: "monitor_resume",
+  description:
+    "Resume a paused repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("monitor_resume", { ...await ctx.resumeMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/monitor-start.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const monitorStartTool: ToolDefinition = {
+  name: "monitor_start",
+  description:
+    "Start or resume the repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+    pollIntervalMs: z.number().int().positive().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("monitor_start", { ...await ctx.startMonitor({
+        cwd: args["cwd"] as string,
+        pollIntervalMs: args["pollIntervalMs"] as number | undefined,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/monitor-stop.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const monitorStopTool: ToolDefinition = {
+  name: "monitor_stop",
+  description:
+    "Stop the repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("monitor_stop", { ...await ctx.stopMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};