@compass-ai/nova 1.0.74 → 1.0.76

package/dist/utils/file-system.js

@@ -1,798 +0,0 @@
-/**
- * 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