@flyingrobots/graft 0.3.5 → 0.5.0

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

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, 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(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      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, ToolContext, 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(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      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, ToolContext, 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(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      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, ToolContext, 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(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      return ctx.respond("monitor_stop", { ...await ctx.stopMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/precision-match.ts

@@ -0,0 +1,51 @@
+export class PrecisionSymbolMatch {
+  readonly name: string;
+  readonly kind: string;
+  readonly path: string;
+  readonly signature?: string;
+  readonly exported: boolean;
+  readonly startLine?: number;
+  readonly endLine?: number;
+
+  constructor(opts: {
+    name: string;
+    kind: string;
+    path: string;
+    signature?: string;
+    exported: boolean;
+    startLine?: number;
+    endLine?: number;
+  }) {
+    if (opts.name.trim().length === 0) {
+      throw new Error("PrecisionSymbolMatch: name must be non-empty");
+    }
+    if (opts.kind.trim().length === 0) {
+      throw new Error("PrecisionSymbolMatch: kind must be non-empty");
+    }
+    if (opts.path.trim().length === 0) {
+      throw new Error("PrecisionSymbolMatch: path must be non-empty");
+    }
+    if (opts.startLine !== undefined && (!Number.isInteger(opts.startLine) || opts.startLine < 1)) {
+      throw new Error("PrecisionSymbolMatch: startLine must be an integer >= 1");
+    }
+    if (opts.endLine !== undefined && (!Number.isInteger(opts.endLine) || opts.endLine < 1)) {
+      throw new Error("PrecisionSymbolMatch: endLine must be an integer >= 1");
+    }
+    if (
+      opts.startLine !== undefined &&
+      opts.endLine !== undefined &&
+      opts.endLine < opts.startLine
+    ) {
+      throw new Error("PrecisionSymbolMatch: endLine must be >= startLine");
+    }
+
+    this.name = opts.name.trim();
+    this.kind = opts.kind.trim();
+    this.path = opts.path.trim();
+    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);
+  }
+}

package/src/mcp/tools/precision-query.ts

@@ -0,0 +1,127 @@
+import picomatch from "picomatch";
+import { PrecisionSymbolMatch } from "./precision-match.js";
+
+type SymbolQueryMode = "glob" | "plain";
+
+export class RankedPrecisionSymbolMatch {
+  readonly match: PrecisionSymbolMatch;
+  readonly score: number;
+
+  constructor(opts: {
+    match: PrecisionSymbolMatch;
+    score: number;
+  }) {
+    if (opts.score < 0) {
+      throw new Error("RankedPrecisionSymbolMatch: score must be >= 0");
+    }
+    this.match = opts.match;
+    this.score = opts.score;
+    Object.freeze(this);
+  }
+}
+
+class PrecisionSymbolQuery {
+  readonly text: string;
+  readonly mode: SymbolQueryMode;
+  readonly #globMatcher?: (name: string) => boolean;
+
+  constructor(query: string) {
+    const normalizedQuery = query.trim();
+    if (normalizedQuery.length === 0) {
+      throw new Error("PrecisionSymbolQuery: query must be non-empty");
+    }
+    this.text = normalizedQuery;
+    if (picomatch.scan(normalizedQuery).isGlob) {
+      this.mode = "glob";
+      this.#globMatcher = picomatch(normalizedQuery, { nocase: true });
+    } else {
+      this.mode = "plain";
+    }
+    Object.freeze(this);
+  }
+
+  score(name: string): number | null {
+    if (this.mode === "glob") {
+      return this.#globMatcher?.(name) === true ? 0 : null;
+    }
+
+    const loweredName = name.toLowerCase();
+    const loweredQuery = this.text.toLowerCase();
+    if (name === this.text) return 0;
+    if (loweredName === loweredQuery) return 1;
+    if (name.startsWith(this.text)) return 2;
+    if (loweredName.startsWith(loweredQuery)) return 3;
+    return loweredName.includes(loweredQuery) ? 4 : null;
+  }
+}
+
+export class PrecisionSearchRequest {
+  readonly exactName?: string;
+  readonly query?: PrecisionSymbolQuery;
+  readonly kind?: string;
+  readonly filePath?: string;
+  readonly pathPrefix?: string;
+  readonly ceiling?: number;
+
+  constructor(opts: {
+    exactName?: string;
+    query?: string;
+    kind?: string;
+    filePath?: string;
+    pathPrefix?: string;
+    ceiling?: number;
+  }) {
+    const exactName = opts.exactName?.trim();
+    const query = opts.query?.trim();
+    const kind = opts.kind?.trim().toLowerCase();
+    const filePath = opts.filePath?.trim();
+    const pathPrefix = opts.pathPrefix?.trim();
+
+    if ((exactName?.length ?? 0) === 0 && (query?.length ?? 0) === 0) {
+      throw new Error("PrecisionSearchRequest: exactName or query is required");
+    }
+    if (
+      opts.ceiling !== undefined &&
+      (!Number.isInteger(opts.ceiling) || opts.ceiling < 1)
+    ) {
+      throw new Error("PrecisionSearchRequest: ceiling must be an integer >= 1");
+    }
+
+    if (exactName !== undefined && exactName.length > 0) this.exactName = exactName;
+    if (query !== undefined && query.length > 0) this.query = new PrecisionSymbolQuery(query);
+    if (kind !== undefined && kind.length > 0) this.kind = kind;
+    if (filePath !== undefined && filePath.length > 0) this.filePath = filePath;
+    if (pathPrefix !== undefined && pathPrefix.length > 0) this.pathPrefix = pathPrefix;
+    if (opts.ceiling !== undefined) this.ceiling = opts.ceiling;
+    Object.freeze(this);
+  }
+
+  selectLens(): "file" | "exact" | "all" {
+    if (this.filePath !== undefined) return "file";
+    if (this.exactName !== undefined) return "exact";
+    return "all";
+  }
+
+  rank(match: PrecisionSymbolMatch): RankedPrecisionSymbolMatch | null {
+    if (this.exactName !== undefined && match.name !== this.exactName) return null;
+    if (this.kind !== undefined && match.kind.toLowerCase() !== this.kind) return null;
+    if (this.filePath !== undefined && match.path !== this.filePath) return null;
+    if (this.pathPrefix !== undefined && !match.path.startsWith(this.pathPrefix)) return null;
+    if (this.query === undefined) {
+      return new RankedPrecisionSymbolMatch({ match, score: 0 });
+    }
+    const score = this.query.score(match.name);
+    return score === null ? null : new RankedPrecisionSymbolMatch({ match, score });
+  }
+
+  sort(matches: readonly RankedPrecisionSymbolMatch[]): PrecisionSymbolMatch[] {
+    return [...matches]
+      .sort((a, b) =>
+        a.score - b.score ||
+        (this.query?.mode === "plain" ? a.match.name.length - b.match.name.length : 0) ||
+        a.match.path.localeCompare(b.match.path) ||
+        a.match.name.localeCompare(b.match.name)
+      )
+      .map((entry) => entry.match);
+  }
+}

package/src/mcp/tools/precision.ts

@@ -0,0 +1,312 @@
+import * as path from "node:path";
+import type WarpApp from "@git-stunts/git-warp";
+import { getFileAtRef, GitError } from "../../git/diff.js";
+import { detectLang } from "../../parser/lang.js";
+import { extractOutline } from "../../parser/outline.js";
+import type { JumpEntry, OutlineEntry } from "../../parser/types.js";
+import { allSymbolsLens, fileSymbolsLens, symbolByNameLens } from "../../warp/observers.js";
+import type { GitClient } from "../../ports/git.js";
+import type { ToolContext } from "../context.js";
+import { evaluateMcpRefusal, type McpPolicyRefusal } from "../policy.js";
+import { PrecisionSearchRequest, type RankedPrecisionSymbolMatch } from "./precision-query.js";
+import { PrecisionSymbolMatch } from "./precision-match.js";
+
+const MAX_RANGE_LINES = 250;
+
+export { PrecisionSearchRequest } from "./precision-query.js";
+export { PrecisionSymbolMatch } from "./precision-match.js";
+export type PrecisionPolicyRefusal = McpPolicyRefusal;
+
+async function git(gitClient: GitClient, args: readonly string[], cwd: string): Promise<string> {
+  const result = await gitClient.run({ args, cwd });
+  if (result.error !== undefined || result.status !== 0) {
+    throw result.error ?? new Error(result.stderr.trim() || `git exited with status ${String(result.status)}`);
+  }
+  return result.stdout;
+}
+
+function buildJumpLookup(
+  jumpTable: readonly JumpEntry[],
+): Map<string, { start: number; end: number }[]> {
+  const lookup = new Map<string, { start: number; end: number }[]>();
+  for (const entry of jumpTable) {
+    const existing = lookup.get(entry.symbol) ?? [];
+    existing.push({ start: entry.start, end: entry.end });
+    lookup.set(entry.symbol, existing);
+  }
+  return lookup;
+}
+
+function decodeSymbolPath(nodeId: string): string | null {
+  if (!nodeId.startsWith("sym:")) return null;
+  const lastColon = nodeId.lastIndexOf(":");
+  if (lastColon <= "sym:".length) return null;
+  return nodeId.slice("sym:".length, lastColon);
+}
+
+function toMatch(
+  nodeId: string,
+  props: Record<string, unknown>,
+): PrecisionSymbolMatch | null {
+  const name = props["name"];
+  const kind = props["kind"];
+  const path = decodeSymbolPath(nodeId);
+  if (typeof name !== "string" || typeof kind !== "string" || path === null) {
+    return null;
+  }
+
+  return new PrecisionSymbolMatch({
+    name,
+    kind,
+    path,
+    ...(typeof props["signature"] === "string" ? { signature: props["signature"] } : {}),
+    exported: props["exported"] === true,
+    ...(typeof props["startLine"] === "number" ? { startLine: props["startLine"] } : {}),
+    ...(typeof props["endLine"] === "number" ? { endLine: props["endLine"] } : {}),
+  });
+}
+
+
+export function normalizeRepoPath(projectRoot: string, input: string): string {
+  if (!path.isAbsolute(input)) return input;
+  const rel = path.relative(projectRoot, input);
+  if (rel === "") return ".";
+  return rel.startsWith("..") ? input : rel;
+}
+
+export function requireRepoPath(projectRoot: string, input: string): string {
+  const normalized = normalizeRepoPath(projectRoot, input);
+  if (path.isAbsolute(normalized)) {
+    throw new Error(`Path must be inside the repository for git-ref queries: ${input}`);
+  }
+  return normalized;
+}
+
+export async function resolveGitRef(ref: string, gitClient: GitClient, cwd: string): Promise<string> {
+  try {
+    return (await git(gitClient, ["rev-parse", "--verify", ref], cwd)).trim();
+  } catch {
+    throw new GitError(`ref does not exist: ${ref}`);
+  }
+}
+
+export async function listTrackedFilesAtRef(
+  dirPath: string,
+  gitClient: GitClient,
+  cwd: string,
+  ref: string,
+): Promise<string[]> {
+  try {
+    const args = dirPath.length > 0
+      ? ["ls-tree", "-r", "--name-only", ref, "--", dirPath]
+      : ["ls-tree", "-r", "--name-only", ref];
+    const output = (await git(gitClient, args, cwd)).trim();
+    return output.length === 0 ? [] : output.split("\n");
+  } catch {
+    return [];
+  }
+}
+
+export async function isWorkingTreeDirty(gitClient: GitClient, cwd: string): Promise<boolean> {
+  try {
+    return (await git(gitClient, ["status", "--porcelain"], cwd)).trim().length > 0;
+  } catch {
+    return true;
+  }
+}
+
+export async function getIndexedCommitCeilings(warp: WarpApp): Promise<ReadonlyMap<string, number>> {
+  const { receipts } = await warp.core().materialize({ receipts: true });
+  const ceilings = new Map<string, number>();
+
+  for (const receipt of receipts) {
+    const commitAdd = receipt.ops.find((op) =>
+      op.op === "NodeAdd" &&
+      op.result === "applied" &&
+      op.target.startsWith("commit:")
+    );
+    if (commitAdd !== undefined) {
+      ceilings.set(commitAdd.target.slice("commit:".length), receipt.lamport);
+    }
+  }
+
+  return ceilings;
+}
+
+export function collectSymbols(
+  entries: readonly OutlineEntry[],
+  filePath: string,
+  jumpTable: readonly JumpEntry[],
+  jumpCursor: Map<string, number> = new Map<string, number>(),
+): PrecisionSymbolMatch[] {
+  const jumpLookup = buildJumpLookup(jumpTable);
+  const results: PrecisionSymbolMatch[] = [];
+
+  for (const entry of entries) {
+    const candidates = jumpLookup.get(entry.name) ?? [];
+    const jumpIndex = jumpCursor.get(entry.name) ?? 0;
+    const jump = candidates[jumpIndex];
+    if (jump !== undefined) {
+      jumpCursor.set(entry.name, jumpIndex + 1);
+    }
+    results.push(new PrecisionSymbolMatch({
+      name: entry.name,
+      kind: entry.kind,
+      path: filePath,
+      exported: entry.exported,
+      ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
+      ...(jump?.start !== undefined ? { startLine: jump.start } : {}),
+      ...(jump?.end !== undefined ? { endLine: jump.end } : {}),
+    }));
+
+    if (entry.children !== undefined && entry.children.length > 0) {
+      results.push(...collectSymbols(entry.children, filePath, jumpTable, jumpCursor));
+    }
+  }
+
+  return results;
+}
+
+export async function loadFileContent(
+  ctx: ToolContext,
+  filePath: string,
+  ref?: string,
+): Promise<string | null> {
+  if (ref !== undefined) {
+    return getFileAtRef(ref, filePath, { cwd: ctx.projectRoot, git: ctx.git });
+  }
+
+  try {
+    return await ctx.fs.readFile(ctx.resolvePath(filePath), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function evaluatePrecisionPolicy(
+  ctx: ToolContext,
+  filePath: string,
+  content: string,
+): PrecisionPolicyRefusal | null {
+  const actual = {
+    lines: content.split("\n").length,
+    bytes: Buffer.byteLength(content),
+  };
+  return evaluateMcpRefusal(ctx, filePath, actual);
+}
+
+export async function searchWarpSymbols(
+  warp: WarpApp,
+  request: PrecisionSearchRequest,
+): Promise<PrecisionSymbolMatch[]> {
+  const lensMode = request.selectLens();
+  if (lensMode === "file" && request.filePath === undefined) {
+    throw new Error("PrecisionSearchRequest selected file lens without filePath");
+  }
+  if (lensMode === "exact" && request.exactName === undefined) {
+    throw new Error("PrecisionSearchRequest selected exact lens without exactName");
+  }
+  let lens;
+  if (lensMode === "file") {
+    const filePath = request.filePath;
+    if (filePath === undefined) {
+      throw new Error("PrecisionSearchRequest selected file lens without filePath");
+    }
+    lens = fileSymbolsLens(filePath);
+  } else if (lensMode === "exact") {
+    const exactName = request.exactName;
+    if (exactName === undefined) {
+      throw new Error("PrecisionSearchRequest selected exact lens without exactName");
+    }
+    lens = symbolByNameLens(exactName);
+  } else {
+    lens = allSymbolsLens();
+  }
+  const observer = await warp.observer(
+    lens,
+    request.ceiling !== undefined ? { source: { kind: "live", ceiling: request.ceiling } } : undefined,
+  );
+  const nodeIds = await observer.getNodes();
+
+  const matches = await Promise.all(nodeIds.map(async (nodeId) => {
+    const props = await observer.getNodeProps(nodeId);
+    if (props === null) return null;
+    const match = toMatch(nodeId, props);
+    if (match === null) return null;
+    return request.rank(match);
+  }));
+
+  const visibleMatches = matches.filter((match): match is RankedPrecisionSymbolMatch => match !== null);
+  return request.sort(visibleMatches);
+}
+
+export async function searchLiveSymbols(
+  ctx: ToolContext,
+  filePaths: readonly string[],
+  request: PrecisionSearchRequest,
+  ref?: string,
+): Promise<PrecisionSymbolMatch[]> {
+  const matches: RankedPrecisionSymbolMatch[] = [];
+
+  for (const filePath of filePaths) {
+    const lang = detectLang(filePath);
+    if (lang === null) continue;
+
+    const content = await loadFileContent(ctx, filePath, ref);
+    if (content === null) continue;
+
+    const result = extractOutline(content, lang);
+    const symbols = collectSymbols(result.entries, filePath, result.jumpTable ?? []);
+
+    for (const symbol of symbols) {
+      const ranked = request.rank(symbol);
+      if (ranked !== null) matches.push(ranked);
+    }
+  }
+
+  return request.sort(matches);
+}
+
+export function readRangeFromContent(
+  filePath: string,
+  content: string,
+  start: number,
+  end: number,
+): {
+  path: string;
+  content?: string | undefined;
+  startLine?: number | undefined;
+  endLine?: number | undefined;
+  truncated?: boolean | undefined;
+  clipped?: boolean | undefined;
+  reason?: string | undefined;
+} {
+  if (start > end) {
+    return { path: filePath, reason: "INVALID_RANGE" };
+  }
+
+  const allLines = content.split("\n");
+  const totalLines = allLines.length;
+  let effectiveEnd = end;
+  let truncated = false;
+  let clipped = false;
+
+  if (effectiveEnd - start + 1 > MAX_RANGE_LINES) {
+    effectiveEnd = start + MAX_RANGE_LINES - 1;
+    truncated = true;
+  }
+
+  if (effectiveEnd > totalLines) {
+    effectiveEnd = totalLines;
+    clipped = true;
+  }
+
+  return {
+    path: filePath,
+    content: allLines.slice(start - 1, effectiveEnd).join("\n"),
+    startLine: start,
+    endLine: effectiveEnd,
+    ...(truncated ? { truncated: true, reason: "RANGE_EXCEEDED" } : {}),
+    ...(clipped ? { clipped: true } : {}),
+  };
+}