@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/lock-logger.cjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Lock Logger
+ *
+ * Dedicated logging for phase lock operations.
+ * Logs to console only (no file logging).
+ *
+ * Features:
+ * - Structured logging
+ * - Log levels: INFO, WARN, ERROR
+ * - Automatic timestamp and context
+ *
+ * Usage:
+ *   const LockLogger = require('./lock-logger.cjs');
+ *   const lockLogger = new LockLogger();
+ *
+ *   lockLogger.log('INFO', 'acquire', { phase: '47', agent_id: 'agent-1', result: 'success' });
+ *   lockLogger.log('WARN', 'conflict', { phase: '47', holder_agent: 'agent-2' });
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * LockLogger class for lock operation logging.
+ */
+class LockLogger {
+  /**
+   * Creates a new LockLogger instance.
+   */
+  constructor() {
+    // Console only - no file logging
+  }
+
+  /**
+   * Log a lock operation.
+   * @param {string} level - Log level: INFO, WARN, ERROR
+   * @param {string} operation - Operation type: acquire, release, heartbeat, conflict, stale
+   * @param {Object} data - Operation data
+   */
+  log(level, operation, data = {}) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level: level.toUpperCase(),
+      operation,
+      ...data
+    };
+
+    // Log to console
+    if (level === 'ERROR') {
+      console.error(`[EZ LOCK] ${JSON.stringify(entry)}`);
+    } else if (level === 'WARN') {
+      console.warn(`[EZ LOCK] ${JSON.stringify(entry)}`);
+    } else if (process.env.DEBUG === 'ez-agents') {
+      console.log(`[EZ LOCK] ${JSON.stringify(entry)}`);
+    }
+  }
+
+  /**
+   * Log lock acquire.
+   * @param {string} phase - Phase number
+   * @param {string} agentId - Agent identifier
+   * @param {Object} result - Acquire result
+   */
+  logAcquire(phase, agentId, result) {
+    const data = {
+      phase,
+      agent_id: agentId,
+      result: result.acquired ? 'success' : (result.conflict ? 'conflict' : 'error'),
+      message: result.message
+    };
+
+    if (result.lockInfo) {
+      data.holder_agent = result.lockInfo.agent_id;
+      data.holder_name = result.lockInfo.agent_name;
+      data.expires_at = result.expiresAt;
+    }
+
+    const level = result.acquired ? 'INFO' : (result.conflict ? 'WARN' : 'ERROR');
+    this.log(level, 'acquire', data);
+  }
+
+  /**
+   * Log lock release.
+   * @param {string} phase - Phase number
+   * @param {string} agentId - Agent identifier
+   * @param {Object} result - Release result
+   */
+  logRelease(phase, agentId, result) {
+    const data = {
+      phase,
+      agent_id: agentId,
+      result: result.released ? 'success' : 'error',
+      message: result.message
+    };
+
+    if (result.lockInfo) {
+      data.held_duration_ms = Date.now() - new Date(result.lockInfo.acquired_at).getTime();
+    }
+
+    const level = result.released ? 'INFO' : 'ERROR';
+    this.log(level, 'release', data);
+  }
+
+  /**
+   * Log heartbeat.
+   * @param {string} phase - Phase number
+   * @param {string} agentId - Agent identifier
+   * @param {Object} result - Heartbeat result
+   */
+  logHeartbeat(phase, agentId, result) {
+    const data = {
+      phase,
+      agent_id: agentId,
+      result: result.success ? 'success' : 'error',
+      message: result.message
+    };
+
+    if (result.lockInfo) {
+      data.expires_at = result.lockInfo.expires_at;
+    }
+
+    const level = result.success ? 'INFO' : 'WARN';
+    this.log(level, 'heartbeat', data);
+  }
+
+  /**
+   * Log stale lock detection.
+   * @param {string} phase - Phase number
+   * @param {Object} lockInfo - Stale lock info
+   */
+  logStale(phase, lockInfo) {
+    const data = {
+      phase,
+      previous_agent: lockInfo.agent_id,
+      previous_name: lockInfo.agent_name,
+      reason: 'expired',
+      action: 'auto-release'
+    };
+
+    if (lockInfo.expires_at) {
+      data.expired_at = lockInfo.expires_at;
+    }
+
+    this.log('WARN', 'stale', data);
+  }
+
+  /**
+   * Log lock status update.
+   * @param {number} lockCount - Number of active locks
+   * @param {Object} result - Update result
+   */
+  logStateUpdate(lockCount, result) {
+    const data = {
+      lock_count: lockCount,
+      result: result.updated ? 'success' : 'error'
+    };
+
+    if (result.error) {
+      data.error = result.error;
+    }
+
+    const level = result.updated ? 'INFO' : 'WARN';
+    this.log(level, 'state_update', data);
+  }
+
+  /**
+   * Get log file path (returns null - no file logging).
+   * @returns {null} - Always null
+   */
+  getLogPath() {
+    return null;
+  }
+
+  /**
+   * Read recent log entries (returns empty array - no file logging).
+   * @param {number} limit - Number of entries to read
+   * @returns {Array<Object>} - Empty array
+   */
+  readRecent(limit = 100) {
+    return [];
+  }
+
+  /**
+   * Clear log file (no-op - no file logging).
+   * @returns {boolean} - Always true
+   */
+  clear() {
+    return true;
+  }
+}
+
+module.exports = LockLogger;

package/bin/lib/lock-state.cjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Lock State
+ *
+ * Integrates lock state into STATE.md and provides lock status reporting.
+ * Updates STATE.md automatically on lock acquire/release.
+ *
+ * Features:
+ * - Scan all active locks
+ * - Format lock status as markdown table
+ * - Update STATE.md lock status section
+ * - Auto-reconcile stale entries
+ *
+ * Usage:
+ *   const LockState = require('./lock-state.cjs');
+ *   const lockState = new LockState();
+ *
+ *   // Get formatted lock status
+ *   const status = await lockState.getLockStatus();
+ *   const table = lockState.formatLockStatusTable(status);
+ *
+ *   // Update STATE.md
+ *   await lockState.updateStateLockSection(table);
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Default configuration.
+ */
+const DEFAULT_CONFIG = {
+  locksDir: path.join(process.cwd(), '.planning', 'locks'),
+  statePath: path.join(process.cwd(), '.planning', 'STATE.md'),
+  staleThresholdMinutes: 90
+};
+
+/**
+ * LockState class for managing lock state integration.
+ */
+class LockState {
+  /**
+   * Creates a new LockState instance.
+   * @param {Object} options - Configuration options
+   * @param {string} options.locksDir - Directory for lock files
+   * @param {string} options.statePath - Path to STATE.md
+   */
+  constructor(options = {}) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...options
+    };
+  }
+
+  /**
+   * Get status of all active locks.
+   * @returns {Promise<Array<Object>>} - Array of lock status objects
+   */
+  async getLockStatus() {
+    try {
+      if (!fs.existsSync(this.config.locksDir)) {
+        return [];
+      }
+
+      const files = fs.readdirSync(this.config.locksDir)
+        .filter(f => f.endsWith('.lock.json'));
+
+      const activeLocks = [];
+      const now = new Date();
+
+      for (const file of files) {
+        const filePath = path.join(this.config.locksDir, file);
+        try {
+          const lockInfo = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+
+          // Check if lock is stale
+          const expiresAt = new Date(lockInfo.expires_at);
+          const lastHeartbeat = new Date(lockInfo.last_heartbeat);
+          const staleThreshold = new Date(now.getTime() - this.config.staleThresholdMinutes * 60000);
+
+          const isStale = now > expiresAt || lastHeartbeat < staleThreshold;
+
+          if (!isStale) {
+            const acquiredAt = new Date(lockInfo.acquired_at);
+            const durationMs = now - acquiredAt;
+            const durationMin = Math.round(durationMs / 60000);
+
+            activeLocks.push({
+              phase: lockInfo.phase,
+              agentId: lockInfo.agent_id,
+              agentName: lockInfo.agent_name,
+              expiresAt: lockInfo.expires_at,
+              acquiredAt: lockInfo.acquired_at,
+              durationMin,
+              sessionId: lockInfo.session_id,
+              milestone: lockInfo.milestone
+            });
+          }
+        } catch (err) {
+          logger.warn('Failed to read lock file', { file, error: err.message });
+        }
+      }
+
+      // Sort by phase number
+      activeLocks.sort((a, b) => parseInt(a.phase) - parseInt(b.phase));
+
+      return activeLocks;
+
+    } catch (err) {
+      logger.error('Failed to get lock status', { error: err.message });
+      return [];
+    }
+  }
+
+  /**
+   * Format lock status as markdown table.
+   * @param {Array<Object>} locks - Lock status objects
+   * @returns {string} - Markdown table string
+   */
+  formatLockStatusTable(locks) {
+    if (!locks || locks.length === 0) {
+      return 'No active locks.\n';
+    }
+
+    let table = '| Phase | Agent | Expires | Duration |\n';
+    table += '|-------|-------|---------|----------|\n';
+
+    for (const lock of locks) {
+      const expiresDate = new Date(lock.expiresAt);
+      const expiresStr = expiresDate.toISOString().replace('T', ' ').substring(0, 16);
+      const durationStr = this._formatDuration(lock.durationMin);
+
+      table += `| ${lock.phase} | ${lock.agentId} | ${expiresStr} | ${durationStr} |\n`;
+    }
+
+    return table;
+  }
+
+  /**
+   * Update STATE.md with lock status section.
+   * @param {string} table - Markdown table to insert
+   * @returns {Promise<Object>} - Update result
+   */
+  async updateStateLockSection(table) {
+    try {
+      if (!fs.existsSync(this.config.statePath)) {
+        logger.warn('STATE.md not found', { path: this.config.statePath });
+        return {
+          updated: false,
+          error: 'STATE.md not found'
+        };
+      }
+
+      let content = fs.readFileSync(this.config.statePath, 'utf8');
+
+      // Check if Lock Status section exists
+      const lockStatusRegex = /## Lock Status\s*\n([\s\S]*?)(?=\n## |\n# |\s*$)/;
+      const hasLockSection = lockStatusRegex.test(content);
+
+      const newSection = `## Lock Status\n\n${table}\n`;
+
+      if (hasLockSection) {
+        // Replace existing section
+        content = content.replace(lockStatusRegex, newSection);
+      } else {
+        // Add new section after the last existing section
+        const lastSectionMatch = content.match(/(## [^\n]+\n[\s\S]*)$/);
+        if (lastSectionMatch) {
+          content = content.replace(lastSectionMatch[0], lastSectionMatch[0] + '\n' + newSection);
+        } else {
+          // Append to end
+          content += '\n' + newSection;
+        }
+      }
+
+      // Atomic write
+      const tempFile = this.config.statePath + '.tmp';
+      fs.writeFileSync(tempFile, content, 'utf8');
+      fs.renameSync(tempFile, this.config.statePath);
+
+      logger.info('STATE.md lock section updated', {
+        lockCount: table.split('\n').length - 3 // Subtract header rows
+      });
+
+      return {
+        updated: true,
+        lockCount: table.split('\n').length - 3
+      };
+
+    } catch (err) {
+      logger.error('Failed to update STATE.md lock section', { error: err.message });
+      return {
+        updated: false,
+        error: err.message
+      };
+    }
+  }
+
+  /**
+   * Reconcile STATE.md with actual locks (remove stale entries).
+   * @returns {Promise<Object>} - Reconcile result
+   */
+  async reconcile() {
+    try {
+      const activeLocks = await this.getLockStatus();
+      const table = this.formatLockStatusTable(activeLocks);
+      return await this.updateStateLockSection(table);
+    } catch (err) {
+      logger.error('Lock state reconcile failed', { error: err.message });
+      return {
+        reconciled: false,
+        error: err.message
+      };
+    }
+  }
+
+  /**
+   * Get lock status summary for quick display.
+   * @returns {Promise<string>} - Summary string
+   */
+  async getSummary() {
+    const locks = await this.getLockStatus();
+
+    if (locks.length === 0) {
+      return 'No active locks';
+    }
+
+    const summary = locks.map(lock => {
+      return `Phase ${lock.phase}: ${lock.agentId} (expires ${new Date(lock.expiresAt).toLocaleString()})`;
+    });
+
+    return summary.join('\n');
+  }
+
+  /**
+   * Format duration in human-readable format.
+   * @param {number} minutes - Duration in minutes
+   * @returns {string} - Formatted duration
+   * @private
+   */
+  _formatDuration(minutes) {
+    if (minutes < 60) {
+      return `${minutes} min`;
+    }
+
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+
+    if (hours < 24) {
+      return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
+    }
+
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+
+    return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
+  }
+}
+
+module.exports = LockState;

package/bin/lib/lockfile-validator.cjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+/**
+ * Lockfile Validator — Validate package manager lockfiles
+ *
+ * Validates lockfile integrity for npm, yarn, and pnpm:
+ * - npm: package-lock.json (JSON format with lockfileVersion)
+ * - yarn: yarn.lock (YAML-like format with metadata header)
+ * - pnpm: pnpm-lock.yaml (YAML format with lockfileVersion)
+ *
+ * Usage:
+ *   const LockfileValidator = require('./lockfile-validator.cjs');
+ *   const validator = new LockfileValidator(cwd);
+ *   const result = validator.validate('npm');
+ *   // Returns: { valid, reason, lockfileVersion?, packageCount? }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+
+/**
+ * Lockfile Validator class
+ * Validates lockfile integrity for different package managers
+ */
+class LockfileValidator {
+  /**
+   * Create a LockfileValidator instance
+   * @param {string} cwd - Working directory (default: process.cwd())
+   */
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+    this.logger = new Logger();
+  }
+
+  /**
+   * Validate lockfile for a specific package manager
+   * @param {string} manager - Package manager name ('npm', 'yarn', or 'pnpm')
+   * @returns {Object} Validation result
+   *   - {boolean} valid - Whether lockfile is valid
+   *   - {string} reason - Reason code if invalid
+   *   - {string} message - Human-readable message if invalid
+   *   - {number} lockfileVersion - Lockfile version (if valid)
+   *   - {number} packageCount - Number of packages (if valid)
+   */
+  validate(manager) {
+    const lockfilePath = this.getLockfilePath(manager);
+
+    this.logger.debug('Validating lockfile', {
+      manager,
+      lockfilePath,
+      cwd: this.cwd
+    });
+
+    // Check file existence
+    if (!fs.existsSync(lockfilePath)) {
+      this.logger.debug('Lockfile not found', { lockfilePath });
+      return {
+        valid: false,
+        reason: 'lockfile_missing',
+        message: `No ${path.basename(lockfilePath)} found`
+      };
+    }
+
+    try {
+      const content = fs.readFileSync(lockfilePath, 'utf-8');
+
+      switch (manager) {
+        case 'npm':
+          return this.validateNpmLockfile(content);
+        case 'yarn':
+          return this.validateYarnLockfile(content);
+        case 'pnpm':
+          return this.validatePnpmLockfile(content);
+        default:
+          return {
+            valid: false,
+            reason: 'unknown_manager',
+            message: `Unknown package manager: ${manager}`
+          };
+      }
+    } catch (err) {
+      this.logger.error('Lockfile read error', {
+        manager,
+        lockfilePath,
+        error: err.message
+      });
+      return {
+        valid: false,
+        reason: 'read_error',
+        message: err.message
+      };
+    }
+  }
+
+  /**
+   * Validate npm lockfile (package-lock.json)
+   * @param {string} content - Lockfile content
+   * @returns {Object} Validation result
+   */
+  validateNpmLockfile(content) {
+    try {
+      const lockfile = JSON.parse(content);
+
+      // Check required fields
+      if (!lockfile.lockfileVersion) {
+        return {
+          valid: false,
+          reason: 'invalid_format',
+          message: 'Missing lockfileVersion field'
+        };
+      }
+
+      if (!lockfile.packages && !lockfile.dependencies) {
+        return {
+          valid: false,
+          reason: 'empty_lockfile',
+          message: 'Lockfile has no dependencies'
+        };
+      }
+
+      const packageCount = Object.keys(lockfile.packages || lockfile.dependencies || {}).length;
+
+      this.logger.debug('npm lockfile valid', {
+        lockfileVersion: lockfile.lockfileVersion,
+        packageCount
+      });
+
+      return {
+        valid: true,
+        lockfileVersion: lockfile.lockfileVersion,
+        packageCount
+      };
+    } catch (err) {
+      this.logger.debug('npm lockfile invalid JSON', { error: err.message });
+      return {
+        valid: false,
+        reason: 'invalid_json',
+        message: `Invalid JSON: ${err.message}`
+      };
+    }
+  }
+
+  /**
+   * Validate yarn lockfile (yarn.lock)
+   * @param {string} content - Lockfile content
+   * @returns {Object} Validation result
+   */
+  validateYarnLockfile(content) {
+    // Yarn lockfile is YAML-like format
+    // Check for basic structure: __metadata__ (Yarn 2+) or "# yarn lockfile v" (Yarn 1)
+    const hasYarn2Metadata = content.includes('__metadata:');
+    const hasYarn1Header = content.match(/^# yarn lockfile v/i);
+
+    if (!hasYarn2Metadata && !hasYarn1Header) {
+      this.logger.debug('yarn lockfile invalid format');
+      return {
+        valid: false,
+        reason: 'invalid_format',
+        message: 'Invalid yarn.lock format'
+      };
+    }
+
+    // Count dependency entries (lines starting with package name pattern)
+    const entryCount = (content.match(/^"?[^@\s]+@/gm) || []).length;
+
+    this.logger.debug('yarn lockfile valid', {
+      version: hasYarn2Metadata ? '2+' : '1',
+      entryCount
+    });
+
+    return {
+      valid: true,
+      entryCount
+    };
+  }
+
+  /**
+   * Validate pnpm lockfile (pnpm-lock.yaml)
+   * @param {string} content - Lockfile content
+   * @returns {Object} Validation result
+   */
+  validatePnpmLockfile(content) {
+    // Check for lockfileVersion
+    const versionMatch = content.match(/^lockfileVersion:\s*(\d+)/m);
+    if (!versionMatch) {
+      this.logger.debug('pnpm lockfile missing lockfileVersion');
+      return {
+        valid: false,
+        reason: 'invalid_format',
+        message: 'Missing lockfileVersion in pnpm-lock.yaml'
+      };
+    }
+
+    const lockfileVersion = parseInt(versionMatch[1], 10);
+
+    // Count dependency entries (lines starting with "  /" which are package specs)
+    const entryCount = (content.match(/^  \/[^:]+:/gm) || []).length;
+
+    this.logger.debug('pnpm lockfile valid', {
+      lockfileVersion,
+      entryCount
+    });
+
+    return {
+      valid: true,
+      lockfileVersion,
+      entryCount
+    };
+  }
+
+  /**
+   * Get the lockfile path for a specific package manager
+   * @param {string} manager - Package manager name
+   * @returns {string} Full path to lockfile
+   */
+  getLockfilePath(manager) {
+    const lockfiles = {
+      'npm': 'package-lock.json',
+      'yarn': 'yarn.lock',
+      'pnpm': 'pnpm-lock.yaml'
+    };
+    return path.join(this.cwd, lockfiles[manager] || 'package-lock.json');
+  }
+}
+
+module.exports = LockfileValidator;