octie-cli 1.0.0

package/dist/core/storage/atomic-write.js

@@ -0,0 +1,379 @@
+/**
+ * Atomic file write operations
+ *
+ * Implements safe file writes using temp file + rename strategy.
+ * Ensures data integrity by:
+ * 1. Writing to temporary file first
+ * 2. Verifying write success
+ * 3. Creating backup of existing file
+ * 4. Atomic rename to final location
+ *
+ * @module core/storage/atomic-write
+ */
+import { promises as fs } from 'node:fs';
+import { join, sep, normalize, isAbsolute } from 'node:path';
+import { tmpdir } from 'node:os';
+import { FileOperationError } from '../../types/index.js';
+/**
+ * Default configuration for atomic writes
+ */
+const DEFAULT_CONFIG = {
+    backupCount: 5,
+    tempDir: tmpdir(),
+    tempPrefix: '.octie-tmp-',
+};
+/**
+ * Atomic File Writer class
+ *
+ * Provides safe file write operations using atomic rename strategy.
+ * Prevents data corruption by writing to temp file first, then renaming.
+ */
+export class AtomicFileWriter {
+    _config;
+    /**
+     * Create a new AtomicFileWriter
+     * @param config - Optional configuration
+     */
+    constructor(config = {}) {
+        this._config = {
+            backupCount: config.backupCount ?? DEFAULT_CONFIG.backupCount,
+            tempDir: config.tempDir ?? DEFAULT_CONFIG.tempDir,
+            tempPrefix: config.tempPrefix ?? DEFAULT_CONFIG.tempPrefix,
+        };
+    }
+    /**
+     * Write data to file atomically
+     *
+     * Process:
+     * 1. Write to temporary file
+     * 2. Verify write success (check file size)
+     * 3. Create backup of existing file (if exists)
+     * 4. Atomic rename to final location
+     *
+     * @param filePath - Target file path
+     * @param data - Data to write (will be JSON stringified if object)
+     * @param options - Write options
+     * @throws {FileOperationError} If write operation fails
+     */
+    async write(filePath, data, options = {}) {
+        const { createBackup = true, indent = 2 } = options;
+        // Prepare content
+        let content;
+        if (typeof data === 'string') {
+            content = data;
+        }
+        else {
+            content = JSON.stringify(data, null, indent);
+        }
+        // Validate content is not empty
+        if (content.length === 0) {
+            throw new FileOperationError('Cannot write empty content', filePath);
+        }
+        // Generate temp file path
+        const tempPath = this._getTempPath(filePath);
+        try {
+            // Step 1: Write to temporary file
+            await fs.writeFile(tempPath, content, 'utf8');
+            // Step 2: Verify write succeeded
+            const stats = await fs.stat(tempPath);
+            if (stats.size === 0) {
+                throw new FileOperationError('Write produced empty file', filePath);
+            }
+            // Use Buffer.byteLength for proper Unicode handling
+            const expectedBytes = Buffer.byteLength(content, 'utf8');
+            if (stats.size !== expectedBytes) {
+                throw new FileOperationError(`Write size mismatch: expected ${expectedBytes} bytes, got ${stats.size} bytes`, filePath);
+            }
+            // Step 3: Create backup if file exists and backup requested
+            if (createBackup) {
+                await this._createBackup(filePath);
+            }
+            // Step 4: Atomic rename to final location
+            await fs.rename(tempPath, filePath);
+        }
+        catch (error) {
+            // Cleanup temp file on failure
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            if (error instanceof FileOperationError) {
+                throw error;
+            }
+            throw new FileOperationError(`Atomic write failed: ${error instanceof Error ? error.message : String(error)}`, filePath);
+        }
+    }
+    /**
+     * Read file contents
+     * @param filePath - File path to read
+     * @returns File contents as string
+     * @throws {FileOperationError} If read fails
+     */
+    async read(filePath) {
+        try {
+            return await fs.readFile(filePath, 'utf8');
+        }
+        catch (error) {
+            throw new FileOperationError(`Read failed: ${error instanceof Error ? error.message : String(error)}`, filePath);
+        }
+    }
+    /**
+     * Read and parse JSON file
+     * @param filePath - File path to read
+     * @returns Parsed JSON object
+     * @throws {FileOperationError} If read or parse fails
+     */
+    async readJSON(filePath) {
+        try {
+            const content = await this.read(filePath);
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (error instanceof FileOperationError) {
+                throw error;
+            }
+            throw new FileOperationError(`JSON parse failed: ${error instanceof Error ? error.message : String(error)}`, filePath);
+        }
+    }
+    /**
+     * Create backup of existing file
+     * @param filePath - File to backup
+     * @private
+     */
+    async _createBackup(filePath) {
+        try {
+            // Check if file exists
+            await fs.access(filePath);
+            // Create backup path
+            const backupPath = this._getBackupPath(filePath);
+            // Copy to backup
+            await fs.copyFile(filePath, backupPath);
+            // Rotate old backups
+            await this._rotateBackups(filePath);
+        }
+        catch (error) {
+            // If file doesn't exist, that's ok - no backup needed
+            if (error.code === 'ENOENT') {
+                return;
+            }
+            // Log but don't fail on backup errors
+            console.warn(`Backup creation failed for ${filePath}:`, error);
+        }
+    }
+    /**
+     * Rotate backup files, keeping only the configured number
+     * @param filePath - Original file path
+     * @private
+     */
+    async _rotateBackups(filePath) {
+        const dir = this._getDirPath(filePath);
+        const baseName = this._getBaseName(filePath);
+        try {
+            // List existing backup files
+            const files = await fs.readdir(dir);
+            const backupFiles = files
+                .filter(f => f.startsWith(`${baseName}.bak`) || f.startsWith(`${baseName}.bak.`))
+                .sort()
+                .reverse(); // Newest first
+            // Remove excess backups
+            const backupsToDelete = backupFiles.slice(this._config.backupCount);
+            for (const file of backupsToDelete) {
+                await fs.unlink(join(dir, file));
+            }
+        }
+        catch (error) {
+            // Log but don't fail on rotation errors
+            console.warn(`Backup rotation failed for ${filePath}:`, error);
+        }
+    }
+    /**
+     * Get backup file path
+     * @param filePath - Original file path
+     * @returns Backup file path
+     * @private
+     */
+    _getBackupPath(filePath) {
+        const dir = this._getDirPath(filePath);
+        const baseName = this._getBaseName(filePath);
+        const timestamp = Date.now();
+        return join(dir, `${baseName}.bak.${timestamp}`);
+    }
+    /**
+     * Get temporary file path
+     * @param filePath - Target file path
+     * @returns Temporary file path
+     * @private
+     */
+    _getTempPath(filePath) {
+        const dir = this._getDirPath(filePath);
+        const baseName = this._getBaseName(filePath);
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 8);
+        // Use same directory as target file for cross-device compatibility (Windows EXDEV fix)
+        return join(dir, `${this._config.tempPrefix}${baseName}-${timestamp}-${random}.tmp`);
+    }
+    /**
+     * Get directory path from file path
+     * @param filePath - File path
+     * @returns Directory path
+     * @private
+     */
+    _getDirPath(filePath) {
+        const parts = filePath.split(sep);
+        parts.pop(); // Remove file name
+        return parts.join(sep) || '.';
+    }
+    /**
+     * Get base name from file path (without extension)
+     * @param filePath - File path
+     * @returns Base name
+     * @private
+     */
+    _getBaseName(filePath) {
+        const parts = filePath.split(sep);
+        const fileName = parts[parts.length - 1] || '';
+        // Remove extension
+        const lastDot = fileName.lastIndexOf('.');
+        return lastDot > 0 ? fileName.substring(0, lastDot) : fileName;
+    }
+    /**
+     * Check if file exists
+     * @param filePath - File path to check
+     * @returns True if file exists
+     */
+    async exists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete file
+     * @param filePath - File path to delete
+     * @throws {FileOperationError} If delete fails
+     */
+    async delete(filePath) {
+        try {
+            await fs.unlink(filePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return; // Already deleted
+            }
+            throw new FileOperationError(`Delete failed: ${error instanceof Error ? error.message : String(error)}`, filePath);
+        }
+    }
+    /**
+     * Ensure directory exists, create if missing
+     * @param dirPath - Directory path
+     * @throws {FileOperationError} If directory creation fails
+     */
+    async ensureDir(dirPath) {
+        try {
+            await fs.mkdir(dirPath, { recursive: true });
+        }
+        catch (error) {
+            throw new FileOperationError(`Directory creation failed: ${error instanceof Error ? error.message : String(error)}`, dirPath);
+        }
+    }
+}
+/**
+ * Cross-platform path utilities
+ */
+export class PathUtils {
+    /**
+     * Normalize path for consistent storage
+     * Converts backslashes to forward slashes, removes redundant separators
+     * @param path - Path to normalize
+     * @returns Normalized path
+     */
+    static normalizePath(path) {
+        return normalize(path).split(sep).join('/');
+    }
+    /**
+     * Join path segments
+     * @param segments - Path segments to join
+     * @returns Joined path
+     */
+    static join(...segments) {
+        return join(...segments);
+    }
+    /**
+     * Check if path is absolute
+     * @param path - Path to check
+     * @returns True if path is absolute
+     */
+    static isAbsolute(path) {
+        return isAbsolute(path);
+    }
+    /**
+     * Make path relative to another path
+     * @param from - Base path
+     * @param to - Target path
+     * @returns Relative path
+     */
+    static relative(from, to) {
+        // Use relative from path module
+        const { relative } = require('node:path');
+        return relative(from, to);
+    }
+    /**
+     * Get project configuration path
+     * Platform-aware configuration directory
+     * @param projectName - Project name
+     * @returns Configuration path
+     */
+    static getConfigPath(projectName) {
+        const platform = process.platform;
+        const homedir = require('node:os').homedir();
+        switch (platform) {
+            case 'win32':
+                return join(process.env.APPDATA || homedir, projectName);
+            case 'darwin':
+                return join(homedir, 'Library', 'Application Support', projectName);
+            default: // linux and others
+                return join(homedir, '.config', projectName);
+        }
+    }
+    /**
+     * Get project data path
+     * Platform-aware data directory
+     * @param projectName - Project name
+     * @returns Data path
+     */
+    static getDataPath(projectName) {
+        const platform = process.platform;
+        const homedir = require('node:os').homedir();
+        switch (platform) {
+            case 'win32':
+                return join(process.env.LOCALAPPDATA || join(homedir, 'AppData', 'Local'), projectName);
+            case 'darwin':
+                return join(homedir, 'Library', 'Application Support', projectName);
+            default: // linux and others
+                return join(homedir, '.local', 'share', projectName);
+        }
+    }
+    /**
+     * Sanitize file path to prevent directory traversal
+     * @param filePath - File path to sanitize
+     * @param basePath - Base path to resolve against
+     * @returns Sanitized, absolute path
+     * @throws {FileOperationError} If path tries to escape base directory
+     */
+    static sanitizePath(filePath, basePath = process.cwd()) {
+        const normalized = normalize(filePath);
+        const resolved = join(basePath, normalized);
+        // Check if resolved path is within base path
+        const relativePath = this.relative(basePath, resolved);
+        if (relativePath.startsWith('..')) {
+            throw new FileOperationError('Path traversal detected: file path cannot escape base directory', filePath);
+        }
+        return resolved;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/core/storage/atomic-write.js.map

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

package/dist/core/storage/file-store.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Task Storage for file operations
+ *
+ * Manages persistent storage of task graphs using atomic file operations.
+ * Handles project.json, backups, and .octie directory structure.
+ *
+ * Directory Structure:
+ * .octie/
+ * ├── project.json          # Main task storage
+ * ├── project.json.bak      # Latest backup
+ * ├── project.json.bak.{ts} # Rotated backups
+ * ├── indexes/              # Pre-computed indexes
+ * ├── cache/                # Serialized graph cache
+ * └── config.json           # Project configuration
+ *
+ * @module core/storage
+ */
+import type { ProjectMetadata } from '../../types/index.js';
+import { TaskGraphStore } from '../graph/index.js';
+/**
+ * Task Storage configuration
+ */
+export interface TaskStorageConfig {
+    /** Project directory path */
+    projectDir?: string;
+    /** Octie directory name (default: '.octie') */
+    octieDirName?: string;
+    /** Project file name (default: 'project.json') */
+    projectFileName?: string;
+    /** Auto-backup enabled (default: true) */
+    autoBackup?: boolean;
+    /** Number of backups to keep (default: 5) */
+    backupCount?: number;
+}
+/**
+ * Task Storage class
+ *
+ * Manages persistent storage of task graphs with atomic operations.
+ */
+export declare class TaskStorage {
+    private _projectDir;
+    private _octieDirName;
+    private _projectFileName;
+    private _autoBackup;
+    private _backupCount;
+    private _writer;
+    /**
+     * Create a new TaskStorage instance
+     * @param config - Storage configuration
+     */
+    constructor(config?: TaskStorageConfig);
+    /**
+     * Get the Octie directory path
+     */
+    get octieDirPath(): string;
+    /**
+     * Get the project file path
+     */
+    get projectFilePath(): string;
+    /**
+     * Get the backup file path
+     */
+    get backupFilePath(): string;
+    /**
+     * Get the indexes directory path
+     */
+    get indexesDirPath(): string;
+    /**
+     * Get the cache directory path
+     */
+    get cacheDirPath(): string;
+    /**
+     * Get the config file path
+     */
+    get configFilePath(): string;
+    /**
+     * Initialize the Octie directory structure
+     * Creates .octie directory with subdirectories if they don't exist
+     */
+    init(): Promise<void>;
+    /**
+     * Check if Octie directory exists
+     * @returns True if .octie directory exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Load project from file
+     * @returns TaskGraphStore instance
+     * @throws {FileOperationError} If file doesn't exist or is invalid
+     */
+    load(): Promise<TaskGraphStore>;
+    /**
+     * Save project to file
+     * @param graph - TaskGraphStore to save
+     * @param options - Save options
+     */
+    save(graph: TaskGraphStore, options?: {
+        createBackup?: boolean;
+    }): Promise<void>;
+    /**
+     * Build indexes for fast lookups
+     * @param graph - TaskGraphStore to index
+     * @returns ProjectIndexes
+     * @private
+     */
+    private _buildIndexes;
+    /**
+     * Validate project file structure
+     * @param projectFile - Project file to validate
+     * @throws {ValidationError} If structure is invalid
+     * @private
+     */
+    private _validateProjectFile;
+    /**
+     * Get project metadata only (faster than full load)
+     * @returns Project metadata
+     * @throws {FileOperationError} If file doesn't exist
+     */
+    getMetadata(): Promise<ProjectMetadata>;
+    /**
+     * Delete project file and backups
+     * Use with caution - this is destructive
+     */
+    delete(): Promise<void>;
+    /**
+     * Create a new project with default metadata
+     * @param projectName - Project name
+     * @param description - Optional project description
+     */
+    createProject(projectName: string, description?: string): Promise<void>;
+    /**
+     * List backup files
+     * @returns Array of backup file paths
+     */
+    listBackups(): Promise<string[]>;
+    /**
+     * Restore from latest backup
+     * @throws {FileOperationError} If no backup exists
+     */
+    restoreFromBackup(): Promise<void>;
+}
+/**
+ * Get project path for current directory
+ * Searches upward from current directory for .octie folder
+ * @returns Project directory path or undefined if not found
+ */
+export declare function findProjectPath(startDir?: string): Promise<string | undefined>;
+//# sourceMappingURL=file-store.d.ts.map

package/dist/core/storage/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../../src/core/storage/file-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAA+B,eAAe,EAAa,MAAM,sBAAsB,CAAC;AAGpG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAanD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAmB;IAElC;;;OAGG;gBACS,MAAM,GAAE,iBAAsB;IAY1C;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC;IAwCrC;;;;OAIG;IACG,IAAI,CACR,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO,GACvC,OAAO,CAAC,IAAI,CAAC;IA8ChB;;;;;OAKG;YACW,aAAa;IAiE3B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAwB5B;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAmB7C;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB7B;;;;OAIG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C7E;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAkBtC;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAwBzC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA4BnG"}