byterover-cli 0.2.0 → 0.3.0

package/dist/infra/cipher/file-system/gitignore-filter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Result of filtering paths through gitignore rules.
+ */
+export interface FilterResult {
+    /** Paths that passed the filter (not ignored) */
+    filtered: string[];
+    /** Number of paths that were ignored */
+    ignoredCount: number;
+}
+/**
+ * GitignoreFilter handles .gitignore-based file filtering.
+ *
+ * It reads .gitignore files from the project root and applies
+ * the ignore rules to filter out paths that should be excluded.
+ *
+ * Usage:
+ * ```typescript
+ * const filter = new GitignoreFilter('/path/to/project')
+ * await filter.initialize()
+ * const result = filter.filterPaths(['src/index.ts', 'node_modules/pkg/index.js'])
+ * // result.filtered = ['src/index.ts']
+ * // result.ignoredCount = 1
+ * ```
+ */
+export declare class GitignoreFilter {
+    private ig;
+    private initialized;
+    private readonly rootPath;
+    /**
+     * Creates a new GitignoreFilter instance.
+     *
+     * @param rootPath - Root path of the project to search for .gitignore files
+     */
+    constructor(rootPath: string);
+    /**
+     * Filters an array of paths, removing those that match gitignore rules.
+     *
+     * @param relativePaths - Array of paths relative to the root to filter
+     * @returns FilterResult with filtered paths and ignored count
+     * @throws Error if filter not initialized
+     */
+    filterPaths(relativePaths: string[]): FilterResult;
+    /**
+     * Initializes the filter by reading .gitignore files.
+     * Must be called before using filterPaths or isIgnored.
+     *
+     * Reads:
+     * - .gitignore from the root path
+     * - Optionally could be extended to read nested .gitignore files
+     *
+     * Always adds common ignore patterns:
+     * - .git directory
+     */
+    initialize(): Promise<void>;
+    /**
+     * Checks if a single path is ignored by gitignore rules.
+     *
+     * @param relativePath - Path relative to the root to check
+     * @returns true if the path should be ignored
+     * @throws Error if filter not initialized
+     */
+    isIgnored(relativePath: string): boolean;
+    /**
+     * Checks if the filter has been initialized.
+     *
+     * @returns true if initialize() has been called
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Creates and initializes a GitignoreFilter for the given path.
+ * Convenience function that combines construction and initialization.
+ *
+ * @param rootPath - Root path of the project
+ * @returns Initialized GitignoreFilter instance
+ */
+export declare function createGitignoreFilter(rootPath: string): Promise<GitignoreFilter>;

package/dist/infra/cipher/file-system/gitignore-filter.js

@@ -0,0 +1,120 @@
+import ignore from 'ignore';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * GitignoreFilter handles .gitignore-based file filtering.
+ *
+ * It reads .gitignore files from the project root and applies
+ * the ignore rules to filter out paths that should be excluded.
+ *
+ * Usage:
+ * ```typescript
+ * const filter = new GitignoreFilter('/path/to/project')
+ * await filter.initialize()
+ * const result = filter.filterPaths(['src/index.ts', 'node_modules/pkg/index.js'])
+ * // result.filtered = ['src/index.ts']
+ * // result.ignoredCount = 1
+ * ```
+ */
+export class GitignoreFilter {
+    ig;
+    initialized = false;
+    rootPath;
+    /**
+     * Creates a new GitignoreFilter instance.
+     *
+     * @param rootPath - Root path of the project to search for .gitignore files
+     */
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+        this.ig = ignore();
+    }
+    /**
+     * Filters an array of paths, removing those that match gitignore rules.
+     *
+     * @param relativePaths - Array of paths relative to the root to filter
+     * @returns FilterResult with filtered paths and ignored count
+     * @throws Error if filter not initialized
+     */
+    filterPaths(relativePaths) {
+        if (!this.initialized) {
+            throw new Error('GitignoreFilter not initialized. Call initialize() first.');
+        }
+        const filtered = [];
+        let ignoredCount = 0;
+        for (const relativePath of relativePaths) {
+            // Normalize path separators
+            const normalizedPath = relativePath.split(path.sep).join('/');
+            if (this.ig.ignores(normalizedPath)) {
+                ignoredCount++;
+            }
+            else {
+                filtered.push(relativePath);
+            }
+        }
+        return { filtered, ignoredCount };
+    }
+    /**
+     * Initializes the filter by reading .gitignore files.
+     * Must be called before using filterPaths or isIgnored.
+     *
+     * Reads:
+     * - .gitignore from the root path
+     * - Optionally could be extended to read nested .gitignore files
+     *
+     * Always adds common ignore patterns:
+     * - .git directory
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Always ignore .git directory
+        this.ig.add('.git');
+        // Try to read .gitignore from root
+        const gitignorePath = path.join(this.rootPath, '.gitignore');
+        try {
+            const content = await fs.readFile(gitignorePath, 'utf8');
+            this.ig.add(content);
+        }
+        catch {
+            // .gitignore doesn't exist or can't be read, continue without it
+        }
+        this.initialized = true;
+    }
+    /**
+     * Checks if a single path is ignored by gitignore rules.
+     *
+     * @param relativePath - Path relative to the root to check
+     * @returns true if the path should be ignored
+     * @throws Error if filter not initialized
+     */
+    isIgnored(relativePath) {
+        if (!this.initialized) {
+            throw new Error('GitignoreFilter not initialized. Call initialize() first.');
+        }
+        // Normalize path separators for cross-platform compatibility
+        const normalizedPath = relativePath.split(path.sep).join('/');
+        return this.ig.ignores(normalizedPath);
+    }
+    /**
+     * Checks if the filter has been initialized.
+     *
+     * @returns true if initialize() has been called
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+}
+/**
+ * Creates and initializes a GitignoreFilter for the given path.
+ * Convenience function that combines construction and initialization.
+ *
+ * @param rootPath - Root path of the project
+ * @returns Initialized GitignoreFilter instance
+ */
+export async function createGitignoreFilter(rootPath) {
+    const filter = new GitignoreFilter(rootPath);
+    await filter.initialize();
+    return filter;
+}

package/dist/infra/cipher/file-system/glob-utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * File metadata for sorting purposes.
+ */
+export interface FileMetadata {
+    modifiedTime: Date;
+    path: string;
+    size: number;
+}
+/**
+ * Default recency threshold: 24 hours in milliseconds.
+ * Files modified within this period are considered "recent".
+ */
+export declare const RECENCY_THRESHOLD_MS: number;
+/**
+ * Collects metadata for a list of file paths.
+ *
+ * @param filePaths - Array of file paths to collect metadata for
+ * @param basePath - Base path for resolving relative paths
+ * @returns Promise resolving to array of FileMetadata objects
+ */
+export declare function collectFileMetadata(filePaths: string[], basePath: string): Promise<FileMetadata[]>;
+/**
+ * Sorts files by recency with smart ordering:
+ * - Files modified within the recency threshold come first (newest to oldest)
+ * - Older files are sorted alphabetically
+ *
+ * This approach prioritizes recently modified files for developer convenience
+ * while maintaining predictable ordering for older files.
+ *
+ * @param files - Array of FileMetadata to sort
+ * @param recencyThresholdMs - Threshold in ms for considering a file "recent" (default: 24 hours)
+ * @returns Sorted array of FileMetadata
+ */
+export declare function sortFilesByRecency(files: FileMetadata[], recencyThresholdMs?: number): FileMetadata[];
+/**
+ * Escapes a pattern if it matches an actual file/directory.
+ *
+ * This handles edge cases where file/directory names contain glob special characters
+ * (e.g., `[test]`, `(dashboard)`, `file?.txt`). If the pattern exactly matches
+ * an existing path, we escape it to prevent glob interpretation.
+ *
+ * @param pattern - The glob pattern to potentially escape
+ * @param cwd - Current working directory for checking file existence
+ * @returns The pattern, escaped if it matches an existing file
+ */
+export declare function escapeIfExactMatch(pattern: string, cwd: string): Promise<string>;
+/**
+ * Escapes glob special characters in a string.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for use in glob patterns
+ */
+export declare function escapeGlobCharacters(str: string): string;
+/**
+ * Extracts paths from FileMetadata array.
+ *
+ * @param files - Array of FileMetadata
+ * @returns Array of file paths
+ */
+export declare function extractPaths(files: FileMetadata[]): string[];

package/dist/infra/cipher/file-system/glob-utils.js

@@ -0,0 +1,120 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Default recency threshold: 24 hours in milliseconds.
+ * Files modified within this period are considered "recent".
+ */
+export const RECENCY_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Collects metadata for a list of file paths.
+ *
+ * @param filePaths - Array of file paths to collect metadata for
+ * @param basePath - Base path for resolving relative paths
+ * @returns Promise resolving to array of FileMetadata objects
+ */
+export async function collectFileMetadata(filePaths, basePath) {
+    const results = [];
+    for (const filePath of filePaths) {
+        try {
+            const fullPath = path.isAbsolute(filePath) ? filePath : path.join(basePath, filePath);
+            // eslint-disable-next-line no-await-in-loop
+            const stats = await fs.stat(fullPath);
+            results.push({
+                modifiedTime: stats.mtime,
+                path: filePath,
+                size: stats.size,
+            });
+        }
+        catch {
+            // If we can't stat the file, include it with default metadata
+            results.push({
+                modifiedTime: new Date(0),
+                path: filePath,
+                size: 0,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Sorts files by recency with smart ordering:
+ * - Files modified within the recency threshold come first (newest to oldest)
+ * - Older files are sorted alphabetically
+ *
+ * This approach prioritizes recently modified files for developer convenience
+ * while maintaining predictable ordering for older files.
+ *
+ * @param files - Array of FileMetadata to sort
+ * @param recencyThresholdMs - Threshold in ms for considering a file "recent" (default: 24 hours)
+ * @returns Sorted array of FileMetadata
+ */
+export function sortFilesByRecency(files, recencyThresholdMs = RECENCY_THRESHOLD_MS) {
+    const now = Date.now();
+    const threshold = now - recencyThresholdMs;
+    // Partition files into recent and old
+    const recentFiles = [];
+    const oldFiles = [];
+    for (const file of files) {
+        if (file.modifiedTime.getTime() >= threshold) {
+            recentFiles.push(file);
+        }
+        else {
+            oldFiles.push(file);
+        }
+    }
+    // Sort recent files by modification time (newest first)
+    recentFiles.sort((a, b) => b.modifiedTime.getTime() - a.modifiedTime.getTime());
+    // Sort old files alphabetically by path
+    oldFiles.sort((a, b) => a.path.localeCompare(b.path));
+    return [...recentFiles, ...oldFiles];
+}
+/**
+ * Glob special characters that need escaping.
+ */
+const GLOB_SPECIAL_CHARS = /[*?[\]{}()!@#]/;
+/**
+ * Escapes a pattern if it matches an actual file/directory.
+ *
+ * This handles edge cases where file/directory names contain glob special characters
+ * (e.g., `[test]`, `(dashboard)`, `file?.txt`). If the pattern exactly matches
+ * an existing path, we escape it to prevent glob interpretation.
+ *
+ * @param pattern - The glob pattern to potentially escape
+ * @param cwd - Current working directory for checking file existence
+ * @returns The pattern, escaped if it matches an existing file
+ */
+export async function escapeIfExactMatch(pattern, cwd) {
+    // If pattern doesn't contain special characters, no escaping needed
+    if (!GLOB_SPECIAL_CHARS.test(pattern)) {
+        return pattern;
+    }
+    // Check if the pattern exactly matches a file or directory
+    const fullPath = path.isAbsolute(pattern) ? pattern : path.join(cwd, pattern);
+    try {
+        await fs.access(fullPath);
+        // File/directory exists, escape special characters
+        return escapeGlobCharacters(pattern);
+    }
+    catch {
+        // File doesn't exist, treat as glob pattern
+        return pattern;
+    }
+}
+/**
+ * Escapes glob special characters in a string.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for use in glob patterns
+ */
+export function escapeGlobCharacters(str) {
+    return str.replaceAll(/([*?[\]{}()!@#])/g, String.raw `\$1`);
+}
+/**
+ * Extracts paths from FileMetadata array.
+ *
+ * @param files - Array of FileMetadata
+ * @returns Array of file paths
+ */
+export function extractPaths(files) {
+    return files.map((f) => f.path);
+}

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

@@ -0,0 +1,69 @@
+import type { FileSystemConfig, ValidationResult } from '../../../core/domain/cipher/file-system/types.js';
+/**
+ * Validates file paths against security policies.
+ * Implements defense-in-depth with multiple layers of validation:
+ * 1. Empty path check
+ * 2. Path normalization
+ * 3. Path traversal detection
+ * 4. Allowed paths whitelist
+ * 5. Blocked paths blacklist
+ * 6. File extension validation
+ */
+export declare class PathValidator {
+    private readonly blockedExtensions;
+    private readonly normalizedAllowedPaths;
+    private readonly normalizedBlockedPaths;
+    private readonly workingDirectory;
+    /**
+     * Creates a new path validator
+     * @param config - File system configuration
+     */
+    constructor(config: FileSystemConfig);
+    /**
+     * Validates a file path against all security policies.
+     *
+     * @param filePath - Path to validate
+     * @param operation - Operation type ('read' or 'write')
+     * @returns Validation result with normalized path or error message
+     */
+    validate(filePath: string, operation: 'read' | 'write'): ValidationResult;
+    /**
+     * Checks if a file has a blocked extension.
+     *
+     * @param filePath - File path to check
+     * @returns True if extension is blocked
+     */
+    private hasBlockedExtension;
+    /**
+     * Checks if a path is within the allowed paths.
+     *
+     * @param normalizedPath - Normalized absolute path
+     * @returns True if path is allowed
+     */
+    private isPathAllowed;
+    /**
+     * Checks if a path matches any blocked path patterns.
+     * Supports both absolute and relative blocked paths.
+     *
+     * @param normalizedPath - Normalized absolute path
+     * @returns Error message if blocked, false if not blocked
+     */
+    private isPathBlocked;
+    /**
+     * Checks if a path contains path traversal attempts.
+     * Detects both explicit traversal sequences and resolved paths outside working directory.
+     *
+     * @param originalPath - Original path provided by user
+     * @param normalizedPath - Normalized absolute path
+     * @returns True if path traversal detected
+     */
+    private isPathTraversal;
+    /**
+     * Normalizes and resolves a file path to an absolute path.
+     * Uses realpath to resolve symlinks if the path exists.
+     *
+     * @param filePath - Path to normalize
+     * @returns Normalized absolute path
+     */
+    private normalizeAndResolve;
+}

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

@@ -0,0 +1,184 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { getErrorMessage } from '../../../utils/error-helpers.js';
+/**
+ * Validates file paths against security policies.
+ * Implements defense-in-depth with multiple layers of validation:
+ * 1. Empty path check
+ * 2. Path normalization
+ * 3. Path traversal detection
+ * 4. Allowed paths whitelist
+ * 5. Blocked paths blacklist
+ * 6. File extension validation
+ */
+export class PathValidator {
+    blockedExtensions;
+    normalizedAllowedPaths;
+    normalizedBlockedPaths;
+    workingDirectory;
+    /**
+     * Creates a new path validator
+     * @param config - File system configuration
+     */
+    constructor(config) {
+        this.workingDirectory = path.resolve(config.workingDirectory);
+        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));
+        // Normalize blocked paths
+        this.normalizedBlockedPaths = config.blockedPaths.map((blockedPath) => path.isAbsolute(blockedPath) ? path.normalize(blockedPath) : blockedPath);
+    }
+    /**
+     * Validates a file path against all security policies.
+     *
+     * @param filePath - Path to validate
+     * @param operation - Operation type ('read' or 'write')
+     * @returns Validation result with normalized path or error message
+     */
+    validate(filePath, operation) {
+        // 1. Check for empty path
+        if (!filePath || filePath.trim().length === 0) {
+            return {
+                error: 'Path cannot be empty',
+                valid: false,
+            };
+        }
+        // 2. Normalize and resolve the path
+        let normalizedPath;
+        try {
+            normalizedPath = this.normalizeAndResolve(filePath);
+        }
+        catch (error) {
+            return {
+                error: `Failed to resolve path: ${getErrorMessage(error)}`,
+                valid: false,
+            };
+        }
+        // 3. Check for path traversal
+        if (this.isPathTraversal(filePath, normalizedPath)) {
+            return {
+                error: 'Path traversal detected',
+                valid: false,
+            };
+        }
+        // 4. Check if path is in allowed paths
+        if (!this.isPathAllowed(normalizedPath)) {
+            return {
+                error: `Path not in allowed paths. Allowed: ${this.normalizedAllowedPaths.join(', ')}`,
+                valid: false,
+            };
+        }
+        // 5. Check if path is blocked
+        const blockReason = this.isPathBlocked(normalizedPath);
+        if (blockReason) {
+            return {
+                error: blockReason,
+                valid: false,
+            };
+        }
+        // 6. Check file extension (only for write operations to prevent creating dangerous files)
+        if (operation === 'write' && this.hasBlockedExtension(filePath)) {
+            const ext = path.extname(filePath).toLowerCase();
+            return {
+                error: `File extension blocked: ${ext}`,
+                valid: false,
+            };
+        }
+        return {
+            normalizedPath,
+            valid: true,
+        };
+    }
+    /**
+     * Checks if a file has a blocked extension.
+     *
+     * @param filePath - File path to check
+     * @returns True if extension is blocked
+     */
+    hasBlockedExtension(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return this.blockedExtensions.has(ext);
+    }
+    /**
+     * Checks if a path is within the allowed paths.
+     *
+     * @param normalizedPath - Normalized absolute path
+     * @returns True if path is allowed
+     */
+    isPathAllowed(normalizedPath) {
+        return this.normalizedAllowedPaths.some((allowedPath) => {
+            const relative = path.relative(allowedPath, normalizedPath);
+            // Path is allowed if it's within the allowed path (doesn't start with ..)
+            return !relative.startsWith('..') && !path.isAbsolute(relative);
+        });
+    }
+    /**
+     * Checks if a path matches any blocked path patterns.
+     * Supports both absolute and relative blocked paths.
+     *
+     * @param normalizedPath - Normalized absolute path
+     * @returns Error message if blocked, false if not blocked
+     */
+    isPathBlocked(normalizedPath) {
+        // Check against all allowed path roots
+        for (const allowedRoot of this.normalizedAllowedPaths) {
+            for (const blocked of this.normalizedBlockedPaths) {
+                // If blocked path is absolute, check directly
+                if (path.isAbsolute(blocked)) {
+                    const blockedFull = path.normalize(blocked);
+                    if (normalizedPath === blockedFull || normalizedPath.startsWith(blockedFull + path.sep)) {
+                        return `Within blocked directory: ${blocked}`;
+                    }
+                }
+                else {
+                    // If blocked path is relative, check against all allowed roots
+                    const blockedFull = path.resolve(allowedRoot, blocked);
+                    if (normalizedPath === blockedFull || normalizedPath.startsWith(blockedFull + path.sep)) {
+                        return `Within blocked directory: ${blocked}`;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Checks if a path contains path traversal attempts.
+     * Detects both explicit traversal sequences and resolved paths outside working directory.
+     *
+     * @param originalPath - Original path provided by user
+     * @param normalizedPath - Normalized absolute path
+     * @returns True if path traversal detected
+     */
+    isPathTraversal(originalPath, normalizedPath) {
+        // Check for explicit traversal sequences
+        if (originalPath.includes('../') || originalPath.includes('..\\')) {
+            // Verify that the resolved path doesn't escape working directory
+            const relative = path.relative(this.workingDirectory, normalizedPath);
+            if (relative.startsWith('..') || path.isAbsolute(relative)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Normalizes and resolves a file path to an absolute path.
+     * Uses realpath to resolve symlinks if the path exists.
+     *
+     * @param filePath - Path to normalize
+     * @returns Normalized absolute path
+     */
+    normalizeAndResolve(filePath) {
+        // First resolve relative to working directory
+        let normalizedPath = path.resolve(this.workingDirectory, 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);
+        }
+        return normalizedPath;
+    }
+}