claude-flow-novice 2.15.3 → 2.15.5

package/dist/lib/atomic-file-writer.js

@@ -0,0 +1,377 @@
+/**
+ * Atomic File Writer
+ *
+ * Provides atomic file write operations with SHA256 checksum verification,
+ * rollback capability, and permission preservation.
+ * Part of Task 4.2: Centralized File Locking & Atomic Operations
+ *
+ * Features:
+ * - Write-then-move pattern (write to temp, verify, move to target)
+ * - SHA256 checksum verification
+ * - Automatic rollback on failure
+ * - Preserve file permissions and ownership
+ * - Backup creation before overwrite
+ * - Integration with file lock manager
+ *
+ * Usage:
+ *   const writer = new AtomicFileWriter();
+ *   await writer.writeFile('/path/to/file.txt', content, {
+ *     createBackup: true,
+ *     preservePermissions: true
+ *   });
+ */ import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { promisify } from 'util';
+import { randomUUID } from 'crypto';
+import { createLogger } from './logging.js';
+import { createError, ErrorCode } from './errors.js';
+import { withFileLock } from './file-lock-manager.js';
+const logger = createLogger('atomic-file-writer');
+const fsWriteFile = promisify(fs.writeFile);
+const fsReadFile = promisify(fs.readFile);
+const fsRename = promisify(fs.rename);
+const fsUnlink = promisify(fs.unlink);
+const fsStat = promisify(fs.stat);
+const fsMkdir = promisify(fs.mkdir);
+const fsChmod = promisify(fs.chmod);
+const fsChown = promisify(fs.chown);
+const fsAccess = promisify(fs.access);
+const fsCopyFile = promisify(fs.copyFile);
+/**
+ * Atomic File Writer
+ *
+ * Provides safe atomic file writes with verification and rollback.
+ */ export class AtomicFileWriter {
+    /**
+   * Write file atomically with verification
+   *
+   * @param filePath - Target file path
+   * @param content - Content to write (string or Buffer)
+   * @param options - Write options
+   * @returns Promise<WriteResult> - Write result with metadata
+   */ async writeFile(filePath, content, options = {}) {
+        const startTime = Date.now();
+        const absolutePath = path.resolve(filePath);
+        const opts = {
+            encoding: options.encoding || 'utf8',
+            createBackup: options.createBackup || false,
+            preservePermissions: options.preservePermissions !== false,
+            preserveOwnership: options.preserveOwnership || false,
+            verifyChecksum: options.verifyChecksum !== false,
+            useLock: options.useLock !== false,
+            lockOptions: options.lockOptions || {},
+            backupDir: options.backupDir
+        };
+        logger.debug('Starting atomic write', {
+            filePath: absolutePath,
+            contentLength: typeof content === 'string' ? content.length : content.length,
+            options: opts
+        });
+        // Calculate expected checksum
+        const expectedChecksum = this.calculateChecksum(content);
+        // Execute write with lock if requested
+        if (opts.useLock) {
+            return withFileLock(absolutePath, async ()=>this.performWrite(absolutePath, content, opts, expectedChecksum, startTime), opts.lockOptions);
+        } else {
+            return this.performWrite(absolutePath, content, opts, expectedChecksum, startTime);
+        }
+    }
+    /**
+   * Perform the actual write operation
+   */ async performWrite(absolutePath, content, options, expectedChecksum, startTime) {
+        const dir = path.dirname(absolutePath);
+        const tempPath = path.join(dir, `.${path.basename(absolutePath)}.${randomUUID()}.tmp`);
+        let backupPath;
+        let originalMetadata = null;
+        let rolledBack = false;
+        try {
+            // Ensure directory exists
+            await this.ensureDirectory(dir);
+            // Get original file metadata (if exists)
+            originalMetadata = await this.getFileMetadata(absolutePath);
+            // Create backup if requested and file exists
+            if (options.createBackup && originalMetadata.exists) {
+                backupPath = await this.createBackup(absolutePath, options.backupDir);
+                logger.info('Backup created', {
+                    original: absolutePath,
+                    backup: backupPath
+                });
+            }
+            // Write to temporary file
+            logger.debug('Writing to temporary file', {
+                tempPath
+            });
+            await fsWriteFile(tempPath, content, options.encoding);
+            // Verify checksum
+            if (options.verifyChecksum) {
+                const actualChecksum = await this.calculateFileChecksum(tempPath);
+                if (actualChecksum !== expectedChecksum) {
+                    throw createError(ErrorCode.CHECKSUM_MISMATCH, 'Checksum verification failed after write', {
+                        expected: expectedChecksum,
+                        actual: actualChecksum,
+                        filePath: absolutePath
+                    });
+                }
+                logger.debug('Checksum verified', {
+                    checksum: actualChecksum
+                });
+            }
+            // Preserve permissions if requested
+            if (options.preservePermissions && originalMetadata.exists) {
+                await fsChmod(tempPath, originalMetadata.mode);
+                logger.debug('Permissions preserved', {
+                    mode: originalMetadata.mode.toString(8)
+                });
+            }
+            // Preserve ownership if requested (requires privileges)
+            if (options.preserveOwnership && originalMetadata.exists) {
+                try {
+                    await fsChown(tempPath, originalMetadata.uid, originalMetadata.gid);
+                    logger.debug('Ownership preserved', {
+                        uid: originalMetadata.uid,
+                        gid: originalMetadata.gid
+                    });
+                } catch (error) {
+                    logger.warn('Failed to preserve ownership (requires elevated privileges)', error instanceof Error ? error : undefined);
+                }
+            }
+            // Atomic move to target location
+            logger.debug('Moving to target location', {
+                from: tempPath,
+                to: absolutePath
+            });
+            await fsRename(tempPath, absolutePath);
+            // Get final file size
+            const stat = await fsStat(absolutePath);
+            const bytesWritten = stat.size;
+            const durationMs = Date.now() - startTime;
+            logger.info('Atomic write completed successfully', {
+                filePath: absolutePath,
+                bytesWritten,
+                checksum: expectedChecksum,
+                durationMs
+            });
+            return {
+                success: true,
+                filePath: absolutePath,
+                checksum: expectedChecksum,
+                bytesWritten,
+                durationMs,
+                backupPath,
+                rolledBack: false
+            };
+        } catch (error) {
+            logger.error('Atomic write failed, attempting rollback', error instanceof Error ? error : undefined, {
+                filePath: absolutePath
+            });
+            // Attempt rollback
+            try {
+                // Remove temp file if it exists
+                if (await this.fileExists(tempPath)) {
+                    await fsUnlink(tempPath);
+                    logger.debug('Temporary file removed', {
+                        tempPath
+                    });
+                }
+                // Restore from backup if available
+                if (backupPath && await this.fileExists(backupPath)) {
+                    await fsCopyFile(backupPath, absolutePath);
+                    logger.info('Restored from backup after failed write', {
+                        backup: backupPath,
+                        target: absolutePath
+                    });
+                    rolledBack = true;
+                }
+            } catch (rollbackError) {
+                logger.error('Rollback failed', rollbackError instanceof Error ? rollbackError : undefined, {
+                    filePath: absolutePath,
+                    backupPath
+                });
+            }
+            const durationMs = Date.now() - startTime;
+            throw createError(ErrorCode.FILE_WRITE_FAILED, `Atomic write failed: ${absolutePath}`, {
+                filePath: absolutePath,
+                durationMs,
+                backupPath,
+                rolledBack
+            }, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+   * Calculate SHA256 checksum of content
+   */ calculateChecksum(content) {
+        const hash = crypto.createHash('sha256');
+        hash.update(content);
+        return hash.digest('hex');
+    }
+    /**
+   * Calculate SHA256 checksum of file
+   */ async calculateFileChecksum(filePath) {
+        return new Promise((resolve, reject)=>{
+            const hash = crypto.createHash('sha256');
+            const stream = fs.createReadStream(filePath);
+            stream.on('data', (chunk)=>hash.update(chunk));
+            stream.on('end', ()=>resolve(hash.digest('hex')));
+            stream.on('error', reject);
+        });
+    }
+    /**
+   * Get file metadata for permission preservation
+   */ async getFileMetadata(filePath) {
+        try {
+            const stats = await fsStat(filePath);
+            return {
+                mode: stats.mode,
+                uid: stats.uid,
+                gid: stats.gid,
+                exists: true
+            };
+        } catch (error) {
+            // File doesn't exist
+            return {
+                mode: 0o644,
+                uid: process.getuid ? process.getuid() : 0,
+                gid: process.getgid ? process.getgid() : 0,
+                exists: false
+            };
+        }
+    }
+    /**
+   * Create backup of existing file
+   */ async createBackup(filePath, backupDir) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const basename = path.basename(filePath);
+        const targetDir = backupDir || path.dirname(filePath);
+        // Ensure backup directory exists
+        await this.ensureDirectory(targetDir);
+        const backupPath = path.join(targetDir, `${basename}.${timestamp}.backup`);
+        try {
+            await fsCopyFile(filePath, backupPath);
+            return backupPath;
+        } catch (error) {
+            throw createError(ErrorCode.BACKUP_FAILED, `Failed to create backup: ${filePath}`, {
+                filePath,
+                backupPath
+            }, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+   * Check if file exists
+   */ async fileExists(filePath) {
+        try {
+            await fsAccess(filePath, fs.constants.F_OK);
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    /**
+   * Ensure directory exists
+   */ async ensureDirectory(dirPath) {
+        try {
+            await fsMkdir(dirPath, {
+                recursive: true
+            });
+        } catch (error) {
+            // Ignore error if directory already exists
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+        }
+    }
+    /**
+   * Read file atomically with checksum verification
+   *
+   * @param filePath - File to read
+   * @param expectedChecksum - Optional expected checksum
+   * @param encoding - File encoding (default: 'utf8')
+   * @returns Promise<{content: string, checksum: string}> - File content and checksum
+   */ async readFile(filePath, expectedChecksum, encoding = 'utf8') {
+        const absolutePath = path.resolve(filePath);
+        try {
+            const content = await fsReadFile(absolutePath, encoding);
+            const checksum = this.calculateChecksum(content);
+            if (expectedChecksum && checksum !== expectedChecksum) {
+                throw createError(ErrorCode.CHECKSUM_MISMATCH, 'Checksum verification failed during read', {
+                    expected: expectedChecksum,
+                    actual: checksum,
+                    filePath: absolutePath
+                });
+            }
+            logger.debug('File read with checksum verification', {
+                filePath: absolutePath,
+                checksum,
+                verified: !!expectedChecksum
+            });
+            return {
+                content,
+                checksum
+            };
+        } catch (error) {
+            throw createError(ErrorCode.FILE_READ_FAILED, `Failed to read file: ${absolutePath}`, {
+                filePath: absolutePath
+            }, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+   * Verify file checksum
+   *
+   * @param filePath - File to verify
+   * @param expectedChecksum - Expected SHA256 checksum
+   * @returns Promise<boolean> - True if checksum matches
+   */ async verifyChecksum(filePath, expectedChecksum) {
+        const absolutePath = path.resolve(filePath);
+        try {
+            const actualChecksum = await this.calculateFileChecksum(absolutePath);
+            const matches = actualChecksum === expectedChecksum;
+            logger.debug('Checksum verification', {
+                filePath: absolutePath,
+                expected: expectedChecksum,
+                actual: actualChecksum,
+                matches
+            });
+            return matches;
+        } catch (error) {
+            logger.error('Checksum verification failed', error instanceof Error ? error : undefined, {
+                filePath: absolutePath
+            });
+            return false;
+        }
+    }
+}
+/**
+ * Singleton instance
+ */ let defaultWriter = null;
+/**
+ * Get the default atomic file writer instance
+ */ export function getAtomicFileWriter() {
+    if (!defaultWriter) {
+        defaultWriter = new AtomicFileWriter();
+    }
+    return defaultWriter;
+}
+/**
+ * Helper function for atomic writes
+ *
+ * @param filePath - Target file path
+ * @param content - Content to write
+ * @param options - Write options
+ * @returns Promise<WriteResult> - Write result
+ */ export async function atomicWriteFile(filePath, content, options = {}) {
+    const writer = getAtomicFileWriter();
+    return writer.writeFile(filePath, content, options);
+}
+/**
+ * Helper function for atomic reads with checksum
+ *
+ * @param filePath - File to read
+ * @param expectedChecksum - Optional expected checksum
+ * @param encoding - File encoding
+ * @returns Promise<{content: string, checksum: string}>
+ */ export async function atomicReadFile(filePath, expectedChecksum, encoding = 'utf8') {
+    const writer = getAtomicFileWriter();
+    return writer.readFile(filePath, expectedChecksum, encoding);
+}
+
+//# sourceMappingURL=atomic-file-writer.js.map

package/dist/lib/atomic-file-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/atomic-file-writer.ts"],"sourcesContent":["/**\r\n * Atomic File Writer\r\n *\r\n * Provides atomic file write operations with SHA256 checksum verification,\r\n * rollback capability, and permission preservation.\r\n * Part of Task 4.2: Centralized File Locking & Atomic Operations\r\n *\r\n * Features:\r\n * - Write-then-move pattern (write to temp, verify, move to target)\r\n * - SHA256 checksum verification\r\n * - Automatic rollback on failure\r\n * - Preserve file permissions and ownership\r\n * - Backup creation before overwrite\r\n * - Integration with file lock manager\r\n *\r\n * Usage:\r\n *   const writer = new AtomicFileWriter();\r\n *   await writer.writeFile('/path/to/file.txt', content, {\r\n *     createBackup: true,\r\n *     preservePermissions: true\r\n *   });\r\n */\r\n\r\nimport * as fs from 'fs';\r\nimport * as path from 'path';\r\nimport * as crypto from 'crypto';\r\nimport { promisify } from 'util';\r\nimport { randomUUID } from 'crypto';\r\nimport { createLogger } from './logging.js';\r\nimport { createError, ErrorCode } from './errors.js';\r\nimport { withFileLock, LockAcquisitionOptions } from './file-lock-manager.js';\r\n\r\nconst logger = createLogger('atomic-file-writer');\r\n\r\nconst fsWriteFile = promisify(fs.writeFile);\r\nconst fsReadFile = promisify(fs.readFile);\r\nconst fsRename = promisify(fs.rename);\r\nconst fsUnlink = promisify(fs.unlink);\r\nconst fsStat = promisify(fs.stat);\r\nconst fsMkdir = promisify(fs.mkdir);\r\nconst fsChmod = promisify(fs.chmod);\r\nconst fsChown = promisify(fs.chown);\r\nconst fsAccess = promisify(fs.access);\r\nconst fsCopyFile = promisify(fs.copyFile);\r\n\r\n/**\r\n * File write options\r\n */\r\nexport interface WriteOptions {\r\n  /** File encoding (default: 'utf8') */\r\n  encoding?: BufferEncoding;\r\n  /** Create backup before overwrite (default: false) */\r\n  createBackup?: boolean;\r\n  /** Preserve file permissions (default: true) */\r\n  preservePermissions?: boolean;\r\n  /** Preserve file ownership (default: false, requires sudo) */\r\n  preserveOwnership?: boolean;\r\n  /** Verify checksum after write (default: true) */\r\n  verifyChecksum?: boolean;\r\n  /** Lock file during write (default: true) */\r\n  useLock?: boolean;\r\n  /** Lock options (if useLock is true) */\r\n  lockOptions?: LockAcquisitionOptions;\r\n  /** Backup directory (default: same as target) */\r\n  backupDir?: string;\r\n}\r\n\r\n/**\r\n * Write result with metadata\r\n */\r\nexport interface WriteResult {\r\n  /** Success status */\r\n  success: boolean;\r\n  /** File path */\r\n  filePath: string;\r\n  /** SHA256 checksum of written content */\r\n  checksum: string;\r\n  /** Bytes written */\r\n  bytesWritten: number;\r\n  /** Write duration in milliseconds */\r\n  durationMs: number;\r\n  /** Backup path (if created) */\r\n  backupPath?: string;\r\n  /** Whether rollback occurred */\r\n  rolledBack: boolean;\r\n}\r\n\r\n/**\r\n * File metadata for permission preservation\r\n */\r\ninterface FileMetadata {\r\n  mode: number;\r\n  uid: number;\r\n  gid: number;\r\n  exists: boolean;\r\n}\r\n\r\n/**\r\n * Atomic File Writer\r\n *\r\n * Provides safe atomic file writes with verification and rollback.\r\n */\r\nexport class AtomicFileWriter {\r\n  /**\r\n   * Write file atomically with verification\r\n   *\r\n   * @param filePath - Target file path\r\n   * @param content - Content to write (string or Buffer)\r\n   * @param options - Write options\r\n   * @returns Promise<WriteResult> - Write result with metadata\r\n   */\r\n  async writeFile(\r\n    filePath: string,\r\n    content: string | Buffer,\r\n    options: WriteOptions = {}\r\n  ): Promise<WriteResult> {\r\n    const startTime = Date.now();\r\n    const absolutePath = path.resolve(filePath);\r\n\r\n    const opts = {\r\n      encoding: (options.encoding || 'utf8') as BufferEncoding,\r\n      createBackup: options.createBackup || false,\r\n      preservePermissions: options.preservePermissions !== false,\r\n      preserveOwnership: options.preserveOwnership || false,\r\n      verifyChecksum: options.verifyChecksum !== false,\r\n      useLock: options.useLock !== false,\r\n      lockOptions: options.lockOptions || {},\r\n      backupDir: options.backupDir,\r\n    };\r\n\r\n    logger.debug('Starting atomic write', {\r\n      filePath: absolutePath,\r\n      contentLength: typeof content === 'string' ? content.length : content.length,\r\n      options: opts,\r\n    });\r\n\r\n    // Calculate expected checksum\r\n    const expectedChecksum = this.calculateChecksum(content);\r\n\r\n    // Execute write with lock if requested\r\n    if (opts.useLock) {\r\n      return withFileLock(\r\n        absolutePath,\r\n        async () => this.performWrite(absolutePath, content, opts, expectedChecksum, startTime),\r\n        opts.lockOptions\r\n      );\r\n    } else {\r\n      return this.performWrite(absolutePath, content, opts, expectedChecksum, startTime);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Perform the actual write operation\r\n   */\r\n  private async performWrite(\r\n    absolutePath: string,\r\n    content: string | Buffer,\r\n    options: Required<WriteOptions>,\r\n    expectedChecksum: string,\r\n    startTime: number\r\n  ): Promise<WriteResult> {\r\n    const dir = path.dirname(absolutePath);\r\n    const tempPath = path.join(dir, `.${path.basename(absolutePath)}.${randomUUID()}.tmp`);\r\n    let backupPath: string | undefined;\r\n    let originalMetadata: FileMetadata | null = null;\r\n    let rolledBack = false;\r\n\r\n    try {\r\n      // Ensure directory exists\r\n      await this.ensureDirectory(dir);\r\n\r\n      // Get original file metadata (if exists)\r\n      originalMetadata = await this.getFileMetadata(absolutePath);\r\n\r\n      // Create backup if requested and file exists\r\n      if (options.createBackup && originalMetadata.exists) {\r\n        backupPath = await this.createBackup(absolutePath, options.backupDir);\r\n        logger.info('Backup created', { original: absolutePath, backup: backupPath });\r\n      }\r\n\r\n      // Write to temporary file\r\n      logger.debug('Writing to temporary file', { tempPath });\r\n      await fsWriteFile(tempPath, content, options.encoding);\r\n\r\n      // Verify checksum\r\n      if (options.verifyChecksum) {\r\n        const actualChecksum = await this.calculateFileChecksum(tempPath);\r\n        if (actualChecksum !== expectedChecksum) {\r\n          throw createError(\r\n            ErrorCode.CHECKSUM_MISMATCH,\r\n            'Checksum verification failed after write',\r\n            {\r\n              expected: expectedChecksum,\r\n              actual: actualChecksum,\r\n              filePath: absolutePath,\r\n            }\r\n          );\r\n        }\r\n        logger.debug('Checksum verified', { checksum: actualChecksum });\r\n      }\r\n\r\n      // Preserve permissions if requested\r\n      if (options.preservePermissions && originalMetadata.exists) {\r\n        await fsChmod(tempPath, originalMetadata.mode);\r\n        logger.debug('Permissions preserved', { mode: originalMetadata.mode.toString(8) });\r\n      }\r\n\r\n      // Preserve ownership if requested (requires privileges)\r\n      if (options.preserveOwnership && originalMetadata.exists) {\r\n        try {\r\n          await fsChown(tempPath, originalMetadata.uid, originalMetadata.gid);\r\n          logger.debug('Ownership preserved', {\r\n            uid: originalMetadata.uid,\r\n            gid: originalMetadata.gid,\r\n          });\r\n        } catch (error) {\r\n          logger.warn(\r\n            'Failed to preserve ownership (requires elevated privileges)',\r\n            error instanceof Error ? error : undefined\r\n          );\r\n        }\r\n      }\r\n\r\n      // Atomic move to target location\r\n      logger.debug('Moving to target location', { from: tempPath, to: absolutePath });\r\n      await fsRename(tempPath, absolutePath);\r\n\r\n      // Get final file size\r\n      const stat = await fsStat(absolutePath);\r\n      const bytesWritten = stat.size;\r\n\r\n      const durationMs = Date.now() - startTime;\r\n\r\n      logger.info('Atomic write completed successfully', {\r\n        filePath: absolutePath,\r\n        bytesWritten,\r\n        checksum: expectedChecksum,\r\n        durationMs,\r\n      });\r\n\r\n      return {\r\n        success: true,\r\n        filePath: absolutePath,\r\n        checksum: expectedChecksum,\r\n        bytesWritten,\r\n        durationMs,\r\n        backupPath,\r\n        rolledBack: false,\r\n      };\r\n    } catch (error) {\r\n      logger.error(\r\n        'Atomic write failed, attempting rollback',\r\n        error instanceof Error ? error : undefined,\r\n        { filePath: absolutePath }\r\n      );\r\n\r\n      // Attempt rollback\r\n      try {\r\n        // Remove temp file if it exists\r\n        if (await this.fileExists(tempPath)) {\r\n          await fsUnlink(tempPath);\r\n          logger.debug('Temporary file removed', { tempPath });\r\n        }\r\n\r\n        // Restore from backup if available\r\n        if (backupPath && (await this.fileExists(backupPath))) {\r\n          await fsCopyFile(backupPath, absolutePath);\r\n          logger.info('Restored from backup after failed write', {\r\n            backup: backupPath,\r\n            target: absolutePath,\r\n          });\r\n          rolledBack = true;\r\n        }\r\n      } catch (rollbackError) {\r\n        logger.error(\r\n          'Rollback failed',\r\n          rollbackError instanceof Error ? rollbackError : undefined,\r\n          { filePath: absolutePath, backupPath }\r\n        );\r\n      }\r\n\r\n      const durationMs = Date.now() - startTime;\r\n\r\n      throw createError(\r\n        ErrorCode.FILE_WRITE_FAILED,\r\n        `Atomic write failed: ${absolutePath}`,\r\n        {\r\n          filePath: absolutePath,\r\n          durationMs,\r\n          backupPath,\r\n          rolledBack,\r\n        },\r\n        error instanceof Error ? error : undefined\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Calculate SHA256 checksum of content\r\n   */\r\n  private calculateChecksum(content: string | Buffer): string {\r\n    const hash = crypto.createHash('sha256');\r\n    hash.update(content);\r\n    return hash.digest('hex');\r\n  }\r\n\r\n  /**\r\n   * Calculate SHA256 checksum of file\r\n   */\r\n  private async calculateFileChecksum(filePath: string): Promise<string> {\r\n    return new Promise((resolve, reject) => {\r\n      const hash = crypto.createHash('sha256');\r\n      const stream = fs.createReadStream(filePath);\r\n\r\n      stream.on('data', (chunk) => hash.update(chunk));\r\n      stream.on('end', () => resolve(hash.digest('hex')));\r\n      stream.on('error', reject);\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Get file metadata for permission preservation\r\n   */\r\n  private async getFileMetadata(filePath: string): Promise<FileMetadata> {\r\n    try {\r\n      const stats = await fsStat(filePath);\r\n      return {\r\n        mode: stats.mode,\r\n        uid: stats.uid,\r\n        gid: stats.gid,\r\n        exists: true,\r\n      };\r\n    } catch (error) {\r\n      // File doesn't exist\r\n      return {\r\n        mode: 0o644, // Default permissions\r\n        uid: process.getuid ? process.getuid() : 0,\r\n        gid: process.getgid ? process.getgid() : 0,\r\n        exists: false,\r\n      };\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Create backup of existing file\r\n   */\r\n  private async createBackup(filePath: string, backupDir?: string): Promise<string> {\r\n    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\r\n    const basename = path.basename(filePath);\r\n    const targetDir = backupDir || path.dirname(filePath);\r\n\r\n    // Ensure backup directory exists\r\n    await this.ensureDirectory(targetDir);\r\n\r\n    const backupPath = path.join(targetDir, `${basename}.${timestamp}.backup`);\r\n\r\n    try {\r\n      await fsCopyFile(filePath, backupPath);\r\n      return backupPath;\r\n    } catch (error) {\r\n      throw createError(\r\n        ErrorCode.BACKUP_FAILED,\r\n        `Failed to create backup: ${filePath}`,\r\n        { filePath, backupPath },\r\n        error instanceof Error ? error : undefined\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Check if file exists\r\n   */\r\n  private async fileExists(filePath: string): Promise<boolean> {\r\n    try {\r\n      await fsAccess(filePath, fs.constants.F_OK);\r\n      return true;\r\n    } catch {\r\n      return false;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Ensure directory exists\r\n   */\r\n  private async ensureDirectory(dirPath: string): Promise<void> {\r\n    try {\r\n      await fsMkdir(dirPath, { recursive: true });\r\n    } catch (error) {\r\n      // Ignore error if directory already exists\r\n      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\r\n        throw error;\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Read file atomically with checksum verification\r\n   *\r\n   * @param filePath - File to read\r\n   * @param expectedChecksum - Optional expected checksum\r\n   * @param encoding - File encoding (default: 'utf8')\r\n   * @returns Promise<{content: string, checksum: string}> - File content and checksum\r\n   */\r\n  async readFile(\r\n    filePath: string,\r\n    expectedChecksum?: string,\r\n    encoding: BufferEncoding = 'utf8'\r\n  ): Promise<{ content: string; checksum: string }> {\r\n    const absolutePath = path.resolve(filePath);\r\n\r\n    try {\r\n      const content = await fsReadFile(absolutePath, encoding);\r\n      const checksum = this.calculateChecksum(content);\r\n\r\n      if (expectedChecksum && checksum !== expectedChecksum) {\r\n        throw createError(\r\n          ErrorCode.CHECKSUM_MISMATCH,\r\n          'Checksum verification failed during read',\r\n          {\r\n            expected: expectedChecksum,\r\n            actual: checksum,\r\n            filePath: absolutePath,\r\n          }\r\n        );\r\n      }\r\n\r\n      logger.debug('File read with checksum verification', {\r\n        filePath: absolutePath,\r\n        checksum,\r\n        verified: !!expectedChecksum,\r\n      });\r\n\r\n      return { content, checksum };\r\n    } catch (error) {\r\n      throw createError(\r\n        ErrorCode.FILE_READ_FAILED,\r\n        `Failed to read file: ${absolutePath}`,\r\n        { filePath: absolutePath },\r\n        error instanceof Error ? error : undefined\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Verify file checksum\r\n   *\r\n   * @param filePath - File to verify\r\n   * @param expectedChecksum - Expected SHA256 checksum\r\n   * @returns Promise<boolean> - True if checksum matches\r\n   */\r\n  async verifyChecksum(filePath: string, expectedChecksum: string): Promise<boolean> {\r\n    const absolutePath = path.resolve(filePath);\r\n\r\n    try {\r\n      const actualChecksum = await this.calculateFileChecksum(absolutePath);\r\n      const matches = actualChecksum === expectedChecksum;\r\n\r\n      logger.debug('Checksum verification', {\r\n        filePath: absolutePath,\r\n        expected: expectedChecksum,\r\n        actual: actualChecksum,\r\n        matches,\r\n      });\r\n\r\n      return matches;\r\n    } catch (error) {\r\n      logger.error(\r\n        'Checksum verification failed',\r\n        error instanceof Error ? error : undefined,\r\n        { filePath: absolutePath }\r\n      );\r\n      return false;\r\n    }\r\n  }\r\n}\r\n\r\n/**\r\n * Singleton instance\r\n */\r\nlet defaultWriter: AtomicFileWriter | null = null;\r\n\r\n/**\r\n * Get the default atomic file writer instance\r\n */\r\nexport function getAtomicFileWriter(): AtomicFileWriter {\r\n  if (!defaultWriter) {\r\n    defaultWriter = new AtomicFileWriter();\r\n  }\r\n  return defaultWriter;\r\n}\r\n\r\n/**\r\n * Helper function for atomic writes\r\n *\r\n * @param filePath - Target file path\r\n * @param content - Content to write\r\n * @param options - Write options\r\n * @returns Promise<WriteResult> - Write result\r\n */\r\nexport async function atomicWriteFile(\r\n  filePath: string,\r\n  content: string | Buffer,\r\n  options: WriteOptions = {}\r\n): Promise<WriteResult> {\r\n  const writer = getAtomicFileWriter();\r\n  return writer.writeFile(filePath, content, options);\r\n}\r\n\r\n/**\r\n * Helper function for atomic reads with checksum\r\n *\r\n * @param filePath - File to read\r\n * @param expectedChecksum - Optional expected checksum\r\n * @param encoding - File encoding\r\n * @returns Promise<{content: string, checksum: string}>\r\n */\r\nexport async function atomicReadFile(\r\n  filePath: string,\r\n  expectedChecksum?: string,\r\n  encoding: BufferEncoding = 'utf8'\r\n): Promise<{ content: string; checksum: string }> {\r\n  const writer = getAtomicFileWriter();\r\n  return writer.readFile(filePath, expectedChecksum, encoding);\r\n}\r\n"],"names":["fs","path","crypto","promisify","randomUUID","createLogger","createError","ErrorCode","withFileLock","logger","fsWriteFile","writeFile","fsReadFile","readFile","fsRename","rename","fsUnlink","unlink","fsStat","stat","fsMkdir","mkdir","fsChmod","chmod","fsChown","chown","fsAccess","access","fsCopyFile","copyFile","AtomicFileWriter","filePath","content","options","startTime","Date","now","absolutePath","resolve","opts","encoding","createBackup","preservePermissions","preserveOwnership","verifyChecksum","useLock","lockOptions","backupDir","debug","contentLength","length","expectedChecksum","calculateChecksum","performWrite","dir","dirname","tempPath","join","basename","backupPath","originalMetadata","rolledBack","ensureDirectory","getFileMetadata","exists","info","original","backup","actualChecksum","calculateFileChecksum","CHECKSUM_MISMATCH","expected","actual","checksum","mode","toString","uid","gid","error","warn","Error","undefined","from","to","bytesWritten","size","durationMs","success","fileExists","target","rollbackError","FILE_WRITE_FAILED","hash","createHash","update","digest","Promise","reject","stream","createReadStream","on","chunk","stats","process","getuid","getgid","timestamp","toISOString","replace","targetDir","BACKUP_FAILED","constants","F_OK","dirPath","recursive","code","verified","FILE_READ_FAILED","matches","defaultWriter","getAtomicFileWriter","atomicWriteFile","writer","atomicReadFile"],"mappings":"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"}