@aria-cli/tools 1.0.12 → 1.0.14

package/dist/executors/filesystem.js

@@ -1,1122 +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 { 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 = {
-    ".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,
-};
-/**
- * Normalize common aliases before passing encodings to Node fs APIs.
- */
-const SUPPORTED_ENCODINGS = new Set([
-    "utf8",
-    "utf16le",
-    "latin1",
-    "ascii",
-    "base64",
-    "base64url",
-    "hex",
-    "ucs2",
-    "binary",
-]);
-function normalizeEncoding(inputEncoding) {
-    if (!inputEncoding)
-        return "utf8";
-    const normalized = inputEncoding.toLowerCase();
-    const canonical = normalized === "utf-8" ? "utf8" : normalized;
-    if (!SUPPORTED_ENCODINGS.has(canonical)) {
-        throw new Error(`Unsupported encoding: ${inputEncoding}`);
-    }
-    return canonical;
-}
-/**
- * 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, realHome) {
-    // 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, ctx) {
-    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) {
-    return text.replace(/\r\n/g, "\n");
-}
-function hashSha256(text) {
-    return crypto.createHash("sha256").update(text, "utf8").digest("hex");
-}
-function splitLinesWithoutTrailingEmpty(content) {
-    const lines = content.split("\n");
-    if (content.endsWith("\n") && lines.length > 0 && lines[lines.length - 1] === "") {
-        lines.pop();
-    }
-    return lines;
-}
-function getReadWindow(content, offset, limit) {
-    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 = [];
-    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, encoding, offset, limit) {
-    const startLine = Math.max(0, offset);
-    const maxLines = Math.max(1, limit);
-    const visible = [];
-    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,
-    };
-}
-function dedupeRanges(ranges) {
-    const seen = new Set();
-    const result = [];
-    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) {
-    const match = line.match(/^[\t ]*/);
-    return match ? match[0].length : 0;
-}
-function stripCommonIndent(lines) {
-    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) {
-    const starts = [0];
-    for (let i = 0; i < content.length; i++) {
-        if (content[i] === "\n") {
-            starts.push(i + 1);
-        }
-    }
-    return starts;
-}
-function normalizeSearchLines(raw) {
-    const lines = [...raw];
-    if (lines.length > 0 && lines[lines.length - 1] === "") {
-        lines.pop();
-    }
-    return lines;
-}
-function getLineWindowRanges(content, oldText, predicate) {
-    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 = [];
-    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, oldText) {
-    if (oldText.length === 0)
-        return [];
-    const ranges = [];
-    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, oldText) {
-    const trimmedNeedle = oldText.trim();
-    if (trimmedNeedle.length === 0)
-        return [];
-    if (!oldText.includes("\n")) {
-        const lines = content.split("\n");
-        const starts = lineStartOffsets(content);
-        const ranges = [];
-        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, oldText) {
-    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) {
-    return line.trim().replace(/\s+/g, " ");
-}
-function findWhitespaceNormalizedRanges(content, oldText) {
-    if (!oldText.includes("\n")) {
-        const needle = normalizeWhitespace(oldText);
-        if (!needle)
-            return [];
-        const lines = content.split("\n");
-        const starts = lineStartOffsets(content);
-        const ranges = [];
-        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, ranges, replacement) {
-    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;
-}
-/**
- * Reads a file's contents.
- */
-export async function executeReadFile(input, ctx) {
-    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;
-        let returnedContent;
-        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));
-    }
-}
-/**
- * Writes content to a file.
- */
-export async function executeWriteFile(input, ctx) {
-    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?.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;
-        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));
-    }
-}
-/**
- * Edits a file by replacing text.
- */
-export async function executeEditFile(input, ctx) {
-    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 = [
-            { 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));
-    }
-}
-function getStatType(stat) {
-    if (stat.isFile())
-        return "file";
-    if (stat.isDirectory())
-        return "directory";
-    if (stat.isSymbolicLink())
-        return "symlink";
-    return "other";
-}
-function getErrorCode(err) {
-    if (typeof err !== "object" || err === null)
-        return undefined;
-    const withCode = err;
-    return typeof withCode.code === "string" ? withCode.code : undefined;
-}
-export const LS_INTERNALS = {
-    async readType(entryPath) {
-        const stat = await fs.lstat(entryPath);
-        return getStatType(stat);
-    },
-    async readMetadata(entryPath) {
-        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, fallback) {
-    if (value === undefined)
-        return fallback;
-    if (!Number.isFinite(value))
-        return fallback;
-    if (value <= 0)
-        return 0;
-    return Math.floor(value);
-}
-function getEntryDepth(relativePath) {
-    return relativePath.split("/").filter(Boolean).length;
-}
-function insertRetainedPath(retained, candidate, maxEntries) {
-    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, ctx) {
-    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 = [];
-        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 = [];
-        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;
-        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 = {
-            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));
-    }
-}
-/**
- * Finds files matching a glob pattern.
- */
-export async function executeGlob(input, ctx) {
-    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));
-    }
-}
-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) {
-    const parts = [];
-    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) {
-    return raw
-        .replace(/\\./g, "x")
-        .replace(/\[[^\]]*\]/g, "x")
-        .replace(/[\^\$]/g, "")
-        .replace(/(^|[^\\])(?:\*|\+|\?|\{\d+(?:,\d*)?\})/g, "$1");
-}
-function hasAmbiguousRepeatedAlternation(pattern) {
-    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) {
-    return [...pattern.matchAll(/(^|[^\\])(?:\*|\+|\?|\{\d+(?:,\d*)?\})/g)].length;
-}
-function getUnsafeRegexReason(pattern) {
-    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, ctx) {
-    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;
-        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 = [];
-        const errors = [];
-        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));
-    }
-}
-/**
- * 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, regex, maxMatches) {
-    const matches = [];
-    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)}`,
-        };
-    }
-}