mcp-fs-shell-windows 0.2.7 → 0.2.19

package/dist/delete_files_by_pattern/handler.js

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPath, stripLongPathAll } from "../helpers/path.js";
 export async function handleDeleteFilesByPattern(directory, pattern, includeDirectories, allowedDirectories) {
     const validPath = await validatePath(directory, allowedDirectories);
     let regex;
@@ -21,23 +21,23 @@ export async function handleDeleteFilesByPattern(directory, pattern, includeDire
             if (entry.isDirectory()) {
                 if (includeDirectories) {
                     await fs.rm(fullPath, { recursive: true, force: true });
-                    deleted.push(`${fullPath} (directory)`);
+                    deleted.push(`${stripLongPath(fullPath)} (directory)`);
                 }
                 else {
-                    skipped.push(`${fullPath} (directory; set includeDirectories: true to delete)`);
+                    skipped.push(`${stripLongPath(fullPath)} (directory; set includeDirectories: true to delete)`);
                 }
             }
             else {
                 await fs.unlink(fullPath);
-                deleted.push(fullPath);
+                deleted.push(stripLongPath(fullPath));
             }
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            skipped.push(`${fullPath} (${errorMessage})`);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
+            skipped.push(`${stripLongPath(fullPath)} (${errorMessage})`);
         }
     }
-    let output = `Pattern "${pattern}" in ${validPath}:\n`;
+    let output = `Pattern "${pattern}" in ${stripLongPath(validPath)}:\n`;
     output += `- ${deleted.length} deleted\n`;
     if (skipped.length > 0) {
         output += `- ${skipped.length} skipped:\n` + skipped.map((s) => `  ${s}`).join("\n");

package/dist/dir_diff/handler.js

@@ -0,0 +1,155 @@
+import fs from "fs/promises";
+import { createReadStream } from "fs";
+import { createHash } from "crypto";
+import path from "path";
+import { validatePath } from "../helpers/path.js";
+import { minimatch } from "minimatch";
+import { createUnifiedDiff } from "../helpers/diff.js";
+const TEXT_SIZE_LIMIT = 1024 * 1024; // 1 MiB
+const NUL_SCAN_LIMIT = 8192; // 8 KiB
+// Same minimatch machinery/options as list_directory's ignore param, but
+// matched against the file's relative path (forward slashes).
+function isIgnored(relPath, ignore) {
+    if (ignore.length === 0)
+        return false;
+    return ignore.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+}
+async function walkTree(root, ignore) {
+    const files = new Map();
+    async function visit(abs, rel) {
+        let entries;
+        try {
+            entries = await fs.readdir(abs, { withFileTypes: true });
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return;
+            throw error;
+        }
+        // Deterministic traversal order
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const relPath = rel === "" ? entry.name : `${rel}/${entry.name}`;
+            if (isIgnored(relPath, ignore))
+                continue;
+            const absPath = path.join(abs, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absPath, relPath);
+            }
+            else if (entry.isFile()) {
+                const stats = await fs.stat(absPath);
+                files.set(relPath, { abs: absPath, size: stats.size });
+            }
+        }
+    }
+    await visit(root, "");
+    return files;
+}
+function sha256File(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolve(hash.digest("hex")));
+        stream.on("error", reject);
+    });
+}
+async function looksLikeText(filePath, size) {
+    if (size > TEXT_SIZE_LIMIT)
+        return false;
+    if (size === 0)
+        return true;
+    const scanLength = Math.min(size, NUL_SCAN_LIMIT);
+    const buffer = Buffer.alloc(scanLength);
+    const handle = await fs.open(filePath, "r");
+    try {
+        await handle.read(buffer, 0, scanLength, 0);
+    }
+    finally {
+        await handle.close();
+    }
+    return buffer.indexOf(0) === -1;
+}
+export async function handleDirDiff(dirA, dirB, ignore, maxFiles, allowedDirectories) {
+    const validA = await validatePath(dirA, allowedDirectories);
+    const validB = await validatePath(dirB, allowedDirectories);
+    for (const [original, valid] of [
+        [dirA, validA],
+        [dirB, validB],
+    ]) {
+        let stats;
+        try {
+            stats = await fs.stat(valid);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT") {
+                throw new Error(`Directory does not exist: ${original}`);
+            }
+            throw error;
+        }
+        if (!stats.isDirectory()) {
+            throw new Error(`Not a directory: ${original}`);
+        }
+    }
+    const filesA = await walkTree(validA, ignore);
+    const filesB = await walkTree(validB, ignore);
+    const union = Array.from(new Set([...filesA.keys(), ...filesB.keys()])).sort();
+    let truncated = false;
+    let comparePaths = union;
+    if (maxFiles !== undefined && union.length > maxFiles) {
+        comparePaths = union.slice(0, maxFiles);
+        truncated = true;
+    }
+    const added = [];
+    const removed = [];
+    const changed = [];
+    let identical = 0;
+    for (const relPath of comparePaths) {
+        const a = filesA.get(relPath);
+        const b = filesB.get(relPath);
+        if (!a || !b) {
+            if (a && !b) {
+                removed.push({ path: relPath, size: a.size });
+            }
+            else if (b && !a) {
+                added.push({ path: relPath, size: b.size });
+            }
+            continue;
+        }
+        // Present in both: decide by size first, then sha256.
+        const sizeA = a.size;
+        const sizeB = b.size;
+        const shaA = await sha256File(a.abs);
+        const shaB = await sha256File(b.abs);
+        if (sizeA === sizeB && shaA === shaB) {
+            identical++;
+            continue;
+        }
+        const entry = { path: relPath, sizeA, sizeB, shaA, shaB };
+        // Attach a unified diff when BOTH sides look like text.
+        if (sizeA <= TEXT_SIZE_LIMIT &&
+            sizeB <= TEXT_SIZE_LIMIT &&
+            (await looksLikeText(a.abs, sizeA)) &&
+            (await looksLikeText(b.abs, sizeB))) {
+            const textA = await fs.readFile(a.abs, "utf8");
+            const textB = await fs.readFile(b.abs, "utf8");
+            entry.diff = createUnifiedDiff(textA, textB, relPath, relPath);
+        }
+        changed.push(entry);
+    }
+    return JSON.stringify({
+        added,
+        removed,
+        changed,
+        counts: {
+            added: added.length,
+            removed: removed.length,
+            changed: changed.length,
+            identical,
+            compared: comparePaths.length,
+        },
+        truncated,
+    }, null, 2);
+}

package/dist/dir_diff/schema.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const DirDiffArgsSchema = z.object({
+    dirA: z.string().describe("First directory (baseline). Files present only here are reported as removed."),
+    dirB: z.string().describe("Second directory (comparison target). Files present only here are reported as added."),
+    ignore: z.array(z.string()).optional().default([]).describe("Glob patterns (minimatch, same semantics as list_directory's ignore param) matched against each file's relative path; ignored paths are excluded from all lists and counts."),
+    maxFiles: z.number().int().min(1).optional().describe("Cap on total files compared (union of both trees, after ignore). If the union exceeds it, the comparison stops and truncated=true; counts reflect only what was compared."),
+});

package/dist/directory_tree/helpers.js

@@ -30,16 +30,16 @@ export async function buildDirectoryTree(currentPath, rootPath, excludePatterns
         if (shouldExclude) {
             continue;
         }
+        // Links (junctions/symlinks) are reported as type 'link' and never
+        // recursed into, so their targets are never traversed.
         const entryData = {
             name: entry.name,
-            type: entry.isDirectory() ? 'directory' : 'file'
+            type: entry.isSymbolicLink() ? 'link' : entry.isDirectory() ? 'directory' : 'file'
         };
         if (entry.isDirectory()) {
+            // Empty directories stay in the tree (children: []) - only EXCLUDED
+            // entries are skipped.
             entryData.children = await buildDirectoryTree(entryPath, rootPath, excludePatterns, allowedDirectories);
-            // Skip empty directories after exclusion
-            if (entryData.children.length === 0) {
-                continue;
-            }
         }
         result.push(entryData);
     }

package/dist/edit_files/handler.js

@@ -1,5 +1,5 @@
 import fs from "fs/promises";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
 // Detect the dominant line ending of a file so it can be preserved on write.
 function detectEol(text) {
     if (text.includes("\r\n"))
@@ -42,7 +42,7 @@ export async function handleEditFiles(files, allowedDirectories) {
             results.push(`File: ${file.path}\n${editLog.join("\n")}`);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             errors.push(`Failed to edit ${file.path}: ${errorMessage}`);
         }
     }

package/dist/file_diff/handler.js

@@ -1,5 +1,5 @@
 import fs from "fs/promises";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
 import { createUnifiedDiff } from "../helpers/diff.js";
 export async function handleFileDiff(file1Path, file2Path, allowedDirectories) {
     const validFile1Path = await validatePath(file1Path, allowedDirectories);
@@ -22,7 +22,7 @@ export async function handleFileDiff(file1Path, file2Path, allowedDirectories) {
         return formattedDiff;
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
         throw new Error(`Error comparing files: ${errorMessage}`);
     }
 }

package/dist/file_info/handler.js

@@ -1,5 +1,33 @@
 import fs from "fs/promises";
-import { validatePath } from "../helpers/path.js";
+import { execFile } from "child_process";
+import { validatePathPreservingLinks } from "../helpers/path.js";
+// Best-effort NTFS attribute list (e.g. "Archive", "ReadOnly, Hidden") via a
+// single encoded PowerShell call. The command string is built in JS with the
+// path single-quote-escaped and then encoded as UTF-16LE Base64 for
+// -EncodedCommand, which avoids all argv quoting/Unicode issues. Resolves
+// null on any failure (missing powershell, timeout, bad path, ...).
+function getWindowsAttributes(filePath) {
+    return new Promise((resolve) => {
+        let b64;
+        try {
+            const escaped = filePath.replace(/'/g, "''");
+            const command = `(Get-Item -LiteralPath '${escaped}' -Force).Attributes.ToString()`;
+            b64 = Buffer.from(command, "utf16le").toString("base64");
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        execFile("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-EncodedCommand", b64], { timeout: 10000, windowsHide: true }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const text = stdout.trim();
+            resolve(text.length > 0 ? text : null);
+        });
+    });
+}
 export async function getFileStats(filePath) {
     const stats = await fs.stat(filePath);
     return {
@@ -13,8 +41,9 @@ export async function getFileStats(filePath) {
     };
 }
 export async function handleGetFileInfo(filePath, allowedDirectories) {
-    const validPath = await validatePath(filePath, allowedDirectories);
+    const validPath = await validatePathPreservingLinks(filePath, allowedDirectories);
     const stats = await fs.stat(validPath);
+    const linkStats = await fs.lstat(validPath);
     const formattedInfo = {
         path: filePath,
         size: `${stats.size} bytes`,
@@ -22,8 +51,15 @@ export async function handleGetFileInfo(filePath, allowedDirectories) {
         created: stats.birthtime.toISOString(),
         modified: stats.mtime.toISOString(),
         accessed: stats.atime.toISOString(),
-        permissions: stats.mode.toString(8).slice(-3)
+        permissions: stats.mode.toString(8).slice(-3),
+        isReparsePoint: String(linkStats.isSymbolicLink())
     };
+    if (process.platform === "win32") {
+        const attributes = await getWindowsAttributes(validPath);
+        if (attributes !== null) {
+            formattedInfo.attributes = attributes;
+        }
+    }
     return Object.entries(formattedInfo)
         .map(([key, value]) => `${key}: ${value}`)
         .join("\n");

package/dist/fuzzy_find_files/handler.js

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPath } from "../helpers/path.js";
 function levenshtein(a, b) {
     if (a === b)
         return 0;
@@ -68,7 +68,7 @@ export async function handleFuzzyFindFiles(query, searchPath, recursive, maxResu
     }
     let output = `Top ${top.length} fuzzy matches for "${query}" (scanned ${scanned} entries${truncated ? ", stopped at scan limit" : ""}):\n`;
     top.forEach((c, i) => {
-        output += `${i + 1}. (distance ${c.distance}) ${c.path}\n`;
+        output += `${i + 1}. (distance ${c.distance}) ${stripLongPath(c.path)}\n`;
     });
     return output;
 }

package/dist/helpers/encoding.js

@@ -0,0 +1,154 @@
+// Text-encoding support for the fork's text tools: detection, decode, and
+// encode for utf8, utf16le, utf16be, and cp1252.
+export const TEXT_ENCODINGS = [
+    "utf8",
+    "utf16le",
+    "utf16be",
+    "cp1252",
+];
+const BOM_UTF8 = [0xef, 0xbb, 0xbf];
+const BOM_UTF16LE = [0xff, 0xfe];
+const BOM_UTF16BE = [0xfe, 0xff];
+function startsWithBytes(buf, sig) {
+    if (buf.length < sig.length)
+        return false;
+    for (let i = 0; i < sig.length; i++) {
+        if (buf[i] !== sig[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Detect the text encoding of a raw buffer:
+ *   BOM FF FE    -> utf16le
+ *   BOM FE FF    -> utf16be
+ *   BOM EF BB BF -> utf8 (the BOM is stripped at decode time)
+ *   otherwise, if the buffer decodes as STRICT UTF-8 (no invalid sequences
+ *   and no U+FFFD replacement characters) -> utf8
+ *   otherwise -> cp1252 (cp1252 accepts any byte value, so it is the fallback)
+ */
+export function detectEncoding(buf) {
+    if (startsWithBytes(buf, BOM_UTF16LE))
+        return "utf16le";
+    if (startsWithBytes(buf, BOM_UTF16BE))
+        return "utf16be";
+    if (startsWithBytes(buf, BOM_UTF8))
+        return "utf8";
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+        if (text.includes("\uFFFD"))
+            return "cp1252";
+        return "utf8";
+    }
+    catch {
+        return "cp1252";
+    }
+}
+/**
+ * Decode a raw buffer with the given encoding, stripping a BOM matching that
+ * encoding when present (EF BB BF for utf8, FF FE for utf16le, FE FF for utf16be).
+ */
+export function decodeText(buf, encoding) {
+    let b = buf;
+    if (encoding === "utf8") {
+        if (startsWithBytes(b, BOM_UTF8))
+            b = b.subarray(3);
+        return new TextDecoder("utf-8").decode(b);
+    }
+    if (encoding === "utf16le") {
+        if (startsWithBytes(b, BOM_UTF16LE))
+            b = b.subarray(2);
+        return new TextDecoder("utf-16le").decode(b);
+    }
+    if (encoding === "utf16be") {
+        if (startsWithBytes(b, BOM_UTF16BE))
+            b = b.subarray(2);
+        // Decode by swapping byte order to little-endian (drop a trailing odd byte).
+        const usable = b.length - (b.length % 2);
+        const swapped = Buffer.alloc(usable);
+        for (let i = 0; i + 1 < usable; i += 2) {
+            swapped[i] = b[i + 1];
+            swapped[i + 1] = b[i];
+        }
+        return new TextDecoder("utf-16le").decode(swapped);
+    }
+    // cp1252: accepts any byte value (WHATWG maps the 5 undefined bytes to U+FFFD).
+    return new TextDecoder("cp1252").decode(b);
+}
+// Unicode code points that map into cp1252's 0x80-0x9F range. Everything else
+// encodable is an identity mapping: U+0000-U+007F -> 0x00-0x7F and
+// U+00A0-U+00FF -> 0xA0-0xFF.
+const CP1252_SPECIAL = new Map([
+    [0x20ac, 0x80], // EURO SIGN
+    [0x201a, 0x82], // SINGLE LOW-9 QUOTATION MARK
+    [0x0192, 0x83], // LATIN SMALL LETTER F WITH HOOK
+    [0x201e, 0x84], // DOUBLE LOW-9 QUOTATION MARK
+    [0x2026, 0x85], // HORIZONTAL ELLIPSIS
+    [0x2020, 0x86], // DAGGER
+    [0x2021, 0x87], // DOUBLE DAGGER
+    [0x02c6, 0x88], // MODIFIER LETTER CIRCUMFLEX ACCENT
+    [0x2030, 0x89], // PER MILLE SIGN
+    [0x0160, 0x8a], // LATIN CAPITAL LETTER S WITH CARON
+    [0x2039, 0x8b], // SINGLE LEFT-POINTING ANGLE QUOTATION MARK
+    [0x0152, 0x8c], // LATIN CAPITAL LIGATURE OE
+    [0x017d, 0x8e], // LATIN CAPITAL LETTER Z WITH CARON
+    [0x2018, 0x91], // LEFT SINGLE QUOTATION MARK
+    [0x2019, 0x92], // RIGHT SINGLE QUOTATION MARK
+    [0x201c, 0x93], // LEFT DOUBLE QUOTATION MARK
+    [0x201d, 0x94], // RIGHT DOUBLE QUOTATION MARK
+    [0x2022, 0x95], // BULLET
+    [0x2013, 0x96], // EN DASH
+    [0x2014, 0x97], // EM DASH
+    [0x02dc, 0x98], // SMALL TILDE
+    [0x2122, 0x99], // TRADE MARK SIGN
+    [0x0161, 0x9a], // LATIN SMALL LETTER S WITH CARON
+    [0x203a, 0x9b], // SINGLE RIGHT-POINTING ANGLE QUOTATION MARK
+    [0x0153, 0x9c], // LATIN SMALL LIGATURE OE
+    [0x017e, 0x9e], // LATIN SMALL LETTER Z WITH CARON
+    [0x0178, 0x9f], // LATIN CAPITAL LETTER Y WITH DIAERESIS
+]);
+function cp1252CodePointToByte(cp) {
+    if (cp <= 0x7f)
+        return cp;
+    if (cp >= 0xa0 && cp <= 0xff)
+        return cp;
+    return CP1252_SPECIAL.get(cp) ?? null;
+}
+/**
+ * Encode a string to the given encoding. utf16le/utf16be output is prefixed
+ * with its BOM (FF FE / FE FF); utf8/cp1252 output is not. Throws for code
+ * points with no cp1252 mapping (no silent replacement).
+ */
+export function encodeText(text, encoding) {
+    if (encoding === "utf8") {
+        return Buffer.from(text, "utf-8");
+    }
+    if (encoding === "utf16le") {
+        return Buffer.concat([
+            Buffer.from([0xff, 0xfe]),
+            Buffer.from(text, "utf-16le"),
+        ]);
+    }
+    if (encoding === "utf16be") {
+        const le = Buffer.from(text, "utf-16le");
+        const be = Buffer.alloc(le.length);
+        for (let i = 0; i + 1 < le.length; i += 2) {
+            be[i] = le[i + 1];
+            be[i + 1] = le[i];
+        }
+        return Buffer.concat([Buffer.from([0xfe, 0xff]), be]);
+    }
+    // cp1252: one byte per code point. text.length (UTF-16 code units) is a safe
+    // upper bound on the byte count (surrogate pairs shrink, never grow).
+    const out = Buffer.alloc(text.length);
+    let n = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        const byte = cp1252CodePointToByte(cp);
+        if (byte === null) {
+            throw new Error(`Cannot encode character U+${cp.toString(16).toUpperCase()} to cp1252: no mapping`);
+        }
+        out[n++] = byte;
+    }
+    return out.subarray(0, n);
+}

package/dist/helpers/path.js

@@ -11,12 +11,75 @@ export function expandHome(filepath) {
     }
     return filepath;
 }
+// --- Windows long-path (\\?\) support -------------------------------------
+//
+// Windows limits plain API paths to 260 characters (MAX_PATH) unless the
+// path is given in extended-length form: \\?\C:\... for drive paths and
+// \\?\UNC\server\share\... for UNC paths. When the machine-level long-path
+// policy (LongPathsEnabled) is off - or for maximum portability - file
+// operations on longer plain paths fail with ENOENT. Converting validated
+// paths to extended-length form removes the 260-char ceiling.
+//
+// toLongPath() is applied at the END of path validation (validatePath /
+// validatePathPreservingLinks) so every handler inherits it through that
+// single choke point. stripLongPath() is the display inverse: user-facing
+// output must never contain the \\?\ prefix.
+const LONG_PREFIX = "\\\\?\\"; // \\?\
+const LONG_UNC_PREFIX = "\\\\?\\UNC\\"; // \\?\UNC\
+// Convert an absolute path to Windows extended-length form. No-op guard:
+// win32 only. Returns unchanged when already extended-length. Drive paths
+// are prefixed only when longer than 255 chars; UNC paths are always
+// prefixed (the \\?\UNC\ form is equivalent at any length).
+export function toLongPath(absPath) {
+    if (process.platform !== "win32")
+        return absPath;
+    if (absPath.startsWith(LONG_PREFIX) || absPath.startsWith("//?/"))
+        return absPath;
+    if (/^[A-Za-z]:\\/.test(absPath) && absPath.length > 255) {
+        return LONG_PREFIX + absPath;
+    }
+    if (absPath.startsWith("\\\\")) {
+        return LONG_UNC_PREFIX + absPath.slice(2);
+    }
+    return absPath;
+}
+// Display inverse of toLongPath: strip a leading extended-length prefix
+// (the UNC form comes back with a normal double leading backslash).
+export function stripLongPath(p) {
+    if (p.startsWith(LONG_UNC_PREFIX))
+        return "\\\\" + p.slice(LONG_UNC_PREFIX.length);
+    if (p.startsWith(LONG_PREFIX))
+        return p.slice(LONG_PREFIX.length);
+    if (p.startsWith("//?/UNC/"))
+        return "//" + p.slice(7);
+    if (p.startsWith("//?/"))
+        return p.slice(4);
+    return p;
+}
+// Sanitize a string (e.g. an error message) that may embed extended-length
+// paths: replace every occurrence of a prefix with its plain equivalent.
+export function stripLongPathAll(s) {
+    return s
+        .split(LONG_UNC_PREFIX)
+        .join("\\\\")
+        .split(LONG_PREFIX)
+        .join("")
+        .split("//?/UNC/")
+        .join("//")
+        .split("//?/")
+        .join("");
+}
 // Security utilities
 export async function validatePath(requestedPath, allowedDirectories) {
     const expandedPath = expandHome(requestedPath);
-    const absolute = path.isAbsolute(expandedPath)
-        ? path.resolve(expandedPath)
-        : path.resolve(process.cwd(), expandedPath);
+    // Extended-length (\\?\) inputs are normalized to their plain form first,
+    // so resolution and allow-root checks run against the original shape;
+    // the prefix is (re-)applied at the end of validation. The allow-roots
+    // check below therefore still runs on the ORIGINAL (unprefixed) path.
+    const plain = stripLongPath(expandedPath);
+    const absolute = path.isAbsolute(plain)
+        ? path.resolve(plain)
+        : path.resolve(process.cwd(), plain);
     const normalizedRequested = normalizePath(absolute);
     // Check if path is within allowed directories
     const isAllowed = allowedDirectories.some(dir => normalizedRequested.startsWith(dir));
@@ -25,13 +88,13 @@ export async function validatePath(requestedPath, allowedDirectories) {
     }
     // Handle symlinks by checking their real path
     try {
-        const realPath = await fs.realpath(absolute);
+        const realPath = stripLongPath(await fs.realpath(absolute));
         const normalizedReal = normalizePath(realPath);
         const isRealPathAllowed = allowedDirectories.some(dir => normalizedReal.startsWith(dir));
         if (!isRealPathAllowed) {
             throw new Error("Access denied - symlink target outside allowed directories");
         }
-        return realPath;
+        return toLongPath(realPath);
     }
     catch (error) {
         // Target doesn't exist yet: walk up to the nearest existing ancestor
@@ -59,8 +122,72 @@ export async function validatePath(requestedPath, allowedDirectories) {
         if (!isAncestorAllowed) {
             throw new Error("Access denied - parent directory outside allowed directories");
         }
-        return absolute;
+        return toLongPath(absolute);
+    }
+}
+// Like validatePath, but for tools that must classify/operate on the path
+// ITSELF without following reparse points (junctions/symlinks): verifies the
+// literal path is within an allowed directory, keeps the symlink-escape guard
+// (a path that resolves OUTSIDE the allowed directories is rejected), but
+// returns the UN-resolved path. Dangling links and not-yet-existing paths are
+// validated via the nearest existing ancestor, exactly like validatePath.
+export async function validatePathPreservingLinks(requestedPath, allowedDirectories) {
+    const expandedPath = expandHome(requestedPath);
+    // Same as validatePath: normalize extended-length (\\?\) inputs to their
+    // plain form first, then re-apply the prefix at the end.
+    const plain = stripLongPath(expandedPath);
+    const absolute = path.isAbsolute(plain)
+        ? path.resolve(plain)
+        : path.resolve(process.cwd(), plain);
+    const normalizedRequested = normalizePath(absolute);
+    // Check if path is within allowed directories
+    const isAllowed = allowedDirectories.some(dir => normalizedRequested.startsWith(dir));
+    if (!isAllowed) {
+        throw new Error(`Access denied - path outside allowed directories: ${absolute} not in ${allowedDirectories.join(', ')}`);
+    }
+    // Symlink-escape guard: if the path resolves outside the allowed
+    // directories, reject (same policy as validatePath).
+    try {
+        const realPath = stripLongPath(await fs.realpath(absolute));
+        const normalizedReal = normalizePath(realPath);
+        const isRealPathAllowed = allowedDirectories.some(dir => normalizedReal.startsWith(dir));
+        if (!isRealPathAllowed) {
+            throw new Error("Access denied - symlink target outside allowed directories");
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("Access denied")) {
+            throw error;
+        }
+        // Target doesn't exist yet (or is a dangling link): walk up to the
+        // nearest existing ancestor and verify it is within an allowed directory
+        let ancestor = path.dirname(absolute);
+        let realAncestor = null;
+        while (true) {
+            try {
+                realAncestor = await fs.realpath(ancestor);
+                break;
+            }
+            catch {
+                const up = path.dirname(ancestor);
+                if (up === ancestor) {
+                    break;
+                }
+                ancestor = up;
+            }
+        }
+        if (realAncestor === null) {
+            throw new Error(`Parent directory does not exist: ${path.dirname(absolute)}`);
+        }
+        const normalizedAncestor = normalizePath(realAncestor);
+        const isAncestorAllowed = allowedDirectories.some(dir => normalizedAncestor.startsWith(dir));
+        if (!isAncestorAllowed) {
+            throw new Error("Access denied - parent directory outside allowed directories");
+        }
     }
+    // Return the literal (normalized) path - reparse points NOT followed.
+    // Extended-length form is applied last, exactly like validatePath.
+    return toLongPath(normalizedRequested);
 }
 // Create a directory (and parents) if needed. Tolerates volume roots,
 // which Node's recursive mkdir can reject with EPERM on Windows.