claude-flow-novice 2.15.3 → 2.15.5

package/dist/lib/file-operations.js

@@ -0,0 +1,367 @@
+/**
+ * File Operations Utilities
+ *
+ * Provides atomic file writes and file locking mechanisms for safe concurrent operations.
+ * Part of Task 0.5: Implementation Tooling & Utilities (Foundation)
+ *
+ * Usage:
+ *   await atomicWrite('/path/to/file.json', JSON.stringify(data));
+ *   const lock = await acquireLock('/path/to/file.json');
+ *   // ... perform operations ...
+ *   await releaseLock(lock);
+ */ import * as fs from 'fs';
+import * as path from 'path';
+import { promisify } from 'util';
+import { randomUUID } from 'crypto';
+import { createError, ErrorCode, createTimeoutError } from './errors.js';
+import { createLogger } from './logging.js';
+const logger = createLogger('file-operations');
+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 fsAccess = promisify(fs.access);
+/**
+ * Default lock options
+ */ const DEFAULT_LOCK_OPTIONS = {
+    timeoutMs: 30000,
+    retryIntervalMs: 100,
+    staleTimeoutMs: 60000
+};
+/**
+ * Atomically write content to a file
+ *
+ * Pattern: Write to temp file → verify → move to target
+ * This ensures that the file is never left in a partially written state.
+ *
+ * @param filePath - Target file path
+ * @param content - Content to write
+ * @param encoding - File encoding (default: 'utf8')
+ * @returns Promise that resolves when write is complete
+ * @throws FILE_WRITE_FAILED if write operation fails
+ */ export async function atomicWrite(filePath, content, encoding = 'utf8') {
+    const absolutePath = path.resolve(filePath);
+    const dir = path.dirname(absolutePath);
+    const tempPath = path.join(dir, `.${path.basename(absolutePath)}.${randomUUID()}.tmp`);
+    try {
+        // Ensure directory exists
+        await ensureDirectory(dir);
+        // Write to temporary file
+        logger.debug('Writing to temporary file', {
+            tempPath
+        });
+        await fsWriteFile(tempPath, content, encoding);
+        // Verify write by reading back
+        const written = await fsReadFile(tempPath, encoding);
+        if (written !== content) {
+            throw createError(ErrorCode.FILE_WRITE_FAILED, 'Content verification failed after write', {
+                filePath: absolutePath,
+                tempPath
+            });
+        }
+        // Atomically move temp file to target
+        logger.debug('Moving temp file to target', {
+            tempPath,
+            target: absolutePath
+        });
+        await fsRename(tempPath, absolutePath);
+        logger.info('Atomic write completed', {
+            filePath: absolutePath
+        });
+    } catch (error) {
+        // Clean up temp file if it exists
+        try {
+            await fsUnlink(tempPath);
+        } catch  {
+        // Ignore cleanup errors
+        }
+        throw createError(ErrorCode.FILE_WRITE_FAILED, `Failed to write file: ${absolutePath}`, {
+            filePath: absolutePath,
+            tempPath
+        }, error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Acquire a lock on a file
+ *
+ * Creates a lock file with metadata about the lock holder.
+ * Implements stale lock detection and automatic cleanup.
+ *
+ * @param filePath - File path to lock
+ * @param options - Lock options
+ * @returns FileLock object
+ * @throws LOCK_TIMEOUT if lock cannot be acquired within timeout
+ */ export async function acquireLock(filePath, options = {}) {
+    const opts = {
+        ...DEFAULT_LOCK_OPTIONS,
+        ...options
+    };
+    const absolutePath = path.resolve(filePath);
+    const lockPath = `${absolutePath}.lock`;
+    const lockId = randomUUID();
+    const startTime = Date.now();
+    logger.debug('Acquiring lock', {
+        filePath: absolutePath,
+        lockId
+    });
+    while(Date.now() - startTime < opts.timeoutMs){
+        try {
+            // Check if lock file exists
+            const lockExists = await fileExists(lockPath);
+            if (lockExists) {
+                // Check if lock is stale
+                const isStale = await isLockStale(lockPath, opts.staleTimeoutMs);
+                if (isStale) {
+                    logger.warn('Removing stale lock', {
+                        lockPath
+                    });
+                    await fsUnlink(lockPath);
+                } else {
+                    // Lock is held by another process, wait and retry
+                    await sleep(opts.retryIntervalMs);
+                    continue;
+                }
+            }
+            // Attempt to create lock file
+            const lockData = {
+                filePath: absolutePath,
+                lockPath,
+                acquired: new Date(),
+                lockId,
+                pid: process.pid
+            };
+            // Write lock file atomically
+            await atomicWrite(lockPath, JSON.stringify(lockData, null, 2));
+            // Verify we actually acquired the lock (check for race condition)
+            const verifyData = await fsReadFile(lockPath, 'utf8');
+            const verifyLock = JSON.parse(verifyData);
+            if (verifyLock.lockId !== lockId) {
+                // Another process won the race
+                logger.debug('Lost lock race', {
+                    lockId,
+                    winnerId: verifyLock.lockId
+                });
+                await sleep(opts.retryIntervalMs);
+                continue;
+            }
+            logger.info('Lock acquired', {
+                filePath: absolutePath,
+                lockId
+            });
+            return lockData;
+        } catch (error) {
+            logger.error('Error acquiring lock', error instanceof Error ? error : undefined, {
+                filePath: absolutePath,
+                lockId
+            });
+            throw createError(ErrorCode.LOCK_TIMEOUT, `Failed to acquire lock: ${absolutePath}`, {
+                filePath: absolutePath,
+                lockPath
+            }, error instanceof Error ? error : undefined);
+        }
+    }
+    // Timeout reached
+    throw createTimeoutError(`acquire lock on ${absolutePath}`, opts.timeoutMs);
+}
+/**
+ * Release a file lock
+ *
+ * @param lock - FileLock object from acquireLock
+ * @returns Promise that resolves when lock is released
+ */ export async function releaseLock(lock) {
+    try {
+        // Verify lock still exists and belongs to us
+        const lockExists = await fileExists(lock.lockPath);
+        if (!lockExists) {
+            logger.warn('Lock file already removed', {
+                lockPath: lock.lockPath
+            });
+            return;
+        }
+        const currentData = await fsReadFile(lock.lockPath, 'utf8');
+        const currentLock = JSON.parse(currentData);
+        if (currentLock.lockId !== lock.lockId) {
+            logger.warn('Lock was taken by another process', {
+                ourLockId: lock.lockId,
+                currentLockId: currentLock.lockId
+            });
+            return;
+        }
+        // Remove lock file
+        await fsUnlink(lock.lockPath);
+        logger.info('Lock released', {
+            filePath: lock.filePath,
+            lockId: lock.lockId
+        });
+    } catch (error) {
+        logger.error('Error releasing lock', error instanceof Error ? error : undefined, {
+            lockPath: lock.lockPath,
+            lockId: lock.lockId
+        });
+        throw createError(ErrorCode.FILE_WRITE_FAILED, `Failed to release lock: ${lock.lockPath}`, {
+            lockPath: lock.lockPath,
+            lockId: lock.lockId
+        }, error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Execute a function with a file lock
+ *
+ * @param filePath - File path to lock
+ * @param fn - Function to execute while holding the lock
+ * @param options - Lock options
+ * @returns Result of the function
+ */ export async function withLock(filePath, fn, options = {}) {
+    const lock = await acquireLock(filePath, options);
+    try {
+        return await fn();
+    } finally{
+        await releaseLock(lock);
+    }
+}
+/**
+ * Check if a lock is stale
+ *
+ * @param lockPath - Path to lock file
+ * @param staleTimeoutMs - Stale timeout in milliseconds
+ * @returns True if lock is stale
+ */ async function isLockStale(lockPath, staleTimeoutMs) {
+    try {
+        const lockData = await fsReadFile(lockPath, 'utf8');
+        const lock = JSON.parse(lockData);
+        const acquiredTime = new Date(lock.acquired).getTime();
+        const now = Date.now();
+        const age = now - acquiredTime;
+        return age > staleTimeoutMs;
+    } catch  {
+        // If we can't read the lock file, consider it stale
+        return true;
+    }
+}
+/**
+ * Check if a file exists
+ *
+ * @param filePath - File path to check
+ * @returns True if file exists
+ */ export async function fileExists(filePath) {
+    try {
+        await fsAccess(filePath, fs.constants.F_OK);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Ensure directory exists, creating it if necessary
+ *
+ * @param dirPath - Directory path
+ * @returns Promise that resolves when directory exists
+ */ export async function ensureDirectory(dirPath) {
+    try {
+        await fsMkdir(dirPath, {
+            recursive: true
+        });
+    } catch (error) {
+        // Ignore error if directory already exists
+        if (error.code !== 'EEXIST') {
+            throw error;
+        }
+    }
+}
+/**
+ * Sleep for specified duration
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Promise that resolves after duration
+ */ function sleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}
+/**
+ * Read file with automatic retry
+ *
+ * @param filePath - File path to read
+ * @param encoding - File encoding (default: 'utf8')
+ * @param maxRetries - Maximum retry attempts (default: 3)
+ * @returns File content
+ */ export async function readFileWithRetry(filePath, encoding = 'utf8', maxRetries = 3) {
+    let lastError;
+    for(let attempt = 0; attempt < maxRetries; attempt++){
+        try {
+            return await fsReadFile(filePath, encoding);
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries - 1) {
+                await sleep(100 * Math.pow(2, attempt)); // Exponential backoff
+            }
+        }
+    }
+    throw createError(ErrorCode.FILE_NOT_FOUND, `Failed to read file after ${maxRetries} attempts: ${filePath}`, {
+        filePath,
+        maxRetries
+    }, lastError);
+}
+/**
+ * Write file with automatic retry
+ *
+ * @param filePath - File path to write
+ * @param content - Content to write
+ * @param encoding - File encoding (default: 'utf8')
+ * @param maxRetries - Maximum retry attempts (default: 3)
+ * @returns Promise that resolves when write is complete
+ */ export async function writeFileWithRetry(filePath, content, encoding = 'utf8', maxRetries = 3) {
+    let lastError;
+    for(let attempt = 0; attempt < maxRetries; attempt++){
+        try {
+            await atomicWrite(filePath, content, encoding);
+            return;
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries - 1) {
+                await sleep(100 * Math.pow(2, attempt)); // Exponential backoff
+            }
+        }
+    }
+    throw createError(ErrorCode.FILE_WRITE_FAILED, `Failed to write file after ${maxRetries} attempts: ${filePath}`, {
+        filePath,
+        maxRetries
+    }, lastError);
+}
+/**
+ * Copy file atomically
+ *
+ * @param sourcePath - Source file path
+ * @param targetPath - Target file path
+ * @returns Promise that resolves when copy is complete
+ */ export async function atomicCopy(sourcePath, targetPath) {
+    const content = await fsReadFile(sourcePath, 'utf8');
+    await atomicWrite(targetPath, content);
+    logger.info('Atomic copy completed', {
+        source: sourcePath,
+        target: targetPath
+    });
+}
+/**
+ * Move file atomically
+ *
+ * @param sourcePath - Source file path
+ * @param targetPath - Target file path
+ * @returns Promise that resolves when move is complete
+ */ export async function atomicMove(sourcePath, targetPath) {
+    const absoluteSource = path.resolve(sourcePath);
+    const absoluteTarget = path.resolve(targetPath);
+    try {
+        await fsRename(absoluteSource, absoluteTarget);
+        logger.info('Atomic move completed', {
+            source: absoluteSource,
+            target: absoluteTarget
+        });
+    } catch (error) {
+        // If rename fails (e.g., cross-device), fall back to copy + delete
+        await atomicCopy(absoluteSource, absoluteTarget);
+        await fsUnlink(absoluteSource);
+    }
+}
+
+//# sourceMappingURL=file-operations.js.map

package/dist/lib/file-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/file-operations.ts"],"sourcesContent":["/**\r\n * File Operations Utilities\r\n *\r\n * Provides atomic file writes and file locking mechanisms for safe concurrent operations.\r\n * Part of Task 0.5: Implementation Tooling & Utilities (Foundation)\r\n *\r\n * Usage:\r\n *   await atomicWrite('/path/to/file.json', JSON.stringify(data));\r\n *   const lock = await acquireLock('/path/to/file.json');\r\n *   // ... perform operations ...\r\n *   await releaseLock(lock);\r\n */\r\n\r\nimport * as fs from 'fs';\r\nimport * as path from 'path';\r\nimport { promisify } from 'util';\r\nimport { randomUUID } from 'crypto';\r\nimport { createError, ErrorCode, createTimeoutError } from './errors.js';\r\nimport { createLogger } from './logging.js';\r\n\r\nconst logger = createLogger('file-operations');\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 fsAccess = promisify(fs.access);\r\n\r\n/**\r\n * File lock information\r\n */\r\nexport interface FileLock {\r\n  /** Path to the file being locked */\r\n  filePath: string;\r\n  /** Path to the lock file */\r\n  lockPath: string;\r\n  /** When the lock was acquired */\r\n  acquired: Date;\r\n  /** Lock ID (unique identifier) */\r\n  lockId: string;\r\n  /** Process ID that acquired the lock */\r\n  pid: number;\r\n}\r\n\r\n/**\r\n * Lock options\r\n */\r\nexport interface LockOptions {\r\n  /** Timeout in milliseconds (default: 30000) */\r\n  timeoutMs?: number;\r\n  /** Retry interval in milliseconds (default: 100) */\r\n  retryIntervalMs?: number;\r\n  /** Stale lock timeout in milliseconds (default: 60000) */\r\n  staleTimeoutMs?: number;\r\n}\r\n\r\n/**\r\n * Default lock options\r\n */\r\nconst DEFAULT_LOCK_OPTIONS: Required<LockOptions> = {\r\n  timeoutMs: 30000, // 30 seconds\r\n  retryIntervalMs: 100, // 100ms\r\n  staleTimeoutMs: 60000, // 60 seconds\r\n};\r\n\r\n/**\r\n * Atomically write content to a file\r\n *\r\n * Pattern: Write to temp file → verify → move to target\r\n * This ensures that the file is never left in a partially written state.\r\n *\r\n * @param filePath - Target file path\r\n * @param content - Content to write\r\n * @param encoding - File encoding (default: 'utf8')\r\n * @returns Promise that resolves when write is complete\r\n * @throws FILE_WRITE_FAILED if write operation fails\r\n */\r\nexport async function atomicWrite(\r\n  filePath: string,\r\n  content: string,\r\n  encoding: BufferEncoding = 'utf8'\r\n): Promise<void> {\r\n  const absolutePath = path.resolve(filePath);\r\n  const dir = path.dirname(absolutePath);\r\n  const tempPath = path.join(dir, `.${path.basename(absolutePath)}.${randomUUID()}.tmp`);\r\n\r\n  try {\r\n    // Ensure directory exists\r\n    await ensureDirectory(dir);\r\n\r\n    // Write to temporary file\r\n    logger.debug('Writing to temporary file', { tempPath });\r\n    await fsWriteFile(tempPath, content, encoding);\r\n\r\n    // Verify write by reading back\r\n    const written = await fsReadFile(tempPath, encoding);\r\n    if (written !== content) {\r\n      throw createError(\r\n        ErrorCode.FILE_WRITE_FAILED,\r\n        'Content verification failed after write',\r\n        { filePath: absolutePath, tempPath }\r\n      );\r\n    }\r\n\r\n    // Atomically move temp file to target\r\n    logger.debug('Moving temp file to target', { tempPath, target: absolutePath });\r\n    await fsRename(tempPath, absolutePath);\r\n\r\n    logger.info('Atomic write completed', { filePath: absolutePath });\r\n  } catch (error) {\r\n    // Clean up temp file if it exists\r\n    try {\r\n      await fsUnlink(tempPath);\r\n    } catch {\r\n      // Ignore cleanup errors\r\n    }\r\n\r\n    throw createError(\r\n      ErrorCode.FILE_WRITE_FAILED,\r\n      `Failed to write file: ${absolutePath}`,\r\n      { filePath: absolutePath, tempPath },\r\n      error instanceof Error ? error : undefined\r\n    );\r\n  }\r\n}\r\n\r\n/**\r\n * Acquire a lock on a file\r\n *\r\n * Creates a lock file with metadata about the lock holder.\r\n * Implements stale lock detection and automatic cleanup.\r\n *\r\n * @param filePath - File path to lock\r\n * @param options - Lock options\r\n * @returns FileLock object\r\n * @throws LOCK_TIMEOUT if lock cannot be acquired within timeout\r\n */\r\nexport async function acquireLock(\r\n  filePath: string,\r\n  options: LockOptions = {}\r\n): Promise<FileLock> {\r\n  const opts = { ...DEFAULT_LOCK_OPTIONS, ...options };\r\n  const absolutePath = path.resolve(filePath);\r\n  const lockPath = `${absolutePath}.lock`;\r\n  const lockId = randomUUID();\r\n  const startTime = Date.now();\r\n\r\n  logger.debug('Acquiring lock', { filePath: absolutePath, lockId });\r\n\r\n  while (Date.now() - startTime < opts.timeoutMs) {\r\n    try {\r\n      // Check if lock file exists\r\n      const lockExists = await fileExists(lockPath);\r\n\r\n      if (lockExists) {\r\n        // Check if lock is stale\r\n        const isStale = await isLockStale(lockPath, opts.staleTimeoutMs);\r\n\r\n        if (isStale) {\r\n          logger.warn('Removing stale lock', { lockPath });\r\n          await fsUnlink(lockPath);\r\n        } else {\r\n          // Lock is held by another process, wait and retry\r\n          await sleep(opts.retryIntervalMs);\r\n          continue;\r\n        }\r\n      }\r\n\r\n      // Attempt to create lock file\r\n      const lockData: FileLock = {\r\n        filePath: absolutePath,\r\n        lockPath,\r\n        acquired: new Date(),\r\n        lockId,\r\n        pid: process.pid,\r\n      };\r\n\r\n      // Write lock file atomically\r\n      await atomicWrite(lockPath, JSON.stringify(lockData, null, 2));\r\n\r\n      // Verify we actually acquired the lock (check for race condition)\r\n      const verifyData = await fsReadFile(lockPath, 'utf8');\r\n      const verifyLock = JSON.parse(verifyData) as FileLock;\r\n\r\n      if (verifyLock.lockId !== lockId) {\r\n        // Another process won the race\r\n        logger.debug('Lost lock race', { lockId, winnerId: verifyLock.lockId });\r\n        await sleep(opts.retryIntervalMs);\r\n        continue;\r\n      }\r\n\r\n      logger.info('Lock acquired', { filePath: absolutePath, lockId });\r\n      return lockData;\r\n    } catch (error) {\r\n      logger.error('Error acquiring lock', error instanceof Error ? error : undefined, {\r\n        filePath: absolutePath,\r\n        lockId,\r\n      });\r\n      throw createError(\r\n        ErrorCode.LOCK_TIMEOUT,\r\n        `Failed to acquire lock: ${absolutePath}`,\r\n        { filePath: absolutePath, lockPath },\r\n        error instanceof Error ? error : undefined\r\n      );\r\n    }\r\n  }\r\n\r\n  // Timeout reached\r\n  throw createTimeoutError(`acquire lock on ${absolutePath}`, opts.timeoutMs);\r\n}\r\n\r\n/**\r\n * Release a file lock\r\n *\r\n * @param lock - FileLock object from acquireLock\r\n * @returns Promise that resolves when lock is released\r\n */\r\nexport async function releaseLock(lock: FileLock): Promise<void> {\r\n  try {\r\n    // Verify lock still exists and belongs to us\r\n    const lockExists = await fileExists(lock.lockPath);\r\n\r\n    if (!lockExists) {\r\n      logger.warn('Lock file already removed', { lockPath: lock.lockPath });\r\n      return;\r\n    }\r\n\r\n    const currentData = await fsReadFile(lock.lockPath, 'utf8');\r\n    const currentLock = JSON.parse(currentData) as FileLock;\r\n\r\n    if (currentLock.lockId !== lock.lockId) {\r\n      logger.warn('Lock was taken by another process', {\r\n        ourLockId: lock.lockId,\r\n        currentLockId: currentLock.lockId,\r\n      });\r\n      return;\r\n    }\r\n\r\n    // Remove lock file\r\n    await fsUnlink(lock.lockPath);\r\n    logger.info('Lock released', { filePath: lock.filePath, lockId: lock.lockId });\r\n  } catch (error) {\r\n    logger.error('Error releasing lock', error instanceof Error ? error : undefined, {\r\n      lockPath: lock.lockPath,\r\n      lockId: lock.lockId,\r\n    });\r\n    throw createError(\r\n      ErrorCode.FILE_WRITE_FAILED,\r\n      `Failed to release lock: ${lock.lockPath}`,\r\n      { lockPath: lock.lockPath, lockId: lock.lockId },\r\n      error instanceof Error ? error : undefined\r\n    );\r\n  }\r\n}\r\n\r\n/**\r\n * Execute a function with a file lock\r\n *\r\n * @param filePath - File path to lock\r\n * @param fn - Function to execute while holding the lock\r\n * @param options - Lock options\r\n * @returns Result of the function\r\n */\r\nexport async function withLock<T>(\r\n  filePath: string,\r\n  fn: () => Promise<T>,\r\n  options: LockOptions = {}\r\n): Promise<T> {\r\n  const lock = await acquireLock(filePath, options);\r\n\r\n  try {\r\n    return await fn();\r\n  } finally {\r\n    await releaseLock(lock);\r\n  }\r\n}\r\n\r\n/**\r\n * Check if a lock is stale\r\n *\r\n * @param lockPath - Path to lock file\r\n * @param staleTimeoutMs - Stale timeout in milliseconds\r\n * @returns True if lock is stale\r\n */\r\nasync function isLockStale(lockPath: string, staleTimeoutMs: number): Promise<boolean> {\r\n  try {\r\n    const lockData = await fsReadFile(lockPath, 'utf8');\r\n    const lock = JSON.parse(lockData) as FileLock;\r\n\r\n    const acquiredTime = new Date(lock.acquired).getTime();\r\n    const now = Date.now();\r\n    const age = now - acquiredTime;\r\n\r\n    return age > staleTimeoutMs;\r\n  } catch {\r\n    // If we can't read the lock file, consider it stale\r\n    return true;\r\n  }\r\n}\r\n\r\n/**\r\n * Check if a file exists\r\n *\r\n * @param filePath - File path to check\r\n * @returns True if file exists\r\n */\r\nexport async function 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, creating it if necessary\r\n *\r\n * @param dirPath - Directory path\r\n * @returns Promise that resolves when directory exists\r\n */\r\nexport async function 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 * Sleep for specified duration\r\n *\r\n * @param ms - Duration in milliseconds\r\n * @returns Promise that resolves after duration\r\n */\r\nfunction sleep(ms: number): Promise<void> {\r\n  return new Promise((resolve) => setTimeout(resolve, ms));\r\n}\r\n\r\n/**\r\n * Read file with automatic retry\r\n *\r\n * @param filePath - File path to read\r\n * @param encoding - File encoding (default: 'utf8')\r\n * @param maxRetries - Maximum retry attempts (default: 3)\r\n * @returns File content\r\n */\r\nexport async function readFileWithRetry(\r\n  filePath: string,\r\n  encoding: BufferEncoding = 'utf8',\r\n  maxRetries: number = 3\r\n): Promise<string> {\r\n  let lastError: Error | undefined;\r\n\r\n  for (let attempt = 0; attempt < maxRetries; attempt++) {\r\n    try {\r\n      return await fsReadFile(filePath, encoding);\r\n    } catch (error) {\r\n      lastError = error instanceof Error ? error : new Error(String(error));\r\n      if (attempt < maxRetries - 1) {\r\n        await sleep(100 * Math.pow(2, attempt)); // Exponential backoff\r\n      }\r\n    }\r\n  }\r\n\r\n  throw createError(\r\n    ErrorCode.FILE_NOT_FOUND,\r\n    `Failed to read file after ${maxRetries} attempts: ${filePath}`,\r\n    { filePath, maxRetries },\r\n    lastError\r\n  );\r\n}\r\n\r\n/**\r\n * Write file with automatic retry\r\n *\r\n * @param filePath - File path to write\r\n * @param content - Content to write\r\n * @param encoding - File encoding (default: 'utf8')\r\n * @param maxRetries - Maximum retry attempts (default: 3)\r\n * @returns Promise that resolves when write is complete\r\n */\r\nexport async function writeFileWithRetry(\r\n  filePath: string,\r\n  content: string,\r\n  encoding: BufferEncoding = 'utf8',\r\n  maxRetries: number = 3\r\n): Promise<void> {\r\n  let lastError: Error | undefined;\r\n\r\n  for (let attempt = 0; attempt < maxRetries; attempt++) {\r\n    try {\r\n      await atomicWrite(filePath, content, encoding);\r\n      return;\r\n    } catch (error) {\r\n      lastError = error instanceof Error ? error : new Error(String(error));\r\n      if (attempt < maxRetries - 1) {\r\n        await sleep(100 * Math.pow(2, attempt)); // Exponential backoff\r\n      }\r\n    }\r\n  }\r\n\r\n  throw createError(\r\n    ErrorCode.FILE_WRITE_FAILED,\r\n    `Failed to write file after ${maxRetries} attempts: ${filePath}`,\r\n    { filePath, maxRetries },\r\n    lastError\r\n  );\r\n}\r\n\r\n/**\r\n * Copy file atomically\r\n *\r\n * @param sourcePath - Source file path\r\n * @param targetPath - Target file path\r\n * @returns Promise that resolves when copy is complete\r\n */\r\nexport async function atomicCopy(sourcePath: string, targetPath: string): Promise<void> {\r\n  const content = await fsReadFile(sourcePath, 'utf8');\r\n  await atomicWrite(targetPath, content);\r\n  logger.info('Atomic copy completed', { source: sourcePath, target: targetPath });\r\n}\r\n\r\n/**\r\n * Move file atomically\r\n *\r\n * @param sourcePath - Source file path\r\n * @param targetPath - Target file path\r\n * @returns Promise that resolves when move is complete\r\n */\r\nexport async function atomicMove(sourcePath: string, targetPath: string): Promise<void> {\r\n  const absoluteSource = path.resolve(sourcePath);\r\n  const absoluteTarget = path.resolve(targetPath);\r\n\r\n  try {\r\n    await fsRename(absoluteSource, absoluteTarget);\r\n    logger.info('Atomic move completed', { source: absoluteSource, target: absoluteTarget });\r\n  } catch (error) {\r\n    // If rename fails (e.g., cross-device), fall back to copy + delete\r\n    await atomicCopy(absoluteSource, absoluteTarget);\r\n    await fsUnlink(absoluteSource);\r\n  }\r\n}\r\n"],"names":["fs","path","promisify","randomUUID","createError","ErrorCode","createTimeoutError","createLogger","logger","fsWriteFile","writeFile","fsReadFile","readFile","fsRename","rename","fsUnlink","unlink","fsStat","stat","fsMkdir","mkdir","fsAccess","access","DEFAULT_LOCK_OPTIONS","timeoutMs","retryIntervalMs","staleTimeoutMs","atomicWrite","filePath","content","encoding","absolutePath","resolve","dir","dirname","tempPath","join","basename","ensureDirectory","debug","written","FILE_WRITE_FAILED","target","info","error","Error","undefined","acquireLock","options","opts","lockPath","lockId","startTime","Date","now","lockExists","fileExists","isStale","isLockStale","warn","sleep","lockData","acquired","pid","process","JSON","stringify","verifyData","verifyLock","parse","winnerId","LOCK_TIMEOUT","releaseLock","lock","currentData","currentLock","ourLockId","currentLockId","withLock","fn","acquiredTime","getTime","age","constants","F_OK","dirPath","recursive","code","ms","Promise","setTimeout","readFileWithRetry","maxRetries","lastError","attempt","String","Math","pow","FILE_NOT_FOUND","writeFileWithRetry","atomicCopy","sourcePath","targetPath","source","atomicMove","absoluteSource","absoluteTarget"],"mappings":"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"}

package/dist/lib/idempotent-write.js

@@ -0,0 +1,237 @@
+/**
+ * Idempotent Write Utility
+ *
+ * Provides content-based deduplication for metrics logging using SHA256 hashing.
+ * Part of Task 2.3: Unified Metrics and Execution Logging
+ *
+ * Features:
+ * - Content-based idempotency keys (prevents duplicate metrics)
+ * - TTL-based cleanup (24-hour retention)
+ * - Atomic write tracking across databases
+ */ import * as crypto from 'crypto';
+import { createLogger } from './logging.js';
+const logger = createLogger('idempotent-write');
+/**
+ * Default TTL for idempotency keys (24 hours)
+ */ const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Create idempotency key from execution metrics
+ *
+ * Key is based on: agent_id + task_id + timestamp + duration_ms
+ * This combination ensures uniqueness while allowing retries to be detected
+ *
+ * @param metrics - Execution metrics to create key from
+ * @returns SHA256 hash as idempotency key
+ */ export function createIdempotentKey(metrics) {
+    // Normalize timestamp to ISO string for consistent hashing
+    const timestampStr = metrics.timestamp instanceof Date ? metrics.timestamp.toISOString() : new Date(metrics.timestamp).toISOString();
+    // Build content string for hashing
+    const content = [
+        metrics.agent_id,
+        metrics.task_id,
+        timestampStr,
+        metrics.duration_ms.toString(),
+        metrics.status
+    ].join(':');
+    // Generate SHA256 hash
+    const hash = crypto.createHash('sha256').update(content).digest('hex');
+    logger.debug('Created idempotency key', {
+        agent_id: metrics.agent_id,
+        task_id: metrics.task_id,
+        key: hash.substring(0, 16) + '...'
+    });
+    return hash;
+}
+/**
+ * Check if metrics have already been written
+ *
+ * @param key - Idempotency key to check
+ * @param db - Database adapter
+ * @returns True if already written, false otherwise
+ */ export async function hasBeenWritten(key, db) {
+    try {
+        // Query idempotency_keys table
+        const result = await db.get(`idempotency_keys:${key}`);
+        if (!result) {
+            logger.debug('Idempotency key not found', {
+                key: key.substring(0, 16) + '...'
+            });
+            return false;
+        }
+        // Check if key has expired
+        const expiresAt = new Date(result.expires_at);
+        const now = new Date();
+        if (expiresAt < now) {
+            logger.debug('Idempotency key expired', {
+                key: key.substring(0, 16) + '...',
+                expired_at: expiresAt.toISOString()
+            });
+            return false;
+        }
+        logger.debug('Idempotency key found', {
+            key: key.substring(0, 16) + '...',
+            written_at: result.written_at
+        });
+        return true;
+    } catch (error) {
+        logger.error('Failed to check idempotency key', {
+            key: key.substring(0, 16) + '...',
+            error: error instanceof Error ? error.message : String(error)
+        });
+        // On error, assume not written to allow retry
+        return false;
+    }
+}
+/**
+ * Mark metrics as written
+ *
+ * @param key - Idempotency key
+ * @param db - Database adapter
+ * @param metricsId - Optional metrics ID to link
+ * @param ttlMs - Time-to-live in milliseconds (default: 24 hours)
+ */ export async function markWritten(key, db, metricsId, ttlMs = DEFAULT_TTL_MS) {
+    try {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + ttlMs);
+        const idempotencyRecord = {
+            key,
+            metrics_id: metricsId,
+            written_at: now,
+            expires_at: expiresAt
+        };
+        // Insert into idempotency_keys table
+        await db.insert('idempotency_keys', idempotencyRecord);
+        logger.debug('Marked idempotency key as written', {
+            key: key.substring(0, 16) + '...',
+            metrics_id: metricsId,
+            expires_at: expiresAt.toISOString()
+        });
+    } catch (error) {
+        logger.error('Failed to mark idempotency key', {
+            key: key.substring(0, 16) + '...',
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}
+/**
+ * Batch check for written metrics
+ *
+ * @param keys - Array of idempotency keys
+ * @param db - Database adapter
+ * @returns Map of key -> boolean (written status)
+ */ export async function batchCheckWritten(keys, db) {
+    const results = new Map();
+    try {
+        // Check all keys in parallel
+        const checks = keys.map(async (key)=>{
+            const written = await hasBeenWritten(key, db);
+            return {
+                key,
+                written
+            };
+        });
+        const checkResults = await Promise.all(checks);
+        // Build result map
+        checkResults.forEach(({ key, written })=>{
+            results.set(key, written);
+        });
+        logger.debug('Batch idempotency check complete', {
+            total_keys: keys.length,
+            already_written: Array.from(results.values()).filter((v)=>v).length
+        });
+        return results;
+    } catch (error) {
+        logger.error('Failed to batch check idempotency keys', {
+            total_keys: keys.length,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}
+/**
+ * Batch mark metrics as written
+ *
+ * @param entries - Array of { key, metricsId? } entries
+ * @param db - Database adapter
+ * @param ttlMs - Time-to-live in milliseconds (default: 24 hours)
+ */ export async function batchMarkWritten(entries, db, ttlMs = DEFAULT_TTL_MS) {
+    try {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + ttlMs);
+        const records = entries.map(({ key, metricsId })=>({
+                key,
+                metrics_id: metricsId,
+                written_at: now,
+                expires_at: expiresAt
+            }));
+        // Batch insert
+        await db.insertMany('idempotency_keys', records);
+        logger.debug('Batch marked idempotency keys as written', {
+            total_keys: entries.length,
+            expires_at: expiresAt.toISOString()
+        });
+    } catch (error) {
+        logger.error('Failed to batch mark idempotency keys', {
+            total_keys: entries.length,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}
+/**
+ * Cleanup expired idempotency keys
+ *
+ * @param db - Database adapter
+ * @returns Number of keys deleted
+ */ export async function cleanupExpiredKeys(db) {
+    try {
+        const now = new Date();
+        // Query for expired keys
+        const expiredKeys = await db.query('idempotency_keys', [
+            {
+                field: 'expires_at',
+                operator: 'lt',
+                value: now
+            }
+        ]);
+        // Delete expired keys
+        let deletedCount = 0;
+        for (const key of expiredKeys){
+            await db.delete('idempotency_keys', key.key);
+            deletedCount++;
+        }
+        logger.info('Cleaned up expired idempotency keys', {
+            deleted_count: deletedCount
+        });
+        return deletedCount;
+    } catch (error) {
+        logger.error('Failed to cleanup expired idempotency keys', {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}
+/**
+ * Validate cost accuracy (within $0.001 precision)
+ *
+ * @param cost - Cost value to validate
+ * @returns True if cost is accurate to $0.001
+ */ export function validateCostAccuracy(cost) {
+    const rounded = parseFloat(cost.toFixed(3));
+    return Math.abs(cost - rounded) < 0.0001;
+}
+/**
+ * Round cost to $0.001 precision
+ *
+ * Uses standard "round half up" behavior for consistent rounding.
+ *
+ * @param cost - Cost value to round
+ * @returns Cost rounded to 3 decimal places
+ */ export function roundCost(cost) {
+    // Use Math.round for proper "round half up" behavior
+    // Multiply by 1000, round, then divide by 1000 for $0.001 precision
+    return Math.round(cost * 1000) / 1000;
+}
+
+//# sourceMappingURL=idempotent-write.js.map