@aria-cli/tools 1.0.9 → 1.0.11

package/src/executors/filesystem.ts

@@ -1,1428 +0,0 @@
-/**
- * @aria/tools - Filesystem tool executors
- *
- * Implementation of filesystem operations for ARIA tool system.
- */
-
-import * as fs from "node:fs/promises";
-import * as fsSync from "node:fs";
-import * as nodePath from "node:path";
-import * as crypto from "node:crypto";
-import * as readline from "node:readline";
-import { structuredPatch as computePatch } from "diff";
-import fastGlob from "fast-glob";
-import type { ToolContext, ToolResult } from "../types.js";
-import { success, fail, getErrorMessage, isPathWithinBase } from "./utils.js";
-import { recordFrgMutation } from "./frg-freshness.js";
-import { recordSearchMutation } from "./search-freshness.js";
-
-/** Media file extensions for binary reading */
-const MEDIA_EXTENSIONS = new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".svg",
-  ".bmp",
-  ".ico",
-  ".mp3",
-  ".wav",
-  ".ogg",
-  ".flac",
-  ".aac",
-  ".mp4",
-  ".webm",
-  ".mov",
-  ".pdf",
-]);
-
-/** MIME type lookup */
-const MIME_TYPES: Record<string, string> = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".bmp": "image/bmp",
-  ".ico": "image/x-icon",
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".ogg": "audio/ogg",
-  ".flac": "audio/flac",
-  ".aac": "audio/aac",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".mov": "video/quicktime",
-  ".pdf": "application/pdf",
-};
-
-const MAX_MEDIA_SIZE_BYTES = 10 * 1024 * 1024; // 10MB
-const DEFAULT_READ_LIMIT = 2000;
-const MAX_READ_BYTES = 200 * 1024; // 200KB
-
-/**
- * Hard output caps to avoid overwhelming tool responses.
- * read_file already has media-size capping and line slicing support.
- */
-export const FILESYSTEM_OUTPUT_LIMITS = {
-  MAX_GLOB_RESULTS: 2000,
-  MAX_GREP_MATCHES: 2000,
-  MAX_GREP_ERRORS: 200,
-  MAX_GREP_FILE_BYTES: 2 * 1024 * 1024,
-  MAX_GREP_LINE_BYTES: 16 * 1024,
-} as const;
-
-/**
- * Normalize common aliases before passing encodings to Node fs APIs.
- */
-const SUPPORTED_ENCODINGS = new Set<BufferEncoding>([
-  "utf8",
-  "utf16le",
-  "latin1",
-  "ascii",
-  "base64",
-  "base64url",
-  "hex",
-  "ucs2",
-  "binary",
-]);
-
-function normalizeEncoding(inputEncoding?: string): BufferEncoding {
-  if (!inputEncoding) return "utf8";
-  const normalized = inputEncoding.toLowerCase();
-  const canonical = normalized === "utf-8" ? "utf8" : normalized;
-  if (!SUPPORTED_ENCODINGS.has(canonical as BufferEncoding)) {
-    throw new Error(`Unsupported encoding: ${inputEncoding}`);
-  }
-  return canonical as BufferEncoding;
-}
-
-/**
- * Sensitive dot-directories under $HOME that must never be accessed by tools.
- * These contain credentials, keys, and tokens that have no legitimate use in
- * ARIA's filesystem operations.
- */
-const BLOCKED_HOME_DIRS = new Set([
-  ".ssh",
-  ".gnupg",
-  ".gpg",
-  ".aws",
-  ".azure",
-  ".config/gcloud",
-  ".docker",
-  ".kube",
-  ".npmrc",
-  ".pypirc",
-  ".netrc",
-  ".git-credentials",
-  ".password-store",
-]);
-
-/**
- * Returns true if `resolved` falls inside a blocked sensitive directory under home.
- * Paths are compared after normalisation so symlink tricks don't bypass.
- */
-function isBlockedHomePath(resolved: string, realHome: string): boolean {
-  // Strip home prefix to get the relative tail, e.g. ".ssh/id_rsa"
-  const homePrefix = realHome.endsWith(nodePath.sep) ? realHome : realHome + nodePath.sep;
-  if (!resolved.startsWith(homePrefix)) return false;
-  const tail = resolved.slice(homePrefix.length);
-
-  for (const blocked of BLOCKED_HOME_DIRS) {
-    if (tail === blocked || tail.startsWith(blocked + nodePath.sep)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Resolves a path relative to the working directory if not absolute.
- * Resolves symlinks to prevent bypassing path restrictions.
- * Throws if the resolved path is outside the working directory (path traversal protection).
- */
-function resolvePath(inputPath: string, ctx: ToolContext): string {
-  let resolved = nodePath.isAbsolute(inputPath)
-    ? nodePath.resolve(inputPath)
-    : nodePath.resolve(ctx.workingDir, inputPath);
-  // Resolve symlinks on both the path and the base to prevent bypass
-  // and to handle platforms where /tmp → /private/tmp (macOS)
-  let realBase = ctx.workingDir;
-  try {
-    realBase = fsSync.realpathSync(ctx.workingDir);
-  } catch {
-    // Base dir should exist, but fall back to original if not
-  }
-  try {
-    resolved = fsSync.realpathSync(resolved);
-  } catch {
-    // Path may not exist yet (write to new file / mkdir).
-    // Walk up to find the nearest existing ancestor and resolve from there,
-    // to handle symlinked temp dirs (e.g., /tmp → /private/tmp on macOS).
-    let current = resolved;
-    let suffix = "";
-    while (current !== nodePath.dirname(current)) {
-      const parent = nodePath.dirname(current);
-      suffix = suffix
-        ? nodePath.join(nodePath.basename(current), suffix)
-        : nodePath.basename(current);
-      try {
-        const realAncestor = fsSync.realpathSync(parent);
-        resolved = nodePath.join(realAncestor, suffix);
-        break;
-      } catch {
-        current = parent;
-      }
-    }
-  }
-
-  // 1. Check working directory containment (standard sandbox)
-  if (isPathWithinBase(resolved, realBase)) {
-    return resolved;
-  }
-
-  // 2. Check home directory containment (allows access to ~/.aria/, ~/projects, etc.)
-  //    Sensitive dot-directories are blocklisted unless autonomy is "full".
-  const home = process.env.HOME;
-  if (home) {
-    try {
-      const realHome = fsSync.realpathSync(home);
-      if (isPathWithinBase(resolved, realHome)) {
-        if (ctx.autonomy !== "full" && isBlockedHomePath(resolved, realHome)) {
-          throw new Error(
-            `Path not allowed: access to sensitive home directory is blocked (set autonomy to "full" to override)`,
-          );
-        }
-        return resolved;
-      }
-    } catch (err) {
-      if (err instanceof Error && err.message.includes("sensitive home directory")) {
-        throw err;
-      }
-      // Home not accessible/exists — fall through to final guard
-    }
-  }
-
-  // Always enforce containment. This closes bypasses where
-  // absolute paths could escape the workspace if outer sandboxing is misconfigured.
-  throw new Error(
-    `Path traversal not allowed: resolved path is outside working directory and home directory`,
-  );
-}
-
-function normalizeLineEndings(text: string): string {
-  return text.replace(/\r\n/g, "\n");
-}
-
-function hashSha256(text: string): string {
-  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
-}
-
-interface TextWindow {
-  content: string;
-  startLine: number;
-  endLine: number;
-  totalLines: number;
-  truncated: boolean;
-  nextOffset?: number;
-  bytes: number;
-}
-
-function splitLinesWithoutTrailingEmpty(content: string): string[] {
-  const lines = content.split("\n");
-  if (content.endsWith("\n") && lines.length > 0 && lines[lines.length - 1] === "") {
-    lines.pop();
-  }
-  return lines;
-}
-
-function getReadWindow(content: string, offset: number, limit: number): TextWindow {
-  const lines = splitLinesWithoutTrailingEmpty(content);
-  const startLine = Math.max(0, offset);
-  const maxLines = Math.max(1, limit);
-  const sliced = lines.slice(startLine, startLine + maxLines);
-
-  const visible: string[] = [];
-  let bytes = 0;
-  let truncatedByBytes = false;
-  for (const line of sliced) {
-    const lineBytes = Buffer.byteLength(line, "utf8");
-    const separatorBytes = visible.length > 0 ? 1 : 0; // "\n"
-    if (bytes + lineBytes + separatorBytes > MAX_READ_BYTES) {
-      truncatedByBytes = true;
-      break;
-    }
-    visible.push(line);
-    bytes += lineBytes + separatorBytes;
-  }
-
-  const endExclusive = startLine + visible.length;
-  const truncatedByLines = endExclusive < lines.length;
-  const truncated = truncatedByBytes || truncatedByLines;
-  const nextOffset = truncated ? endExclusive : undefined;
-
-  return {
-    content: visible.join("\n"),
-    startLine,
-    endLine: endExclusive,
-    totalLines: lines.length,
-    truncated,
-    nextOffset,
-    bytes,
-  };
-}
-
-async function getReadWindowFromFile(
-  filePath: string,
-  encoding: BufferEncoding,
-  offset: number,
-  limit: number,
-): Promise<TextWindow> {
-  const startLine = Math.max(0, offset);
-  const maxLines = Math.max(1, limit);
-  const visible: string[] = [];
-  let bytes = 0;
-  let totalLines = 0;
-  let truncatedByBytes = false;
-  let hasExtraLines = false;
-
-  const input = fsSync.createReadStream(filePath, { encoding });
-  const lines = readline.createInterface({ input, crlfDelay: Infinity });
-
-  try {
-    for await (const line of lines) {
-      totalLines++;
-      if (totalLines <= startLine) {
-        continue;
-      }
-
-      if (visible.length >= maxLines) {
-        hasExtraLines = true;
-        continue;
-      }
-
-      const lineBytes = Buffer.byteLength(line, encoding);
-      const separatorBytes = visible.length > 0 ? 1 : 0;
-      if (bytes + lineBytes + separatorBytes > MAX_READ_BYTES) {
-        truncatedByBytes = true;
-        hasExtraLines = true;
-        continue;
-      }
-
-      visible.push(line);
-      bytes += lineBytes + separatorBytes;
-    }
-  } finally {
-    lines.close();
-    input.destroy();
-  }
-
-  const endExclusive = startLine + visible.length;
-  const truncatedByLines = hasExtraLines;
-  const truncated = truncatedByBytes || truncatedByLines;
-  const nextOffset = truncated ? endExclusive : undefined;
-
-  return {
-    content: visible.join("\n"),
-    startLine,
-    endLine: endExclusive,
-    totalLines,
-    truncated,
-    nextOffset,
-    bytes,
-  };
-}
-
-interface TextRange {
-  start: number;
-  end: number;
-}
-
-type MatchStrategyName =
-  | "exact"
-  | "trimmed_line_block"
-  | "indentation_flexible"
-  | "whitespace_normalized";
-
-function dedupeRanges(ranges: TextRange[]): TextRange[] {
-  const seen = new Set<string>();
-  const result: TextRange[] = [];
-  for (const range of ranges) {
-    const key = `${range.start}:${range.end}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    result.push(range);
-  }
-  return result.sort((a, b) => a.start - b.start || a.end - b.end);
-}
-
-function countLeadingWhitespace(line: string): number {
-  const match = line.match(/^[\t ]*/);
-  return match ? match[0].length : 0;
-}
-
-function stripCommonIndent(lines: string[]): string[] {
-  let min = Number.POSITIVE_INFINITY;
-  for (const line of lines) {
-    if (line.trim().length === 0) continue;
-    min = Math.min(min, countLeadingWhitespace(line));
-  }
-  if (!Number.isFinite(min) || min <= 0) return [...lines];
-  return lines.map((line) => (line.trim().length === 0 ? line : line.slice(min)));
-}
-
-function lineStartOffsets(content: string): number[] {
-  const starts: number[] = [0];
-  for (let i = 0; i < content.length; i++) {
-    if (content[i] === "\n") {
-      starts.push(i + 1);
-    }
-  }
-  return starts;
-}
-
-function normalizeSearchLines(raw: string[]): string[] {
-  const lines = [...raw];
-  if (lines.length > 0 && lines[lines.length - 1] === "") {
-    lines.pop();
-  }
-  return lines;
-}
-
-function getLineWindowRanges(
-  content: string,
-  oldText: string,
-  predicate: (window: string[], search: string[]) => boolean,
-): TextRange[] {
-  if (!oldText.includes("\n")) return [];
-
-  const contentLines = content.split("\n");
-  const searchLines = normalizeSearchLines(oldText.split("\n"));
-  if (searchLines.length === 0 || searchLines.length > contentLines.length) {
-    return [];
-  }
-
-  const starts = lineStartOffsets(content);
-  const ranges: TextRange[] = [];
-  for (let i = 0; i <= contentLines.length - searchLines.length; i++) {
-    const window = contentLines.slice(i, i + searchLines.length);
-    if (!predicate(window, searchLines)) continue;
-
-    const start = starts[i] ?? 0;
-    const lastLineIdx = i + searchLines.length - 1;
-    const lineStart = starts[lastLineIdx] ?? 0;
-    const line = contentLines[lastLineIdx] ?? "";
-    const end = lineStart + line.length;
-    ranges.push({ start, end });
-  }
-
-  return dedupeRanges(ranges);
-}
-
-function findExactRanges(content: string, oldText: string): TextRange[] {
-  if (oldText.length === 0) return [];
-  const ranges: TextRange[] = [];
-  let cursor = 0;
-  while (cursor <= content.length) {
-    const idx = content.indexOf(oldText, cursor);
-    if (idx === -1) break;
-    ranges.push({ start: idx, end: idx + oldText.length });
-    cursor = idx + Math.max(oldText.length, 1);
-  }
-  return dedupeRanges(ranges);
-}
-
-function findTrimmedLineBlockRanges(content: string, oldText: string): TextRange[] {
-  const trimmedNeedle = oldText.trim();
-  if (trimmedNeedle.length === 0) return [];
-
-  if (!oldText.includes("\n")) {
-    const lines = content.split("\n");
-    const starts = lineStartOffsets(content);
-    const ranges: TextRange[] = [];
-    for (let i = 0; i < lines.length; i++) {
-      if ((lines[i] ?? "").trim() !== trimmedNeedle) continue;
-      const start = starts[i] ?? 0;
-      const line = lines[i] ?? "";
-      ranges.push({ start, end: start + line.length });
-    }
-    return dedupeRanges(ranges);
-  }
-
-  return getLineWindowRanges(content, oldText, (window, search) =>
-    window.every((line, idx) => line.trim() === (search[idx] ?? "").trim()),
-  );
-}
-
-function findIndentFlexibleRanges(content: string, oldText: string): TextRange[] {
-  return getLineWindowRanges(content, oldText, (window, search) => {
-    const normalizedWindow = stripCommonIndent(window);
-    const normalizedSearch = stripCommonIndent(search);
-    if (normalizedWindow.length !== normalizedSearch.length) return false;
-    for (let i = 0; i < normalizedWindow.length; i++) {
-      if ((normalizedWindow[i] ?? "") !== (normalizedSearch[i] ?? "")) return false;
-    }
-    return true;
-  });
-}
-
-function normalizeWhitespace(line: string): string {
-  return line.trim().replace(/\s+/g, " ");
-}
-
-function findWhitespaceNormalizedRanges(content: string, oldText: string): TextRange[] {
-  if (!oldText.includes("\n")) {
-    const needle = normalizeWhitespace(oldText);
-    if (!needle) return [];
-    const lines = content.split("\n");
-    const starts = lineStartOffsets(content);
-    const ranges: TextRange[] = [];
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i] ?? "";
-      if (normalizeWhitespace(line) !== needle) continue;
-      const start = starts[i] ?? 0;
-      ranges.push({ start, end: start + line.length });
-    }
-    return dedupeRanges(ranges);
-  }
-
-  return getLineWindowRanges(content, oldText, (window, search) =>
-    window.every(
-      (line, idx) => normalizeWhitespace(line) === normalizeWhitespace(search[idx] ?? ""),
-    ),
-  );
-}
-
-function applyRanges(content: string, ranges: TextRange[], replacement: string): string {
-  const sorted = [...ranges].sort((a, b) => b.start - a.start || b.end - a.end);
-  let next = content;
-  for (const range of sorted) {
-    next = next.slice(0, range.start) + replacement + next.slice(range.end);
-  }
-  return next;
-}
-
-// ============================================================================
-// Read File
-// ============================================================================
-
-export interface ReadFileInput {
-  path: string;
-  /** File encoding */
-  encoding?: string;
-  /** Line offset (0-based) to start reading from */
-  offset?: number;
-  /** Number of lines to read */
-  limit?: number;
-}
-
-/**
- * Reads a file's contents.
- */
-export async function executeReadFile(input: ReadFileInput, ctx: ToolContext): Promise<ToolResult> {
-  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
-  try {
-    if (input.offset !== undefined && (!Number.isInteger(input.offset) || input.offset < 0)) {
-      return fail("offset must be a non-negative integer");
-    }
-    if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit <= 0)) {
-      return fail("limit must be a positive integer");
-    }
-
-    const filePath = resolvePath(input.path, ctx);
-    const stat = await fs.stat(filePath);
-    const encoding = normalizeEncoding(input.encoding);
-
-    if (stat.isDirectory()) {
-      return fail(`Path is a directory: ${filePath}`);
-    }
-
-    // Detect media files by extension — return base64 object unless caller explicitly requested
-    // a non-UTF8 text/binary encoding.
-    const ext = nodePath.extname(filePath).toLowerCase();
-    const isMediaFile = MEDIA_EXTENSIONS.has(ext);
-    if (isMediaFile && stat.size > MAX_MEDIA_SIZE_BYTES) {
-      return fail(
-        `File too large for media reading: ${(stat.size / 1024 / 1024).toFixed(1)}MB (max 10MB)`,
-      );
-    }
-
-    const useMediaEncoding = !input.encoding || encoding === "utf8";
-    if (isMediaFile && useMediaEncoding) {
-      const buffer = await fs.readFile(filePath);
-      const base64 = buffer.toString("base64");
-      const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
-
-      return success(
-        `Read media file: ${nodePath.basename(filePath)} (${mimeType}, ${(stat.size / 1024).toFixed(1)}KB)`,
-        {
-          type: "media",
-          mimeType,
-          base64,
-          size: stat.size,
-          path: filePath,
-        },
-      );
-    }
-
-    const explicitWindow = input.offset !== undefined || input.limit !== undefined;
-    let window: TextWindow;
-    let returnedContent: string;
-
-    if (!explicitWindow && stat.size <= MAX_READ_BYTES) {
-      const content = normalizeLineEndings(await fs.readFile(filePath, { encoding }));
-      window = getReadWindow(content, 0, DEFAULT_READ_LIMIT);
-      returnedContent = window.truncated ? window.content : content;
-    } else {
-      window = await getReadWindowFromFile(
-        filePath,
-        encoding,
-        input.offset ?? 0,
-        input.limit ?? DEFAULT_READ_LIMIT,
-      );
-      returnedContent = window.content;
-    }
-
-    const returnedBytes = Buffer.byteLength(returnedContent, encoding);
-
-    const lineSummary = `lines ${window.startLine + 1}-${window.endLine} of ${window.totalLines}`;
-    const truncationSummary = window.truncated
-      ? ` (truncated; use offset=${window.nextOffset ?? window.endLine} to continue)`
-      : "";
-
-    return success(
-      `Read ${returnedContent.length} characters (${lineSummary}, ${returnedBytes} bytes) from ${filePath}${truncationSummary}`,
-      returnedContent,
-    );
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}
-
-// ============================================================================
-// Write File
-// ============================================================================
-
-export interface WriteFileInput {
-  path: string;
-  content: string;
-  /** File encoding */
-  encoding?: string;
-  /** Append to file instead of overwriting */
-  append?: boolean;
-  /**
-   * Optional optimistic concurrency guard.
-   * If provided, write only succeeds when current file content hash matches this value.
-   */
-  expectedHash?: string;
-}
-
-/**
- * Writes content to a file.
- */
-export async function executeWriteFile(
-  input: WriteFileInput,
-  ctx: ToolContext,
-): Promise<ToolResult> {
-  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
-  try {
-    const filePath = resolvePath(input.path, ctx);
-    const encoding = normalizeEncoding(input.encoding);
-    const expectedHash = input.expectedHash?.trim().toLowerCase();
-
-    if (expectedHash && !/^[a-f0-9]{64}$/.test(expectedHash)) {
-      return fail("expectedHash must be a 64-character lowercase/uppercase SHA-256 hex digest");
-    }
-
-    let existed = false;
-    let previousContent = "";
-    try {
-      previousContent = await fs.readFile(filePath, { encoding });
-      existed = true;
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException)?.code;
-      if (code !== "ENOENT") {
-        throw err;
-      }
-    }
-
-    const previousHash = existed ? hashSha256(normalizeLineEndings(previousContent)) : undefined;
-    if (expectedHash) {
-      if (!existed) {
-        return fail("expectedHash was provided but the file does not exist");
-      }
-      if (previousHash !== expectedHash) {
-        return fail(`Hash mismatch for ${filePath}: file changed since last read`, {
-          expectedHash,
-          actualHash: previousHash,
-          path: filePath,
-        });
-      }
-    }
-
-    // Ensure parent directory exists
-    const parentDir = nodePath.dirname(filePath);
-    await fs.mkdir(parentDir, { recursive: true });
-
-    if (input.append) {
-      await fs.appendFile(filePath, input.content, { encoding });
-    } else {
-      await fs.writeFile(filePath, input.content, { encoding });
-    }
-
-    const currentContent = input.append ? previousContent + input.content : input.content;
-    const currentHash = hashSha256(normalizeLineEndings(currentContent));
-    const bytesWritten = Buffer.byteLength(input.content, encoding);
-    const action = input.append ? "appended" : existed ? "overwritten" : "created";
-
-    // Compute structured diff for overwrites and appends (not new files)
-    let structuredPatchData: unknown[] | undefined;
-    if (existed) {
-      const patch = computePatch(filePath, filePath, previousContent, currentContent, "", "", {
-        context: 3,
-      });
-      structuredPatchData = patch.hunks;
-    }
-
-    recordFrgMutation(filePath, "write", currentContent);
-    recordSearchMutation(filePath, "write", currentContent);
-
-    return success(`Successfully ${action} ${filePath} (${bytesWritten} bytes written)`, {
-      filePath,
-      action,
-      existed,
-      bytesWritten,
-      previousHash,
-      currentHash,
-      ...(structuredPatchData ? { structuredPatch: structuredPatchData } : {}),
-    });
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}
-
-// ============================================================================
-// Edit File
-// ============================================================================
-
-export interface EditFileInput {
-  path: string;
-  oldText: string;
-  newText: string;
-  /** Replace all occurrences instead of just the first */
-  replaceAll?: boolean;
-  /**
-   * Optional replacement count assertion.
-   * When provided, the edit fails unless this exact number of replacements is applied.
-   */
-  expectedReplacements?: number;
-  /**
-   * Optional optimistic concurrency guard.
-   * If provided, edit only succeeds when current file content hash matches this value.
-   */
-  expectedHash?: string;
-}
-
-/**
- * Edits a file by replacing text.
- */
-export async function executeEditFile(input: EditFileInput, ctx: ToolContext): Promise<ToolResult> {
-  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
-  try {
-    // Validate oldText is not empty to prevent matching everywhere
-    if (input.oldText === "") {
-      return fail("oldText cannot be empty");
-    }
-    if (
-      input.expectedReplacements !== undefined &&
-      (!Number.isInteger(input.expectedReplacements) || input.expectedReplacements <= 0)
-    ) {
-      return fail("expectedReplacements must be a positive integer");
-    }
-    const expectedHash = input.expectedHash?.trim().toLowerCase();
-    if (expectedHash && !/^[a-f0-9]{64}$/.test(expectedHash)) {
-      return fail("expectedHash must be a 64-character lowercase/uppercase SHA-256 hex digest");
-    }
-    if (!input.replaceAll && (input.expectedReplacements ?? 1) > 1) {
-      return fail("expectedReplacements > 1 requires replaceAll=true");
-    }
-
-    const filePath = resolvePath(input.path, ctx);
-    const originalContent = await fs.readFile(filePath, "utf-8");
-    const originalNormalized = normalizeLineEndings(originalContent);
-    const currentHash = hashSha256(originalNormalized);
-    if (expectedHash && currentHash !== expectedHash) {
-      return fail(`Hash mismatch for ${filePath}: file changed since last read`, {
-        path: filePath,
-        expectedHash,
-        actualHash: currentHash,
-      });
-    }
-    const hadCRLF = originalContent.includes("\r\n");
-    const content = originalNormalized;
-    const oldText = normalizeLineEndings(input.oldText);
-    const newText = normalizeLineEndings(input.newText);
-
-    const strategies: Array<{ name: MatchStrategyName; ranges: TextRange[] }> = [
-      { name: "exact", ranges: findExactRanges(content, oldText) },
-      { name: "trimmed_line_block", ranges: findTrimmedLineBlockRanges(content, oldText) },
-      { name: "indentation_flexible", ranges: findIndentFlexibleRanges(content, oldText) },
-      { name: "whitespace_normalized", ranges: findWhitespaceNormalizedRanges(content, oldText) },
-    ];
-
-    const selected = strategies.find((entry) => entry.ranges.length > 0);
-    if (!selected) {
-      return fail(`Text not found in file after trying all strategies: "${input.oldText}"`);
-    }
-
-    const ranges = selected.ranges;
-    const selectedRanges = input.replaceAll ? ranges : [ranges[0]!];
-    const replacements = selectedRanges.length;
-    const expectedReplacements = input.expectedReplacements;
-
-    if (expectedReplacements !== undefined && replacements !== expectedReplacements) {
-      return fail(
-        `Replacement count mismatch: expected ${expectedReplacements}, would apply ${replacements}`,
-        {
-          path: filePath,
-          strategy: selected.name,
-          matchesFound: ranges.length,
-          replacements,
-          expectedReplacements,
-        },
-      );
-    }
-
-    let updated = applyRanges(content, selectedRanges, newText);
-
-    // Compute structured diff before CRLF restoration (both sides are LF-normalized)
-    const patch = computePatch(filePath, filePath, content, updated, "", "", { context: 3 });
-
-    if (hadCRLF) {
-      updated = updated.replace(/\n/g, "\r\n");
-    }
-
-    await fs.writeFile(filePath, updated, "utf-8");
-    recordFrgMutation(filePath, "write", updated);
-    recordSearchMutation(filePath, "write", updated);
-
-    return success(
-      `Edited ${filePath} using strategy=${selected.name} (${replacements} replacement(s))`,
-      {
-        filePath,
-        strategy: selected.name,
-        matchesFound: ranges.length,
-        replacements,
-        expectedReplacements,
-        replaceAll: input.replaceAll === true,
-        previousHash: currentHash,
-        currentHash: hashSha256(normalizeLineEndings(updated)),
-        structuredPatch: patch.hunks,
-      },
-    );
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}
-
-// ============================================================================
-// List Directory
-// ============================================================================
-
-export interface ListDirInput {
-  path?: string;
-  /** Include dotfiles and dot-directories */
-  all?: boolean;
-  /** Include detailed metadata fields */
-  long?: boolean;
-  /** Recursion depth: 1 lists immediate children, 2 includes grandchildren, etc. */
-  depth?: number;
-  /** Maximum number of entries to return */
-  limit?: number;
-  /** Number of entries to skip before returning */
-  offset?: number;
-  /** Glob patterns to ignore */
-  ignore?: string[];
-}
-
-/** Backward-compatible ls input alias. */
-export interface LsInput extends ListDirInput {}
-
-export interface LsEntry {
-  name: string;
-  type: "file" | "directory" | "symlink" | "other";
-  /** File size in bytes (present when long=true) */
-  size?: number;
-  /** POSIX mode bits as a zero-padded octal string, e.g. "644" */
-  mode?: string;
-  /** Last modified time in epoch milliseconds (integer, present when long=true) */
-  mtimeMs?: number;
-  /** Last modified time as ISO-8601 string (present when long=true) */
-  modifiedAt?: string;
-}
-
-export interface ListDirEntry extends LsEntry {
-  /** Relative path from listing root */
-  path: string;
-  /** Depth from listing root where 1 is an immediate child */
-  depth: number;
-}
-
-export interface ListDirOutput {
-  path: string;
-  depth: number;
-  limit: number;
-  offset: number;
-  ignore: string[];
-  truncated: boolean;
-  total: number;
-  entries: ListDirEntry[];
-}
-
-function getStatType(stat: fsSync.Stats): LsEntry["type"] {
-  if (stat.isFile()) return "file";
-  if (stat.isDirectory()) return "directory";
-  if (stat.isSymbolicLink()) return "symlink";
-  return "other";
-}
-
-function getErrorCode(err: unknown): string | undefined {
-  if (typeof err !== "object" || err === null) return undefined;
-  const withCode = err as { code?: unknown };
-  return typeof withCode.code === "string" ? withCode.code : undefined;
-}
-
-export const LS_INTERNALS = {
-  async readType(entryPath: string): Promise<LsEntry["type"]> {
-    const stat = await fs.lstat(entryPath);
-    return getStatType(stat);
-  },
-  async readMetadata(
-    entryPath: string,
-  ): Promise<Required<Pick<LsEntry, "size" | "mode" | "mtimeMs" | "modifiedAt">>> {
-    const stat = await fs.lstat(entryPath);
-    return {
-      size: stat.size,
-      mode: (stat.mode & 0o777).toString(8).padStart(3, "0"),
-      mtimeMs: Math.trunc(stat.mtimeMs),
-      modifiedAt: stat.mtime.toISOString(),
-    };
-  },
-};
-
-function normalizeNonNegativeInteger(value: number | undefined, fallback: number): number {
-  if (value === undefined) return fallback;
-  if (!Number.isFinite(value)) return fallback;
-  if (value <= 0) return 0;
-  return Math.floor(value);
-}
-
-function getEntryDepth(relativePath: string): number {
-  return relativePath.split("/").filter(Boolean).length;
-}
-
-function insertRetainedPath(retained: string[], candidate: string, maxEntries: number): void {
-  if (maxEntries <= 0) return;
-  if (retained.length < maxEntries) {
-    retained.push(candidate);
-    return;
-  }
-
-  let maxIndex = 0;
-  for (let i = 1; i < retained.length; i++) {
-    if (retained[i]!.localeCompare(retained[maxIndex]!) > 0) {
-      maxIndex = i;
-    }
-  }
-
-  if (candidate.localeCompare(retained[maxIndex]!) < 0) {
-    retained[maxIndex] = candidate;
-  }
-}
-
-/**
- * List files and directories with structured metadata.
- */
-export async function executeLs(input: ListDirInput, ctx: ToolContext): Promise<ToolResult> {
-  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
-  try {
-    const dirPath = resolvePath(input.path ?? ".", ctx);
-    const dirStat = await fs.stat(dirPath);
-    if (!dirStat.isDirectory()) {
-      return fail(`Path is not a directory: ${dirPath}`);
-    }
-
-    const includeAll = input.all === true;
-    const includeLong = input.long === true;
-    const depth = normalizeNonNegativeInteger(input.depth, 1);
-    const offset = normalizeNonNegativeInteger(input.offset, 0);
-    const ignore = (input.ignore ?? []).filter((pattern) => pattern.trim() !== "");
-
-    const requestedLimit =
-      input.limit !== undefined ? normalizeNonNegativeInteger(input.limit, 0) : null;
-    const retainedRelativePaths: string[] = [];
-    let total = 0;
-
-    for (const relativePath of await fastGlob.glob("**/*", {
-      cwd: dirPath,
-      onlyFiles: false,
-      absolute: false,
-      dot: includeAll,
-      deep: depth,
-      ignore: ignore.length > 0 ? ignore : undefined,
-    })) {
-      total++;
-      if (requestedLimit === null) {
-        retainedRelativePaths.push(relativePath);
-        continue;
-      }
-      insertRetainedPath(retainedRelativePaths, relativePath, offset + requestedLimit);
-    }
-
-    retainedRelativePaths.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-    const limit = requestedLimit === null ? Math.max(total - offset, 0) : requestedLimit;
-    const pageRelativePaths = retainedRelativePaths.slice(offset, offset + limit);
-    const truncated = offset + limit < total;
-
-    const pageEntries: ListDirEntry[] = [];
-    for (const relativePath of pageRelativePaths) {
-      const entryPath = nodePath.join(dirPath, relativePath);
-      const name = nodePath.basename(relativePath);
-      const entryDepth = getEntryDepth(relativePath);
-      try {
-        const type = await LS_INTERNALS.readType(entryPath);
-        pageEntries.push({
-          name,
-          path: relativePath,
-          depth: entryDepth,
-          type,
-        });
-      } catch (err) {
-        const code = getErrorCode(err);
-        // Entry may disappear between glob traversal and metadata reads.
-        if (code === "ENOENT" || code === "ENOTDIR") {
-          continue;
-        }
-        // Keep listing useful even if one entry cannot be typed.
-        pageEntries.push({
-          name,
-          path: relativePath,
-          depth: entryDepth,
-          type: "other",
-        });
-      }
-    }
-
-    let entries: ListDirEntry[];
-    if (includeLong) {
-      // Use sequential metadata reads to avoid EMFILE in large directories.
-      // Any per-entry metadata failure should not fail the whole listing.
-      entries = [];
-      for (const entry of pageEntries) {
-        const entryPath = nodePath.join(dirPath, entry.path);
-        try {
-          const metadata = await LS_INTERNALS.readMetadata(entryPath);
-          entries.push({
-            ...entry,
-            ...metadata,
-          });
-        } catch (err) {
-          const code = getErrorCode(err);
-          // File may disappear between readdir and lstat; skip stale entries.
-          if (code === "ENOENT" || code === "ENOTDIR") {
-            continue;
-          }
-          // Keep listing useful even if one entry's metadata cannot be read.
-          entries.push(entry);
-        }
-      }
-    } else {
-      entries = pageEntries;
-    }
-
-    const output: ListDirOutput = {
-      path: dirPath,
-      depth,
-      limit,
-      offset,
-      ignore,
-      truncated,
-      total,
-      entries,
-    };
-
-    const truncationNote = truncated ? " (truncated)" : "";
-    return success(`Listed ${entries.length} entries in ${dirPath}${truncationNote}`, output);
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}
-
-// ============================================================================
-// Glob
-// ============================================================================
-
-export interface GlobInput {
-  pattern: string;
-  /** Working directory for the glob */
-  cwd?: string;
-  /** Patterns to ignore */
-  ignore?: string[];
-}
-
-/**
- * Finds files matching a glob pattern.
- */
-export async function executeGlob(input: GlobInput, ctx: ToolContext): Promise<ToolResult> {
-  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
-  try {
-    const cwd = input.cwd ? resolvePath(input.cwd, ctx) : ctx.workingDir;
-
-    const files = await fastGlob.glob(input.pattern, {
-      cwd,
-      onlyFiles: true,
-      absolute: false,
-      ignore: input.ignore,
-    });
-
-    const truncated = files.length > FILESYSTEM_OUTPUT_LIMITS.MAX_GLOB_RESULTS;
-    const cappedFiles = truncated
-      ? files.slice(0, FILESYSTEM_OUTPUT_LIMITS.MAX_GLOB_RESULTS)
-      : files;
-    const suffix = truncated ? ` (truncated to ${cappedFiles.length})` : "";
-
-    return success(`Found ${files.length} files matching ${input.pattern}${suffix}`, cappedFiles);
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}
-
-// ============================================================================
-// Grep
-// ============================================================================
-
-export interface GrepInput {
-  pattern: string;
-  path?: string;
-  /** Glob pattern to filter files */
-  glob?: string;
-  /** Case insensitive search */
-  ignoreCase?: boolean;
-}
-
-export interface GrepMatch {
-  file: string;
-  line: number;
-  content: string;
-}
-
-const MAX_GREP_PATTERN_LENGTH = 512;
-const MAX_GREP_QUANTIFIERS = 64;
-const BACKREFERENCE_RE = /\\[1-9][0-9]*/;
-const NESTED_QUANTIFIER_RE =
-  /\((?:\?:)?(?:[^()\\]|\\.)*(?:\+|\*|\{\d+(?:,\d*)?\})(?:[^()\\]|\\.)*\)(?:\+|\*|\{\d+(?:,\d*)?\})/;
-const NESTED_WILDCARD_RE =
-  /\((?:\?:)?(?:[^()\\]|\\.)*\.(?:\+|\*|\{\d+(?:,\d*)?\})(?:[^()\\]|\\.)*\)(?:\+|\*|\{\d+(?:,\d*)?\})/;
-const LOOKAROUND_RE = /\(\?(?:=|!|<=|<!)/;
-const REPEATED_SIMPLE_GROUP_RE = /\((?:\?:)?((?:[^()\\]|\\.)+)\)(?:\+|\*|\{\d+(?:,\d*)?\})/g;
-const UNESCAPED_QUANTIFIER_TOKEN_RE = /(^|[^\\])(?:\*|\+|\?|\{\d+(?:,\d*)?\})/;
-
-function splitTopLevelAlternatives(groupSource: string): string[] {
-  const parts: string[] = [];
-  let current = "";
-  let escaped = false;
-  let inClass = false;
-  let depth = 0;
-
-  for (let i = 0; i < groupSource.length; i++) {
-    const ch = groupSource[i]!;
-
-    if (escaped) {
-      current += ch;
-      escaped = false;
-      continue;
-    }
-
-    if (ch === "\\") {
-      current += ch;
-      escaped = true;
-      continue;
-    }
-
-    if (inClass) {
-      current += ch;
-      if (ch === "]") {
-        inClass = false;
-      }
-      continue;
-    }
-
-    if (ch === "[") {
-      inClass = true;
-      current += ch;
-      continue;
-    }
-
-    if (ch === "(") {
-      depth++;
-      current += ch;
-      continue;
-    }
-
-    if (ch === ")" && depth > 0) {
-      depth--;
-      current += ch;
-      continue;
-    }
-
-    if (ch === "|" && depth === 0) {
-      parts.push(current);
-      current = "";
-      continue;
-    }
-
-    current += ch;
-  }
-
-  parts.push(current);
-  return parts;
-}
-
-function normalizeAlternative(raw: string): string {
-  return raw
-    .replace(/\\./g, "x")
-    .replace(/\[[^\]]*\]/g, "x")
-    .replace(/[\^\$]/g, "")
-    .replace(/(^|[^\\])(?:\*|\+|\?|\{\d+(?:,\d*)?\})/g, "$1");
-}
-
-function hasAmbiguousRepeatedAlternation(pattern: string): boolean {
-  for (const match of pattern.matchAll(new RegExp(REPEATED_SIMPLE_GROUP_RE.source, "g"))) {
-    const groupSource = match[1];
-    if (!groupSource || !groupSource.includes("|")) continue;
-
-    const alternatives = splitTopLevelAlternatives(groupSource);
-    if (alternatives.length < 2) continue;
-    if (alternatives.some((alt) => alt.length === 0)) {
-      return true;
-    }
-
-    // Quantified alternatives inside an already repeated group are common
-    // catastrophic-backtracking shapes ((a+|aa)+, (a?|aa)+, etc.).
-    if (alternatives.some((alt) => UNESCAPED_QUANTIFIER_TOKEN_RE.test(alt))) {
-      return true;
-    }
-
-    const normalized = alternatives.map(normalizeAlternative);
-    for (let i = 0; i < normalized.length; i++) {
-      for (let j = i + 1; j < normalized.length; j++) {
-        const left = normalized[i]!;
-        const right = normalized[j]!;
-        if (!left || !right) {
-          return true;
-        }
-        if (left.startsWith(right) || right.startsWith(left)) {
-          return true;
-        }
-      }
-    }
-  }
-  return false;
-}
-
-function countUnescapedQuantifiers(pattern: string): number {
-  return [...pattern.matchAll(/(^|[^\\])(?:\*|\+|\?|\{\d+(?:,\d*)?\})/g)].length;
-}
-
-function getUnsafeRegexReason(pattern: string): string | null {
-  if (pattern.length > MAX_GREP_PATTERN_LENGTH) {
-    return `pattern length exceeds ${MAX_GREP_PATTERN_LENGTH} characters`;
-  }
-  if (LOOKAROUND_RE.test(pattern)) {
-    return "lookaround assertions are not allowed";
-  }
-  if (BACKREFERENCE_RE.test(pattern)) {
-    return "backreferences are not allowed";
-  }
-  if (countUnescapedQuantifiers(pattern) > MAX_GREP_QUANTIFIERS) {
-    return `pattern uses too many quantifiers (max ${MAX_GREP_QUANTIFIERS})`;
-  }
-  if (NESTED_QUANTIFIER_RE.test(pattern) || NESTED_WILDCARD_RE.test(pattern)) {
-    return "nested quantifiers are not allowed";
-  }
-  if (hasAmbiguousRepeatedAlternation(pattern)) {
-    return "ambiguous alternation inside repeated groups is not allowed";
-  }
-  return null;
-}
-
-/**
- * Searches for a pattern in files.
- */
-export async function executeGrep(input: GrepInput, ctx: ToolContext): Promise<ToolResult> {
-  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
-  try {
-    const unsafeReason = getUnsafeRegexReason(input.pattern);
-    if (unsafeReason) {
-      return fail(`Unsafe regular expression rejected: ${unsafeReason}`);
-    }
-
-    // Validate regex
-    let regex: RegExp;
-    try {
-      regex = new RegExp(input.pattern, input.ignoreCase ? "gi" : "g");
-    } catch {
-      return fail(`Invalid regular expression: ${input.pattern}`);
-    }
-
-    const targetPath = resolvePath(input.path ?? ".", ctx);
-    const stat = await fs.stat(targetPath);
-
-    const matches: GrepMatch[] = [];
-    const errors: string[] = [];
-    let truncated = false;
-
-    if (stat.isDirectory()) {
-      // Search in directory
-      const globPattern = input.glob ?? "**/*";
-      const files = await fastGlob.glob(globPattern, {
-        cwd: targetPath,
-        onlyFiles: true,
-        absolute: true,
-      });
-
-      for (const file of files) {
-        if (matches.length >= FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_MATCHES) {
-          truncated = true;
-          break;
-        }
-        const remaining = FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_MATCHES - matches.length;
-        const result = await searchInFile(file, regex, remaining);
-        matches.push(...result.matches);
-        if (result.truncated) {
-          truncated = true;
-        }
-        if (result.error) {
-          if (errors.length < FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_ERRORS) {
-            errors.push(result.error);
-          }
-        }
-        if (truncated) {
-          break;
-        }
-      }
-    } else {
-      // Search in single file
-      const result = await searchInFile(
-        targetPath,
-        regex,
-        FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_MATCHES,
-      );
-      matches.push(...result.matches);
-      if (result.truncated) {
-        truncated = true;
-      }
-      if (result.error) {
-        if (errors.length < FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_ERRORS) {
-          errors.push(result.error);
-        }
-      }
-    }
-
-    // Return matches with optional errors array for visibility
-    // Note: errors are logged but don't fail the overall search
-    const suffix = truncated ? ` (truncated to ${matches.length})` : "";
-    return success(`Found ${matches.length} matches for pattern "${input.pattern}"${suffix}`, {
-      matches,
-      errors: errors.length > 0 ? errors : undefined,
-      truncated,
-    });
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}
-
-/**
- * Result from searching a single file - may include errors for files that couldn't be read.
- */
-interface SearchFileResult {
-  matches: GrepMatch[];
-  error?: string;
-  truncated?: boolean;
-}
-
-/**
- * Searches for a regex pattern in a single file.
- * Uses string.match() instead of regex.test() to avoid global regex lastIndex issues.
- */
-async function searchInFile(
-  filePath: string,
-  regex: RegExp,
-  maxMatches: number,
-): Promise<SearchFileResult> {
-  const matches: GrepMatch[] = [];
-  let skippedLongLine = false;
-  if (maxMatches <= 0) {
-    return { matches, truncated: true };
-  }
-
-  try {
-    const stat = await fs.stat(filePath);
-    if (stat.size > FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_FILE_BYTES) {
-      return {
-        matches: [],
-        error: `Skipped file ${filePath}: exceeds ${FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_FILE_BYTES} bytes`,
-      };
-    }
-
-    // Create a non-global version for testing to avoid lastIndex issues
-    const testRegex = new RegExp(regex.source, regex.flags.replace("g", ""));
-    const input = fsSync.createReadStream(filePath, { encoding: "utf8" });
-    const lines = readline.createInterface({ input, crlfDelay: Infinity });
-    let lineNumber = 0;
-
-    try {
-      for await (const line of lines) {
-        lineNumber++;
-        const lineBytes = Buffer.byteLength(line, "utf8");
-        if (lineBytes > FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_LINE_BYTES) {
-          skippedLongLine = true;
-          continue;
-        }
-        if (!testRegex.test(line)) {
-          continue;
-        }
-        matches.push({
-          file: filePath,
-          line: lineNumber,
-          content: line,
-        });
-        if (matches.length >= maxMatches) {
-          lines.close();
-          input.destroy();
-          return { matches, truncated: true };
-        }
-      }
-      if (skippedLongLine) {
-        return {
-          matches,
-          error: `Skipped lines longer than ${FILESYSTEM_OUTPUT_LIMITS.MAX_GREP_LINE_BYTES} bytes in ${filePath}`,
-        };
-      }
-      return { matches };
-    } finally {
-      lines.close();
-      input.destroy();
-    }
-  } catch (err) {
-    // Return error info for files that can't be read (binary, permissions, etc.)
-    // This allows callers to decide whether to log or surface these errors
-    return {
-      matches: [],
-      error: `Could not read file ${filePath}: ${getErrorMessage(err)}`,
-    };
-  }
-}