@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/file-hash-tracker.d.ts

@@ -0,0 +1,95 @@
+/**
+ * File Hash Tracker - Tracks file content hashes to detect external modifications.
+ *
+ * This module provides a mechanism to detect when files have been modified externally
+ * between the time they were read by the LLM and when the LLM attempts to write changes.
+ * This prevents accidental data loss from race conditions.
+ *
+ * Usage:
+ * 1. When a file is read, call `trackFileHash(path, content)` to store its hash
+ * 2. Before writing, call `validateFileIntegrity(path)` to check for external changes
+ * 3. After writing, call `updateFileHash(path, newContent)` to update the tracked hash
+ */
+/**
+ * Error thrown when a file has been modified externally since it was last read
+ */
+export declare class FileModifiedExternallyError extends Error {
+    readonly filePath: string;
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    constructor(filePath: string, expectedHash: string, actualHash: string);
+    /**
+     * Returns a structured error response suitable for the LLM
+     */
+    toToolResponse(): {
+        success: boolean;
+        error: string;
+        message: string;
+        filePath: string;
+        suggestion: string;
+    };
+}
+/**
+ * Tracks a file's content hash after it has been read.
+ * Call this whenever a file is read by the LLM.
+ *
+ * @param filePath - Absolute path to the file
+ * @param content - The content that was read from the file
+ */
+export declare function trackFileHash(filePath: string, content: string): void;
+/**
+ * Updates the tracked hash for a file after it has been written.
+ * Call this after successfully writing to a file.
+ *
+ * @param filePath - Absolute path to the file
+ * @param newContent - The new content that was written
+ */
+export declare function updateFileHash(filePath: string, newContent: string): void;
+/**
+ * Validates that a file has not been modified externally since it was last read.
+ * Call this before writing to a file.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Object with validation result
+ * @throws FileModifiedExternallyError if the file was modified externally
+ */
+export declare function validateFileIntegrity(filePath: string): Promise<{
+    valid: boolean;
+    wasTracked: boolean;
+    currentHash?: string;
+    expectedHash?: string;
+}>;
+/**
+ * Checks if a file is being tracked
+ *
+ * @param filePath - Absolute path to the file
+ * @returns True if the file is tracked
+ */
+export declare function isFileTracked(filePath: string): boolean;
+/**
+ * Gets the tracked hash for a file
+ *
+ * @param filePath - Absolute path to the file
+ * @returns The tracked hash or undefined if not tracked
+ */
+export declare function getTrackedHash(filePath: string): string | undefined;
+/**
+ * Removes tracking for a specific file
+ *
+ * @param filePath - Absolute path to the file
+ */
+export declare function untrackFile(filePath: string): void;
+/**
+ * Clears all tracked files.
+ * Call this at the start of a new session or when cleaning up.
+ */
+export declare function clearTrackedFiles(): void;
+/**
+ * Gets statistics about tracked files
+ */
+export declare function getTrackingStats(): {
+    trackedCount: number;
+    oldestTrackedAt: number | null;
+    newestTrackedAt: number | null;
+};
+//# sourceMappingURL=file-hash-tracker.d.ts.map

package/dist/services/file-hash-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-hash-tracker.d.ts","sourceRoot":"","sources":["../../src/services/file-hash-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAWtE;;OAEG;IACH,cAAc;;;;;;;CASf;AAoCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAWrE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAWzE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACrE,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC,CA8CD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAkBA"}

package/dist/services/file-hash-tracker.js

@@ -0,0 +1,199 @@
+/**
+ * File Hash Tracker - Tracks file content hashes to detect external modifications.
+ *
+ * This module provides a mechanism to detect when files have been modified externally
+ * between the time they were read by the LLM and when the LLM attempts to write changes.
+ * This prevents accidental data loss from race conditions.
+ *
+ * Usage:
+ * 1. When a file is read, call `trackFileHash(path, content)` to store its hash
+ * 2. Before writing, call `validateFileIntegrity(path)` to check for external changes
+ * 3. After writing, call `updateFileHash(path, newContent)` to update the tracked hash
+ */
+import { hash } from '../utils/crypto.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Error thrown when a file has been modified externally since it was last read
+ */
+export class FileModifiedExternallyError extends Error {
+    filePath;
+    expectedHash;
+    actualHash;
+    constructor(filePath, expectedHash, actualHash) {
+        super(`File "${filePath}" was modified externally since it was last read. ` +
+            `Please re-read the file before making changes.`);
+        this.name = 'FileModifiedExternallyError';
+        this.filePath = filePath;
+        this.expectedHash = expectedHash;
+        this.actualHash = actualHash;
+    }
+    /**
+     * Returns a structured error response suitable for the LLM
+     */
+    toToolResponse() {
+        return {
+            success: false,
+            error: 'FILE_MODIFIED_EXTERNALLY',
+            message: this.message,
+            filePath: this.filePath,
+            suggestion: 'Re-read the file using read_file before attempting to edit it again.',
+        };
+    }
+}
+/**
+ * In-memory storage of file hashes
+ * Key: normalized absolute file path
+ * Value: TrackedFile info
+ */
+const trackedFiles = new Map();
+/**
+ * Normalizes a file path for consistent map key lookup
+ */
+function normalizePath(filePath) {
+    // Normalize path separators and resolve to absolute
+    return filePath.replace(/\\/g, '/').toLowerCase();
+}
+/**
+ * Computes the SHA-256 hash of file content
+ */
+function computeHash(content) {
+    return hash(content);
+}
+/**
+ * Tracks a file's content hash after it has been read.
+ * Call this whenever a file is read by the LLM.
+ *
+ * @param filePath - Absolute path to the file
+ * @param content - The content that was read from the file
+ */
+export function trackFileHash(filePath, content) {
+    const normalizedPath = normalizePath(filePath);
+    const contentHash = computeHash(content);
+    trackedFiles.set(normalizedPath, {
+        contentHash,
+        trackedAt: Date.now(),
+        path: filePath,
+    });
+    logger.debug(`[FileHashTracker] Tracked file: ${filePath} (hash: ${contentHash.substring(0, 8)}...)`);
+}
+/**
+ * Updates the tracked hash for a file after it has been written.
+ * Call this after successfully writing to a file.
+ *
+ * @param filePath - Absolute path to the file
+ * @param newContent - The new content that was written
+ */
+export function updateFileHash(filePath, newContent) {
+    const normalizedPath = normalizePath(filePath);
+    const contentHash = computeHash(newContent);
+    trackedFiles.set(normalizedPath, {
+        contentHash,
+        trackedAt: Date.now(),
+        path: filePath,
+    });
+    logger.debug(`[FileHashTracker] Updated hash for: ${filePath} (hash: ${contentHash.substring(0, 8)}...)`);
+}
+/**
+ * Validates that a file has not been modified externally since it was last read.
+ * Call this before writing to a file.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Object with validation result
+ * @throws FileModifiedExternallyError if the file was modified externally
+ */
+export async function validateFileIntegrity(filePath) {
+    const normalizedPath = normalizePath(filePath);
+    const tracked = trackedFiles.get(normalizedPath);
+    // If file was never tracked, we can't validate - allow the write
+    if (!tracked) {
+        logger.debug(`[FileHashTracker] File not tracked, skipping validation: ${filePath}`);
+        return { valid: true, wasTracked: false };
+    }
+    // Read current file content and compute hash
+    try {
+        const fs = await import('fs/promises');
+        const currentContent = await fs.readFile(filePath, 'utf-8');
+        const currentHash = computeHash(currentContent);
+        if (currentHash !== tracked.contentHash) {
+            logger.warn(`[FileHashTracker] File modified externally: ${filePath} ` +
+                `(expected: ${tracked.contentHash.substring(0, 8)}..., got: ${currentHash.substring(0, 8)}...)`);
+            throw new FileModifiedExternallyError(filePath, tracked.contentHash, currentHash);
+        }
+        logger.debug(`[FileHashTracker] File integrity validated: ${filePath}`);
+        return {
+            valid: true,
+            wasTracked: true,
+            currentHash,
+            expectedHash: tracked.contentHash,
+        };
+    }
+    catch (error) {
+        if (error instanceof FileModifiedExternallyError) {
+            throw error;
+        }
+        // File might have been deleted - that's a different kind of change
+        if (error.code === 'ENOENT') {
+            logger.warn(`[FileHashTracker] File was deleted externally: ${filePath}`);
+            throw new FileModifiedExternallyError(filePath, tracked.contentHash, '<file deleted>');
+        }
+        throw error;
+    }
+}
+/**
+ * Checks if a file is being tracked
+ *
+ * @param filePath - Absolute path to the file
+ * @returns True if the file is tracked
+ */
+export function isFileTracked(filePath) {
+    const normalizedPath = normalizePath(filePath);
+    return trackedFiles.has(normalizedPath);
+}
+/**
+ * Gets the tracked hash for a file
+ *
+ * @param filePath - Absolute path to the file
+ * @returns The tracked hash or undefined if not tracked
+ */
+export function getTrackedHash(filePath) {
+    const normalizedPath = normalizePath(filePath);
+    return trackedFiles.get(normalizedPath)?.contentHash;
+}
+/**
+ * Removes tracking for a specific file
+ *
+ * @param filePath - Absolute path to the file
+ */
+export function untrackFile(filePath) {
+    const normalizedPath = normalizePath(filePath);
+    trackedFiles.delete(normalizedPath);
+    logger.debug(`[FileHashTracker] Untracked file: ${filePath}`);
+}
+/**
+ * Clears all tracked files.
+ * Call this at the start of a new session or when cleaning up.
+ */
+export function clearTrackedFiles() {
+    trackedFiles.clear();
+    logger.debug('[FileHashTracker] Cleared all tracked files');
+}
+/**
+ * Gets statistics about tracked files
+ */
+export function getTrackingStats() {
+    const entries = Array.from(trackedFiles.values());
+    if (entries.length === 0) {
+        return {
+            trackedCount: 0,
+            oldestTrackedAt: null,
+            newestTrackedAt: null,
+        };
+    }
+    const timestamps = entries.map(e => e.trackedAt);
+    return {
+        trackedCount: entries.length,
+        oldestTrackedAt: Math.min(...timestamps),
+        newestTrackedAt: Math.max(...timestamps),
+    };
+}
+//# sourceMappingURL=file-hash-tracker.js.map

package/dist/services/file-hash-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-hash-tracker.js","sourceRoot":"","sources":["../../src/services/file-hash-tracker.ts"],"names":[],"mappings":"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"}

package/dist/services/file-service.d.ts

@@ -0,0 +1,274 @@
+/**
+ * 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 { DiffResult } from '../utils/diff.js';
+import { BackupRecord } from './backup-manager.js';
+/**
+ * Complexity context for SMART approval mode
+ */
+export interface ComplexityContext {
+    /** Complexity mode from the classifier (direct, clarification, plan) */
+    mode: 'direct' | 'clarification' | 'plan';
+    /** Confidence score (0-100) of the classification */
+    confidence: number;
+}
+/**
+ * Options for file write operations
+ */
+export interface FileWriteOptions {
+    /** Whether to create a backup before writing (default: true) */
+    createBackup?: boolean;
+    /** Whether to request approval before writing (default: true) */
+    requireApproval?: boolean;
+    /** Description of the operation for approval dialog */
+    description?: string;
+    /** Whether to use atomic write (default: true) */
+    atomic?: boolean;
+    /** Complexity context for SMART mode approval decisions */
+    complexityContext?: ComplexityContext;
+}
+/**
+ * Options for file read operations
+ */
+export interface FileReadOptions {
+    /** Encoding for reading the file (default: 'utf8') */
+    encoding?: BufferEncoding;
+    /** Fallback value if file doesn't exist */
+    fallback?: string;
+    /** Whether to require approval for external files (default: true) */
+    requireApprovalForExternal?: boolean;
+}
+/**
+ * Result of a file operation
+ */
+export interface FileOperationResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Path to the affected file */
+    filePath: string;
+    /** Type of operation performed */
+    operation: 'create' | 'modify' | 'delete' | 'rename';
+    /** Backup record if a backup was created */
+    backup?: BackupRecord;
+    /** Error message if operation failed */
+    error?: string;
+    /** Diff result for modifications */
+    diff?: DiffResult;
+}
+/**
+ * Represents a file operation in a transaction
+ */
+interface TransactionOperation {
+    /** Unique identifier for the operation */
+    id: string;
+    /** Type of operation */
+    type: 'create' | 'modify' | 'delete' | 'rename';
+    /** Target file path */
+    filePath: string;
+    /** New content for create/modify operations */
+    content?: string;
+    /** New path for rename operations */
+    newPath?: string;
+    /** Backup record for rollback */
+    backup?: BackupRecord;
+    /** Original content before modification */
+    originalContent?: string;
+    /** Whether the operation has been executed */
+    executed: boolean;
+}
+/**
+ * Represents a multi-file transaction
+ */
+export interface FileTransaction {
+    /** Unique identifier for the transaction */
+    id: string;
+    /** Timestamp when transaction was created */
+    createdAt: string;
+    /** Operations in this transaction */
+    operations: TransactionOperation[];
+    /** Current status of the transaction */
+    status: 'pending' | 'committed' | 'rolled_back' | 'failed';
+}
+/**
+ * FileService provides safe file operations with backup integration,
+ * approval workflow, and transaction support for atomic multi-file operations.
+ */
+declare class FileService {
+    /** Project root directory for path validation */
+    private projectRoot;
+    /** Currently active transaction */
+    private activeTransaction;
+    /** Set of external file paths that have been approved for reading this session */
+    private approvedExternalPaths;
+    /**
+     * Sets the project root directory for path validation
+     * @param projectRoot - The root directory of the project
+     */
+    setProjectRoot(projectRoot: string): void;
+    /**
+     * Gets the current project root
+     * @returns The project root directory
+     */
+    getProjectRoot(): string;
+    /**
+     * 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
+     */
+    readFile(filePath: string, options?: FileReadOptions): Promise<string | null>;
+    /**
+     * 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
+     */
+    private isExternalPath;
+    /**
+     * 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
+     */
+    readJsonFile<T>(filePath: string, fallback?: T): Promise<T | null>;
+    /**
+     * 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
+     */
+    writeFile(filePath: string, content: string, options?: FileWriteOptions): Promise<FileOperationResult>;
+    /**
+     * 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
+     */
+    writeJsonFile(filePath: string, data: unknown, options?: FileWriteOptions): Promise<FileOperationResult>;
+    /**
+     * Deletes a file with backup and approval integration
+     * @param filePath - Path to the file to delete
+     * @param options - Operation options
+     * @returns Operation result
+     */
+    deleteFile(filePath: string, options?: Omit<FileWriteOptions, 'atomic'>): Promise<FileOperationResult>;
+    /**
+     * 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
+     */
+    renameFile(oldPath: string, newPath: string, options?: Omit<FileWriteOptions, 'atomic'>): Promise<FileOperationResult>;
+    /**
+     * Checks if a file exists
+     * @param filePath - Path to check
+     * @returns True if file exists
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * Checks if a path is a file
+     * @param filePath - Path to check
+     * @returns True if path is a file
+     */
+    isFile(filePath: string): Promise<boolean>;
+    /**
+     * Checks if a path is a directory
+     * @param filePath - Path to check
+     * @returns True if path is a directory
+     */
+    isDirectory(filePath: string): Promise<boolean>;
+    /**
+     * Gets file statistics
+     * @param filePath - Path to the file
+     * @returns File stats or null if not found
+     */
+    getStats(filePath: string): Promise<{
+        size: number;
+        modified: Date;
+        created: Date;
+        isFile: boolean;
+        isDirectory: boolean;
+    } | null>;
+    /**
+     * Begins a new transaction for atomic multi-file operations
+     * @returns The transaction ID
+     */
+    beginTransaction(): string;
+    /**
+     * Adds a file write operation to the current transaction
+     * @param filePath - Path to the file
+     * @param content - Content to write
+     */
+    addWriteOperation(filePath: string, content: string): void;
+    /**
+     * Adds a file delete operation to the current transaction
+     * @param filePath - Path to the file to delete
+     */
+    addDeleteOperation(filePath: string): void;
+    /**
+     * 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: string, newPath: string): void;
+    /**
+     * Commits the current transaction, executing all operations atomically
+     * @param options - Options for the commit
+     * @returns Array of operation results
+     */
+    commitTransaction(options?: {
+        requireApproval?: boolean;
+        description?: string;
+    }): Promise<FileOperationResult[]>;
+    /**
+     * Rolls back the current transaction, restoring all modified files
+     */
+    rollbackTransaction(): Promise<void>;
+    /**
+     * Gets the current active transaction
+     * @returns The active transaction or null
+     */
+    getActiveTransaction(): FileTransaction | null;
+    /**
+     * Checks if there is an active transaction
+     * @returns True if a transaction is in progress
+     */
+    hasActiveTransaction(): boolean;
+    /**
+     * Restores a file from its most recent backup
+     * @param filePath - Path to the file to restore
+     * @returns True if restoration was successful
+     */
+    restoreFromBackup(filePath: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    getDiff(filePath: string, newContent: string): Promise<DiffResult | null>;
+    /**
+     * 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
+     */
+    private validatePath;
+}
+/**
+ * Gets the singleton FileService instance
+ * @returns The FileService instance
+ */
+export declare function getFileService(): FileService;
+export { FileService };
+//# sourceMappingURL=file-service.d.ts.map

package/dist/services/file-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-service.d.ts","sourceRoot":"","sources":["../../src/services/file-service.ts"],"names":[],"mappings":"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"}