@saber2pr/ai-agent 0.0.10 → 0.0.11

package/lib/tools/filesystem/lib.js

@@ -0,0 +1,330 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAllowedDirectories = setAllowedDirectories;
+exports.getAllowedDirectories = getAllowedDirectories;
+exports.formatSize = formatSize;
+exports.normalizeLineEndings = normalizeLineEndings;
+exports.createUnifiedDiff = createUnifiedDiff;
+exports.validatePath = validatePath;
+exports.getFileStats = getFileStats;
+exports.readFileContent = readFileContent;
+exports.writeFileContent = writeFileContent;
+exports.applyFileEdits = applyFileEdits;
+exports.tailFile = tailFile;
+exports.headFile = headFile;
+exports.searchFilesWithValidation = searchFilesWithValidation;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const diff_1 = require("diff");
+const minimatch_1 = require("minimatch");
+const path_utils_js_1 = require("./path-utils.js");
+const path_validation_js_1 = require("./path-validation.js");
+// Global allowed directories - set by the main module
+let allowedDirectories = [];
+// Function to set allowed directories from the main module
+function setAllowedDirectories(directories) {
+    allowedDirectories = [...directories];
+}
+// Function to get current allowed directories
+function getAllowedDirectories() {
+    return [...allowedDirectories];
+}
+// Pure Utility Functions
+function formatSize(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    if (bytes === 0)
+        return '0 B';
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    if (i < 0 || i === 0)
+        return `${bytes} ${units[0]}`;
+    const unitIndex = Math.min(i, units.length - 1);
+    return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
+}
+function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, '\n');
+}
+function createUnifiedDiff(originalContent, newContent, filepath = 'file') {
+    // Ensure consistent line endings for diff
+    const normalizedOriginal = normalizeLineEndings(originalContent);
+    const normalizedNew = normalizeLineEndings(newContent);
+    return (0, diff_1.createTwoFilesPatch)(filepath, filepath, normalizedOriginal, normalizedNew, 'original', 'modified');
+}
+// Security & Validation Functions
+async function validatePath(cwd, requestedPath) {
+    const expandedPath = (0, path_utils_js_1.expandHome)(requestedPath);
+    const absolute = path_1.default.isAbsolute(expandedPath)
+        ? path_1.default.resolve(expandedPath)
+        : path_1.default.resolve(cwd, expandedPath);
+    const normalizedRequested = (0, path_utils_js_1.normalizePath)(absolute);
+    // Security: Check if path is within allowed directories before any file operations
+    const isAllowed = (0, path_validation_js_1.isPathWithinAllowedDirectories)(normalizedRequested, allowedDirectories);
+    if (!isAllowed) {
+        throw new Error(`Access denied - path outside allowed directories: ${absolute} not in ${allowedDirectories.join(', ')}`);
+    }
+    // Security: Handle symlinks by checking their real path to prevent symlink attacks
+    // This prevents attackers from creating symlinks that point outside allowed directories
+    try {
+        const realPath = await promises_1.default.realpath(absolute);
+        const normalizedReal = (0, path_utils_js_1.normalizePath)(realPath);
+        if (!(0, path_validation_js_1.isPathWithinAllowedDirectories)(normalizedReal, allowedDirectories)) {
+            throw new Error(`Access denied - symlink target outside allowed directories: ${realPath} not in ${allowedDirectories.join(', ')}`);
+        }
+        return realPath;
+    }
+    catch (error) {
+        // Security: For new files that don't exist yet, verify parent directory
+        // This ensures we can't create files in unauthorized locations
+        if (error.code === 'ENOENT') {
+            const parentDir = path_1.default.dirname(absolute);
+            try {
+                const realParentPath = await promises_1.default.realpath(parentDir);
+                const normalizedParent = (0, path_utils_js_1.normalizePath)(realParentPath);
+                if (!(0, path_validation_js_1.isPathWithinAllowedDirectories)(normalizedParent, allowedDirectories)) {
+                    throw new Error(`Access denied - parent directory outside allowed directories: ${realParentPath} not in ${allowedDirectories.join(', ')}`);
+                }
+                return absolute;
+            }
+            catch {
+                throw new Error(`Parent directory does not exist: ${parentDir}`);
+            }
+        }
+        throw error;
+    }
+}
+// File Operations
+async function getFileStats(filePath) {
+    const stats = await promises_1.default.stat(filePath);
+    return {
+        size: stats.size,
+        created: stats.birthtime,
+        modified: stats.mtime,
+        accessed: stats.atime,
+        isDirectory: stats.isDirectory(),
+        isFile: stats.isFile(),
+        permissions: stats.mode.toString(8).slice(-3),
+    };
+}
+async function readFileContent(filePath, encoding = 'utf-8') {
+    return await promises_1.default.readFile(filePath, encoding);
+}
+async function writeFileContent(filePath, content) {
+    try {
+        // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
+        // preventing writes through pre-existing symlinks
+        await promises_1.default.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            // Security: Use atomic rename to prevent race conditions where symlinks
+            // could be created between validation and write. Rename operations
+            // replace the target file atomically and don't follow symlinks.
+            const tempPath = `${filePath}.${(0, crypto_1.randomBytes)(16).toString('hex')}.tmp`;
+            try {
+                await promises_1.default.writeFile(tempPath, content, 'utf-8');
+                await promises_1.default.rename(tempPath, filePath);
+            }
+            catch (renameError) {
+                try {
+                    await promises_1.default.unlink(tempPath);
+                }
+                catch { }
+                throw renameError;
+            }
+        }
+        else {
+            throw error;
+        }
+    }
+}
+async function applyFileEdits(filePath, edits, dryRun = false) {
+    var _a;
+    // Read file content and normalize line endings
+    const content = normalizeLineEndings(await promises_1.default.readFile(filePath, 'utf-8'));
+    // Apply edits sequentially
+    let modifiedContent = content;
+    for (const edit of edits) {
+        const normalizedOld = normalizeLineEndings(edit.oldText);
+        const normalizedNew = normalizeLineEndings(edit.newText);
+        // If exact match exists, use it
+        if (modifiedContent.includes(normalizedOld)) {
+            modifiedContent = modifiedContent.replace(normalizedOld, normalizedNew);
+            continue;
+        }
+        // Otherwise, try line-by-line matching with flexibility for whitespace
+        const oldLines = normalizedOld.split('\n');
+        const contentLines = modifiedContent.split('\n');
+        let matchFound = false;
+        for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
+            const potentialMatch = contentLines.slice(i, i + oldLines.length);
+            // Compare lines with normalized whitespace
+            const isMatch = oldLines.every((oldLine, j) => {
+                const contentLine = potentialMatch[j];
+                return oldLine.trim() === contentLine.trim();
+            });
+            if (isMatch) {
+                // Preserve original indentation of first line
+                const originalIndent = ((_a = contentLines[i].match(/^\s*/)) === null || _a === void 0 ? void 0 : _a[0]) || '';
+                const newLines = normalizedNew.split('\n').map((line, j) => {
+                    var _a, _b, _c;
+                    if (j === 0)
+                        return originalIndent + line.trimStart();
+                    // For subsequent lines, try to preserve relative indentation
+                    const oldIndent = ((_b = (_a = oldLines[j]) === null || _a === void 0 ? void 0 : _a.match(/^\s*/)) === null || _b === void 0 ? void 0 : _b[0]) || '';
+                    const newIndent = ((_c = line.match(/^\s*/)) === null || _c === void 0 ? void 0 : _c[0]) || '';
+                    if (oldIndent && newIndent) {
+                        const relativeIndent = newIndent.length - oldIndent.length;
+                        return originalIndent + ' '.repeat(Math.max(0, relativeIndent)) + line.trimStart();
+                    }
+                    return line;
+                });
+                contentLines.splice(i, oldLines.length, ...newLines);
+                modifiedContent = contentLines.join('\n');
+                matchFound = true;
+                break;
+            }
+        }
+        if (!matchFound) {
+            throw new Error(`Could not find exact match for edit:\n${edit.oldText}`);
+        }
+    }
+    // Create unified diff
+    const diff = createUnifiedDiff(content, modifiedContent, filePath);
+    // Format diff with appropriate number of backticks
+    let numBackticks = 3;
+    while (diff.includes('`'.repeat(numBackticks))) {
+        numBackticks++;
+    }
+    const formattedDiff = `${'`'.repeat(numBackticks)}diff\n${diff}${'`'.repeat(numBackticks)}\n\n`;
+    if (!dryRun) {
+        // Security: Use atomic rename to prevent race conditions where symlinks
+        // could be created between validation and write. Rename operations
+        // replace the target file atomically and don't follow symlinks.
+        const tempPath = `${filePath}.${(0, crypto_1.randomBytes)(16).toString('hex')}.tmp`;
+        try {
+            await promises_1.default.writeFile(tempPath, modifiedContent, 'utf-8');
+            await promises_1.default.rename(tempPath, filePath);
+        }
+        catch (error) {
+            try {
+                await promises_1.default.unlink(tempPath);
+            }
+            catch { }
+            throw error;
+        }
+    }
+    return formattedDiff;
+}
+// Memory-efficient implementation to get the last N lines of a file
+async function tailFile(filePath, numLines) {
+    const CHUNK_SIZE = 1024; // Read 1KB at a time
+    const stats = await promises_1.default.stat(filePath);
+    const fileSize = stats.size;
+    if (fileSize === 0)
+        return '';
+    // Open file for reading
+    const fileHandle = await promises_1.default.open(filePath, 'r');
+    try {
+        const lines = [];
+        let position = fileSize;
+        let chunk = Buffer.alloc(CHUNK_SIZE);
+        let linesFound = 0;
+        let remainingText = '';
+        // Read chunks from the end of the file until we have enough lines
+        while (position > 0 && linesFound < numLines) {
+            const size = Math.min(CHUNK_SIZE, position);
+            position -= size;
+            const { bytesRead } = await fileHandle.read(chunk, 0, size, position);
+            if (!bytesRead)
+                break;
+            // Get the chunk as a string and prepend any remaining text from previous iteration
+            const readData = chunk.slice(0, bytesRead).toString('utf-8');
+            const chunkText = readData + remainingText;
+            // Split by newlines and count
+            const chunkLines = normalizeLineEndings(chunkText).split('\n');
+            // If this isn't the end of the file, the first line is likely incomplete
+            // Save it to prepend to the next chunk
+            if (position > 0) {
+                remainingText = chunkLines[0];
+                chunkLines.shift(); // Remove the first (incomplete) line
+            }
+            // Add lines to our result (up to the number we need)
+            for (let i = chunkLines.length - 1; i >= 0 && linesFound < numLines; i--) {
+                lines.unshift(chunkLines[i]);
+                linesFound++;
+            }
+        }
+        return lines.join('\n');
+    }
+    finally {
+        await fileHandle.close();
+    }
+}
+// New function to get the first N lines of a file
+async function headFile(filePath, numLines) {
+    const fileHandle = await promises_1.default.open(filePath, 'r');
+    try {
+        const lines = [];
+        let buffer = '';
+        let bytesRead = 0;
+        const chunk = Buffer.alloc(1024); // 1KB buffer
+        // Read chunks and count lines until we have enough or reach EOF
+        while (lines.length < numLines) {
+            const result = await fileHandle.read(chunk, 0, chunk.length, bytesRead);
+            if (result.bytesRead === 0)
+                break; // End of file
+            bytesRead += result.bytesRead;
+            buffer += chunk.slice(0, result.bytesRead).toString('utf-8');
+            const newLineIndex = buffer.lastIndexOf('\n');
+            if (newLineIndex !== -1) {
+                const completeLines = buffer.slice(0, newLineIndex).split('\n');
+                buffer = buffer.slice(newLineIndex + 1);
+                for (const line of completeLines) {
+                    lines.push(line);
+                    if (lines.length >= numLines)
+                        break;
+                }
+            }
+        }
+        // If there is leftover content and we still need lines, add it
+        if (buffer.length > 0 && lines.length < numLines) {
+            lines.push(buffer);
+        }
+        return lines.join('\n');
+    }
+    finally {
+        await fileHandle.close();
+    }
+}
+async function searchFilesWithValidation(cwd, rootPath, pattern, allowedDirectories, options = {}) {
+    const { excludePatterns = [] } = options;
+    const results = [];
+    async function search(currentPath) {
+        const entries = await promises_1.default.readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path_1.default.join(currentPath, entry.name);
+            try {
+                await validatePath(cwd, fullPath);
+                const relativePath = path_1.default.relative(rootPath, fullPath);
+                const shouldExclude = excludePatterns.some(excludePattern => (0, minimatch_1.minimatch)(relativePath, excludePattern, { dot: true }));
+                if (shouldExclude)
+                    continue;
+                // Use glob matching for the search pattern
+                if ((0, minimatch_1.minimatch)(relativePath, pattern, { dot: true })) {
+                    results.push(fullPath);
+                }
+                if (entry.isDirectory()) {
+                    await search(fullPath);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    await search(rootPath);
+    return results;
+}

package/lib/tools/filesystem/path-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts WSL or Unix-style Windows paths to Windows format
+ * @param p The path to convert
+ * @returns Converted Windows path
+ */
+export declare function convertToWindowsPath(p: string): string;
+/**
+ * Normalizes path by standardizing format while preserving OS-specific behavior
+ * @param p The path to normalize
+ * @returns Normalized path
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * Expands home directory tildes in paths
+ * @param filepath The path to expand
+ * @returns Expanded path
+ */
+export declare function expandHome(filepath: string): string;

package/lib/tools/filesystem/path-utils.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertToWindowsPath = convertToWindowsPath;
+exports.normalizePath = normalizePath;
+exports.expandHome = expandHome;
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+/**
+ * Converts WSL or Unix-style Windows paths to Windows format
+ * @param p The path to convert
+ * @returns Converted Windows path
+ */
+function convertToWindowsPath(p) {
+    // Handle WSL paths (/mnt/c/...)
+    // NEVER convert WSL paths - they are valid Linux paths that work with Node.js fs operations in WSL
+    // Converting them to Windows format (C:\...) breaks fs operations inside WSL
+    if (p.startsWith('/mnt/')) {
+        return p; // Leave WSL paths unchanged
+    }
+    // Handle Unix-style Windows paths (/c/...)
+    // Only convert when running on Windows
+    if (p.match(/^\/[a-zA-Z]\//) && process.platform === 'win32') {
+        const driveLetter = p.charAt(1).toUpperCase();
+        const pathPart = p.slice(2).replace(/\//g, '\\');
+        return `${driveLetter}:${pathPart}`;
+    }
+    // Handle standard Windows paths, ensuring backslashes
+    if (p.match(/^[a-zA-Z]:/)) {
+        return p.replace(/\//g, '\\');
+    }
+    // Leave non-Windows paths unchanged
+    return p;
+}
+/**
+ * Normalizes path by standardizing format while preserving OS-specific behavior
+ * @param p The path to normalize
+ * @returns Normalized path
+ */
+function normalizePath(p) {
+    // Remove any surrounding quotes and whitespace
+    p = p.trim().replace(/^["']|["']$/g, '');
+    // Check if this is a Unix path that should not be converted
+    // WSL paths (/mnt/) should ALWAYS be preserved as they work correctly in WSL with Node.js fs
+    // Regular Unix paths should also be preserved
+    const isUnixPath = p.startsWith('/') && (
+    // Always preserve WSL paths (/mnt/c/, /mnt/d/, etc.)
+    p.match(/^\/mnt\/[a-z]\//i) ||
+        // On non-Windows platforms, treat all absolute paths as Unix paths
+        (process.platform !== 'win32') ||
+        // On Windows, preserve Unix paths that aren't Unix-style Windows paths (/c/, /d/, etc.)
+        (process.platform === 'win32' && !p.match(/^\/[a-zA-Z]\//)));
+    if (isUnixPath) {
+        // For Unix paths, just normalize without converting to Windows format
+        // Replace double slashes with single slashes and remove trailing slashes
+        return p.replace(/\/+/g, '/').replace(/(?<!^)\/$/, '');
+    }
+    // Convert Unix-style Windows paths (/c/, /d/) to Windows format if on Windows
+    // This function will now leave /mnt/ paths unchanged
+    p = convertToWindowsPath(p);
+    // Handle double backslashes, preserving leading UNC \\
+    if (p.startsWith('\\\\')) {
+        // For UNC paths, first normalize any excessive leading backslashes to exactly \\
+        // Then normalize double backslashes in the rest of the path
+        let uncPath = p;
+        // Replace multiple leading backslashes with exactly two
+        uncPath = uncPath.replace(/^\\{2,}/, '\\\\');
+        // Now normalize any remaining double backslashes in the rest of the path
+        const restOfPath = uncPath.substring(2).replace(/\\\\/g, '\\');
+        p = '\\\\' + restOfPath;
+    }
+    else {
+        // For non-UNC paths, normalize all double backslashes
+        p = p.replace(/\\\\/g, '\\');
+    }
+    // Use Node's path normalization, which handles . and .. segments
+    let normalized = path_1.default.normalize(p);
+    // Fix UNC paths after normalization (path.normalize can remove a leading backslash)
+    if (p.startsWith('\\\\') && !normalized.startsWith('\\\\')) {
+        normalized = '\\' + normalized;
+    }
+    // Handle Windows paths: convert slashes and ensure drive letter is capitalized
+    if (normalized.match(/^[a-zA-Z]:/)) {
+        let result = normalized.replace(/\//g, '\\');
+        // Capitalize drive letter if present
+        if (/^[a-z]:/.test(result)) {
+            result = result.charAt(0).toUpperCase() + result.slice(1);
+        }
+        return result;
+    }
+    // On Windows, convert forward slashes to backslashes for relative paths
+    // On Linux/Unix, preserve forward slashes
+    if (process.platform === 'win32') {
+        return normalized.replace(/\//g, '\\');
+    }
+    // On non-Windows platforms, keep the normalized path as-is
+    return normalized;
+}
+/**
+ * Expands home directory tildes in paths
+ * @param filepath The path to expand
+ * @returns Expanded path
+ */
+function expandHome(filepath) {
+    if (filepath.startsWith('~/') || filepath === '~') {
+        return path_1.default.join(os_1.default.homedir(), filepath.slice(1));
+    }
+    return filepath;
+}

package/lib/tools/filesystem/path-validation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks if an absolute path is within any of the allowed directories.
+ *
+ * @param absolutePath - The absolute path to check (will be normalized)
+ * @param allowedDirectories - Array of absolute allowed directory paths (will be normalized)
+ * @returns true if the path is within an allowed directory, false otherwise
+ * @throws Error if given relative paths after normalization
+ */
+export declare function isPathWithinAllowedDirectories(absolutePath: string, allowedDirectories: string[]): boolean;

package/lib/tools/filesystem/path-validation.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPathWithinAllowedDirectories = isPathWithinAllowedDirectories;
+const path_1 = __importDefault(require("path"));
+/**
+ * Checks if an absolute path is within any of the allowed directories.
+ *
+ * @param absolutePath - The absolute path to check (will be normalized)
+ * @param allowedDirectories - Array of absolute allowed directory paths (will be normalized)
+ * @returns true if the path is within an allowed directory, false otherwise
+ * @throws Error if given relative paths after normalization
+ */
+function isPathWithinAllowedDirectories(absolutePath, allowedDirectories) {
+    // Type validation
+    if (typeof absolutePath !== 'string' || !Array.isArray(allowedDirectories)) {
+        return false;
+    }
+    // Reject empty inputs
+    if (!absolutePath || allowedDirectories.length === 0) {
+        return false;
+    }
+    // Reject null bytes (forbidden in paths)
+    if (absolutePath.includes('\x00')) {
+        return false;
+    }
+    // Normalize the input path
+    let normalizedPath;
+    try {
+        normalizedPath = path_1.default.resolve(path_1.default.normalize(absolutePath));
+    }
+    catch {
+        return false;
+    }
+    // Verify it's absolute after normalization
+    if (!path_1.default.isAbsolute(normalizedPath)) {
+        throw new Error('Path must be absolute after normalization');
+    }
+    // Check against each allowed directory
+    return allowedDirectories.some(dir => {
+        if (typeof dir !== 'string' || !dir) {
+            return false;
+        }
+        // Reject null bytes in allowed dirs
+        if (dir.includes('\x00')) {
+            return false;
+        }
+        // Normalize the allowed directory
+        let normalizedDir;
+        try {
+            normalizedDir = path_1.default.resolve(path_1.default.normalize(dir));
+        }
+        catch {
+            return false;
+        }
+        // Verify allowed directory is absolute after normalization
+        if (!path_1.default.isAbsolute(normalizedDir)) {
+            throw new Error('Allowed directories must be absolute paths after normalization');
+        }
+        // Check if normalizedPath is within normalizedDir
+        // Path is inside if it's the same or a subdirectory
+        if (normalizedPath === normalizedDir) {
+            return true;
+        }
+        // Special case for root directory to avoid double slash
+        // On Windows, we need to check if both paths are on the same drive
+        if (normalizedDir === path_1.default.sep) {
+            return normalizedPath.startsWith(path_1.default.sep);
+        }
+        // On Windows, also check for drive root (e.g., "C:\")
+        if (path_1.default.sep === '\\' && normalizedDir.match(/^[A-Za-z]:\\?$/)) {
+            // Ensure both paths are on the same drive
+            const dirDrive = normalizedDir.charAt(0).toLowerCase();
+            const pathDrive = normalizedPath.charAt(0).toLowerCase();
+            return pathDrive === dirDrive && normalizedPath.startsWith(normalizedDir.replace(/\\?$/, '\\'));
+        }
+        return normalizedPath.startsWith(normalizedDir + path_1.default.sep);
+    });
+}

package/lib/tools/filesystem/roots-utils.d.ts

@@ -0,0 +1,12 @@
+import type { Root } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Resolves requested root directories from MCP root specifications.
+ *
+ * Converts root URI specifications (file:// URIs or plain paths) into normalized
+ * directory paths, validating that each path exists and is a directory.
+ * Includes symlink resolution for security.
+ *
+ * @param requestedRoots - Array of root specifications with URI and optional name
+ * @returns Promise resolving to array of validated directory paths
+ */
+export declare function getValidRootDirectories(requestedRoots: readonly Root[]): Promise<string[]>;

package/lib/tools/filesystem/roots-utils.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidRootDirectories = getValidRootDirectories;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const path_utils_js_1 = require("./path-utils.js");
+/**
+ * Converts a root URI to a normalized directory path with basic security validation.
+ * @param rootUri - File URI (file://...) or plain directory path
+ * @returns Promise resolving to validated path or null if invalid
+ */
+async function parseRootUri(rootUri) {
+    try {
+        const rawPath = rootUri.startsWith('file://') ? rootUri.slice(7) : rootUri;
+        const expandedPath = rawPath.startsWith('~/') || rawPath === '~'
+            ? path_1.default.join(os_1.default.homedir(), rawPath.slice(1))
+            : rawPath;
+        const absolutePath = path_1.default.resolve(expandedPath);
+        const resolvedPath = await fs_1.promises.realpath(absolutePath);
+        return (0, path_utils_js_1.normalizePath)(resolvedPath);
+    }
+    catch {
+        return null; // Path doesn't exist or other error
+    }
+}
+/**
+ * Formats error message for directory validation failures.
+ * @param dir - Directory path that failed validation
+ * @param error - Error that occurred during validation
+ * @param reason - Specific reason for failure
+ * @returns Formatted error message
+ */
+function formatDirectoryError(dir, error, reason) {
+    if (reason) {
+        return `Skipping ${reason}: ${dir}`;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return `Skipping invalid directory: ${dir} due to error: ${message}`;
+}
+/**
+ * Resolves requested root directories from MCP root specifications.
+ *
+ * Converts root URI specifications (file:// URIs or plain paths) into normalized
+ * directory paths, validating that each path exists and is a directory.
+ * Includes symlink resolution for security.
+ *
+ * @param requestedRoots - Array of root specifications with URI and optional name
+ * @returns Promise resolving to array of validated directory paths
+ */
+async function getValidRootDirectories(requestedRoots) {
+    const validatedDirectories = [];
+    for (const requestedRoot of requestedRoots) {
+        const resolvedPath = await parseRootUri(requestedRoot.uri);
+        if (!resolvedPath) {
+            console.error(formatDirectoryError(requestedRoot.uri, undefined, 'invalid path or inaccessible'));
+            continue;
+        }
+        try {
+            const stats = await fs_1.promises.stat(resolvedPath);
+            if (stats.isDirectory()) {
+                validatedDirectories.push(resolvedPath);
+            }
+            else {
+                console.error(formatDirectoryError(resolvedPath, undefined, 'non-directory root'));
+            }
+        }
+        catch (error) {
+            console.error(formatDirectoryError(resolvedPath, error));
+        }
+    }
+    return validatedDirectories;
+}

package/lib/tools/ts-lsp/index.d.ts

@@ -0,0 +1 @@
+export declare const getTsLspTools: (targetDir: string) => import("../../types/type").ToolInfo[];