@compass-ai/nova 1.0.73 → 1.0.74

package/dist/utils/file-system.js

@@ -0,0 +1,798 @@
+/**
+ * File system utilities with safe operations and error handling.
+ *
+ * This module provides a comprehensive set of file system utilities wrapping fs-extra
+ * for safe read/write operations, atomic file updates, and directory management.
+ * All operations include proper error handling and logging.
+ *
+ * Features:
+ * - Safe file reading with fallback support
+ * - Atomic file writing with temporary files
+ * - JSON file read/write with automatic parsing
+ * - Directory management (ensure, read, check)
+ * - File/directory existence and type checking
+ * - File copying, moving, and removal
+ * - File statistics retrieval
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { logger } from './logger.js';
+import { PROJECT_COMPASS_DIR, CHAT_ARCHIVE_DIR } from '../constants/defaults.js';
+/**
+ * Safely reads a file with error handling.
+ *
+ * Returns the file content as a string, or null/fallback if the file doesn't exist.
+ * Throws an error for other file system errors (permission denied, etc.).
+ *
+ * @param filePath - Path to the file to read
+ * @param options - Read options including encoding and fallback value
+ * @returns File content as string, fallback value, or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const content = await safeReadFile('/path/to/file.txt');
+ *
+ * // With fallback
+ * const content = await safeReadFile('/path/to/file.txt', { fallback: '' });
+ *
+ * // With specific encoding
+ * const content = await safeReadFile('/path/to/file.txt', { encoding: 'utf16le' });
+ * ```
+ */
+export async function safeReadFile(filePath, options = {}) {
+    const { encoding = 'utf8', fallback } = options;
+    try {
+        const content = await fs.readFile(filePath, { encoding });
+        return content;
+    }
+    catch (error) {
+        const nodeError = error;
+        // File doesn't exist - return fallback or null
+        if (nodeError.code === 'ENOENT') {
+            return fallback ?? null;
+        }
+        // Log and re-throw other errors
+        logger.error(`Failed to read file: ${filePath}`, error);
+        throw error;
+    }
+}
+/**
+ * Safely reads and parses a JSON file.
+ *
+ * Returns the parsed JSON object, or null/fallback if the file doesn't exist
+ * or contains invalid JSON.
+ *
+ * @param filePath - Path to the JSON file to read
+ * @param fallback - Optional fallback value if file doesn't exist or is invalid
+ * @returns Parsed JSON object, fallback value, or null
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const config = await safeReadJson<ConfigType>('/path/to/config.json');
+ *
+ * // With fallback
+ * const config = await safeReadJson<ConfigType>('/path/to/config.json', { default: true });
+ *
+ * // Type-safe usage
+ * interface UserData { name: string; age: number; }
+ * const user = await safeReadJson<UserData>('/path/to/user.json');
+ * ```
+ */
+export async function safeReadJson(filePath, fallback) {
+    try {
+        const content = await safeReadFile(filePath);
+        if (content === null) {
+            return fallback ?? null;
+        }
+        return JSON.parse(content);
+    }
+    catch (error) {
+        // If JSON parsing fails, return fallback or re-throw
+        if (error instanceof SyntaxError) {
+            logger.warn(`Invalid JSON in file: ${filePath}`, error);
+            if (fallback !== undefined) {
+                return fallback;
+            }
+        }
+        // For other errors, return fallback if provided, otherwise throw
+        if (fallback !== undefined) {
+            return fallback;
+        }
+        logger.error(`Failed to parse JSON file: ${filePath}`, error);
+        throw error;
+    }
+}
+/**
+ * Safely writes content to a file with optional atomic write and backup.
+ *
+ * By default, uses atomic write (write to temp file, then rename) to prevent
+ * data corruption if the write is interrupted. Can optionally create a backup
+ * of the existing file before overwriting.
+ *
+ * @param filePath - Path to the file to write
+ * @param content - Content to write to the file
+ * @param options - Write options including atomic write and backup settings
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await safeWriteFile('/path/to/file.txt', 'Hello, World!');
+ *
+ * // With backup
+ * await safeWriteFile('/path/to/file.txt', 'New content', { backup: true });
+ *
+ * // Non-atomic write (faster but less safe)
+ * await safeWriteFile('/path/to/file.txt', 'Content', { atomic: false });
+ *
+ * // With specific permissions
+ * await safeWriteFile('/path/to/file.txt', 'Content', { mode: 0o600 });
+ * ```
+ */
+export async function safeWriteFile(filePath, content, options = {}) {
+    const { encoding = 'utf8', createDir = true, atomic = true, backup = false, backupDir, mode, } = options;
+    try {
+        // Ensure parent directory exists
+        if (createDir) {
+            await fs.ensureDir(path.dirname(filePath));
+        }
+        // Create backup if requested and file exists
+        if (backup && (await fs.pathExists(filePath))) {
+            const backupPath = backupDir
+                ? path.join(backupDir, path.basename(filePath) + '.bak')
+                : filePath + '.bak';
+            // Ensure backup directory exists
+            if (backupDir) {
+                await fs.ensureDir(backupDir);
+            }
+            await fs.copy(filePath, backupPath, { overwrite: true });
+            logger.debug(`Backup created: ${backupPath}`);
+        }
+        if (atomic) {
+            // Write to temp file first, then rename for atomic operation
+            const tempPath = `${filePath}.tmp.${Date.now()}.${process.pid}`;
+            try {
+                await fs.writeFile(tempPath, content, { encoding, mode });
+                await fs.rename(tempPath, filePath);
+            }
+            catch (error) {
+                // Clean up temp file on failure
+                try {
+                    await fs.remove(tempPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+                throw error;
+            }
+        }
+        else {
+            // Direct write (faster but not atomic)
+            await fs.writeFile(filePath, content, { encoding, mode });
+        }
+    }
+    catch (error) {
+        logger.error(`Failed to write file: ${filePath}`, error);
+        throw error;
+    }
+}
+/**
+ * Safely writes JSON data to a file.
+ *
+ * Serializes the data to JSON with pretty formatting (2-space indentation)
+ * and writes it using safeWriteFile for atomic operation support.
+ *
+ * @param filePath - Path to the JSON file to write
+ * @param data - Data to serialize and write
+ * @param options - Write options (same as safeWriteFile)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await safeWriteJson('/path/to/config.json', { key: 'value' });
+ *
+ * // With backup
+ * await safeWriteJson('/path/to/data.json', userData, { backup: true });
+ * ```
+ */
+export async function safeWriteJson(filePath, data, options = {}) {
+    const content = JSON.stringify(data, null, 2);
+    await safeWriteFile(filePath, content, options);
+}
+/**
+ * Ensures a directory exists, creating it and any parent directories if necessary.
+ *
+ * @param dirPath - Path to the directory to ensure exists
+ *
+ * @example
+ * ```typescript
+ * await ensureDir('/path/to/nested/directory');
+ * ```
+ */
+export async function ensureDir(dirPath) {
+    await fs.ensureDir(dirPath);
+}
+/**
+ * Checks if a path exists (file or directory).
+ *
+ * @param filePath - Path to check
+ * @returns True if the path exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (await pathExists('/path/to/file.txt')) {
+ *   console.log('File exists');
+ * }
+ * ```
+ */
+export async function pathExists(filePath) {
+    return fs.pathExists(filePath);
+}
+/**
+ * Removes a file or directory (recursively for directories).
+ *
+ * @param filePath - Path to the file or directory to remove
+ *
+ * @example
+ * ```typescript
+ * // Remove a file
+ * await remove('/path/to/file.txt');
+ *
+ * // Remove a directory and all its contents
+ * await remove('/path/to/directory');
+ * ```
+ */
+export async function remove(filePath) {
+    await fs.remove(filePath);
+}
+/**
+ * Copies a file or directory to a new location.
+ *
+ * For directories, copies recursively including all contents.
+ *
+ * @param src - Source path
+ * @param dest - Destination path
+ * @param options - Copy options (overwrite, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Copy a file
+ * await copy('/path/to/source.txt', '/path/to/dest.txt');
+ *
+ * // Copy a directory
+ * await copy('/path/to/source-dir', '/path/to/dest-dir');
+ * ```
+ */
+export async function copy(src, dest, options) {
+    await fs.copy(src, dest, options);
+}
+/**
+ * Moves a file or directory to a new location.
+ *
+ * @param src - Source path
+ * @param dest - Destination path
+ * @param options - Move options (overwrite, etc.)
+ *
+ * @example
+ * ```typescript
+ * await move('/path/to/old-location.txt', '/path/to/new-location.txt');
+ * ```
+ */
+export async function move(src, dest, options) {
+    await fs.move(src, dest, options);
+}
+/**
+ * Gets file or directory statistics.
+ *
+ * @param filePath - Path to get stats for
+ * @returns File stats object, or null if path doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const stats = await stat('/path/to/file.txt');
+ * if (stats) {
+ *   console.log(`Size: ${stats.size} bytes`);
+ *   console.log(`Modified: ${stats.mtime}`);
+ * }
+ * ```
+ */
+export async function stat(filePath) {
+    try {
+        return await fs.stat(filePath);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Lists the contents of a directory.
+ *
+ * @param dirPath - Path to the directory to read
+ * @returns Array of file and directory names, or empty array if directory doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const files = await readDir('/path/to/directory');
+ * for (const file of files) {
+ *   console.log(file);
+ * }
+ * ```
+ */
+export async function readDir(dirPath) {
+    try {
+        return await fs.readdir(dirPath);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Lists directory contents with file type information.
+ *
+ * @param dirPath - Path to the directory to read
+ * @returns Array of Dirent objects with name and type information
+ *
+ * @example
+ * ```typescript
+ * const entries = await readDirWithTypes('/path/to/directory');
+ * for (const entry of entries) {
+ *   if (entry.isFile()) {
+ *     console.log(`File: ${entry.name}`);
+ *   } else if (entry.isDirectory()) {
+ *     console.log(`Directory: ${entry.name}`);
+ *   }
+ * }
+ * ```
+ */
+export async function readDirWithTypes(dirPath) {
+    try {
+        return await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Checks if a path is a directory.
+ *
+ * @param filePath - Path to check
+ * @returns True if the path is a directory, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (await isDirectory('/path/to/check')) {
+ *   console.log('It is a directory');
+ * }
+ * ```
+ */
+export async function isDirectory(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if a path is a file.
+ *
+ * @param filePath - Path to check
+ * @returns True if the path is a file, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (await isFile('/path/to/check')) {
+ *   console.log('It is a file');
+ * }
+ * ```
+ */
+export async function isFile(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if a path is a symbolic link.
+ *
+ * @param filePath - Path to check
+ * @returns True if the path is a symbolic link, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (await isSymlink('/path/to/check')) {
+ *   console.log('It is a symbolic link');
+ * }
+ * ```
+ */
+export async function isSymlink(filePath) {
+    try {
+        const stats = await fs.lstat(filePath);
+        return stats.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets the size of a file in bytes.
+ *
+ * @param filePath - Path to the file
+ * @returns File size in bytes, or 0 if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const size = await getFileSize('/path/to/file.txt');
+ * console.log(`File size: ${size} bytes`);
+ * ```
+ */
+export async function getFileSize(filePath) {
+    const stats = await stat(filePath);
+    return stats?.size ?? 0;
+}
+/**
+ * Gets the modification time of a file.
+ *
+ * @param filePath - Path to the file
+ * @returns Modification time as Date, or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const mtime = await getModificationTime('/path/to/file.txt');
+ * if (mtime) {
+ *   console.log(`Last modified: ${mtime.toISOString()}`);
+ * }
+ * ```
+ */
+export async function getModificationTime(filePath) {
+    const stats = await stat(filePath);
+    return stats?.mtime ?? null;
+}
+/**
+ * Creates an empty file if it doesn't exist, or updates its modification time if it does.
+ * Similar to the Unix 'touch' command.
+ *
+ * @param filePath - Path to the file to touch
+ *
+ * @example
+ * ```typescript
+ * await touch('/path/to/file.txt');
+ * ```
+ */
+export async function touch(filePath) {
+    await fs.ensureFile(filePath);
+    const now = new Date();
+    await fs.utimes(filePath, now, now);
+}
+/**
+ * Empties a directory by removing all its contents but keeping the directory itself.
+ *
+ * @param dirPath - Path to the directory to empty
+ *
+ * @example
+ * ```typescript
+ * await emptyDir('/path/to/directory');
+ * ```
+ */
+export async function emptyDir(dirPath) {
+    await fs.emptyDir(dirPath);
+}
+/**
+ * Reads a file as a Buffer (for binary files).
+ *
+ * @param filePath - Path to the file to read
+ * @returns File content as Buffer, or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const buffer = await readFileBuffer('/path/to/image.png');
+ * if (buffer) {
+ *   console.log(`Read ${buffer.length} bytes`);
+ * }
+ * ```
+ */
+export async function readFileBuffer(filePath) {
+    try {
+        return await fs.readFile(filePath);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return null;
+        }
+        logger.error(`Failed to read file as buffer: ${filePath}`, error);
+        throw error;
+    }
+}
+/**
+ * Writes a Buffer to a file (for binary files).
+ *
+ * @param filePath - Path to the file to write
+ * @param data - Buffer data to write
+ * @param options - Write options
+ *
+ * @example
+ * ```typescript
+ * const buffer = Buffer.from([0x00, 0x01, 0x02]);
+ * await writeFileBuffer('/path/to/file.bin', buffer);
+ * ```
+ */
+export async function writeFileBuffer(filePath, data, options = {}) {
+    const { createDir = true, atomic = true, backup = false, backupDir, mode } = options;
+    try {
+        if (createDir) {
+            await fs.ensureDir(path.dirname(filePath));
+        }
+        if (backup && (await fs.pathExists(filePath))) {
+            const backupPath = backupDir
+                ? path.join(backupDir, path.basename(filePath) + '.bak')
+                : filePath + '.bak';
+            if (backupDir) {
+                await fs.ensureDir(backupDir);
+            }
+            await fs.copy(filePath, backupPath, { overwrite: true });
+        }
+        if (atomic) {
+            const tempPath = `${filePath}.tmp.${Date.now()}.${process.pid}`;
+            try {
+                await fs.writeFile(tempPath, data, { mode });
+                await fs.rename(tempPath, filePath);
+            }
+            catch (error) {
+                try {
+                    await fs.remove(tempPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+                throw error;
+            }
+        }
+        else {
+            await fs.writeFile(filePath, data, { mode });
+        }
+    }
+    catch (error) {
+        logger.error(`Failed to write buffer to file: ${filePath}`, error);
+        throw error;
+    }
+}
+/**
+ * Appends content to a file, creating it if it doesn't exist.
+ *
+ * @param filePath - Path to the file to append to
+ * @param content - Content to append
+ * @param options - Options including encoding and createDir
+ *
+ * @example
+ * ```typescript
+ * await appendFile('/path/to/log.txt', 'New log entry\n');
+ * ```
+ */
+export async function appendFile(filePath, content, options = {}) {
+    const { encoding = 'utf8', createDir = true } = options;
+    try {
+        if (createDir) {
+            await fs.ensureDir(path.dirname(filePath));
+        }
+        await fs.appendFile(filePath, content, { encoding });
+    }
+    catch (error) {
+        logger.error(`Failed to append to file: ${filePath}`, error);
+        throw error;
+    }
+}
+/**
+ * Checks if a file is readable (exists and has read permissions).
+ *
+ * @param filePath - Path to check
+ * @returns True if the file is readable
+ *
+ * @example
+ * ```typescript
+ * if (await isReadable('/path/to/file.txt')) {
+ *   const content = await safeReadFile('/path/to/file.txt');
+ * }
+ * ```
+ */
+export async function isReadable(filePath) {
+    try {
+        await fs.access(filePath, fs.constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if a file is writable (exists and has write permissions, or parent directory is writable).
+ *
+ * @param filePath - Path to check
+ * @returns True if the file is writable
+ *
+ * @example
+ * ```typescript
+ * if (await isWritable('/path/to/file.txt')) {
+ *   await safeWriteFile('/path/to/file.txt', 'content');
+ * }
+ * ```
+ */
+export async function isWritable(filePath) {
+    try {
+        // Check if file exists and is writable
+        await fs.access(filePath, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        // If file doesn't exist, check if parent directory is writable
+        try {
+            const parentDir = path.dirname(filePath);
+            await fs.access(parentDir, fs.constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Creates a symbolic link.
+ *
+ * @param target - Path that the symlink should point to
+ * @param linkPath - Path where the symlink should be created
+ *
+ * @example
+ * ```typescript
+ * await createSymlink('/path/to/target', '/path/to/link');
+ * ```
+ */
+export async function createSymlink(target, linkPath) {
+    await fs.ensureDir(path.dirname(linkPath));
+    await fs.symlink(target, linkPath);
+}
+/**
+ * Reads the target of a symbolic link.
+ *
+ * @param linkPath - Path to the symbolic link
+ * @returns The target path, or null if not a symlink
+ *
+ * @example
+ * ```typescript
+ * const target = await readSymlink('/path/to/link');
+ * if (target) {
+ *   console.log(`Link points to: ${target}`);
+ * }
+ * ```
+ */
+export async function readSymlink(linkPath) {
+    try {
+        return await fs.readlink(linkPath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Recursively gets all files in a directory.
+ *
+ * @param dirPath - Path to the directory
+ * @param options - Options for filtering
+ * @returns Array of file paths relative to dirPath
+ *
+ * @example
+ * ```typescript
+ * const files = await getFilesRecursive('/path/to/directory');
+ * for (const file of files) {
+ *   console.log(file);
+ * }
+ * ```
+ */
+export async function getFilesRecursive(dirPath, options = {}) {
+    const { maxDepth, filter } = options;
+    const files = [];
+    async function traverse(currentPath, depth) {
+        if (maxDepth !== undefined && depth > maxDepth) {
+            return;
+        }
+        const entries = await readDirWithTypes(currentPath);
+        for (const entry of entries) {
+            const fullPath = path.join(currentPath, entry.name);
+            const relativePath = path.relative(dirPath, fullPath);
+            if (entry.isDirectory()) {
+                await traverse(fullPath, depth + 1);
+            }
+            else if (entry.isFile()) {
+                if (!filter || filter(relativePath)) {
+                    files.push(relativePath);
+                }
+            }
+        }
+    }
+    if (await isDirectory(dirPath)) {
+        await traverse(dirPath, 0);
+    }
+    return files;
+}
+// =============================================================================
+// Chat Archive Directory Utilities
+// =============================================================================
+/**
+ * Gets the full path to the chat archives directory for a project.
+ *
+ * @param projectPath - Root path of the project
+ * @returns Full path to .compass/chats/ directory
+ *
+ * @example
+ * ```typescript
+ * const archiveDir = getArchiveDir('/path/to/project');
+ * // Returns: '/path/to/project/.compass/chats'
+ * ```
+ */
+export function getArchiveDir(projectPath) {
+    return path.join(projectPath, PROJECT_COMPASS_DIR, CHAT_ARCHIVE_DIR);
+}
+/**
+ * Ensures the chat archives directory exists, creating it if necessary.
+ *
+ * @param projectPath - Root path of the project
+ *
+ * @example
+ * ```typescript
+ * await ensureArchiveDir('/path/to/project');
+ * // Creates: /path/to/project/.compass/chats/ if it doesn't exist
+ * ```
+ */
+export async function ensureArchiveDir(projectPath) {
+    const archiveDir = getArchiveDir(projectPath);
+    await fs.ensureDir(archiveDir);
+}
+/**
+ * Lists all chat archive JSON files in the archives directory, sorted by filename.
+ *
+ * Since archive filenames are timestamp-based (YYYY-MM-DD_HH-mm-ss_slug.json),
+ * sorting by filename gives chronological order.
+ *
+ * @param projectPath - Root path of the project
+ * @returns Array of archive filenames (not full paths), sorted chronologically
+ *
+ * @example
+ * ```typescript
+ * const archives = await listArchiveFiles('/path/to/project');
+ * // Returns: ['2024-01-15_10-30-00_fix-auth-bug.json', '2024-01-16_14-22-15_add-feature.json']
+ * ```
+ */
+export async function listArchiveFiles(projectPath) {
+    const archiveDir = getArchiveDir(projectPath);
+    try {
+        const entries = await fs.readdir(archiveDir);
+        return entries
+            .filter((name) => name.endsWith('.json'))
+            .sort(); // Chronological due to timestamp-based naming
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return []; // Directory doesn't exist yet
+        }
+        logger.error(`Failed to list archive files: ${archiveDir}`, error);
+        throw error;
+    }
+}
+//# sourceMappingURL=file-system.js.map