@compass-ai/nova 1.0.72 → 1.0.74

package/dist/services/file-service.js

@@ -0,0 +1,876 @@
+/**
+ * File operations service for safe read/write with backup integration,
+ * atomic multi-file operations, and rollback capability.
+ *
+ * This service provides a high-level interface for file operations that:
+ * - Integrates with BackupManager for automatic backup creation
+ * - Supports atomic multi-file transactions with rollback
+ * - Integrates with ApprovalManager for user consent
+ * - Emits events for UI updates
+ * - Provides safe path handling to prevent directory traversal
+ */
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { safeReadFile, safeWriteFile, safeReadJson, pathExists, ensureDir, remove, copy, stat, isDirectory, isFile, } from '../utils/file-system.js';
+import { sanitizePath, isPathWithin, getGlobalCompassDir, getProjectCompassDir } from '../utils/path.js';
+import { generateDiff } from '../utils/diff.js';
+import { formatTimestamp } from '../utils/format.js';
+import { logger } from '../utils/logger.js';
+import { getBackupManager } from './backup-manager.js';
+import { getApprovalManager } from './approval-manager.js';
+import { getEventEmitter } from '../core/event-emitter.js';
+import { getSystemEventLogger } from './system-event-logger.js';
+import { getTempFileService } from './temp-file-service.js';
+/**
+ * FileService provides safe file operations with backup integration,
+ * approval workflow, and transaction support for atomic multi-file operations.
+ */
+class FileService {
+    /** Project root directory for path validation */
+    projectRoot = process.cwd();
+    /** Currently active transaction */
+    activeTransaction = null;
+    /** Set of external file paths that have been approved for reading this session */
+    approvedExternalPaths = new Set();
+    /**
+     * Sets the project root directory for path validation
+     * @param projectRoot - The root directory of the project
+     */
+    setProjectRoot(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Gets the current project root
+     * @returns The project root directory
+     */
+    getProjectRoot() {
+        return this.projectRoot;
+    }
+    /**
+     * Reads a file safely with path validation
+     * @param filePath - Path to the file (relative or absolute)
+     * @param options - Read options
+     * @returns File content or null if not found
+     */
+    async readFile(filePath, options = {}) {
+        const { requireApprovalForExternal = true } = options;
+        // Allow external paths for reads since we have approval flow for external files
+        const safePath = this.validatePath(filePath, true);
+        if (!safePath) {
+            logger.warn(`Path validation failed for: ${filePath}`);
+            return options.fallback ?? null;
+        }
+        // Check if this is an external file (outside project root)
+        const isExternal = this.isExternalPath(safePath);
+        // Request approval for external files if required and not already approved
+        if (isExternal && requireApprovalForExternal && !this.approvedExternalPaths.has(safePath)) {
+            const approvalManager = getApprovalManager();
+            const approvalResponse = await approvalManager.requestApproval('file_read_external', `Read external file: ${filePath}`, {
+                filePaths: [filePath],
+                affectedFiles: 1,
+            });
+            if (!approvalResponse.approved) {
+                logger.info(`External file read rejected by user: ${filePath}`);
+                return options.fallback ?? null;
+            }
+            // Remember this path as approved for the session
+            this.approvedExternalPaths.add(safePath);
+        }
+        const content = await safeReadFile(safePath, {
+            encoding: options.encoding,
+            fallback: options.fallback,
+        });
+        // Log file read event
+        if (content !== null) {
+            getSystemEventLogger().logFileRead(filePath, content.length, true);
+        }
+        return content;
+    }
+    /**
+     * Checks if a path is external (outside the project root)
+     * @param filePath - Absolute path to check
+     * @returns True if the path is outside the project root
+     */
+    isExternalPath(filePath) {
+        if (!isPathWithin(filePath, this.projectRoot)) {
+            // Compass-managed directories are internal safe paths, not external
+            const globalCompass = getGlobalCompassDir();
+            const projectCompass = getProjectCompassDir(this.projectRoot);
+            if (filePath.startsWith(globalCompass) || filePath.startsWith(projectCompass)) {
+                return false;
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Reads and parses a JSON file
+     * @param filePath - Path to the JSON file
+     * @param fallback - Fallback value if file doesn't exist or is invalid
+     * @returns Parsed JSON or fallback value
+     */
+    async readJsonFile(filePath, fallback) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            logger.warn(`Path validation failed for: ${filePath}`);
+            return fallback ?? null;
+        }
+        return safeReadJson(safePath, fallback);
+    }
+    /**
+     * Writes content to a file with backup and approval integration
+     * @param filePath - Path to the file (relative or absolute)
+     * @param content - Content to write
+     * @param options - Write options
+     * @returns Operation result
+     */
+    async writeFile(filePath, content, options = {}) {
+        const { createBackup = true, requireApproval = true, description, atomic = true, complexityContext, } = options;
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return {
+                success: false,
+                filePath,
+                operation: 'modify',
+                error: 'Path validation failed - potential directory traversal detected',
+            };
+        }
+        const fileExists = await pathExists(safePath);
+        const operation = fileExists ? 'modify' : 'create';
+        // Get original content for diff
+        let originalContent = null;
+        let diff;
+        if (fileExists) {
+            originalContent = await safeReadFile(safePath);
+            if (originalContent !== null) {
+                diff = generateDiff(originalContent, content, {
+                    fileName: path.basename(filePath),
+                });
+            }
+        }
+        else {
+            // For new files, generate diff showing all content as additions
+            diff = generateDiff('', content, {
+                fileName: path.basename(filePath),
+            });
+        }
+        // Request approval if required
+        if (requireApproval) {
+            const approvalManager = getApprovalManager();
+            const approvalType = operation === 'create' ? 'file_create' : 'file_modify';
+            // Create temp preview file for VS Code integration
+            let previewTempRecord;
+            try {
+                const tempFileService = getTempFileService();
+                previewTempRecord = await tempFileService.createTempFile({
+                    prefix: '[Nova]-preview',
+                    extension: path.extname(filePath),
+                    content: content, // Write the full new content for preview
+                    metadata: { originalPath: filePath },
+                });
+            }
+            catch {
+                // Non-critical - proceed without preview if temp file creation fails
+                logger.debug('Failed to create preview temp file, proceeding without preview');
+            }
+            const approvalResponse = await approvalManager.requestApproval(approvalType, description || `${operation === 'create' ? 'Create' : 'Modify'} file: ${filePath}`, {
+                filePaths: [filePath],
+                affectedFiles: 1,
+                linesAdded: diff?.additions,
+                linesRemoved: diff?.deletions,
+                diff: diff?.unified,
+                // Include complexity context for SMART mode decisions
+                complexityMode: complexityContext?.mode,
+                complexityConfidence: complexityContext?.confidence,
+                // Include preview file path for VS Code integration
+                previewFilePath: previewTempRecord?.tempPath,
+            });
+            // Clean up temp preview file after approval (whether approved or rejected)
+            if (previewTempRecord) {
+                try {
+                    const tempFileService = getTempFileService();
+                    await tempFileService.deleteTempFile(previewTempRecord.id);
+                }
+                catch {
+                    // Non-critical - temp file will be cleaned up by periodic cleanup
+                    logger.debug('Failed to delete preview temp file, will be cleaned up later');
+                }
+            }
+            if (!approvalResponse.approved) {
+                // Include user feedback in the error message if provided
+                const errorMessage = approvalResponse.reason
+                    ? approvalResponse.reason
+                    : 'Operation rejected by user';
+                return {
+                    success: false,
+                    filePath,
+                    operation,
+                    error: errorMessage,
+                };
+            }
+        }
+        // Create backup if file exists and backup is requested
+        let backup;
+        if (createBackup && fileExists) {
+            const backupManager = await getBackupManager();
+            const backupRecord = await backupManager.createBackup(safePath);
+            if (backupRecord) {
+                backup = backupRecord;
+            }
+        }
+        // Write the file
+        try {
+            await safeWriteFile(safePath, content, {
+                atomic,
+                createDir: true,
+            });
+            // Emit file-modified event
+            const eventEmitter = getEventEmitter();
+            eventEmitter.emit('file-modified', { path: filePath, operation });
+            logger.info(`File ${operation}d: ${filePath}`);
+            // Log file write event
+            getSystemEventLogger().logFileWrite(filePath, content.length, true);
+            return {
+                success: true,
+                filePath,
+                operation,
+                backup,
+                diff,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error(`Failed to ${operation} file: ${filePath}`, error);
+            // Log file write failure
+            getSystemEventLogger().logFileWrite(filePath, content.length, false, errorMessage);
+            return {
+                success: false,
+                filePath,
+                operation,
+                backup,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Writes JSON content to a file
+     * @param filePath - Path to the file
+     * @param data - Data to serialize and write
+     * @param options - Write options
+     * @returns Operation result
+     */
+    async writeJsonFile(filePath, data, options = {}) {
+        const content = JSON.stringify(data, null, 2);
+        return this.writeFile(filePath, content, options);
+    }
+    /**
+     * Deletes a file with backup and approval integration
+     * @param filePath - Path to the file to delete
+     * @param options - Operation options
+     * @returns Operation result
+     */
+    async deleteFile(filePath, options = {}) {
+        const { createBackup = true, requireApproval = true, description, complexityContext } = options;
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return {
+                success: false,
+                filePath,
+                operation: 'delete',
+                error: 'Path validation failed - potential directory traversal detected',
+            };
+        }
+        if (!(await pathExists(safePath))) {
+            return {
+                success: false,
+                filePath,
+                operation: 'delete',
+                error: 'File does not exist',
+            };
+        }
+        // Request approval if required
+        if (requireApproval) {
+            const approvalManager = getApprovalManager();
+            const approvalResponse = await approvalManager.requestApproval('file_delete', description || `Delete file: ${filePath}`, {
+                filePaths: [filePath],
+                affectedFiles: 1,
+                // Include complexity context for SMART mode decisions
+                complexityMode: complexityContext?.mode,
+                complexityConfidence: complexityContext?.confidence,
+            });
+            if (!approvalResponse.approved) {
+                // Include user feedback in the error message if provided
+                const errorMessage = approvalResponse.reason
+                    ? approvalResponse.reason
+                    : 'Operation rejected by user';
+                return {
+                    success: false,
+                    filePath,
+                    operation: 'delete',
+                    error: errorMessage,
+                };
+            }
+        }
+        // Create backup before deletion
+        let backup;
+        if (createBackup) {
+            const backupManager = await getBackupManager();
+            const backupRecord = await backupManager.createBackup(safePath);
+            if (backupRecord) {
+                backup = backupRecord;
+            }
+        }
+        // Delete the file
+        try {
+            await remove(safePath);
+            // Emit file-modified event
+            const eventEmitter = getEventEmitter();
+            eventEmitter.emit('file-modified', { path: filePath, operation: 'delete' });
+            logger.info(`File deleted: ${filePath}`);
+            // Log file delete event
+            getSystemEventLogger().logFileDelete(filePath, true);
+            return {
+                success: true,
+                filePath,
+                operation: 'delete',
+                backup,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error(`Failed to delete file: ${filePath}`, error);
+            // Log file delete failure
+            getSystemEventLogger().logFileDelete(filePath, false, errorMessage);
+            return {
+                success: false,
+                filePath,
+                operation: 'delete',
+                backup,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Renames or moves a file with backup and approval integration
+     * @param oldPath - Current path of the file
+     * @param newPath - New path for the file
+     * @param options - Operation options
+     * @returns Operation result
+     */
+    async renameFile(oldPath, newPath, options = {}) {
+        const { createBackup = true, requireApproval = true, description, complexityContext } = options;
+        const safeOldPath = this.validatePath(oldPath);
+        const safeNewPath = this.validatePath(newPath);
+        if (!safeOldPath || !safeNewPath) {
+            return {
+                success: false,
+                filePath: oldPath,
+                operation: 'rename',
+                error: 'Path validation failed - potential directory traversal detected',
+            };
+        }
+        if (!(await pathExists(safeOldPath))) {
+            return {
+                success: false,
+                filePath: oldPath,
+                operation: 'rename',
+                error: 'Source file does not exist',
+            };
+        }
+        if (await pathExists(safeNewPath)) {
+            return {
+                success: false,
+                filePath: oldPath,
+                operation: 'rename',
+                error: 'Destination file already exists',
+            };
+        }
+        // Request approval if required
+        if (requireApproval) {
+            const approvalManager = getApprovalManager();
+            const approvalResponse = await approvalManager.requestApproval('file_rename', description || `Rename file: ${oldPath} → ${newPath}`, {
+                filePaths: [oldPath, newPath],
+                affectedFiles: 1,
+                // Include complexity context for SMART mode decisions
+                complexityMode: complexityContext?.mode,
+                complexityConfidence: complexityContext?.confidence,
+            });
+            if (!approvalResponse.approved) {
+                // Include user feedback in the error message if provided
+                const errorMessage = approvalResponse.reason
+                    ? approvalResponse.reason
+                    : 'Operation rejected by user';
+                return {
+                    success: false,
+                    filePath: oldPath,
+                    operation: 'rename',
+                    error: errorMessage,
+                };
+            }
+        }
+        // Create backup before rename
+        let backup;
+        if (createBackup) {
+            const backupManager = await getBackupManager();
+            const backupRecord = await backupManager.createBackup(safeOldPath);
+            if (backupRecord) {
+                backup = backupRecord;
+            }
+        }
+        // Perform the rename
+        try {
+            // Ensure destination directory exists
+            await ensureDir(path.dirname(safeNewPath));
+            // Copy to new location then remove old
+            await copy(safeOldPath, safeNewPath);
+            await remove(safeOldPath);
+            // Emit file-modified event
+            const eventEmitter = getEventEmitter();
+            eventEmitter.emit('file-modified', { path: newPath, operation: 'create' });
+            logger.info(`File renamed: ${oldPath} → ${newPath}`);
+            // Log file rename event
+            getSystemEventLogger().logFileRename(oldPath, newPath, true);
+            return {
+                success: true,
+                filePath: newPath,
+                operation: 'rename',
+                backup,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error(`Failed to rename file: ${oldPath}`, error);
+            // Log file rename failure
+            getSystemEventLogger().logFileRename(oldPath, newPath, false, errorMessage);
+            return {
+                success: false,
+                filePath: oldPath,
+                operation: 'rename',
+                backup,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Checks if a file exists
+     * @param filePath - Path to check
+     * @returns True if file exists
+     */
+    async exists(filePath) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return false;
+        }
+        return pathExists(safePath);
+    }
+    /**
+     * Checks if a path is a file
+     * @param filePath - Path to check
+     * @returns True if path is a file
+     */
+    async isFile(filePath) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return false;
+        }
+        return isFile(safePath);
+    }
+    /**
+     * Checks if a path is a directory
+     * @param filePath - Path to check
+     * @returns True if path is a directory
+     */
+    async isDirectory(filePath) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return false;
+        }
+        return isDirectory(safePath);
+    }
+    /**
+     * Gets file statistics
+     * @param filePath - Path to the file
+     * @returns File stats or null if not found
+     */
+    async getStats(filePath) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return null;
+        }
+        const stats = await stat(safePath);
+        if (!stats) {
+            return null;
+        }
+        return {
+            size: stats.size,
+            modified: stats.mtime,
+            created: stats.birthtime,
+            isFile: stats.isFile(),
+            isDirectory: stats.isDirectory(),
+        };
+    }
+    // ============================================
+    // Transaction Support for Atomic Multi-File Operations
+    // ============================================
+    /**
+     * Begins a new transaction for atomic multi-file operations
+     * @returns The transaction ID
+     */
+    beginTransaction() {
+        if (this.activeTransaction) {
+            throw new Error('A transaction is already in progress. Commit or rollback first.');
+        }
+        this.activeTransaction = {
+            id: uuidv4(),
+            createdAt: formatTimestamp(),
+            operations: [],
+            status: 'pending',
+        };
+        logger.debug(`Transaction started: ${this.activeTransaction.id}`);
+        return this.activeTransaction.id;
+    }
+    /**
+     * Adds a file write operation to the current transaction
+     * @param filePath - Path to the file
+     * @param content - Content to write
+     */
+    addWriteOperation(filePath, content) {
+        if (!this.activeTransaction) {
+            throw new Error('No active transaction. Call beginTransaction() first.');
+        }
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            throw new Error(`Invalid path: ${filePath}`);
+        }
+        this.activeTransaction.operations.push({
+            id: uuidv4(),
+            type: 'modify',
+            filePath: safePath,
+            content,
+            executed: false,
+        });
+        logger.debug(`Added write operation to transaction: ${filePath}`);
+    }
+    /**
+     * Adds a file delete operation to the current transaction
+     * @param filePath - Path to the file to delete
+     */
+    addDeleteOperation(filePath) {
+        if (!this.activeTransaction) {
+            throw new Error('No active transaction. Call beginTransaction() first.');
+        }
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            throw new Error(`Invalid path: ${filePath}`);
+        }
+        this.activeTransaction.operations.push({
+            id: uuidv4(),
+            type: 'delete',
+            filePath: safePath,
+            executed: false,
+        });
+        logger.debug(`Added delete operation to transaction: ${filePath}`);
+    }
+    /**
+     * Adds a file rename operation to the current transaction
+     * @param oldPath - Current path of the file
+     * @param newPath - New path for the file
+     */
+    addRenameOperation(oldPath, newPath) {
+        if (!this.activeTransaction) {
+            throw new Error('No active transaction. Call beginTransaction() first.');
+        }
+        const safeOldPath = this.validatePath(oldPath);
+        const safeNewPath = this.validatePath(newPath);
+        if (!safeOldPath || !safeNewPath) {
+            throw new Error(`Invalid path: ${oldPath} or ${newPath}`);
+        }
+        this.activeTransaction.operations.push({
+            id: uuidv4(),
+            type: 'rename',
+            filePath: safeOldPath,
+            newPath: safeNewPath,
+            executed: false,
+        });
+        logger.debug(`Added rename operation to transaction: ${oldPath} → ${newPath}`);
+    }
+    /**
+     * Commits the current transaction, executing all operations atomically
+     * @param options - Options for the commit
+     * @returns Array of operation results
+     */
+    async commitTransaction(options = {}) {
+        if (!this.activeTransaction) {
+            throw new Error('No active transaction to commit.');
+        }
+        const { requireApproval = true, description } = options;
+        const transaction = this.activeTransaction;
+        const results = [];
+        // Request approval for the entire transaction
+        if (requireApproval && transaction.operations.length > 0) {
+            const approvalManager = getApprovalManager();
+            const filePaths = transaction.operations.map((op) => op.filePath);
+            const approvalResponse = await approvalManager.requestApproval('multi_file_operation', description || `Multi-file operation: ${transaction.operations.length} files`, {
+                filePaths,
+                affectedFiles: transaction.operations.length,
+            });
+            if (!approvalResponse.approved) {
+                transaction.status = 'failed';
+                this.activeTransaction = null;
+                // Include user feedback in the error message if provided
+                const errorMessage = approvalResponse.reason
+                    ? `Transaction rejected: ${approvalResponse.reason}`
+                    : 'Transaction rejected by user';
+                return transaction.operations.map((op) => ({
+                    success: false,
+                    filePath: op.filePath,
+                    operation: op.type === 'rename' ? 'rename' : op.type,
+                    error: errorMessage,
+                }));
+            }
+        }
+        const backupManager = await getBackupManager();
+        // Execute all operations
+        try {
+            for (const operation of transaction.operations) {
+                // Create backup for existing files
+                if (operation.type !== 'create' && (await pathExists(operation.filePath))) {
+                    const backup = await backupManager.createBackup(operation.filePath);
+                    if (backup) {
+                        operation.backup = backup;
+                    }
+                    operation.originalContent = await safeReadFile(operation.filePath) || undefined;
+                }
+                // Execute the operation
+                let result;
+                switch (operation.type) {
+                    case 'create':
+                    case 'modify':
+                        await safeWriteFile(operation.filePath, operation.content || '', {
+                            atomic: true,
+                            createDir: true,
+                        });
+                        result = {
+                            success: true,
+                            filePath: operation.filePath,
+                            operation: operation.type,
+                            backup: operation.backup,
+                        };
+                        break;
+                    case 'delete':
+                        await remove(operation.filePath);
+                        result = {
+                            success: true,
+                            filePath: operation.filePath,
+                            operation: 'delete',
+                            backup: operation.backup,
+                        };
+                        break;
+                    case 'rename':
+                        await ensureDir(path.dirname(operation.newPath));
+                        await copy(operation.filePath, operation.newPath);
+                        await remove(operation.filePath);
+                        result = {
+                            success: true,
+                            filePath: operation.newPath,
+                            operation: 'rename',
+                            backup: operation.backup,
+                        };
+                        break;
+                    default:
+                        result = {
+                            success: false,
+                            filePath: operation.filePath,
+                            operation: 'modify',
+                            error: `Unknown operation type: ${operation.type}`,
+                        };
+                }
+                operation.executed = true;
+                results.push(result);
+                // Emit event for each successful operation
+                if (result.success) {
+                    const eventEmitter = getEventEmitter();
+                    // Map rename to create for event emission (file is created at new location)
+                    const eventOperation = result.operation === 'rename' ? 'create' : result.operation;
+                    eventEmitter.emit('file-modified', {
+                        path: result.filePath,
+                        operation: eventOperation,
+                    });
+                }
+            }
+            transaction.status = 'committed';
+            logger.info(`Transaction committed: ${transaction.id} (${results.length} operations)`);
+        }
+        catch (error) {
+            // Rollback on failure
+            logger.error(`Transaction failed, rolling back: ${transaction.id}`, error);
+            await this.rollbackTransaction();
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            // Mark remaining operations as failed
+            for (const operation of transaction.operations) {
+                if (!operation.executed) {
+                    results.push({
+                        success: false,
+                        filePath: operation.filePath,
+                        operation: operation.type === 'rename' ? 'rename' : operation.type,
+                        error: `Transaction rolled back: ${errorMessage}`,
+                    });
+                }
+            }
+        }
+        this.activeTransaction = null;
+        return results;
+    }
+    /**
+     * Rolls back the current transaction, restoring all modified files
+     */
+    async rollbackTransaction() {
+        if (!this.activeTransaction) {
+            logger.warn('No active transaction to rollback');
+            return;
+        }
+        const transaction = this.activeTransaction;
+        const backupManager = await getBackupManager();
+        // Rollback executed operations in reverse order
+        const executedOps = transaction.operations.filter((op) => op.executed).reverse();
+        for (const operation of executedOps) {
+            try {
+                if (operation.backup) {
+                    // Restore from backup
+                    await backupManager.restore(operation.backup.id);
+                    logger.debug(`Rolled back: ${operation.filePath}`);
+                }
+                else if (operation.type === 'create') {
+                    // Remove created file
+                    if (await pathExists(operation.filePath)) {
+                        await remove(operation.filePath);
+                        logger.debug(`Removed created file: ${operation.filePath}`);
+                    }
+                }
+                else if (operation.type === 'rename' && operation.newPath) {
+                    // Reverse the rename
+                    if (await pathExists(operation.newPath)) {
+                        await copy(operation.newPath, operation.filePath);
+                        await remove(operation.newPath);
+                        logger.debug(`Reversed rename: ${operation.newPath} → ${operation.filePath}`);
+                    }
+                }
+            }
+            catch (error) {
+                logger.error(`Failed to rollback operation: ${operation.filePath}`, error);
+            }
+        }
+        transaction.status = 'rolled_back';
+        this.activeTransaction = null;
+        logger.info(`Transaction rolled back: ${transaction.id}`);
+    }
+    /**
+     * Gets the current active transaction
+     * @returns The active transaction or null
+     */
+    getActiveTransaction() {
+        return this.activeTransaction;
+    }
+    /**
+     * Checks if there is an active transaction
+     * @returns True if a transaction is in progress
+     */
+    hasActiveTransaction() {
+        return this.activeTransaction !== null;
+    }
+    // ============================================
+    // Utility Methods
+    // ============================================
+    /**
+     * Restores a file from its most recent backup
+     * @param filePath - Path to the file to restore
+     * @returns True if restoration was successful
+     */
+    async restoreFromBackup(filePath) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            logger.warn(`Path validation failed for restore: ${filePath}`);
+            return false;
+        }
+        const backupManager = await getBackupManager();
+        return backupManager.restoreLatest(safePath);
+    }
+    /**
+     * Gets the diff between current file content and proposed new content
+     * @param filePath - Path to the file
+     * @param newContent - Proposed new content
+     * @returns Diff result or null if file doesn't exist
+     */
+    async getDiff(filePath, newContent) {
+        const safePath = this.validatePath(filePath);
+        if (!safePath) {
+            return null;
+        }
+        const currentContent = await safeReadFile(safePath);
+        if (currentContent === null) {
+            return null;
+        }
+        return generateDiff(currentContent, newContent, {
+            fileName: path.basename(filePath),
+        });
+    }
+    /**
+     * Validates and sanitizes a file path
+     * @param filePath - Path to validate
+     * @param allowExternal - Whether to allow paths outside project root (default: false)
+     * @returns Sanitized absolute path or null if invalid
+     */
+    validatePath(filePath, allowExternal = false) {
+        // Resolve the path to absolute form
+        const resolvedPath = path.isAbsolute(filePath)
+            ? path.normalize(filePath)
+            : path.resolve(this.projectRoot, filePath);
+        // Check for directory traversal patterns even in absolute paths
+        // This catches attempts like /project/../../../etc/passwd
+        const normalizedPath = path.normalize(resolvedPath);
+        // For relative paths, use sanitizePath to prevent directory traversal
+        if (!path.isAbsolute(filePath)) {
+            const sanitized = sanitizePath(filePath, this.projectRoot);
+            if (!sanitized) {
+                logger.warn(`Path validation failed (directory traversal attempt): ${filePath}`);
+                return null;
+            }
+        }
+        // Check if path is within project root
+        const isWithinProject = isPathWithin(normalizedPath, this.projectRoot);
+        // If path is outside project root
+        if (!isWithinProject) {
+            // Always allow access to the global compass directory (~/.compass/)
+            const globalDir = getGlobalCompassDir();
+            if (isPathWithin(normalizedPath, globalDir)) {
+                logger.debug(`Allowing global compass directory access: ${filePath}`);
+                return normalizedPath;
+            }
+            if (allowExternal) {
+                // External paths are allowed for this operation (e.g., read with approval)
+                logger.debug(`Allowing external path access: ${filePath}`);
+                return normalizedPath;
+            }
+            else {
+                // Block access to paths outside project root
+                logger.warn(`Path is outside project root and external access not allowed: ${filePath}`);
+                return null;
+            }
+        }
+        return normalizedPath;
+    }
+}
+// Singleton instance
+let fileServiceInstance = null;
+/**
+ * Gets the singleton FileService instance
+ * @returns The FileService instance
+ */
+export function getFileService() {
+    if (!fileServiceInstance) {
+        fileServiceInstance = new FileService();
+    }
+    return fileServiceInstance;
+}
+export { FileService };
+//# sourceMappingURL=file-service.js.map