byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/file-system/file-system-service.js

@@ -5,9 +5,113 @@ import { EOL } from 'node:os';
 import path from 'node:path';
 import { DirectoryNotFoundError, EditOperationError, FileNotFoundError, FileTooLargeError, GlobOperationError, InvalidExtensionError, InvalidPathError, InvalidPatternError, PathBlockedError, PathNotAllowedError, PathTraversalError, ReadOperationError, SearchOperationError, ServiceNotInitializedError, StringNotFoundError, StringNotUniqueError, WriteOperationError, } from '../../../core/domain/cipher/errors/file-system-error.js';
 import { getErrorMessage } from '../../../utils/error-helpers.js';
+import { getMimeType, isBinaryFile, isMediaFile, isPdfFile } from './binary-utils.js';
 import { createGitignoreFilter } from './gitignore-filter.js';
 import { collectFileMetadata, escapeIfExactMatch, extractPaths, sortFilesByRecency } from './glob-utils.js';
 import { PathValidator } from './path-validator.js';
+/**
+ * Maximum line length for search results.
+ * Prevents context overflow from minified files or long lines.
+ */
+const MAX_LINE_LENGTH = 2000;
+/**
+ * Default number of lines to read when no limit specified.
+ * Prevents context overflow while providing enough content.
+ */
+const DEFAULT_READ_LIMIT = 2000;
+/**
+ * Number of lines to include in the preview.
+ */
+const PREVIEW_LINES = 20;
+/**
+ * Buffer size for binary file detection (4KB sample).
+ */
+const BINARY_DETECTION_BUFFER_SIZE = 4096;
+/**
+ * Whitelist of .env file patterns that are safe to read.
+ * These are typically example/template files without real secrets.
+ */
+const ENV_WHITELIST = ['.env.sample', '.env.example', '.env.template', '.env.defaults'];
+/**
+ * Truncates a line to MAX_LINE_LENGTH, adding ellipsis if truncated.
+ */
+function truncateLine(line) {
+    if (line.length <= MAX_LINE_LENGTH) {
+        return line;
+    }
+    return line.slice(0, MAX_LINE_LENGTH) + '...';
+}
+/**
+ * Formats content with line numbers in 00001| format.
+ * @param lines - Array of lines to format
+ * @param startLine - Starting line number (1-based)
+ * @returns Formatted string with line numbers
+ */
+function formatWithLineNumbers(lines, startLine) {
+    return lines
+        .map((line, index) => {
+        const lineNum = (startLine + index).toString().padStart(5, '0');
+        return `${lineNum}| ${line}`;
+    })
+        .join('\n');
+}
+/**
+ * Finds similar files in a directory for "Did you mean?" suggestions.
+ * @param dirPath - Directory to search in
+ * @param fileName - File name to find similar matches for
+ * @returns Array of suggested file paths (max 3)
+ */
+async function findSimilarFiles(dirPath, fileName) {
+    try {
+        const entries = await fs.readdir(dirPath);
+        const lowerFileName = fileName.toLowerCase();
+        const suggestions = entries
+            .filter((entry) => {
+            const lowerEntry = entry.toLowerCase();
+            return lowerEntry.includes(lowerFileName) || lowerFileName.includes(lowerEntry);
+        })
+            .slice(0, 3)
+            .map((entry) => path.join(dirPath, entry));
+        return suggestions;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Default patterns to ignore when listing directories.
+ * Common build artifacts, caches, and IDE directories.
+ */
+const DEFAULT_IGNORE_PATTERNS = [
+    'node_modules/',
+    '__pycache__/',
+    '.git/',
+    'dist/',
+    'build/',
+    'target/',
+    'vendor/',
+    'bin/',
+    'obj/',
+    '.idea/',
+    '.vscode/',
+    '.zig-cache/',
+    'zig-out/',
+    '.coverage/',
+    'coverage/',
+    'tmp/',
+    'temp/',
+    '.cache/',
+    'cache/',
+    'logs/',
+    '.venv/',
+    'venv/',
+    'env/',
+    '.byterover/',
+];
+/**
+ * Maximum number of files for directory listing.
+ */
+const LIST_DIRECTORY_LIMIT = 100;
 /**
  * File system service implementation.
  * Provides secure, validated file system operations with comprehensive
@@ -200,17 +304,108 @@ export class FileSystemService {
         }
         this.initialized = true;
     }
+    /**
+     * List files and directories in a path.
+     */
+    async listDirectory(dirPath, options = {}) {
+        this.ensureInitialized();
+        // Resolve path
+        const resolvedPath = path.resolve(this.config.workingDirectory, dirPath || '.');
+        // Validate path
+        const validation = this.pathValidator.validate(resolvedPath, 'read');
+        if (!validation.valid) {
+            this.throwValidationError(resolvedPath, validation.error);
+        }
+        const { normalizedPath } = validation;
+        // Verify directory exists
+        try {
+            const stats = await fs.stat(normalizedPath);
+            if (!stats.isDirectory()) {
+                throw new DirectoryNotFoundError(normalizedPath);
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new DirectoryNotFoundError(normalizedPath);
+            }
+            throw error;
+        }
+        const maxResults = options.maxResults ?? LIST_DIRECTORY_LIMIT;
+        const ignorePatterns = [...DEFAULT_IGNORE_PATTERNS, ...(options.ignore ?? [])];
+        // Use glob with ** pattern to get all files
+        const files = await glob('**/*', {
+            absolute: false,
+            cwd: normalizedPath,
+            follow: false,
+            ignore: ignorePatterns.map((p) => `**/${p}**`),
+            nodir: true,
+        });
+        // Limit results
+        const truncated = files.length > maxResults;
+        const limitedFiles = files.slice(0, maxResults);
+        // Build directory structure
+        const dirs = new Set();
+        const filesByDir = new Map();
+        for (const file of limitedFiles) {
+            const dir = path.dirname(file);
+            const parts = dir === '.' ? [] : dir.split('/');
+            // Add all parent directories
+            for (let i = 0; i <= parts.length; i++) {
+                const currentDirPath = i === 0 ? '.' : parts.slice(0, i).join('/');
+                dirs.add(currentDirPath);
+            }
+            // Add file to its directory
+            if (!filesByDir.has(dir)) {
+                filesByDir.set(dir, []);
+            }
+            filesByDir.get(dir).push(path.basename(file));
+        }
+        // Build entries array
+        const entries = limitedFiles.map((file) => ({
+            isDirectory: false,
+            name: path.basename(file),
+            path: file,
+        }));
+        // Render tree
+        const tree = this.renderDirectoryTree(normalizedPath, dirs, filesByDir);
+        return {
+            count: limitedFiles.length,
+            entries,
+            tree,
+            truncated,
+        };
+    }
     /**
      * Read the contents of a file.
+     *
+     * Features:
+     * - Relative path support (resolved against working directory)
+     * - Image/PDF files returned as base64 attachments
+     * - Binary file detection and rejection
+     * - .env file blocking with whitelist for example files
+     * - XML-wrapped output for clearer LLM parsing
+     * - Preview metadata (first 20 lines)
      */
     async readFile(filePath, options = {}) {
         this.ensureInitialized();
+        // Resolve relative paths against working directory
+        let resolvedPath = filePath;
+        if (!path.isAbsolute(filePath)) {
+            resolvedPath = path.resolve(this.config.workingDirectory, filePath);
+        }
         // Validate path
-        const validation = this.pathValidator.validate(filePath, 'read');
+        const validation = this.pathValidator.validate(resolvedPath, 'read');
         if (!validation.valid) {
-            this.throwValidationError(filePath, validation.error);
+            this.throwValidationError(resolvedPath, validation.error);
         }
         const { normalizedPath } = validation;
+        // Check .env file whitelist (allow .env.sample, .env.example, etc.)
+        const fileName = path.basename(normalizedPath).toLowerCase();
+        const isEnvFile = fileName.includes('.env');
+        const isWhitelisted = ENV_WHITELIST.some((w) => fileName.endsWith(w));
+        if (isEnvFile && !isWhitelisted) {
+            throw new PathBlockedError(normalizedPath, 'Environment files are blocked for security. Only example files (.env.sample, .env.example) are allowed.');
+        }
         try {
             // Check if file exists
             let stats;
@@ -219,6 +414,13 @@ export class FileSystemService {
             }
             catch (error) {
                 if (error.code === 'ENOENT') {
+                    // Try to find similar files for suggestions
+                    const dirPath = path.dirname(normalizedPath);
+                    const baseName = path.basename(normalizedPath);
+                    const suggestions = await findSimilarFiles(dirPath, baseName);
+                    if (suggestions.length > 0) {
+                        throw new FileNotFoundError(normalizedPath, `File not found: ${normalizedPath}\n\nDid you mean one of these?\n${suggestions.join('\n')}`);
+                    }
                     throw new FileNotFoundError(normalizedPath);
                 }
                 throw error;
@@ -227,30 +429,81 @@ export class FileSystemService {
             if (stats.size > this.config.maxFileSize) {
                 throw new FileTooLargeError(normalizedPath, stats.size, this.config.maxFileSize);
             }
-            // Read file
+            // Handle image/PDF files - return as base64 attachment
+            if (isMediaFile(normalizedPath)) {
+                const buffer = await fs.readFile(normalizedPath);
+                const mimeType = getMimeType(normalizedPath) ?? 'application/octet-stream';
+                const fileType = isPdfFile(normalizedPath) ? 'PDF' : 'Image';
+                const baseName = path.basename(normalizedPath);
+                return {
+                    attachment: {
+                        base64: buffer.toString('base64'),
+                        fileName: baseName,
+                        mimeType,
+                    },
+                    content: `[${fileType} file: ${baseName}]`,
+                    encoding: 'base64',
+                    formattedContent: `<file>\n[${fileType} file: ${baseName} (${stats.size} bytes)]\n</file>`,
+                    lines: 1,
+                    message: `${fileType} file read successfully. Content available as base64 attachment.`,
+                    size: stats.size,
+                    totalLines: 1,
+                    truncated: false,
+                };
+            }
+            // Check for binary files (read first 4KB for detection)
+            const handle = await fs.open(normalizedPath, 'r');
+            const sampleBuffer = Buffer.alloc(BINARY_DETECTION_BUFFER_SIZE);
+            const { bytesRead } = await handle.read(sampleBuffer, 0, BINARY_DETECTION_BUFFER_SIZE, 0);
+            await handle.close();
+            if (isBinaryFile(normalizedPath, sampleBuffer.subarray(0, bytesRead))) {
+                throw new ReadOperationError(normalizedPath, 'Cannot read binary file. Use a hex editor or appropriate tool for binary files.');
+            }
+            // Read text file
             const encoding = (options.encoding ?? 'utf8');
-            const content = await fs.readFile(normalizedPath, encoding);
-            // Handle pagination
-            const lines = content.split('\n');
-            let selectedLines;
-            let truncated = false;
-            // Apply offset (1-based, like text editors)
-            const { limit, offset: offset1 } = options;
-            if (offset1 !== undefined || limit !== undefined) {
-                const start = offset1 !== undefined && offset1 > 0 ? Math.max(0, offset1 - 1) : 0;
-                const end = limit === undefined ? lines.length : start + limit;
-                selectedLines = lines.slice(start, end);
-                truncated = end < lines.length;
+            const rawContent = await fs.readFile(normalizedPath, encoding);
+            // Split into lines
+            const allLines = rawContent.split('\n');
+            const totalLines = allLines.length;
+            // Apply offset and limit (with default limit of 2000)
+            const offset = options.offset !== undefined && options.offset > 0 ? options.offset - 1 : 0;
+            const limit = options.limit ?? DEFAULT_READ_LIMIT;
+            const endLine = Math.min(offset + limit, totalLines);
+            const selectedLines = allLines.slice(offset, endLine);
+            const truncated = endLine < totalLines;
+            // Truncate long lines
+            const truncatedLines = selectedLines.map((line) => truncateLine(line));
+            // Format with line numbers
+            const numberedContent = formatWithLineNumbers(truncatedLines, offset + 1);
+            // Build informative message
+            const lastReadLine = offset + selectedLines.length;
+            let message;
+            if (truncated) {
+                const remainingLines = totalLines - lastReadLine;
+                message =
+                    `Read lines ${offset + 1}-${lastReadLine} of ${totalLines} total lines. ` +
+                        `${remainingLines} more lines available. Use offset=${lastReadLine + 1} to continue reading.`;
             }
             else {
-                selectedLines = lines;
+                message = `End of file - read ${selectedLines.length} lines (${totalLines} total).`;
             }
-            const selectedContent = selectedLines.join('\n');
+            // Generate preview (first N lines of selected content)
+            const previewLines = truncatedLines.slice(0, PREVIEW_LINES);
+            const preview = previewLines.join('\n');
+            // Wrap in XML tags for clearer LLM parsing
+            const truncationNote = truncated
+                ? `\n\n(File has more lines. Use offset=${lastReadLine + 1} to continue)`
+                : `\n\n(End of file - ${totalLines} lines)`;
+            const formattedContent = `<file>\n${numberedContent}${truncationNote}\n</file>`;
             return {
-                content: selectedContent,
+                content: truncatedLines.join('\n'),
                 encoding,
+                formattedContent,
                 lines: selectedLines.length,
+                message,
+                preview,
                 size: stats.size,
+                totalLines,
                 truncated,
             };
         }
@@ -260,7 +513,8 @@ export class FileSystemService {
                 error instanceof FileTooLargeError ||
                 error instanceof PathNotAllowedError ||
                 error instanceof PathTraversalError ||
-                error instanceof PathBlockedError) {
+                error instanceof PathBlockedError ||
+                error instanceof ReadOperationError) {
                 throw error;
             }
             // Wrap other errors
@@ -291,12 +545,24 @@ export class FileSystemService {
             if (matches === null) {
                 return this.searchContentJS(pattern, options);
             }
+            // Collect file modification times for sorting (recent files first)
+            const matchesWithMtime = await Promise.all(matches.map(async (match) => {
+                try {
+                    const stats = await fs.stat(match.file);
+                    return { ...match, mtime: stats.mtime.getTime() };
+                }
+                catch {
+                    return { ...match, mtime: 0 };
+                }
+            }));
+            // Sort by modification time (newest first)
+            matchesWithMtime.sort((a, b) => (b.mtime ?? 0) - (a.mtime ?? 0));
             // Apply maxResults limit
-            const truncated = matches.length > maxResults;
+            const truncated = matchesWithMtime.length > maxResults;
             return {
-                filesSearched: new Set(matches.map((m) => m.file)).size,
-                matches: matches.slice(0, maxResults),
-                totalMatches: matches.length,
+                filesSearched: new Set(matchesWithMtime.map((m) => m.file)).size,
+                matches: matchesWithMtime.slice(0, maxResults),
+                totalMatches: matchesWithMtime.length,
                 truncated,
             };
         }
@@ -373,11 +639,11 @@ export class FileSystemService {
         if (contextLines > 0) {
             // Lines before
             for (let j = Math.max(0, lineIndex - contextLines); j < lineIndex; j++) {
-                before.push(lines[j]);
+                before.push(truncateLine(lines[j]));
             }
             // Lines after
             for (let j = lineIndex + 1; j < Math.min(lines.length, lineIndex + 1 + contextLines); j++) {
-                after.push(lines[j]);
+                after.push(truncateLine(lines[j]));
             }
         }
         return { after, before };
@@ -493,13 +759,38 @@ export class FileSystemService {
             if (!Number.isNaN(lineNumber)) {
                 results.push({
                     file: path.resolve(basePath, filePath),
-                    line: content,
+                    line: truncateLine(content),
                     lineNumber,
                 });
             }
         }
         return results;
     }
+    /**
+     * Renders a directory tree as a string.
+     */
+    renderDirectoryTree(basePath, dirs, filesByDir) {
+        const renderDir = (dirPath, depth) => {
+            const indent = '  '.repeat(depth);
+            let output = '';
+            if (depth > 0) {
+                output += `${indent}${path.basename(dirPath)}/\n`;
+            }
+            const childIndent = '  '.repeat(depth + 1);
+            const children = [...dirs].filter((d) => path.dirname(d) === dirPath && d !== dirPath).sort();
+            // Render subdirectories first
+            for (const child of children) {
+                output += renderDir(child, depth + 1);
+            }
+            // Render files
+            const files = filesByDir.get(dirPath) ?? [];
+            for (const file of files.sort()) {
+                output += `${childIndent}${file}\n`;
+            }
+            return output;
+        };
+        return `${basePath}/\n${renderDir('.', 0)}`;
+    }
     /**
      * JavaScript-based content search implementation.
      * Used as fallback when native grep commands are unavailable or when context lines are needed.
@@ -548,7 +839,7 @@ export class FileSystemService {
                 matches.push({
                     context: contextLines > 0 ? context : undefined,
                     file: filePath,
-                    line,
+                    line: truncateLine(line),
                     lineNumber: i + 1, // 1-based line numbers
                 });
             }
@@ -600,7 +891,7 @@ export class FileSystemService {
             const child = spawn(cmd, args, { cwd, windowsHide: true });
             const chunks = [];
             if (signal) {
-                signal.addEventListener('abort', () => child.kill());
+                signal.addEventListener('abort', () => child.kill(), { once: true });
             }
             child.stdout.on('data', (chunk) => chunks.push(chunk));
             child.on('error', reject);
@@ -618,24 +909,24 @@ export class FileSystemService {
     /**
      * Throws the appropriate error based on validation error message.
      */
-    throwValidationError(path, error) {
+    throwValidationError(filePath, error) {
         if (error.includes('empty')) {
-            throw new InvalidPathError(path, error);
+            throw new InvalidPathError(filePath, error);
         }
         if (error.includes('traversal')) {
-            throw new PathTraversalError(path);
+            throw new PathTraversalError(filePath);
         }
         if (error.includes('not in allowed paths')) {
-            throw new PathNotAllowedError(path, this.config.allowedPaths);
+            throw new PathNotAllowedError(filePath, this.config.allowedPaths);
         }
         if (error.includes('blocked')) {
-            throw new PathBlockedError(path, error);
+            throw new PathBlockedError(filePath, error);
         }
         if (error.includes('extension')) {
-            const ext = path.split('.').pop() ?? '';
-            throw new InvalidExtensionError(path, ext);
+            const ext = filePath.split('.').pop() ?? '';
+            throw new InvalidExtensionError(filePath, ext);
         }
         // Fallback
-        throw new InvalidPathError(path, error);
+        throw new InvalidPathError(filePath, error);
     }
 }

package/dist/infra/cipher/file-system/path-validator.d.ts

@@ -62,8 +62,40 @@ export declare class PathValidator {
      * Normalizes and resolves a file path to an absolute path.
      * Uses realpath to resolve symlinks if the path exists.
      *
+     * Handles path duplication prevention:
+     * - If the working directory ends with a path segment that matches the start
+     *   of the relative file path, the resolution is adjusted to prevent duplication.
+     * - Example: workingDir = "/project/.brv/context-tree", filePath = ".brv/context-tree/domain/file.md"
+     *   Without fix: "/project/.brv/context-tree/.brv/context-tree/domain/file.md" (WRONG)
+     *   With fix: "/project/.brv/context-tree/domain/file.md" (CORRECT)
+     *
      * @param filePath - Path to normalize
      * @returns Normalized absolute path
      */
     private normalizeAndResolve;
+    /**
+     * For non-existent files, try to resolve the parent directory's real path
+     * and append the filename. This ensures consistency with existing paths
+     * when symlinks are involved (e.g., /var -> /private/var on macOS).
+     *
+     * @param filePath - Absolute path to a potentially non-existent file
+     * @returns Path with parent directory symlinks resolved
+     */
+    private resolveParentRealPath;
+    /**
+     * Resolves a relative path against the working directory while preventing
+     * path segment duplication.
+     *
+     * @param filePath - Relative path to resolve
+     * @returns Resolved absolute path
+     */
+    private resolveWithoutDuplication;
+    /**
+     * Checks if two arrays of path segments match.
+     *
+     * @param segments1 - First array of path segments
+     * @param segments2 - Second array of path segments
+     * @returns True if all segments match
+     */
+    private segmentsMatch;
 }

package/dist/infra/cipher/file-system/path-validator.js

@@ -21,10 +21,28 @@ export class PathValidator {
      * @param config - File system configuration
      */
     constructor(config) {
-        this.workingDirectory = path.resolve(config.workingDirectory);
+        // Resolve working directory, trying to resolve symlinks for consistency
+        const resolvedWorkingDir = path.resolve(config.workingDirectory);
+        try {
+            this.workingDirectory = realpathSync.native(resolvedWorkingDir);
+        }
+        catch {
+            this.workingDirectory = resolvedWorkingDir;
+        }
         this.blockedExtensions = new Set(config.blockedExtensions.map((ext) => ext.toLowerCase()));
         // Normalize and resolve all allowed paths to absolute paths
-        this.normalizedAllowedPaths = config.allowedPaths.map((allowedPath) => path.resolve(this.workingDirectory, allowedPath));
+        // Also try to resolve symlinks for consistent comparison with realpathSync results
+        this.normalizedAllowedPaths = config.allowedPaths.map((allowedPath) => {
+            const resolved = path.resolve(this.workingDirectory, allowedPath);
+            try {
+                // Try to get the real path (resolving symlinks like /var -> /private/var on macOS)
+                return realpathSync.native(resolved);
+            }
+            catch {
+                // Path might not exist yet, use resolved path as-is
+                return resolved;
+            }
+        });
         // Normalize blocked paths
         this.normalizedBlockedPaths = config.blockedPaths.map((blockedPath) => path.isAbsolute(blockedPath) ? path.normalize(blockedPath) : blockedPath);
     }
@@ -164,21 +182,108 @@ export class PathValidator {
      * Normalizes and resolves a file path to an absolute path.
      * Uses realpath to resolve symlinks if the path exists.
      *
+     * Handles path duplication prevention:
+     * - If the working directory ends with a path segment that matches the start
+     *   of the relative file path, the resolution is adjusted to prevent duplication.
+     * - Example: workingDir = "/project/.brv/context-tree", filePath = ".brv/context-tree/domain/file.md"
+     *   Without fix: "/project/.brv/context-tree/.brv/context-tree/domain/file.md" (WRONG)
+     *   With fix: "/project/.brv/context-tree/domain/file.md" (CORRECT)
+     *
      * @param filePath - Path to normalize
      * @returns Normalized absolute path
      */
     normalizeAndResolve(filePath) {
-        // First resolve relative to working directory
-        let normalizedPath = path.resolve(this.workingDirectory, filePath);
+        // If the path is already absolute, just normalize it.
+        // For relative paths, check for potential path duplication.
+        // This can happen when:
+        // 1. workingDirectory ends with a subdirectory like ".brv/context-tree"
+        // 2. filePath starts with the same subdirectory ".brv/context-tree/..."
+        // In this case, we should resolve from the parent to avoid duplication.
+        let normalizedPath = path.isAbsolute(filePath)
+            ? path.normalize(filePath)
+            : this.resolveWithoutDuplication(filePath);
         // Try to resolve symlinks if path exists
         try {
             // Use native variant to preserve casing on Windows
             normalizedPath = realpathSync.native(normalizedPath);
         }
         catch {
-            // Path doesn't exist yet (e.g., for writes) - use resolved path as-is
-            normalizedPath = path.normalize(normalizedPath);
+            // Path doesn't exist yet (e.g., for writes)
+            // Try to resolve the parent directory's real path for consistency
+            normalizedPath = this.resolveParentRealPath(normalizedPath);
         }
         return normalizedPath;
     }
+    /**
+     * For non-existent files, try to resolve the parent directory's real path
+     * and append the filename. This ensures consistency with existing paths
+     * when symlinks are involved (e.g., /var -> /private/var on macOS).
+     *
+     * @param filePath - Absolute path to a potentially non-existent file
+     * @returns Path with parent directory symlinks resolved
+     */
+    resolveParentRealPath(filePath) {
+        const dir = path.dirname(filePath);
+        const base = path.basename(filePath);
+        try {
+            // Try to resolve the parent directory
+            const realDir = realpathSync.native(dir);
+            return path.join(realDir, base);
+        }
+        catch {
+            // Parent doesn't exist either, try grandparent
+            const grandparentDir = path.dirname(dir);
+            const parentBase = path.basename(dir);
+            try {
+                const realGrandparent = realpathSync.native(grandparentDir);
+                return path.join(realGrandparent, parentBase, base);
+            }
+            catch {
+                // Give up and return normalized path
+                return path.normalize(filePath);
+            }
+        }
+    }
+    /**
+     * Resolves a relative path against the working directory while preventing
+     * path segment duplication.
+     *
+     * @param filePath - Relative path to resolve
+     * @returns Resolved absolute path
+     */
+    resolveWithoutDuplication(filePath) {
+        // Normalize the file path to handle different separators
+        const normalizedFilePath = path.normalize(filePath);
+        // Split both paths into segments for comparison
+        const workingDirSegments = this.workingDirectory.split(path.sep).filter(Boolean);
+        const filePathSegments = normalizedFilePath.split(path.sep).filter(Boolean);
+        // Try to find a matching suffix of workingDirectory that matches
+        // the prefix of filePath to detect potential duplication
+        for (let suffixLen = Math.min(workingDirSegments.length, filePathSegments.length); suffixLen > 0; suffixLen--) {
+            const workingDirSuffix = workingDirSegments.slice(-suffixLen);
+            const filePathPrefix = filePathSegments.slice(0, suffixLen);
+            // Check if the suffix of working dir matches the prefix of file path
+            if (this.segmentsMatch(workingDirSuffix, filePathPrefix)) {
+                // Found a match! Remove the duplicate prefix from file path
+                // and resolve from working directory
+                const remainingSegments = filePathSegments.slice(suffixLen);
+                return path.join(this.workingDirectory, ...remainingSegments);
+            }
+        }
+        // No duplication detected, resolve normally
+        return path.resolve(this.workingDirectory, filePath);
+    }
+    /**
+     * Checks if two arrays of path segments match.
+     *
+     * @param segments1 - First array of path segments
+     * @param segments2 - Second array of path segments
+     * @returns True if all segments match
+     */
+    segmentsMatch(segments1, segments2) {
+        if (segments1.length !== segments2.length) {
+            return false;
+        }
+        return segments1.every((seg, i) => seg === segments2[i]);
+    }
 }