@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/error-registry.cjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Error Registry — Central error code and severity registry
+ *
+ * Provides:
+ * - Standardized error codes with prefixes
+ * - Severity levels for all errors
+ * - Lookup functions for error metadata
+ *
+ * Error Code Scheme:
+ *   ERR_<CATEGORY>_<NAME>
+ *
+ * Categories:
+ *   SESSION, CONTEXT, SECURITY, GIT, QUALITY, PHASE, AGENT, RCA, CACHE, GATE
+ */
+
+const SEVERITY = {
+  CRITICAL: 'critical',  // System unusable — immediate exit
+  ERROR: 'error',        // Operation failed — retry or exit
+  WARNING: 'warning',    // Recoverable issue — continue with warning
+  INFO: 'info',          // Normal operation — informational
+  DEBUG: 'debug'         // Detailed tracing — development only
+};
+
+const ERROR_CODES = {
+  SESSION: {
+    NOT_FOUND: { code: 'ERR_SESSION_NOT_FOUND', severity: SEVERITY.ERROR },
+    CHAIN_BROKEN: { code: 'ERR_SESSION_CHAIN_BROKEN', severity: SEVERITY.CRITICAL },
+    EXPORT_FAILED: { code: 'ERR_SESSION_EXPORT_FAILED', severity: SEVERITY.ERROR },
+    IMPORT_FAILED: { code: 'ERR_SESSION_IMPORT_FAILED', severity: SEVERITY.ERROR },
+    CORRUPTED: { code: 'ERR_SESSION_CORRUPTED', severity: SEVERITY.CRITICAL },
+    VERSION_MISMATCH: { code: 'ERR_SESSION_VERSION_MISMATCH', severity: SEVERITY.ERROR }
+  },
+
+  CONTEXT: {
+    ACCESS_DENIED: { code: 'ERR_CONTEXT_ACCESS_DENIED', severity: SEVERITY.ERROR },
+    URL_FETCH_FAILED: { code: 'ERR_CONTEXT_URL_FETCH_FAILED', severity: SEVERITY.ERROR },
+    FILE_ACCESS_FAILED: { code: 'ERR_CONTEXT_FILE_ACCESS_FAILED', severity: SEVERITY.ERROR },
+    SECURITY_SCAN_FAILED: { code: 'ERR_CONTEXT_SECURITY_SCAN_FAILED', severity: SEVERITY.CRITICAL },
+    XSS_DETECTED: { code: 'ERR_CONTEXT_XSS_DETECTED', severity: SEVERITY.CRITICAL },
+    TIMEOUT: { code: 'ERR_CONTEXT_TIMEOUT', severity: SEVERITY.WARNING }
+  },
+
+  SECURITY: {
+    SCAN_FAILED: { code: 'ERR_SECURITY_SCAN_FAILED', severity: SEVERITY.ERROR },
+    PROVIDER_ERROR: { code: 'ERR_SECURITY_PROVIDER_ERROR', severity: SEVERITY.CRITICAL },
+    COMPLIANCE_FAILED: { code: 'ERR_SECURITY_COMPLIANCE_FAILED', severity: SEVERITY.ERROR },
+    AUDIT_FAILED: { code: 'ERR_SECURITY_AUDIT_FAILED', severity: SEVERITY.ERROR },
+    SECRET_DETECTED: { code: 'ERR_SECURITY_SECRET_DETECTED', severity: SEVERITY.CRITICAL }
+  },
+
+  GIT: {
+    BRANCH_EXISTS: { code: 'ERR_GIT_BRANCH_EXISTS', severity: SEVERITY.ERROR },
+    BRANCH_NOT_FOUND: { code: 'ERR_GIT_BRANCH_NOT_FOUND', severity: SEVERITY.ERROR },
+    MERGE_CONFLICT: { code: 'ERR_GIT_MERGE_CONFLICT', severity: SEVERITY.ERROR },
+    VALIDATION_FAILED: { code: 'ERR_GIT_VALIDATION_FAILED', severity: SEVERITY.ERROR },
+    COMMIT_FAILED: { code: 'ERR_GIT_COMMIT_FAILED', severity: SEVERITY.ERROR },
+    PUSH_FAILED: { code: 'ERR_GIT_PUSH_FAILED', severity: SEVERITY.ERROR }
+  },
+
+  QUALITY: {
+    GATE_FAILED: { code: 'ERR_QUALITY_GATE_FAILED', severity: SEVERITY.ERROR },
+    DEGRADATION_DETECTED: { code: 'ERR_QUALITY_DEGRADATION_DETECTED', severity: SEVERITY.WARNING },
+    METRICS_ERROR: { code: 'ERR_QUALITY_METRICS_ERROR', severity: SEVERITY.ERROR },
+    REPORT_FAILED: { code: 'ERR_QUALITY_REPORT_FAILED', severity: SEVERITY.ERROR }
+  },
+
+  PHASE: {
+    NOT_FOUND: { code: 'ERR_PHASE_NOT_FOUND', severity: SEVERITY.ERROR },
+    LOCKED: { code: 'ERR_PHASE_LOCKED', severity: SEVERITY.ERROR },
+    LOCK_ACQUISITION_FAILED: { code: 'ERR_PHASE_LOCK_ACQUISITION_FAILED', severity: SEVERITY.ERROR },
+    INVALID_STATE: { code: 'ERR_PHASE_INVALID_STATE', severity: SEVERITY.ERROR },
+    TASK_FAILED: { code: 'ERR_PHASE_TASK_FAILED', severity: SEVERITY.ERROR }
+  },
+
+  AGENT: {
+    NOT_FOUND: { code: 'ERR_AGENT_NOT_FOUND', severity: SEVERITY.ERROR },
+    ASSIGNMENT_FAILED: { code: 'ERR_AGENT_ASSIGNMENT_FAILED', severity: SEVERITY.ERROR },
+    TIMEOUT: { code: 'ERR_AGENT_TIMEOUT', severity: SEVERITY.ERROR },
+    NESTING_EXCEEDED: { code: 'ERR_AGENT_NESTING_EXCEEDED', severity: SEVERITY.CRITICAL }
+  },
+
+  RCA: {
+    ANALYSIS_FAILED: { code: 'ERR_RCA_ANALYSIS_FAILED', severity: SEVERITY.ERROR },
+    CONTEXT_CAPTURE_FAILED: { code: 'ERR_RCA_CONTEXT_CAPTURE_FAILED', severity: SEVERITY.WARNING },
+    PATTERN_NOT_FOUND: { code: 'ERR_RCA_PATTERN_NOT_FOUND', severity: SEVERITY.INFO }
+  },
+
+  CACHE: {
+    RECORD_FAILED: { code: 'ERR_CACHE_RECORD_FAILED', severity: SEVERITY.ERROR },
+    LOAD_FAILED: { code: 'ERR_CACHE_LOAD_FAILED', severity: SEVERITY.WARNING },
+    SAVE_FAILED: { code: 'ERR_CACHE_SAVE_FAILED', severity: SEVERITY.WARNING },
+    CORRUPTED: { code: 'ERR_CACHE_CORRUPTED', severity: SEVERITY.ERROR }
+  },
+
+  GATE: {
+    NOT_REGISTERED: { code: 'ERR_GATE_NOT_REGISTERED', severity: SEVERITY.ERROR },
+    EXECUTION_FAILED: { code: 'ERR_GATE_EXECUTION_FAILED', severity: SEVERITY.ERROR },
+    VALIDATION_FAILED: { code: 'ERR_GATE_VALIDATION_FAILED', severity: SEVERITY.ERROR },
+    BYPASS_REQUIRES_REASON: { code: 'ERR_GATE_BYPASS_REQUIRES_REASON', severity: SEVERITY.ERROR }
+  },
+
+  // Generic fallback
+  UNKNOWN: { code: 'ERR_UNKNOWN', severity: SEVERITY.ERROR }
+};
+
+/**
+ * Get error code metadata
+ * @param {string} category - Error category (SESSION, CONTEXT, etc.)
+ * @param {string} name - Error name (NOT_FOUND, CHAIN_BROKEN, etc.)
+ * @returns {{code: string, severity: string}|null} Error metadata or null
+ */
+function getErrorCode(category, name) {
+  return ERROR_CODES[category]?.[name] || null;
+}
+
+/**
+ * Get all error codes
+ * @returns {Object} All error codes by category
+ */
+function getAllCodes() {
+  return ERROR_CODES;
+}
+
+/**
+ * Get severity level by name
+ * @param {string} name - Severity name (CRITICAL, ERROR, etc.)
+ * @returns {string|null} Severity value or null
+ */
+function getSeverity(name) {
+  return SEVERITY[name] || null;
+}
+
+/**
+ * Get all severity levels
+ * @returns {Object} All severity levels
+ */
+function getAllSeverities() {
+  return SEVERITY;
+}
+
+/**
+ * Lookup error by code string
+ * @param {string} codeString - Full error code (e.g., 'ERR_SESSION_NOT_FOUND')
+ * @returns {{category: string, name: string, code: string, severity: string}|null}
+ */
+function lookupByCode(codeString) {
+  for (const [category, errors] of Object.entries(ERROR_CODES)) {
+    for (const [name, data] of Object.entries(errors)) {
+      if (data.code === codeString) {
+        return { category, name, ...data };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate error code format
+ * @param {string} code - Error code to validate
+ * @returns {boolean} True if valid format
+ */
+function isValidCode(code) {
+  return lookupByCode(code) !== null;
+}
+
+module.exports = {
+  SEVERITY,
+  ERROR_CODES,
+  getErrorCode,
+  getAllCodes,
+  getSeverity,
+  getAllSeverities,
+  lookupByCode,
+  isValidCode
+};

package/bin/lib/file-access.cjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * File Access Service
+ *
+ * Provides file reading capabilities with glob pattern support.
+ * Uses micromatch for glob matching with support for negation and brace expansion.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const micromatch = require('micromatch');
+const { FileAccessError } = require('./context-errors.cjs');
+
+const MAX_FILE_COUNT = 1000;
+
+class FileAccessService {
+  /**
+   * Create a new FileAccessService instance
+   * @param {string} cwd - Current working directory (defaults to process.cwd())
+   */
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+  }
+
+  /**
+   * Read files matching patterns
+   * @param {string|string[]} patterns - File patterns (glob or single path)
+   * @returns {Array<{path: string, content: string}>} - Array of file objects
+   * @throws {FileAccessError} - On file access errors
+   */
+  readFiles(patterns) {
+    const patternArray = Array.isArray(patterns) ? patterns : [patterns];
+    
+    // Get all files recursively
+    const allFiles = this._getAllFiles(this.cwd);
+    
+    // Convert paths to relative paths from cwd
+    const relativeFiles = allFiles.map(f => {
+      const relPath = path.relative(this.cwd, f);
+      // Convert to POSIX style paths for glob matching
+      return relPath.replace(/\\/g, '/');
+    });
+    
+    // Filter with micromatch
+    const matchedFiles = micromatch.match(relativeFiles, patternArray, {
+      dot: false, // Don't match hidden files/directories by default
+      nocase: false
+    });
+    
+    // Check max file count
+    if (matchedFiles.length > MAX_FILE_COUNT) {
+      throw new FileAccessError(
+        matchedFiles[0],
+        `Max file count exceeded: ${matchedFiles.length} > ${MAX_FILE_COUNT}`
+      );
+    }
+    
+    // Read file contents
+    const results = matchedFiles.map(filePath => {
+      const fullPath = path.join(this.cwd, filePath);
+      
+      if (!fs.existsSync(fullPath)) {
+        throw new FileAccessError(filePath, 'File not found');
+      }
+      
+      try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return {
+          path: filePath,
+          content
+        };
+      } catch (err) {
+        if (err.code === 'EACCES') {
+          throw new FileAccessError(filePath, 'Permission denied');
+        }
+        throw new FileAccessError(filePath, err.message);
+      }
+    });
+    
+    return results;
+  }
+
+  /**
+   * Get all files recursively from a directory
+   * @param {string} dir - Directory to scan
+   * @returns {string[]} - Array of file paths
+   * @private
+   */
+  _getAllFiles(dir) {
+    const files = [];
+    
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        
+        // Skip hidden directories (starting with .)
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          const subFiles = this._getAllFiles(fullPath);
+          files.push(...subFiles);
+        } else if (entry.isFile()) {
+          files.push(fullPath);
+        }
+      }
+    } catch (err) {
+      // Ignore permission errors during directory traversal
+      if (err.code !== 'EACCES') {
+        throw err;
+      }
+    }
+    
+    return files;
+  }
+
+  /**
+   * Normalize a file path (convert Windows paths to Unix style)
+   * @param {string} filePath - The path to normalize
+   * @returns {string} - Normalized path
+   * @throws {FileAccessError} - On path traversal attempts
+   */
+  normalizePath(filePath) {
+    // Convert Windows backslashes to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+    
+    // Check for path traversal attempts
+    if (normalized.includes('..')) {
+      throw new FileAccessError(filePath, 'Path traversal not allowed');
+    }
+    
+    return normalized;
+  }
+
+  /**
+   * Validate a file path
+   * @param {string} filePath - The path to validate
+   * @returns {boolean} - True if valid
+   */
+  validatePath(filePath) {
+    // Reject paths with null bytes
+    if (filePath.includes('\x00')) {
+      return false;
+    }
+    
+    // Resolve the path
+    const resolvedPath = path.resolve(this.cwd, filePath);
+    
+    // Check if path is within cwd (prevent access outside project)
+    const normalizedCwd = path.resolve(this.cwd).replace(/\\/g, '/');
+    const normalizedResolved = resolvedPath.replace(/\\/g, '/');
+    
+    // Path must be within or equal to cwd
+    if (!normalizedResolved.startsWith(normalizedCwd)) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Check if a file exists
+   * @param {string} filePath - Path to check
+   * @returns {boolean} - True if file exists
+   */
+  fileExists(filePath) {
+    const fullPath = path.join(this.cwd, filePath);
+    return fs.existsSync(fullPath);
+  }
+
+  /**
+   * Read a single file
+   * @param {string} filePath - Path to the file
+   * @returns {{path: string, content: string}} - File object
+   * @throws {FileAccessError} - On file access errors
+   */
+  readFile(filePath) {
+    const results = this.readFiles([filePath]);
+    return results[0] || null;
+  }
+
+  /**
+   * Get file info (size, modified time, etc.)
+   * @param {string} filePath - Path to the file
+   * @returns {{path: string, size: number, mtime: Date}} - File info
+   * @throws {FileAccessError} - On file access errors
+   */
+  getFileInfo(filePath) {
+    const fullPath = path.join(this.cwd, filePath);
+    
+    if (!fs.existsSync(fullPath)) {
+      throw new FileAccessError(filePath, 'File not found');
+    }
+    
+    const stats = fs.statSync(fullPath);
+    
+    return {
+      path: filePath,
+      size: stats.size,
+      mtime: stats.mtime,
+      isDirectory: stats.isDirectory(),
+      isFile: stats.isFile()
+    };
+  }
+}
+
+module.exports = FileAccessService;

package/bin/lib/file-lock.cjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * EZ File Lock — File locking utility for concurrent write protection
+ * 
+ * Uses proper-lockfile to prevent concurrent writes to planning files
+ * Includes deadlock detection (30s timeout) and automatic lock cleanup
+ * 
+ * Fallback: Uses simple lock file mechanism if proper-lockfile is not available
+ * 
+ * Usage:
+ *   const { withLock, isLocked, ifUnlocked } = require('./file-lock.cjs');
+ *   await withLock('.planning/STATE.md', async () => {
+ *     // Safe to write - no other process can modify this file
+ *   });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+// Try to load proper-lockfile, fallback to simple implementation
+let properLockfile = null;
+try {
+  properLockfile = require('proper-lockfile');
+} catch (err) {
+  logger.warn('proper-lockfile not available, using fallback implementation');
+}
+
+const DEFAULT_OPTIONS = {
+  staleTime: 30000,     // Lock considered stale after 30s
+  update: 10000,        // Update lock every 10s to prevent stale
+  retries: {
+    retries: 10,
+    factor: 1.1,
+    minTimeout: 100,
+    maxTimeout: 1000,
+    randomize: true
+  }
+};
+
+// Simple lock file implementation (fallback)
+const LOCK_SUFFIX = '.lock';
+const lockHolders = new Map(); // Track locks held by this process
+
+/**
+ * Get lock file path
+ * @param {string} filePath - Original file path
+ * @returns {string} - Lock file path
+ */
+function getLockPath(filePath) {
+  return filePath + LOCK_SUFFIX;
+}
+
+/**
+ * Simple lock acquisition (fallback when proper-lockfile unavailable)
+ */
+async function simpleLock(filePath, options = {}) {
+  const lockPath = getLockPath(filePath);
+  const startTime = Date.now();
+  const timeout = options.timeout || 30000;
+  const staleTime = options.staleTime || 30000;
+  
+  while (Date.now() - startTime < timeout) {
+    try {
+      // Check if lock file exists and is not stale
+      if (fs.existsSync(lockPath)) {
+        const stats = fs.statSync(lockPath);
+        const age = Date.now() - stats.mtimeMs;
+        
+        if (age < staleTime) {
+          // Lock is held by another process, wait and retry
+          await new Promise(resolve => setTimeout(resolve, 100));
+          continue;
+        }
+        // Lock is stale, remove it
+        try {
+          fs.unlinkSync(lockPath);
+        } catch (err) {
+          // Ignore - another process might have removed it
+        }
+      }
+      
+      // Try to create lock file (using 'wx' flag to fail if it exists)
+      fs.writeFileSync(lockPath, JSON.stringify({
+        pid: process.pid,
+        timestamp: Date.now()
+      }), { encoding: 'utf-8', flag: 'wx' });
+      
+      lockHolders.set(filePath, lockPath);
+      
+      return {
+        release: async () => {
+          try {
+            if (fs.existsSync(lockPath)) {
+              fs.unlinkSync(lockPath);
+            }
+            lockHolders.delete(filePath);
+          } catch (err) {
+            logger.warn(`Failed to release lock: ${lockPath}`, { error: err.message });
+          }
+        }
+      };
+    } catch (err) {
+      // Lock acquisition failed, wait and retry
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+  
+  throw new Error(`Lock acquisition timed out after ${timeout}ms`);
+}
+
+/**
+ * Execute an operation with file lock
+ * @param {string} filePath - Path to file to lock
+ * @param {Function} operation - Async function to execute while locked
+ * @param {Object} options - Lock options
+ * @returns {Promise<any>} - Result of operation
+ */
+async function withLock(filePath, operation, options = {}) {
+  const lockOptions = { ...DEFAULT_OPTIONS, ...options };
+  const absolutePath = path.resolve(filePath);
+  
+  // Ensure file exists
+  if (!fs.existsSync(absolutePath)) {
+    const dir = path.dirname(absolutePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(absolutePath, '', 'utf-8');
+  }
+  
+  let release = null;
+  const startTime = Date.now();
+  
+  try {
+    logger.debug(`Attempting to acquire lock: ${absolutePath}`);
+    
+    if (properLockfile) {
+      // Use proper-lockfile
+      release = await properLockfile.lock(absolutePath, lockOptions);
+    } else {
+      // Use simple fallback
+      const lockResult = await simpleLock(absolutePath, lockOptions);
+      release = lockResult.release;
+    }
+    
+    const acquireTime = Date.now() - startTime;
+    logger.debug(`Lock acquired: ${absolutePath} (${acquireTime}ms)`);
+    
+    const result = await operation();
+    return result;
+  } catch (err) {
+    const waitTime = Date.now() - startTime;
+    if (err.message.includes('timed out') || err.code === 'ELOCKED') {
+      logger.error(`File locked by another process: ${absolutePath}`, { 
+        waited: waitTime,
+        timeout: lockOptions.timeout || 30000
+      });
+      throw new Error(`File locked: ${filePath} (waited ${waitTime}ms)`);
+    }
+    logger.error(`Lock acquisition failed: ${absolutePath}`, { 
+      error: err.message,
+      waited: waitTime 
+    });
+    throw err;
+  } finally {
+    if (release) {
+      try {
+        await release();
+        logger.debug(`Lock released: ${absolutePath}`);
+      } catch (err) {
+        logger.warn(`Failed to release lock: ${absolutePath}`, { 
+          error: err.message 
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Check if a file is currently locked
+ * @param {string} filePath - Path to file
+ * @returns {Promise<boolean>} - True if locked
+ */
+async function isLocked(filePath) {
+  const absolutePath = path.resolve(filePath);
+  
+  if (properLockfile) {
+    if (!fs.existsSync(absolutePath)) {
+      return false;
+    }
+    return properLockfile.check(absolutePath);
+  }
+  
+  // Simple fallback
+  const lockPath = getLockPath(filePath);
+  if (!fs.existsSync(lockPath)) {
+    return false;
+  }
+  
+  // Check if lock is stale
+  try {
+    const stats = fs.statSync(lockPath);
+    const age = Date.now() - stats.mtimeMs;
+    const staleTime = 30000;
+    
+    if (age >= staleTime) {
+      // Lock is stale, remove it
+      fs.unlinkSync(lockPath);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Execute operation only if file is not locked
+ * @param {string} filePath - Path to file
+ * @param {Function} operation - Async function to execute
+ * @param {any} fallback - Value to return if file is locked
+ * @returns {Promise<any>} - Result of operation or fallback
+ */
+async function ifUnlocked(filePath, operation, fallback = null) {
+  const locked = await isLocked(filePath);
+  if (locked) {
+    logger.debug(`File locked, using fallback: ${filePath}`);
+    return fallback;
+  }
+  return withLock(filePath, operation);
+}
+
+module.exports = { withLock, isLocked, ifUnlocked };