march-cli 0.1.0

package/bin/march.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const emitWarning = process.emitWarning;
+process.emitWarning = function filteredWarning(warning, ...args) {
+  const message = typeof warning === "string" ? warning : warning?.message;
+  const type = typeof warning === "string" ? args[0] : warning?.name;
+  if (type === "ExperimentalWarning" && String(message).includes("SQLite")) return;
+  return emitWarning.call(this, warning, ...args);
+};
+
+const { run } = await import("../src/main.mjs");
+const code = await run(process.argv.slice(2));
+process.exitCode = code;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "march-cli",
+  "version": "0.1.0",
+  "description": "March CLI — terminal-native coding agent with context reconstruction",
+  "type": "module",
+  "main": "./src/main.mjs",
+  "bin": {
+    "march": "bin/march.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "dev": "cd .. && node march-cli/bin/march.mjs",
+    "test": "node test/smoke.test.mjs",
+    "test:real": "npm run test:shell-runtime-real && npm run test:shell-tui-real && npm run test:tui-key-real",
+    "test:shell-runtime-real": "node test/shell-real-runtime.acceptance.mjs",
+    "test:shell-tui-real": "node test/shell-tui-real.acceptance.mjs",
+    "test:tui-key-real": "node test/tui-key-real.acceptance.mjs",
+    "context": "cd .. && node march-cli/bin/march.mjs --dump-context"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
+    "@xterm/headless": "^5.5.0",
+    "marked": "^18.0.3",
+    "node-pty": "^1.1.0",
+    "typebox": "^1.0.58",
+    "web-tree-sitter": "^0.26.8"
+  },
+  "optionalDependencies": {
+    "@vscode/ripgrep": "^1.18.0"
+  }
+}

package/src/agent/command-exec-tool.mjs

@@ -0,0 +1,91 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "./tool-result.mjs";
+import { stripAnsi } from "../text/ansi.mjs";
+
+const OUTPUT_LIMIT = 64 * 1024;
+
+export function createCommandExecTool({ cwd }) {
+  return defineTool({
+    name: "command_exec",
+    label: "Command Exec",
+    description: "Run a one-shot command in the project directory. Use terminal_* for interactive or long-running processes.",
+    parameters: Type.Object({
+      command: Type.String({ description: "Command to execute" }),
+      shell: Type.Optional(Type.String({ description: "auto (default), bash, or powershell" })),
+      timeout: Type.Optional(Type.Number({ description: "Timeout in seconds; default 60" })),
+    }),
+    execute: async (_toolCallId, params) => executeCommand({ cwd, ...params }),
+  });
+}
+
+export function executeCommand({ cwd, command, shell = "auto", timeout = 60, spawnSyncImpl = spawnSync }) {
+  let resolved;
+  try {
+    resolved = resolveCommandShell(shell);
+  } catch (err) {
+    return toolText(`Error: ${err.message}`, { error: true });
+  }
+  const result = spawnSyncImpl(resolved.bin, [...resolved.args, String(command ?? "")], {
+    cwd,
+    encoding: "utf8",
+    timeout: Math.max(1, Number(timeout) || 60) * 1000,
+    windowsHide: true,
+    maxBuffer: OUTPUT_LIMIT,
+  });
+  if (result.error) {
+    const isTimeout = result.error.code === "ETIMEDOUT" || result.signal === "SIGTERM";
+    const detail = isTimeout ? ` (timed out after ${timeout}s)` : "";
+    return toolText(`Error: ${result.error.message}${detail}`, { error: true });
+  }
+  const stdout = stripAnsi(result.stdout ?? "");
+  const stderr = stripAnsi(result.stderr ?? "");
+  const output = formatCommandOutput({ stdout, stderr, status: result.status });
+  return toolText(output, {
+    status: result.status,
+    stdout,
+    stderr,
+    shell: resolved.name,
+    error: result.status !== 0,
+  });
+}
+
+export function resolveCommandShell(shell = "auto", platform = process.platform) {
+  const normalized = String(shell ?? "auto").trim().toLowerCase();
+  if (normalized === "powershell" || (normalized === "auto" && platform === "win32")) {
+    return { name: "powershell", bin: findPowerShell() ?? "powershell.exe", args: ["-NoProfile", "-Command"] };
+  }
+  if (normalized === "bash" || normalized === "auto") {
+    return { name: "bash", bin: "bash", args: ["-lc"] };
+  }
+  throw new Error(`unsupported shell: ${shell}`);
+}
+
+function findPowerShell() {
+  for (const name of ["pwsh.exe", "powershell.exe"]) {
+    try {
+      const result = spawnSync("where", [name], { encoding: "utf-8", timeout: 5000, windowsHide: true });
+      if (result.status === 0 && result.stdout) {
+        const first = result.stdout.trim().split(/\r?\n/)[0];
+        if (first && existsSync(first)) return first;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function formatCommandOutput({ stdout, stderr, status }) {
+  const parts = [];
+  if (stdout) parts.push(stdout.trimEnd());
+  if (stderr) parts.push(stderr.trimEnd());
+  if (status && status !== 0) parts.push(`exit ${status}`);
+  const output = parts.filter(Boolean).join("\n");
+  return output ? truncateOutput(output) : "(no output)";
+}
+
+function truncateOutput(text) {
+  if (text.length <= OUTPUT_LIMIT) return text;
+  return `${text.slice(-OUTPUT_LIMIT)}\n... (truncated to last ${OUTPUT_LIMIT} chars)`;
+}

package/src/agent/context-stats-tool.mjs

@@ -0,0 +1,57 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "./tool-result.mjs";
+
+export function createContextStatsTool({ engine }) {
+  return defineTool({
+    name: "context_stats",
+    label: "Context Stats",
+    description: "Show size statistics for the current March context layers without returning the full prompt text.",
+    parameters: Type.Object({}),
+    execute: async () => toolText(formatContextStats(engine), buildContextStats(engine)),
+  });
+}
+
+export function buildContextStats(engine) {
+  const layers = engine.buildContextLayers("");
+  const contextText = layers.map((layer) => layer.text).join("\n\n");
+  const layerStats = layers.map((layer) => ({
+    name: layer.name,
+    chars: layer.text.length,
+    estimatedTokens: estimateTokens(layer.text.length),
+  }));
+  return {
+    totalChars: contextText.length,
+    estimatedTokens: estimateTokens(contextText.length),
+    layers: layerStats,
+    runtime: {
+      turns: engine.turns?.length ?? 0,
+      toolDefs: engine.toolDefs?.length ?? 0,
+    },
+  };
+}
+
+function formatContextStats(engine) {
+  const stats = buildContextStats(engine);
+  const lines = [
+    "Context stats:",
+    `total_chars: ${stats.totalChars}`,
+    `estimated_tokens: ${stats.estimatedTokens}`,
+    "",
+    "Layers:",
+  ];
+  for (const layer of stats.layers) {
+    lines.push(`- ${layer.name}: ${layer.chars} chars, ~${layer.estimatedTokens} tokens`);
+  }
+  lines.push(
+    "",
+    "Runtime:",
+    `- turns: ${stats.runtime.turns}`,
+    `- tool_defs: ${stats.runtime.toolDefs}`,
+  );
+  return lines.join("\n");
+}
+
+function estimateTokens(chars) {
+  return Math.ceil(chars / 4);
+}

package/src/agent/editing/diff-apply.mjs

@@ -0,0 +1,28 @@
+/**
+ * Apply unified-diff-like patches to in-memory text content.
+ * Used by file-edit-tool for dry-run validation and safe application.
+ */
+export function applyReplaceTextPatch(text, oldText, newText) {
+  const idx = text.indexOf(oldText);
+  if (idx === -1) {
+    return { ok: false, error: `Text not found in content` };
+  }
+  const before = text.slice(0, idx);
+  const after = text.slice(idx + oldText.length);
+  return { ok: true, result: before + newText + after };
+}
+
+export function applyReplaceRangePatch(text, startLine, endLine, newText) {
+  const lines = text.split("\n");
+  if (startLine < 1 || startLine > lines.length) {
+    return { ok: false, error: `startLine ${startLine} out of range (1-${lines.length})` };
+  }
+  if (endLine < startLine || endLine > lines.length) {
+    return { ok: false, error: `endLine ${endLine} out of range (${startLine}-${lines.length})` };
+  }
+  const zeroBasedStart = startLine - 1;
+  const before = lines.slice(0, zeroBasedStart);
+  const after = lines.slice(endLine);
+  const newLines = newText === "" ? [] : newText.split("\n");
+  return { ok: true, result: [...before, ...newLines, ...after].join("\n") };
+}

package/src/agent/editing/diff-format.mjs

@@ -0,0 +1,57 @@
+export function formatDiff(oldText, newText, { startLine = 1 } = {}) {
+  if (oldText === "") return newText === "" ? [] : newText.split("\n").map((text, i) => ({ type: "add", text, lineNum: startLine + i }));
+  if (newText === "") return oldText.split("\n").map((text, i) => ({ type: "del", text, lineNum: startLine + i }));
+  const oldLines = oldText.split("\n");
+  const newLines = newText.split("\n");
+
+  let prefix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix++;
+
+  let suffix = 0;
+  while (
+    suffix < oldLines.length - prefix &&
+    suffix < newLines.length - prefix &&
+    oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
+  ) {
+    suffix++;
+  }
+
+  const ctx = 3;
+  const result = [];
+  const ctxStart = Math.max(0, prefix - ctx);
+  for (let i = ctxStart; i < prefix; i++) result.push({ type: "ctx", text: oldLines[i], lineNum: startLine + i });
+
+  const oldEnd = oldLines.length - suffix;
+  for (let i = prefix; i < oldEnd; i++) result.push({ type: "del", text: oldLines[i], lineNum: startLine + i });
+
+  const newEnd = newLines.length - suffix;
+  for (let i = prefix; i < newEnd; i++) result.push({ type: "add", text: newLines[i], lineNum: startLine + i });
+
+  const postStart = oldLines.length - suffix;
+  const postEnd = Math.min(oldLines.length, postStart + ctx);
+  for (let i = postStart; i < postEnd; i++) result.push({ type: "ctx", text: oldLines[i], lineNum: startLine + i });
+  return result;
+}
+
+export function countDiffChanges(diffLines) {
+  let adds = 0, dels = 0;
+  for (const line of diffLines) {
+    if (line.type === "add") adds++;
+    if (line.type === "del") dels++;
+  }
+  return { adds, dels };
+}
+
+export function formatAppliedDiff(edits) {
+  const lines = ["[diff]"];
+  for (const edit of edits) {
+    const oldLineCount = edit.oldText.split("\n").length;
+    lines.push(`@@ lines ${edit.startLine}-${edit.startLine + oldLineCount - 1} @@`);
+    for (const line of formatDiff(edit.oldText, edit.newText, { startLine: edit.startLine })) {
+      if (line.type === "ctx") lines.push(` ${line.lineNum}: ${line.text}`);
+      if (line.type === "del") lines.push(`-${line.lineNum}: ${line.text}`);
+      if (line.type === "add") lines.push(`+${line.lineNum}: ${line.text}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/agent/file-edit-tool.mjs

@@ -0,0 +1,276 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "./tool-result.mjs";
+import { applyReplaceTextPatch, applyReplaceRangePatch } from "./editing/diff-apply.mjs";
+import { formatAppliedDiff, formatDiff } from "./editing/diff-format.mjs";
+import { buildDiagnosticsForPath } from "../context/diagnostics.mjs";
+
+export { formatDiff } from "./editing/diff-format.mjs";
+
+const PATCH_MODE = "patch";
+const WRITE_MODE = "write";
+const OVERWRITE_MODE = "overwrite";
+
+const replaceTextEditSchema = Type.Object({
+  type: Type.Literal("replace_text"),
+  oldText: Type.String({ description: "Exact text to replace. Must match exactly once in the original file." }),
+  newText: Type.String({ description: "Replacement text" }),
+});
+
+const replaceRangeEditSchema = Type.Object({
+  type: Type.Literal("replace_range"),
+  startLine: Type.Number({ description: "1-based inclusive start line" }),
+  endLine: Type.Number({ description: "1-based inclusive end line. This line is deleted too; keep it out of the range or include it in newText if it should remain." }),
+  newText: Type.String({ description: "Replacement text. Omit a trailing newline unless intentionally adding a blank line." }),
+});
+
+export function createEditFileTool({ engine, ui, lspService = null }) {
+  return defineTool({
+    name: "edit_file",
+    label: "Edit File",
+    description:
+      "Single file write tool. Use mode=patch with edits[] for targeted edits. " +
+      "Use mode=write with content for new files. Use mode=overwrite with content for full-file replacement.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Absolute or relative path" }),
+      mode: Type.Optional(Type.Union([
+        Type.Literal(PATCH_MODE),
+        Type.Literal(WRITE_MODE),
+        Type.Literal(OVERWRITE_MODE),
+      ], { description: "patch (default), write, or overwrite" })),
+      edits: Type.Optional(Type.Array(Type.Union([replaceTextEditSchema, replaceRangeEditSchema]), {
+        description: "Patch edits. replace_text uses exact text; replace_range uses 1-based inclusive line numbers and deletes the endLine content too.",
+      })),
+      content: Type.Optional(Type.String({ description: "Full file content for mode=write or mode=overwrite" })),
+    }),
+    execute: async (_toolCallId, params) => executeEditFile({ params, engine, ui, lspService }),
+  });
+}
+
+export async function executeEditFile({ params, engine, ui, lspService = null }) {
+  const absPath = engine.resolvePath(params.path);
+  const mode = params.mode ?? PATCH_MODE;
+
+  if (mode === WRITE_MODE || mode === OVERWRITE_MODE) {
+    return await writeFullFile({ absPath, path: params.path, content: params.content, mode, engine, ui, lspService });
+  }
+  if (mode !== PATCH_MODE) return toolText(`Error: unsupported edit_file mode: ${mode}`, { error: true });
+  return await patchFile({ absPath, path: params.path, edits: params.edits, engine, ui, lspService });
+}
+
+async function writeFullFile({ absPath, path, content, mode, engine, ui, lspService }) {
+  if (typeof content !== "string") {
+    return toolText(`Error: content is required for mode=${mode}`, { error: true });
+  }
+  if (mode === WRITE_MODE && existsSync(absPath)) {
+    return toolText(`Error: ${absPath} already exists. Use mode=overwrite to replace it.`, { error: true });
+  }
+  const oldText = mode === OVERWRITE_MODE && existsSync(absPath) ? readFileSync(absPath, "utf8") : "";
+  const diffLines = formatDiff(oldText, content, { startLine: 1 });
+  try {
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, content, "utf8");
+    lspService?.touchFile?.(absPath);
+    ui.editDiff(absPath, diffLines);
+
+    return await toolTextWithDiagnostics(`${mode === WRITE_MODE ? "Wrote" : "Overwrote"} ${path}\n\n${formatAppliedDiff([{ oldText, newText: content, startLine: 1 }])}`, { path: absPath }, { lspService, path: absPath });
+  } catch (err) {
+    return toolText(`Error writing ${absPath}: ${err.message}`, { error: true });
+  }
+}
+
+async function patchFile({ absPath, path, edits, engine, ui, lspService }) {
+  if (!existsSync(absPath)) {
+    return toolText(`Error: ${absPath} does not exist. Use mode=write to create it.`, { error: true });
+  }
+  if (!Array.isArray(edits) || edits.length === 0) {
+    return toolText("Error: mode=patch requires at least one edit", { error: true });
+  }
+  if (edits.length > 50) {
+    return toolText("Error: maximum 50 edits per call", { error: true });
+  }
+
+  const content = readFileSync(absPath, "utf8");
+  const prepared = preparePatchEdits(content, edits, absPath);
+  if (prepared.error) return toolText(prepared.error, { error: true });
+
+  const newContent = applyPreparedEdits(content, prepared.edits);
+  try {
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, newContent, "utf8");
+    lspService?.touchFile?.(absPath);
+    ui.editDiff(absPath, prepared.edits.flatMap((edit) => formatDiff(edit.oldText, edit.newText, { startLine: edit.startLine })));
+    return await toolTextWithDiagnostics(`Edited ${absPath}\n\n${formatAppliedDiff(prepared.edits)}`, { path: absPath, edits: prepared.edits.length }, { lspService, path: absPath });
+  } catch (err) {
+    return toolText(`Error writing ${absPath}: ${err.message}`, { error: true });
+  }
+}
+
+async function toolTextWithDiagnostics(text, details, { lspService, path, timeoutMs = 3000, intervalMs = 150 } = {}) {
+  const diagnostics = await waitForDiagnosticsForPath({ lspService, path, timeoutMs, intervalMs });
+  return toolText(diagnostics ? `${text}\n\n${diagnostics}` : text, details);
+}
+
+async function waitForDiagnosticsForPath({ lspService, path, timeoutMs, intervalMs }) {
+  if (!lspService?.snapshot || !path) return "";
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const diagnostics = buildDiagnosticsForPath({ snapshot: lspService.snapshot(), path });
+    if (diagnostics) return diagnostics;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return "";
+    await sleep(Math.min(intervalMs, remaining));
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function preparePatchEdits(content, edits, path = "file") {
+  const prepared = [];
+  for (const edit of edits) {
+    const next = prepareOneEdit(content, edit, path);
+    if (next.error) return next;
+    prepared.push(next.edit);
+  }
+  prepared.sort((a, b) => a.start - b.start || a.end - b.end);
+  for (let i = 1; i < prepared.length; i++) {
+    if (prepared[i].start < prepared[i - 1].end) {
+      return { error: `Error: edits overlap in ${path}` };
+    }
+  }
+  return { edits: prepared };
+}
+
+function prepareOneEdit(content, edit, path) {
+  if (edit?.type === "replace_text") return prepareTextEdit(content, edit, path);
+  if (edit?.type === "replace_range") return prepareRangeEdit(content, edit, path);
+  return { error: `Error: unsupported edit type: ${edit?.type}` };
+}
+
+function prepareTextEdit(content, edit, path) {
+  if (!edit.oldText) return { error: "Error: replace_text oldText must be non-empty" };
+  const first = content.indexOf(edit.oldText);
+  if (first < 0) return { error: formatMissingOldTextError(content, edit.oldText, path) };
+  const second = content.indexOf(edit.oldText, first + edit.oldText.length);
+  if (second >= 0) return { error: `Error: oldText is not unique in ${path}. Use replace_range or include more context.` };
+  return {
+    edit: {
+      start: first,
+      end: first + edit.oldText.length,
+      oldText: edit.oldText,
+      newText: edit.newText,
+      startLine: lineNumberForOffset(content, first),
+    },
+  };
+}
+
+function formatMissingOldTextError(content, oldText, path) {
+  const candidate = findClosestTextCandidate(content, oldText);
+  const lines = [`Error: oldText not found in ${path}. File may have changed.`];
+  if (!candidate) return lines.join("\n");
+  lines.push(
+    "",
+    "Closest candidate:",
+    `lines ${candidate.startLine}-${candidate.endLine}, similarity ${candidate.score.toFixed(2)}`,
+    "---",
+    candidate.snippet,
+    "---",
+    `Use replace_range with startLine=${candidate.startLine} endLine=${candidate.endLine} if this is intended.`,
+  );
+  return lines.join("\n");
+}
+
+function findClosestTextCandidate(content, oldText) {
+  const lines = content.split("\n");
+  const oldLineCount = Math.max(1, oldText.split("\n").length);
+  const windowSizes = [...new Set([oldLineCount - 1, oldLineCount, oldLineCount + 1])]
+    .filter((size) => size > 0 && size <= lines.length);
+  let best = null;
+  for (const size of windowSizes) {
+    for (let start = 0; start <= lines.length - size; start++) {
+      const snippet = lines.slice(start, start + size).join("\n");
+      const score = textSimilarity(oldText, snippet);
+      if (!best || score > best.score) {
+        best = { startLine: start + 1, endLine: start + size, score, snippet: truncateSnippet(snippet) };
+      }
+    }
+  }
+  return best?.score >= 0.2 ? best : null;
+}
+
+function textSimilarity(a, b) {
+  const aTokens = tokenizeForSimilarity(a);
+  const bTokens = tokenizeForSimilarity(b);
+  if (aTokens.length === 0 || bTokens.length === 0) return 0;
+  const counts = new Map();
+  for (const token of aTokens) counts.set(token, (counts.get(token) ?? 0) + 1);
+  let common = 0;
+  for (const token of bTokens) {
+    const count = counts.get(token) ?? 0;
+    if (count <= 0) continue;
+    common++;
+    counts.set(token, count - 1);
+  }
+  return (2 * common) / (aTokens.length + bTokens.length);
+}
+
+function tokenizeForSimilarity(text) {
+  const tokens = String(text).toLowerCase().match(/[a-z0-9_]+/g);
+  if (tokens?.length) return tokens;
+  return String(text).replace(/\s+/g, "").split("").filter(Boolean);
+}
+
+function truncateSnippet(text) {
+  const limit = 1200;
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit)}\n...(snippet truncated)`;
+}
+
+function prepareRangeEdit(content, edit, path) {
+  const lines = content.split("\n");
+  const startLine = Math.trunc(edit.startLine);
+  const endLine = Math.trunc(edit.endLine);
+  if (startLine < 1 || endLine > lines.length || startLine > endLine) {
+    return { error: `Error: line range ${startLine}-${endLine} out of bounds (file has ${lines.length} lines)` };
+  }
+  const oldText = lines.slice(startLine - 1, endLine).join("\n");
+  const newText = normalizeRangeNewText(edit.newText, endLine, lines.length);
+  return {
+    edit: {
+      start: offsetForLine(lines, startLine),
+      end: offsetForLine(lines, startLine) + oldText.length,
+      oldText,
+      newText,
+      startLine,
+    },
+  };
+}
+
+function normalizeRangeNewText(newText, endLine, lineCount) {
+  if (endLine < lineCount && /\r?\n$/.test(newText)) return newText.replace(/\r?\n$/, "");
+  return newText;
+}
+
+function lineNumberForOffset(content, offset) {
+  let line = 1;
+  for (let i = 0; i < offset; i++) if (content[i] === "\n") line++;
+  return line;
+}
+
+function offsetForLine(lines, lineNumber) {
+  let offset = 0;
+  for (let i = 0; i < lineNumber - 1; i++) offset += lines[i].length + 1;
+  return offset;
+}
+
+function applyPreparedEdits(content, edits) {
+  let next = content;
+  for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+    next = next.slice(0, edit.start) + edit.newText + next.slice(edit.end);
+  }
+  return next;
+}

package/src/agent/find-tool.mjs

@@ -0,0 +1,112 @@
+import { readdirSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "./tool-result.mjs";
+
+const DEFAULT_LIMIT = 1000;
+const DEFAULT_IGNORES = new Set([".git", "node_modules"]);
+
+export function createFindTool({ cwd }) {
+  return defineTool({
+    name: "find",
+    label: "Find Files",
+    description: "Find files by glob pattern. Pattern is matched relative to the search directory. Basename-only patterns like '*.mjs' search recursively, so find('*.mjs', path:'src') and find('src/**/*.mjs') both work.",
+    parameters: Type.Object({
+      pattern: Type.String({ description: "Glob pattern to match files, e.g. '*.mjs', '**/*.json', or 'src/**/*.test.mjs'" }),
+      path: Type.Optional(Type.String({ description: "Directory to search in (default: current directory)" })),
+      limit: Type.Optional(Type.Number({ description: "Maximum number of results (default 1000)" })),
+    }),
+    execute: async (_toolCallId, params) => executeFind({ cwd, ...params }),
+  });
+}
+
+export function executeFind({ cwd, pattern, path = ".", limit = DEFAULT_LIMIT }) {
+  const searchRoot = resolveSearchRoot(cwd, path);
+  const trimmedPattern = String(pattern ?? "").trim().replaceAll("\\", "/");
+  if (!trimmedPattern) return toolText("Error: pattern is required", { error: true });
+  const effectivePattern = normalizePattern(trimmedPattern);
+
+  const max = Math.max(1, Number(limit) || DEFAULT_LIMIT);
+  let files;
+  try {
+    files = listFiles(searchRoot);
+  } catch (err) {
+    return toolText(`Error: ${err.message}`, { error: true });
+  }
+
+  const matches = [];
+  for (const file of files) {
+    const rel = toPosix(relative(searchRoot, file));
+    if (!matchesGlob(effectivePattern, rel)) continue;
+    matches.push(rel);
+    if (matches.length >= max) break;
+  }
+
+  if (matches.length === 0) return toolText("No files found matching pattern", { pattern: trimmedPattern, effectivePattern, path: searchRoot, count: 0 });
+  const limitHint = matches.length >= max ? `\n\n[Results truncated to ${max}. Increase limit or refine pattern.]` : "";
+  return toolText(`${matches.join("\n")}${limitHint}`, {
+    pattern: trimmedPattern,
+    effectivePattern: effectivePattern === trimmedPattern ? undefined : effectivePattern,
+    path: searchRoot,
+    count: matches.length,
+    resultLimitReached: matches.length >= max ? max : undefined,
+  });
+}
+
+function normalizePattern(pattern) {
+  if (pattern.includes("/") || pattern.includes("**")) return pattern;
+  return `**/${pattern}`;
+}
+
+function resolveSearchRoot(cwd, path) {
+  const raw = String(path || ".");
+  return isAbsolute(raw) ? raw : resolve(cwd, raw);
+}
+
+function listFiles(root) {
+  const out = [];
+  walk(root, out);
+  return out.sort((a, b) => toPosix(a).localeCompare(toPosix(b)));
+}
+
+function walk(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && DEFAULT_IGNORES.has(entry.name)) continue;
+    const path = resolve(dir, entry.name);
+    if (entry.isDirectory()) walk(path, out);
+    else if (entry.isFile()) out.push(path);
+  }
+}
+
+function matchesGlob(pattern, candidate) {
+  return matchSegments(splitGlob(pattern), splitGlob(candidate));
+}
+
+function matchSegments(patternSegments, candidateSegments) {
+  if (patternSegments.length === 0) return candidateSegments.length === 0;
+  const [head, ...tail] = patternSegments;
+  if (head === "**") {
+    if (matchSegments(tail, candidateSegments)) return true;
+    return candidateSegments.length > 0 && matchSegments(patternSegments, candidateSegments.slice(1));
+  }
+  if (candidateSegments.length === 0) return false;
+  return matchSegment(head, candidateSegments[0]) && matchSegments(tail, candidateSegments.slice(1));
+}
+
+function matchSegment(pattern, candidate) {
+  const regex = new RegExp(`^${escapeRegex(pattern).replaceAll("\\*", "[^/]*").replaceAll("\\?", "[^/]")}$`);
+  return regex.test(candidate);
+}
+
+function splitGlob(value) {
+  return String(value).split("/").filter(Boolean);
+}
+
+function toPosix(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[|\\{}()[\]^$+*?.]/g, "\\$&");
+}