snow-ai 0.3.6 → 0.3.8

package/dist/mcp/filesystem.js

@@ -6,6 +6,11 @@ import { promisify } from 'util';
 import { vscodeConnection } from '../utils/vscodeConnection.js';
 import { incrementalSnapshotManager } from '../utils/incrementalSnapshot.js';
 import { tryUnescapeFix, trimPairIfPossible, isOverEscaped, } from '../utils/escapeHandler.js';
+// Utility functions
+import { calculateSimilarity, normalizeForDisplay, } from './utils/filesystem/similarity.utils.js';
+import { analyzeCodeStructure, findSmartContextBoundaries, } from './utils/filesystem/code-analysis.utils.js';
+import { findClosestMatches, generateDiffMessage, } from './utils/filesystem/match-finder.utils.js';
+import { parseEditBySearchParams, parseEditByLineParams, executeBatchOperation, } from './utils/filesystem/batch-operations.utils.js';
 const { resolve, dirname, isAbsolute } = path;
 const execAsync = promisify(exec);
 /**
@@ -47,328 +52,11 @@ export class FilesystemMCPService {
         });
         this.basePath = resolve(basePath);
     }
-    /**
-     * Calculate similarity between two strings using a smarter algorithm
-     * This normalizes whitespace first to avoid false negatives from spacing differences
-     * Returns a value between 0 (completely different) and 1 (identical)
-     */
-    calculateSimilarity(str1, str2, threshold = 0) {
-        // Normalize whitespace for comparison: collapse all whitespace to single spaces
-        const normalize = (s) => s.replace(/\s+/g, ' ').trim();
-        const norm1 = normalize(str1);
-        const norm2 = normalize(str2);
-        const len1 = norm1.length;
-        const len2 = norm2.length;
-        if (len1 === 0)
-            return len2 === 0 ? 1 : 0;
-        if (len2 === 0)
-            return 0;
-        // Quick length check - if lengths differ too much, similarity can't be above threshold
-        const maxLen = Math.max(len1, len2);
-        const minLen = Math.min(len1, len2);
-        const lengthRatio = minLen / maxLen;
-        if (threshold > 0 && lengthRatio < threshold) {
-            return lengthRatio; // Can't possibly meet threshold
-        }
-        // Use Levenshtein distance for better similarity calculation
-        const distance = this.levenshteinDistance(norm1, norm2, Math.ceil(maxLen * (1 - threshold)));
-        return 1 - distance / maxLen;
-    }
-    /**
-     * Calculate Levenshtein distance between two strings with early termination
-     * @param str1 First string
-     * @param str2 Second string
-     * @param maxDistance Maximum distance to compute (early exit if exceeded)
-     * @returns Levenshtein distance, or maxDistance+1 if exceeded
-     */
-    levenshteinDistance(str1, str2, maxDistance = Infinity) {
-        const len1 = str1.length;
-        const len2 = str2.length;
-        // Quick exit for identical strings
-        if (str1 === str2)
-            return 0;
-        // Quick exit if length difference already exceeds maxDistance
-        if (Math.abs(len1 - len2) > maxDistance) {
-            return maxDistance + 1;
-        }
-        // Use single-row algorithm to save memory (only need previous row)
-        let prevRow = Array.from({ length: len2 + 1 }, (_, i) => i);
-        for (let i = 1; i <= len1; i++) {
-            const currRow = [i];
-            let minInRow = i; // Track minimum value in current row
-            for (let j = 1; j <= len2; j++) {
-                const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
-                const val = Math.min(prevRow[j] + 1, // deletion
-                currRow[j - 1] + 1, // insertion
-                prevRow[j - 1] + cost // substitution
-                );
-                currRow[j] = val;
-                minInRow = Math.min(minInRow, val);
-            }
-            // Early termination: if minimum in this row exceeds maxDistance, we can stop
-            if (minInRow > maxDistance) {
-                return maxDistance + 1;
-            }
-            prevRow = currRow;
-        }
-        return prevRow[len2];
-    }
-    /**
-     * Find the closest matching candidates in the file content
-     * Returns top N candidates sorted by similarity
-     * Optimized with safe pre-filtering and early exit
-     * ASYNC to prevent terminal freeze during search
-     */
-    async findClosestMatches(searchContent, fileLines, topN = 3) {
-        const searchLines = searchContent.split('\n');
-        const candidates = [];
-        // Normalize whitespace for display only (makes preview more readable)
-        const normalizeForDisplay = (line) => line.replace(/\t/g, ' ').replace(/  +/g, ' ');
-        // Fast pre-filter: use first line as anchor (only for multi-line searches)
-        const searchFirstLine = searchLines[0]?.replace(/\s+/g, ' ').trim() || '';
-        const threshold = 0.5;
-        const usePreFilter = searchLines.length >= 5; // Only for 5+ line searches
-        const preFilterThreshold = 0.2; // Very conservative - only skip completely unrelated lines
-        // Try to find candidates by sliding window with optimizations
-        const maxCandidates = topN * 3; // Collect more candidates, then pick best
-        const YIELD_INTERVAL = 100; // Yield control every 100 iterations
-        for (let i = 0; i <= fileLines.length - searchLines.length; i++) {
-            // Yield control periodically to prevent UI freeze
-            if (i % YIELD_INTERVAL === 0) {
-                await new Promise(resolve => setImmediate(resolve));
-            }
-            // Quick pre-filter: check first line similarity (only for multi-line)
-            if (usePreFilter) {
-                const firstLineCandidate = fileLines[i]?.replace(/\s+/g, ' ').trim() || '';
-                const firstLineSimilarity = this.calculateSimilarity(searchFirstLine, firstLineCandidate, preFilterThreshold);
-                // Skip only if first line is very different
-                if (firstLineSimilarity < preFilterThreshold) {
-                    continue;
-                }
-            }
-            // Full candidate check
-            const candidateLines = fileLines.slice(i, i + searchLines.length);
-            const candidateContent = candidateLines.join('\n');
-            const similarity = this.calculateSimilarity(searchContent, candidateContent, threshold);
-            // Only consider candidates with >50% similarity
-            if (similarity > threshold) {
-                candidates.push({
-                    startLine: i + 1,
-                    endLine: i + searchLines.length,
-                    similarity,
-                    preview: candidateLines
-                        .map((line, idx) => `${i + idx + 1}→${normalizeForDisplay(line)}`)
-                        .join('\n'),
-                });
-                // Early exit if we found a nearly perfect match
-                if (similarity >= 0.95) {
-                    break;
-                }
-                // Limit candidates to avoid excessive computation
-                if (candidates.length >= maxCandidates) {
-                    break;
-                }
-            }
-        }
-        // Sort by similarity descending and return top N
-        return candidates
-            .sort((a, b) => b.similarity - a.similarity)
-            .slice(0, topN);
-    }
-    /**
-     * Generate a helpful diff message showing differences between search and actual content
-     * Note: This is ONLY for display purposes. Tabs/spaces are normalized for better readability.
-     */
-    generateDiffMessage(searchContent, actualContent, maxLines = 10) {
-        const searchLines = searchContent.split('\n');
-        const actualLines = actualContent.split('\n');
-        const diffLines = [];
-        const maxLen = Math.max(searchLines.length, actualLines.length);
-        // Normalize whitespace for display only (makes diff more readable)
-        const normalizeForDisplay = (line) => line.replace(/\t/g, ' ').replace(/  +/g, ' ');
-        for (let i = 0; i < Math.min(maxLen, maxLines); i++) {
-            const searchLine = searchLines[i] || '';
-            const actualLine = actualLines[i] || '';
-            if (searchLine !== actualLine) {
-                diffLines.push(`Line ${i + 1}:`);
-                diffLines.push(`  Search: ${JSON.stringify(normalizeForDisplay(searchLine))}`);
-                diffLines.push(`  Actual: ${JSON.stringify(normalizeForDisplay(actualLine))}`);
-            }
-        }
-        if (maxLen > maxLines) {
-            diffLines.push(`... (${maxLen - maxLines} more lines)`);
-        }
-        return diffLines.join('\n');
-    }
-    /**
-     * Analyze code structure for balance and completeness
-     * Helps AI identify bracket mismatches, unclosed tags, and boundary issues
-     */
-    analyzeCodeStructure(_content, filePath, editedLines) {
-        const analysis = {
-            bracketBalance: {
-                curly: { open: 0, close: 0, balanced: true },
-                round: { open: 0, close: 0, balanced: true },
-                square: { open: 0, close: 0, balanced: true },
-            },
-            indentationWarnings: [],
-        };
-        // Count brackets in the edited content
-        const editedContent = editedLines.join('\n');
-        // Remove string literals and comments to avoid false positives
-        const cleanContent = editedContent
-            .replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`/g, '""') // Remove strings
-            .replace(/\/\/.*$/gm, '') // Remove single-line comments
-            .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove multi-line comments
-        // Count brackets
-        analysis.bracketBalance.curly.open = (cleanContent.match(/\{/g) || []).length;
-        analysis.bracketBalance.curly.close = (cleanContent.match(/\}/g) || []).length;
-        analysis.bracketBalance.curly.balanced =
-            analysis.bracketBalance.curly.open ===
-                analysis.bracketBalance.curly.close;
-        analysis.bracketBalance.round.open = (cleanContent.match(/\(/g) || []).length;
-        analysis.bracketBalance.round.close = (cleanContent.match(/\)/g) || []).length;
-        analysis.bracketBalance.round.balanced =
-            analysis.bracketBalance.round.open ===
-                analysis.bracketBalance.round.close;
-        analysis.bracketBalance.square.open = (cleanContent.match(/\[/g) || []).length;
-        analysis.bracketBalance.square.close = (cleanContent.match(/\]/g) || []).length;
-        analysis.bracketBalance.square.balanced =
-            analysis.bracketBalance.square.open ===
-                analysis.bracketBalance.square.close;
-        // HTML/JSX tag analysis (for .html, .jsx, .tsx, .vue files)
-        const isMarkupFile = /\.(html|jsx|tsx|vue)$/i.test(filePath);
-        if (isMarkupFile) {
-            const tagPattern = /<\/?([a-zA-Z][a-zA-Z0-9-]*)[^>]*>/g;
-            const selfClosingPattern = /<[a-zA-Z][a-zA-Z0-9-]*[^>]*\/>/g;
-            // Remove self-closing tags
-            const contentWithoutSelfClosing = cleanContent.replace(selfClosingPattern, '');
-            const tags = [];
-            const unclosedTags = [];
-            const unopenedTags = [];
-            let match;
-            while ((match = tagPattern.exec(contentWithoutSelfClosing)) !== null) {
-                const isClosing = match[0]?.startsWith('</');
-                const tagName = match[1]?.toLowerCase();
-                if (!tagName)
-                    continue;
-                if (isClosing) {
-                    const lastOpenTag = tags.pop();
-                    if (!lastOpenTag || lastOpenTag !== tagName) {
-                        unopenedTags.push(tagName);
-                        if (lastOpenTag)
-                            tags.push(lastOpenTag); // Put it back
-                    }
-                }
-                else {
-                    tags.push(tagName);
-                }
-            }
-            unclosedTags.push(...tags);
-            analysis.htmlTags = {
-                unclosedTags,
-                unopenedTags,
-                balanced: unclosedTags.length === 0 && unopenedTags.length === 0,
-            };
-        }
-        // Check indentation consistency
-        const lines = editedContent.split('\n');
-        const indents = lines
-            .filter(line => line.trim().length > 0)
-            .map(line => {
-            const match = line.match(/^(\s*)/);
-            return match ? match[1] : '';
-        })
-            .filter((indent) => indent !== undefined);
-        // Detect mixed tabs/spaces
-        const hasTabs = indents.some(indent => indent.includes('\t'));
-        const hasSpaces = indents.some(indent => indent.includes(' '));
-        if (hasTabs && hasSpaces) {
-            analysis.indentationWarnings.push('Mixed tabs and spaces detected');
-        }
-        // Detect inconsistent indentation levels (spaces only)
-        if (!hasTabs && hasSpaces) {
-            const spaceCounts = indents
-                .filter(indent => indent.length > 0)
-                .map(indent => indent.length);
-            if (spaceCounts.length > 1) {
-                const gcd = spaceCounts.reduce((a, b) => {
-                    while (b !== 0) {
-                        const temp = b;
-                        b = a % b;
-                        a = temp;
-                    }
-                    return a;
-                });
-                const hasInconsistent = spaceCounts.some(count => count % gcd !== 0 && gcd > 1);
-                if (hasInconsistent) {
-                    analysis.indentationWarnings.push(`Inconsistent indentation (expected multiples of ${gcd} spaces)`);
-                }
-            }
-        }
-        // Note: Boundary checking removed - AI should be free to edit partial code blocks
-        // The bracket balance check above is sufficient for detecting real issues
-        return analysis;
-    }
-    /**
-     * Find smart context boundaries for editing
-     * Expands context to include complete code blocks when possible
-     */
-    findSmartContextBoundaries(lines, startLine, endLine, requestedContext) {
-        const totalLines = lines.length;
-        let contextStart = Math.max(1, startLine - requestedContext);
-        let contextEnd = Math.min(totalLines, endLine + requestedContext);
-        let extended = false;
-        // Try to find the start of the enclosing block
-        let bracketDepth = 0;
-        for (let i = startLine - 1; i >= Math.max(0, startLine - 50); i--) {
-            const line = lines[i];
-            if (!line)
-                continue;
-            const trimmed = line.trim();
-            // Count brackets (simple approach)
-            const openBrackets = (line.match(/\{/g) || []).length;
-            const closeBrackets = (line.match(/\}/g) || []).length;
-            bracketDepth += closeBrackets - openBrackets;
-            // If we find a function/class/block definition with balanced brackets
-            if (bracketDepth === 0 &&
-                (trimmed.match(/^(function|class|const|let|var|if|for|while|async|export)\s/i) ||
-                    trimmed.match(/=>\s*\{/) ||
-                    trimmed.match(/^\w+\s*\(/))) {
-                if (i + 1 < contextStart) {
-                    contextStart = i + 1;
-                    extended = true;
-                }
-                break;
-            }
-        }
-        // Try to find the end of the enclosing block
-        bracketDepth = 0;
-        for (let i = endLine - 1; i < Math.min(totalLines, endLine + 50); i++) {
-            const line = lines[i];
-            if (!line)
-                continue;
-            const trimmed = line.trim();
-            // Count brackets
-            const openBrackets = (line.match(/\{/g) || []).length;
-            const closeBrackets = (line.match(/\}/g) || []).length;
-            bracketDepth += openBrackets - closeBrackets;
-            // If we find a closing bracket at depth 0
-            if (bracketDepth === 0 && trimmed.startsWith('}')) {
-                if (i + 1 > contextEnd) {
-                    contextEnd = i + 1;
-                    extended = true;
-                }
-                break;
-            }
-        }
-        return { start: contextStart, end: contextEnd, extended };
-    }
     /**
      * Get the content of a file with optional line range
-     * @param filePath - Path to the file (relative to base path or absolute) or array of file paths
-     * @param startLine - Starting line number (1-indexed, inclusive, optional - defaults to 1)
-     * @param endLine - Ending line number (1-indexed, inclusive, optional - defaults to 500 or file end)
+     * @param filePath - Path to the file (relative to base path or absolute) or array of file paths or array of file config objects
+     * @param startLine - Starting line number (1-indexed, inclusive, optional - defaults to 1). Used for single file or as default for array of strings
+     * @param endLine - Ending line number (1-indexed, inclusive, optional - defaults to file end). Used for single file or as default for array of strings
      * @returns Object containing the requested content with line numbers and metadata
      * @throws Error if file doesn't exist or cannot be read
      */
@@ -378,8 +66,24 @@ export class FilesystemMCPService {
             if (Array.isArray(filePath)) {
                 const filesData = [];
                 const allContents = [];
-                for (const file of filePath) {
+                for (const fileItem of filePath) {
                     try {
+                        // Support both string format and object format
+                        let file;
+                        let fileStartLine;
+                        let fileEndLine;
+                        if (typeof fileItem === 'string') {
+                            // String format: use global startLine/endLine
+                            file = fileItem;
+                            fileStartLine = startLine;
+                            fileEndLine = endLine;
+                        }
+                        else {
+                            // Object format: use per-file startLine/endLine
+                            file = fileItem.path;
+                            fileStartLine = fileItem.startLine ?? startLine;
+                            fileEndLine = fileItem.endLine ?? endLine;
+                        }
                         const fullPath = this.resolvePath(file);
                         // For absolute paths, skip validation to allow access outside base path
                         if (!isAbsolute(file)) {
@@ -402,9 +106,9 @@ export class FilesystemMCPService {
                         const content = await fs.readFile(fullPath, 'utf-8');
                         const lines = content.split('\n');
                         const totalLines = lines.length;
-                        // Default values and logic
-                        const actualStartLine = startLine ?? 1;
-                        const actualEndLine = endLine ?? totalLines;
+                        // Default values and logic (use file-specific values)
+                        const actualStartLine = fileStartLine ?? 1;
+                        const actualEndLine = fileEndLine ?? totalLines;
                         // Validate and adjust line numbers
                         if (actualStartLine < 1) {
                             throw new Error(`Start line must be greater than 0 for ${file}`);
@@ -434,7 +138,9 @@ export class FilesystemMCPService {
                     }
                     catch (error) {
                         const errorMsg = error instanceof Error ? error.message : 'Unknown error';
-                        allContents.push(`❌ ${file}: ${errorMsg}`);
+                        // Extract file path for error message
+                        const filePath = typeof fileItem === 'string' ? fileItem : fileItem.path;
+                        allContents.push(`❌ ${filePath}: ${errorMsg}`);
                     }
                 }
                 return {
@@ -644,18 +350,35 @@ export class FilesystemMCPService {
         }
     }
     /**
-     * Edit a file by searching for exact content and replacing it
+     * Edit file(s) by searching for exact content and replacing it
      * This method uses SMART MATCHING to handle whitespace differences automatically.
      *
-     * @param filePath - Path to the file to edit
-     * @param searchContent - Content to search for (whitespace will be normalized automatically)
-     * @param replaceContent - New content to replace the search content with
+     * @param filePath - Path to the file to edit, or array of file paths, or array of edit config objects
+     * @param searchContent - Content to search for (for single file or unified mode)
+     * @param replaceContent - New content to replace (for single file or unified mode)
      * @param occurrence - Which occurrence to replace (1-indexed, default: 1, use -1 for all)
      * @param contextLines - Number of context lines to return before and after the edit (default: 8)
      * @returns Object containing success message, before/after comparison, and diagnostics from IDE (VSCode or JetBrains)
      * @throws Error if search content is not found or multiple matches exist
      */
     async editFileBySearch(filePath, searchContent, replaceContent, occurrence = 1, contextLines = 8) {
+        // Handle array of files
+        if (Array.isArray(filePath)) {
+            return await executeBatchOperation(filePath, fileItem => parseEditBySearchParams(fileItem, searchContent, replaceContent, occurrence), (path, search, replace, occ) => this.editFileBySearchSingle(path, search, replace, occ, contextLines), (path, result) => {
+                return { path, ...result };
+            });
+        }
+        // Single file mode
+        if (!searchContent || !replaceContent) {
+            throw new Error('searchContent and replaceContent are required for single file mode');
+        }
+        return await this.editFileBySearchSingle(filePath, searchContent, replaceContent, occurrence, contextLines);
+    }
+    /**
+     * Internal method: Edit a single file by search-replace
+     * @private
+     */
+    async editFileBySearchSingle(filePath, searchContent, replaceContent, occurrence, contextLines) {
         try {
             const fullPath = this.resolvePath(filePath);
             // For absolute paths, skip validation to allow access outside base path
@@ -693,7 +416,7 @@ export class FilesystemMCPService {
                 // Quick pre-filter: check first line similarity (only for multi-line searches)
                 if (usePreFilter) {
                     const firstLineCandidate = contentLines[i]?.replace(/\s+/g, ' ').trim() || '';
-                    const firstLineSimilarity = this.calculateSimilarity(searchFirstLine, firstLineCandidate, preFilterThreshold);
+                    const firstLineSimilarity = calculateSimilarity(searchFirstLine, firstLineCandidate, preFilterThreshold);
                     // Skip only if first line is very different (< 30% match)
                     // This is safe because if first line differs this much, full match unlikely
                     if (firstLineSimilarity < preFilterThreshold) {
@@ -703,7 +426,7 @@ export class FilesystemMCPService {
                 // Full candidate check
                 const candidateLines = contentLines.slice(i, i + searchLines.length);
                 const candidateContent = candidateLines.join('\n');
-                const similarity = this.calculateSimilarity(normalizedSearch, candidateContent, threshold);
+                const similarity = calculateSimilarity(normalizedSearch, candidateContent, threshold);
                 // Accept matches above threshold
                 if (similarity >= threshold) {
                     matches.push({
@@ -737,7 +460,7 @@ export class FilesystemMCPService {
                         }
                         const candidateLines = contentLines.slice(i, i + correctedSearchLines.length);
                         const candidateContent = candidateLines.join('\n');
-                        const similarity = this.calculateSimilarity(unescapeFix.correctedString, candidateContent);
+                        const similarity = calculateSimilarity(unescapeFix.correctedString, candidateContent);
                         if (similarity >= threshold) {
                             matches.push({
                                 startLine: i + 1,
@@ -760,7 +483,7 @@ export class FilesystemMCPService {
                 // If still no matches after unescape, provide detailed error
                 if (matches.length === 0) {
                     // Find closest matches for suggestions
-                    const closestMatches = await this.findClosestMatches(normalizedSearch, normalizedContent.split('\n'), 3);
+                    const closestMatches = await findClosestMatches(normalizedSearch, normalizedContent.split('\n'), 3);
                     let errorMessage = `❌ Search content not found in file: ${filePath}\n\n`;
                     errorMessage += `🔍 Using smart fuzzy matching (threshold: 60%)\n`;
                     if (isOverEscaped(searchContent)) {
@@ -778,23 +501,22 @@ export class FilesystemMCPService {
                         if (bestMatch) {
                             const bestMatchLines = lines.slice(bestMatch.startLine - 1, bestMatch.endLine);
                             const bestMatchContent = bestMatchLines.join('\n');
-                            const diffMsg = this.generateDiffMessage(normalizedSearch, bestMatchContent, 5);
+                            const diffMsg = generateDiffMessage(normalizedSearch, bestMatchContent, 5);
                             if (diffMsg) {
                                 errorMessage += `📊 Difference with closest match:\n${diffMsg}\n\n`;
                             }
                         }
                         errorMessage += `💡 Suggestions:\n`;
-                        errorMessage += `  • Make sure you copied content from filesystem_read (without "123→")\n`;
+                        errorMessage += `  • Make sure you copied content from filesystem-read (without "123→")\n`;
                         errorMessage += `  • Whitespace differences are automatically handled\n`;
                         errorMessage += `  • Try copying a larger or smaller code block\n`;
-                        errorMessage += `  • If multiple filesystem_edit_search attempts fail, use terminal_execute to edit via command line (e.g. sed, printf)\n`;
+                        errorMessage += `  • If multiple filesystem-edit_search attempts fail, use terminal-execute to edit via command line (e.g. sed, printf)\n`;
                         errorMessage += `⚠️  No similar content found in the file.\n\n`;
                         errorMessage += `📝 What you searched for (first 5 lines, formatted):\n`;
-                        const normalizeForDisplay = (line) => line.replace(/\s+/g, ' ').trim();
                         searchLines.slice(0, 5).forEach((line, idx) => {
                             errorMessage += `${idx + 1}. ${JSON.stringify(normalizeForDisplay(line))}\n`;
                         });
-                        errorMessage += `\n💡 Copy exact content from filesystem_read (without line numbers)\n`;
+                        errorMessage += `\n💡 Copy exact content from filesystem-read (without line numbers)\n`;
                     }
                     throw new Error(errorMessage);
                 }
@@ -829,7 +551,6 @@ export class FilesystemMCPService {
             const modifiedLines = [...beforeLines, ...replaceLines, ...afterLines];
             const modifiedContent = modifiedLines.join('\n');
             // Calculate replaced content for display (compress whitespace for readability)
-            const normalizeForDisplay = (line) => line.replace(/\s+/g, ' ');
             const replacedLines = lines.slice(startLine - 1, endLine);
             const replacedContent = replacedLines
                 .map((line, idx) => {
@@ -839,7 +560,7 @@ export class FilesystemMCPService {
                 .join('\n');
             // Calculate context boundaries
             const lineDifference = replaceLines.length - (endLine - startLine + 1);
-            const smartBoundaries = this.findSmartContextBoundaries(lines, startLine, endLine, contextLines);
+            const smartBoundaries = findSmartContextBoundaries(lines, startLine, endLine, contextLines);
             const contextStart = smartBoundaries.start;
             const contextEnd = smartBoundaries.end;
             // Extract old content for context (compress whitespace for readability)
@@ -885,7 +606,7 @@ export class FilesystemMCPService {
                 .join('\n');
             // Analyze code structure
             const editedContentLines = replaceLines;
-            const structureAnalysis = this.analyzeCodeStructure(finalContent, filePath, editedContentLines);
+            const structureAnalysis = analyzeCodeStructure(finalContent, filePath, editedContentLines);
             // Get diagnostics from IDE (VSCode or JetBrains) - non-blocking, fire-and-forget
             let diagnostics = [];
             try {
@@ -969,7 +690,7 @@ export class FilesystemMCPService {
                 }
             }
             if (structureAnalysis.indentationWarnings.length > 0) {
-                structureWarnings.push(...structureAnalysis.indentationWarnings.map(w => `Indentation: ${w}`));
+                structureWarnings.push(...structureAnalysis.indentationWarnings.map((w) => `Indentation: ${w}`));
             }
             // Note: Boundary warnings removed - partial edits are common and expected
             if (structureWarnings.length > 0) {
@@ -986,19 +707,38 @@ export class FilesystemMCPService {
         }
     }
     /**
-     * Edit a file by replacing lines within a specified range
+     * Edit file(s) by replacing lines within a specified range
      * BEST PRACTICE: Keep edits small and focused (≤15 lines recommended) for better accuracy.
      * For larger changes, make multiple parallel edits to non-overlapping sections instead of one large edit.
      *
-     * @param filePath - Path to the file to edit
-     * @param startLine - Starting line number (1-indexed, inclusive) - get from filesystem_read output
-     * @param endLine - Ending line number (1-indexed, inclusive) - get from filesystem_read output
-     * @param newContent - New content to replace the specified lines (WITHOUT line numbers)
+     * @param filePath - Path to the file to edit, or array of file paths, or array of edit config objects
+     * @param startLine - Starting line number (for single file or unified mode)
+     * @param endLine - Ending line number (for single file or unified mode)
+     * @param newContent - New content to replace (for single file or unified mode)
      * @param contextLines - Number of context lines to return before and after the edit (default: 8)
      * @returns Object containing success message, precise before/after comparison, and diagnostics from IDE (VSCode or JetBrains)
      * @throws Error if file editing fails
      */
     async editFile(filePath, startLine, endLine, newContent, contextLines = 8) {
+        // Handle array of files
+        if (Array.isArray(filePath)) {
+            return await executeBatchOperation(filePath, fileItem => parseEditByLineParams(fileItem, startLine, endLine, newContent), (path, start, end, content) => this.editFileSingle(path, start, end, content, contextLines), (path, result) => {
+                return { path, ...result };
+            });
+        }
+        // Single file mode
+        if (startLine === undefined ||
+            endLine === undefined ||
+            newContent === undefined) {
+            throw new Error('startLine, endLine, and newContent are required for single file mode');
+        }
+        return await this.editFileSingle(filePath, startLine, endLine, newContent, contextLines);
+    }
+    /**
+     * Internal method: Edit a single file by line range
+     * @private
+     */
+    async editFileSingle(filePath, startLine, endLine, newContent, contextLines) {
         try {
             const fullPath = this.resolvePath(filePath);
             // For absolute paths, skip validation to allow access outside base path
@@ -1026,7 +766,6 @@ export class FilesystemMCPService {
             await incrementalSnapshotManager.backupFile(fullPath);
             // Extract the lines that will be replaced (for comparison)
             // Compress whitespace for display readability
-            const normalizeForDisplay = (line) => line.replace(/\s+/g, ' ');
             const replacedLines = lines.slice(startLine - 1, adjustedEndLine);
             const replacedContent = replacedLines
                 .map((line, idx) => {
@@ -1035,7 +774,7 @@ export class FilesystemMCPService {
             })
                 .join('\n');
             // Calculate context range using smart boundary detection
-            const smartBoundaries = this.findSmartContextBoundaries(lines, startLine, adjustedEndLine, contextLines);
+            const smartBoundaries = findSmartContextBoundaries(lines, startLine, adjustedEndLine, contextLines);
             const contextStart = smartBoundaries.start;
             const contextEnd = smartBoundaries.end;
             // Extract old content for context (compress whitespace for readability)
@@ -1100,7 +839,7 @@ export class FilesystemMCPService {
             }
             // Analyze code structure of the edited content (using formatted content if available)
             const editedContentLines = finalLines.slice(startLine - 1, startLine - 1 + newContentLines.length);
-            const structureAnalysis = this.analyzeCodeStructure(finalLines.join('\n'), filePath, editedContentLines);
+            const structureAnalysis = analyzeCodeStructure(finalLines.join('\n'), filePath, editedContentLines);
             // Try to get diagnostics from IDE (VSCode or JetBrains) after editing (non-blocking)
             let diagnostics = [];
             try {
@@ -1185,7 +924,7 @@ export class FilesystemMCPService {
             }
             // Check indentation
             if (structureAnalysis.indentationWarnings.length > 0) {
-                structureWarnings.push(...structureAnalysis.indentationWarnings.map(w => `Indentation: ${w}`));
+                structureWarnings.push(...structureAnalysis.indentationWarnings.map((w) => `Indentation: ${w}`));
             }
             // Note: Boundary warnings removed - partial edits are common and expected
             // Format structure warnings
@@ -1234,8 +973,8 @@ export class FilesystemMCPService {
 export const filesystemService = new FilesystemMCPService();
 export const mcpTools = [
     {
-        name: 'filesystem_read',
-        description: '📖 Read file content with line numbers. **SUPPORTS MULTIPLE FILES**: Pass either a single file path (string) or multiple file paths (array of strings) to read in one call. ⚠️ **IMPORTANT WORKFLOW**: (1) ALWAYS use ACE search tools FIRST (ace_text_search/ace_search_symbols/ace_file_outline) to locate the relevant code, (2) ONLY use filesystem_read when you know the approximate location and need precise line numbers for editing. **ANTI-PATTERN**: Reading files line-by-line from the top wastes tokens - use search instead! **USAGE**: Call without parameters to read entire file(s), or specify startLine/endLine for partial reads. Returns content with line numbers (format: "123→code") for precise editing. **MULTI-FILE EXAMPLE**: filePath=["src/component.ts", "src/utils.ts"] reads both files together.',
+        name: 'filesystem-read',
+        description: '📖 Read file content with line numbers. **SUPPORTS MULTIPLE FILES WITH FLEXIBLE LINE RANGES**: Pass either (1) a single file path (string), (2) array of file paths (strings) with unified startLine/endLine, or (3) array of file config objects with per-file line ranges. ⚠️ **IMPORTANT WORKFLOW**: (1) ALWAYS use ACE search tools FIRST (ace-text_search/ace-search_symbols/ace-file_outline) to locate the relevant code, (2) ONLY use filesystem-read when you know the approximate location and need precise line numbers for editing. **ANTI-PATTERN**: Reading files line-by-line from the top wastes tokens - use search instead! **USAGE**: Call without parameters to read entire file(s), or specify startLine/endLine for partial reads. Returns content with line numbers (format: "123→code") for precise editing. **EXAMPLES**: (A) Unified: filePath=["a.ts", "b.ts"], startLine=1, endLine=50 reads lines 1-50 from both. (B) Per-file: filePath=[{path:"a.ts", startLine:1, endLine:30}, {path:"b.ts", startLine:100, endLine:150}] reads different ranges from each file.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1250,25 +989,47 @@ export const mcpTools = [
                             items: {
                                 type: 'string',
                             },
-                            description: 'Array of file paths to read in one call',
+                            description: 'Array of file paths to read in one call (uses unified startLine/endLine from top-level parameters)',
+                        },
+                        {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    path: {
+                                        type: 'string',
+                                        description: 'File path',
+                                    },
+                                    startLine: {
+                                        type: 'number',
+                                        description: 'Optional: Starting line for this file (overrides top-level startLine)',
+                                    },
+                                    endLine: {
+                                        type: 'number',
+                                        description: 'Optional: Ending line for this file (overrides top-level endLine)',
+                                    },
+                                },
+                                required: ['path'],
+                            },
+                            description: 'Array of file config objects with per-file line ranges. Each file can have its own startLine/endLine.',
                         },
                     ],
-                    description: 'Path to the file(s) to read (single string or array of strings)',
+                    description: 'Path to the file(s) to read: string, array of strings, or array of {path, startLine?, endLine?} objects',
                 },
                 startLine: {
                     type: 'number',
-                    description: 'Optional: Starting line number (1-indexed). Omit to read from line 1. Applied to all files.',
+                    description: 'Optional: Default starting line number (1-indexed) for all files. Omit to read from line 1. Can be overridden by per-file startLine in object format.',
                 },
                 endLine: {
                     type: 'number',
-                    description: 'Optional: Ending line number (1-indexed). Omit to read to end of file. Applied to all files.',
+                    description: 'Optional: Default ending line number (1-indexed) for all files. Omit to read to end of file. Can be overridden by per-file endLine in object format.',
                 },
             },
             required: ['filePath'],
         },
     },
     {
-        name: 'filesystem_create',
+        name: 'filesystem-create',
         description: 'PREFERRED tool for file creation: Create a new file with specified content. More reliable than terminal commands like echo/cat with redirects. Automatically creates parent directories if needed. Terminal commands can be used as a fallback if needed.',
         inputSchema: {
             type: 'object',
@@ -1291,7 +1052,7 @@ export const mcpTools = [
         },
     },
     {
-        name: 'filesystem_delete',
+        name: 'filesystem-delete',
         description: 'Delete one or multiple files. Supports both single file and batch deletion.',
         inputSchema: {
             type: 'object',
@@ -1321,7 +1082,7 @@ export const mcpTools = [
         },
     },
     {
-        name: 'filesystem_list',
+        name: 'filesystem-list',
         description: 'List files in a directory',
         inputSchema: {
             type: 'object',
@@ -1335,22 +1096,60 @@ export const mcpTools = [
         },
     },
     {
-        name: 'filesystem_edit_search',
-        description: '🎯 **RECOMMENDED** for most edits: Search-and-replace with SMART FUZZY MATCHING that automatically handles whitespace differences. **WORKFLOW**: (1) Use ace_text_search/ace_search_symbols to locate code, (2) Use filesystem_read to view content, (3) Copy the code block you want to change (without line numbers), (4) Use THIS tool - whitespace will be normalized automatically. **WHY**: No line tracking, auto-handles spacing/tabs, finds best match. **BEST FOR**: Modifying functions, fixing bugs, updating logic.',
+        name: 'filesystem-edit_search',
+        description: '🎯 **RECOMMENDED** for most edits: Search-and-replace with SMART FUZZY MATCHING. **SUPPORTS BATCH EDITING**: Pass (1) single file with search/replace, (2) array of file paths with unified search/replace, or (3) array of {path, searchContent, replaceContent, occurrence?} for per-file edits. **WORKFLOW**: (1) Use ace-text_search/ace-search_symbols to locate code, (2) Use filesystem-read to view content, (3) Copy code blocks (without line numbers), (4) Use THIS tool. **WHY**: No line tracking, auto-handles spacing/tabs, finds best match. **BATCH EXAMPLE**: filePath=[{path:"a.ts", searchContent:"old1", replaceContent:"new1"}, {path:"b.ts", searchContent:"old2", replaceContent:"new2"}]',
         inputSchema: {
             type: 'object',
             properties: {
                 filePath: {
-                    type: 'string',
-                    description: 'Path to the file to edit',
+                    oneOf: [
+                        {
+                            type: 'string',
+                            description: 'Path to a single file to edit',
+                        },
+                        {
+                            type: 'array',
+                            items: {
+                                type: 'string',
+                            },
+                            description: 'Array of file paths (uses unified searchContent/replaceContent from top-level)',
+                        },
+                        {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    path: {
+                                        type: 'string',
+                                        description: 'File path',
+                                    },
+                                    searchContent: {
+                                        type: 'string',
+                                        description: 'Content to search for in this file',
+                                    },
+                                    replaceContent: {
+                                        type: 'string',
+                                        description: 'New content to replace with',
+                                    },
+                                    occurrence: {
+                                        type: 'number',
+                                        description: 'Which match to replace (1-indexed, default: 1)',
+                                    },
+                                },
+                                required: ['path', 'searchContent', 'replaceContent'],
+                            },
+                            description: 'Array of edit config objects for per-file search-replace operations',
+                        },
+                    ],
+                    description: 'File path(s) to edit',
                 },
                 searchContent: {
                     type: 'string',
-                    description: 'Content to find and replace. Copy from filesystem_read output WITHOUT line numbers (e.g., "123→"). Whitespace differences are automatically handled - focus on getting the content right.',
+                    description: 'Content to find and replace (for single file or unified mode). Copy from filesystem-read WITHOUT line numbers.',
                 },
                 replaceContent: {
                     type: 'string',
-                    description: 'New content to replace with. Indentation will be preserved automatically.',
+                    description: 'New content to replace with (for single file or unified mode)',
                 },
                 occurrence: {
                     type: 'number',
@@ -1363,30 +1162,68 @@ export const mcpTools = [
                     default: 8,
                 },
             },
-            required: ['filePath', 'searchContent', 'replaceContent'],
+            required: ['filePath'],
         },
     },
     {
-        name: 'filesystem_edit',
-        description: "🔧 Line-based editing for precise control. **WHEN TO USE**: (1) Adding completely new code sections, (2) Deleting specific line ranges, (3) When search-replace is not suitable. **WORKFLOW**: (1) Use ace_text_search/ace_file_outline to locate relevant area, (2) Use filesystem_read to get exact line numbers, (3) Use THIS tool with precise line ranges. **RECOMMENDATION**: For modifying existing code, use filesystem_edit_search instead - it's safer. **BEST PRACTICES**: Keep edits small (≤15 lines), double-check line numbers, verify bracket closure.",
+        name: 'filesystem-edit',
+        description: '🔧 Line-based editing for precise control. **SUPPORTS BATCH EDITING**: Pass (1) single file with line range, (2) array of file paths with unified line range, or (3) array of {path, startLine, endLine, newContent} for per-file edits. **WHEN TO USE**: (1) Adding new code sections, (2) Deleting specific line ranges, (3) When search-replace not suitable. **WORKFLOW**: (1) Use ace-text_search/ace-file_outline to locate area, (2) Use filesystem-read to get line numbers, (3) Use THIS tool. **RECOMMENDATION**: For modifying existing code, use filesystem-edit_search - safer. **BATCH EXAMPLE**: filePath=[{path:"a.ts", startLine:10, endLine:20, newContent:"..."}, {path:"b.ts", startLine:50, endLine:60, newContent:"..."}]',
         inputSchema: {
             type: 'object',
             properties: {
                 filePath: {
-                    type: 'string',
-                    description: 'Path to the file to edit (absolute or relative)',
+                    oneOf: [
+                        {
+                            type: 'string',
+                            description: 'Path to a single file to edit',
+                        },
+                        {
+                            type: 'array',
+                            items: {
+                                type: 'string',
+                            },
+                            description: 'Array of file paths (uses unified startLine/endLine/newContent from top-level)',
+                        },
+                        {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    path: {
+                                        type: 'string',
+                                        description: 'File path',
+                                    },
+                                    startLine: {
+                                        type: 'number',
+                                        description: 'Starting line number (1-indexed, inclusive)',
+                                    },
+                                    endLine: {
+                                        type: 'number',
+                                        description: 'Ending line number (1-indexed, inclusive)',
+                                    },
+                                    newContent: {
+                                        type: 'string',
+                                        description: 'New content to replace lines (without line numbers)',
+                                    },
+                                },
+                                required: ['path', 'startLine', 'endLine', 'newContent'],
+                            },
+                            description: 'Array of edit config objects for per-file line-based edits',
+                        },
+                    ],
+                    description: 'File path(s) to edit',
                 },
                 startLine: {
                     type: 'number',
-                    description: '⚠️  CRITICAL: Starting line number (1-indexed, inclusive). MUST match exact line number from filesystem_read output. Double-check this value!',
+                    description: '⚠️  CRITICAL: Starting line number (1-indexed, inclusive) for single file or unified mode. MUST match filesystem-read output.',
                 },
                 endLine: {
                     type: 'number',
-                    description: '⚠️  CRITICAL: Ending line number (1-indexed, inclusive). MUST match exact line number from filesystem_read output. 💡 TIP: Keep edits small (≤15 lines recommended) for better accuracy.',
+                    description: '⚠️  CRITICAL: Ending line number (1-indexed, inclusive) for single file or unified mode. Keep edits small (≤15 lines).',
                 },
                 newContent: {
                     type: 'string',
-                    description: 'New content to replace specified lines. ⚠️  Do NOT include line numbers. ⚠️  Ensure proper indentation and bracket closure. Keep changes MINIMAL and FOCUSED.',
+                    description: 'New content to replace specified lines (for single file or unified mode). ⚠️  Do NOT include line numbers. Ensure proper indentation.',
                 },
                 contextLines: {
                     type: 'number',
@@ -1394,7 +1231,7 @@ export const mcpTools = [
                     default: 8,
                 },
             },
-            required: ['filePath', 'startLine', 'endLine', 'newContent'],
+            required: ['filePath'],
         },
     },
 ];