@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/log-rotation.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Log Rotation Utility
+ * 
+ * Automatically deletes EZ Agents logs older than 7 days to prevent git spam.
+ * Run this weekly or add to CI/CD cleanup job.
+ * 
+ * Usage: node ez-agents/bin/lib/log-rotation.cjs [--dry-run]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LOGS_DIR = path.join(process.cwd(), '.planning', 'logs');
+const MAX_AGE_DAYS = 7;
+const DRY_RUN = process.argv.includes('--dry-run');
+
+function rotateLogs() {
+  if (!fs.existsSync(LOGS_DIR)) {
+    console.log('Logs directory not found:', LOGS_DIR);
+    return;
+  }
+
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - MAX_AGE_DAYS);
+
+  const files = fs.readdirSync(LOGS_DIR);
+  const logFiles = files.filter(f => f.endsWith('.log'));
+  
+  let deleted = 0;
+  let kept = 0;
+  let totalSize = 0;
+
+  logFiles.forEach(file => {
+    const filePath = path.join(LOGS_DIR, file);
+    const stats = fs.statSync(filePath);
+    
+    if (stats.mtime < cutoff) {
+      if (DRY_RUN) {
+        console.log(`[DRY-RUN] Would delete: ${file} (${formatBytes(stats.size)})`);
+      } else {
+        fs.unlinkSync(filePath);
+        console.log(`Deleted: ${file}`);
+      }
+      deleted++;
+      totalSize += stats.size;
+    } else {
+      kept++;
+    }
+  });
+
+  console.log(`\n${DRY_RUN ? '[DRY-RUN] ' : ''}Log Rotation Complete`);
+  console.log(`  Deleted: ${deleted} files (${formatBytes(totalSize)})`);
+  console.log(`  Kept: ${kept} files (last ${MAX_AGE_DAYS} days)`);
+}
+
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return Math.round(bytes / Math.pow(k, i) * 100) / 100 + ' ' + sizes[i];
+}
+
+// Run if called directly
+if (require.main === module) {
+  rotateLogs();
+}
+
+module.exports = { rotateLogs };

package/bin/lib/logger.cjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Logger — Centralized logging module for EZ workflow
+ *
+ * Provides structured logging with levels (ERROR, WARN, INFO, DEBUG)
+ * Logs to console only (no file logging)
+ * Replaces silent catch {} blocks with proper error logging
+ * Integrated with ErrorCache for recurring error detection
+ *
+ * Usage:
+ *   const Logger = require('./logger.cjs');
+ *   const logger = new Logger();
+ *   logger.error('Something failed', { context: 'details' });
+ */
+
+// Lazy-load ErrorCache to avoid circular dependencies
+let ErrorCacheInstance = null;
+
+/**
+ * Get or create ErrorCache singleton
+ * @returns {Object} ErrorCache instance
+ */
+function getErrorCache() {
+  if (!ErrorCacheInstance) {
+    try {
+      const { ErrorCache } = require('./error-cache.cjs');
+      ErrorCacheInstance = new ErrorCache();
+    } catch (err) {
+      // ErrorCache not available - continue without it
+      ErrorCacheInstance = null;
+    }
+  }
+  return ErrorCacheInstance;
+}
+
+class Logger {
+  /**
+   * Create a Logger instance
+   */
+  constructor() {
+    // No file logging - console only
+  }
+
+  /**
+   * Write a log entry to console
+   * @param {string} level - Log level (ERROR, WARN, INFO, DEBUG)
+   * @param {string} message - Log message
+   * @param {Object} context - Additional context data
+   */
+  log(level, message, context = {}) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      context,
+      pid: process.pid
+    };
+
+    // Always output to console
+    if (level === 'ERROR') {
+      console.error(`[EZ ${level}] ${message}`);
+    } else if (level === 'WARN') {
+      console.warn(`[EZ ${level}] ${message}`);
+    } else if (process.env.DEBUG === 'ez-agents') {
+      // Only output INFO/DEBUG in debug mode
+      console.log(`[EZ ${level}] ${message}`);
+    }
+  }
+
+  /**
+   * Log an ERROR level message
+   * Records error to cache for recurring detection
+   * @param {string} msg - Error message
+   * @param {Object} ctx - Additional context (can include error object)
+   */
+  error(msg, ctx) {
+    // Record to error cache if error object provided
+    if (ctx && ctx.error instanceof Error) {
+      const cache = getErrorCache();
+      if (cache) {
+        const fingerprint = cache.record(ctx.error, ctx);
+        if (cache.isRecurring(fingerprint)) {
+          const entry = cache.get(fingerprint);
+          console.warn(`[EZ RECURRING] (${entry.count}x): ${msg}`);
+        }
+      }
+    }
+    
+    this.log('ERROR', msg, ctx);
+  }
+
+  /**
+   * Log a WARN level message
+   * @param {string} msg - Warning message
+   * @param {Object} ctx - Additional context
+   */
+  warn(msg, ctx) {
+    this.log('WARN', msg, ctx);
+  }
+
+  /**
+   * Log an INFO level message
+   * @param {string} msg - Info message
+   * @param {Object} ctx - Additional context
+   */
+  info(msg, ctx) {
+    this.log('INFO', msg, ctx);
+  }
+
+  /**
+   * Log a DEBUG level message
+   * @param {string} msg - Debug message
+   * @param {Object} ctx - Additional context
+   */
+  debug(msg, ctx) {
+    this.log('DEBUG', msg, ctx);
+  }
+}
+
+// Singleton instance for default usage
+const defaultLogger = new Logger();
+
+module.exports = Logger;
+module.exports.defaultLogger = defaultLogger;

package/bin/lib/memory-compression.cjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+
+/**
+ * Memory Compression — Compress long session transcripts
+ *
+ * Reduces session size by keeping first N and last M messages
+ */
+
+const { defaultLogger: logger } = require('./logger.cjs');
+
+class MemoryCompression {
+  /**
+   * Create a MemoryCompression instance
+   * @param {Object} sessionManager - SessionManager instance
+   */
+  constructor(sessionManager) {
+    this.sessionManager = sessionManager;
+  }
+
+  /**
+   * Compress a session transcript
+   * @param {string} sessionId - Session ID
+   * @param {Object} options - Compression options
+   * @param {number} [options.threshold=50] - Minimum messages before compression
+   * @param {number} [options.keepFirst=5] - Messages to keep at start
+   * @param {number} [options.keepLast=10] - Messages to keep at end
+   * @returns {Object} Compression result
+   */
+  compress(sessionId, options = {}) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return { compressed: false, reason: 'Session not found' };
+    }
+
+    const {
+      threshold = 50,
+      keepFirst = 5,
+      keepLast = 10
+    } = options;
+
+    const transcript = session.context?.transcript || '';
+    
+    // Handle string transcript (split by newlines or messages)
+    let messages = [];
+    if (typeof transcript === 'string') {
+      // Try to parse as JSON array first
+      try {
+        messages = JSON.parse(transcript);
+      } catch {
+        // Split by newlines as fallback
+        messages = transcript.split('\n').filter(line => line.trim());
+      }
+    } else if (Array.isArray(transcript)) {
+      messages = transcript;
+    }
+
+    if (messages.length <= threshold) {
+      logger.info('Session below compression threshold', { sessionId, messageCount: messages.length });
+      return { 
+        compressed: false, 
+        reason: 'Below threshold',
+        messageCount: messages.length,
+        threshold 
+      };
+    }
+
+    // Create compressed transcript
+    const firstMessages = messages.slice(0, keepFirst);
+    const lastMessages = messages.slice(-keepLast);
+    const compressedCount = messages.length - keepFirst - keepLast;
+
+    const placeholder = {
+      role: 'system',
+      content: `... ${compressedCount} messages compressed ...`,
+      timestamp: new Date().toISOString(),
+      compressed: true
+    };
+
+    const compressedMessages = [
+      ...firstMessages,
+      placeholder,
+      ...lastMessages
+    ];
+
+    // Update session
+    const updates = {
+      context: {
+        transcript: compressedMessages
+      },
+      metadata: {
+        compressed: true,
+        compressed_at: new Date().toISOString(),
+        compression_stats: {
+          original_count: messages.length,
+          compressed_count: compressedMessages.length,
+          removed_count: compressedCount
+        }
+      }
+    };
+
+    this.sessionManager.updateSession(sessionId, updates);
+
+    const reduction = Math.round((1 - compressedMessages.length / messages.length) * 100);
+
+    logger.info('Session compressed', { 
+      sessionId, 
+      originalLength: messages.length, 
+      newLength: compressedMessages.length,
+      reduction 
+    });
+
+    return {
+      compressed: true,
+      originalLength: messages.length,
+      newLength: compressedMessages.length,
+      reduction
+    };
+  }
+
+  /**
+   * Get compression stats for a session
+   * @param {string} sessionId - Session ID
+   * @returns {Object} Compression statistics
+   */
+  getCompressionStats(sessionId) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return { compressed: false, reason: 'Session not found' };
+    }
+
+    if (!session.metadata?.compressed) {
+      return { compressed: false };
+    }
+
+    const originalSize = session.metadata.compression_stats?.original_count || 0;
+    const compressedSize = session.metadata.compression_stats?.compressed_count || 0;
+    const reduction = session.metadata.compression_stats?.removed_count || 0;
+    const reductionPercent = originalSize > 0 
+      ? Math.round((reduction / originalSize) * 100) 
+      : 0;
+
+    return {
+      compressed: true,
+      original_size: originalSize,
+      compressed_size: compressedSize,
+      reduction_percent: reductionPercent,
+      compressed_at: session.metadata.compressed_at
+    };
+  }
+
+  /**
+   * Check if session should be compressed
+   * @param {string} sessionId - Session ID
+   * @param {number} threshold - Message threshold
+   * @returns {boolean} True if compression recommended
+   */
+  shouldCompress(sessionId, threshold = 50) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const transcript = session.context?.transcript || '';
+    let messageCount = 0;
+
+    if (typeof transcript === 'string') {
+      try {
+        const messages = JSON.parse(transcript);
+        messageCount = Array.isArray(messages) ? messages.length : 0;
+      } catch {
+        messageCount = transcript.split('\n').filter(line => line.trim()).length;
+      }
+    } else if (Array.isArray(transcript)) {
+      messageCount = transcript.length;
+    }
+
+    return messageCount > threshold;
+  }
+
+  /**
+   * Compress all sessions exceeding threshold
+   * @param {Object} options - Compression options
+   * @returns {Object} Batch compression result
+   */
+  compressAll(options = {}) {
+    const sessions = this.sessionManager.listSessions();
+    const results = {
+      total: sessions.length,
+      compressed: 0,
+      skipped: 0,
+      details: []
+    };
+
+    for (const sessionMeta of sessions) {
+      const shouldCompress = this.shouldCompress(sessionMeta.session_id, options.threshold);
+      
+      if (shouldCompress) {
+        const result = this.compress(sessionMeta.session_id, options);
+        if (result.compressed) {
+          results.compressed++;
+          results.details.push({
+            sessionId: sessionMeta.session_id,
+            ...result
+          });
+        } else {
+          results.skipped++;
+        }
+      } else {
+        results.skipped++;
+      }
+    }
+
+    logger.info('Batch compression complete', {
+      total: results.total,
+      compressed: results.compressed,
+      skipped: results.skipped
+    });
+
+    return results;
+  }
+
+  /**
+   * Decompress a session (restore placeholder info)
+   * Note: Cannot restore original messages, only marks as decompressed
+   * @param {string} sessionId - Session ID
+   * @returns {Object} Decompression result
+   */
+  decompress(sessionId) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return { decompressed: false, reason: 'Session not found' };
+    }
+
+    if (!session.metadata?.compressed) {
+      return { decompressed: false, reason: 'Not compressed' };
+    }
+
+    // Remove compression metadata
+    this.sessionManager.updateSession(sessionId, {
+      metadata: {
+        compressed: false,
+        compressed_at: null,
+        compression_stats: null
+      }
+    });
+
+    logger.info('Session marked as decompressed', { sessionId });
+
+    return {
+      decompressed: true,
+      note: 'Original messages cannot be restored'
+    };
+  }
+}
+
+module.exports = MemoryCompression;

package/bin/lib/milestone.cjs

@@ -0,0 +1,247 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, output, error } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { writeStateMd } = require('./state.cjs');
+
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+  if (!reqIdsRaw || reqIdsRaw.length === 0) {
+    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+  }
+
+  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+  const reqIds = reqIdsRaw
+    .join(' ')
+    .replace(/[\[\]]/g, '')
+    .split(/[,\s]+/)
+    .map(r => r.trim())
+    .filter(Boolean);
+
+  if (reqIds.length === 0) {
+    error('no valid requirement IDs found');
+  }
+
+  const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+  if (!fs.existsSync(reqPath)) {
+    output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
+    return;
+  }
+
+  let reqContent = fs.readFileSync(reqPath, 'utf-8');
+  const updated = [];
+  const notFound = [];
+
+  for (const reqId of reqIds) {
+    let found = false;
+    const reqEscaped = escapeRegex(reqId);
+
+    // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+    if (checkboxPattern.test(reqContent)) {
+      reqContent = reqContent.replace(checkboxPattern, '$1x$2');
+      found = true;
+    }
+
+    // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+    const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+    if (tablePattern.test(reqContent)) {
+      // Re-read since test() advances lastIndex for global regex
+      reqContent = reqContent.replace(
+        new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
+        '$1 Complete $2'
+      );
+      found = true;
+    }
+
+    if (found) {
+      updated.push(reqId);
+    } else {
+      notFound.push(reqId);
+    }
+  }
+
+  if (updated.length > 0) {
+    fs.writeFileSync(reqPath, reqContent, 'utf-8');
+  }
+
+  output({
+    updated: updated.length > 0,
+    marked_complete: updated,
+    not_found: notFound,
+    total: reqIds.length,
+  }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+}
+
+function cmdMilestoneComplete(cwd, version, options, raw) {
+  if (!version) {
+    error('version required for milestone complete (e.g., v1.0)');
+  }
+
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+  const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+  const statePath = path.join(cwd, '.planning', 'STATE.md');
+  const milestonesPath = path.join(cwd, '.planning', 'MILESTONES.md');
+  const archiveDir = path.join(cwd, '.planning', 'milestones');
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const today = new Date().toISOString().split('T')[0];
+  const milestoneName = options.name || version;
+
+  // Ensure archive directory exists
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  // Scope stats and accomplishments to only the phases belonging to the
+  // current milestone's ROADMAP.  Uses the shared filter from core.cjs
+  // (same logic used by cmdPhasesList and other callers).
+  const isDirInMilestone = getMilestonePhaseFilter(cwd);
+
+  // Gather stats from phases (scoped to current milestone only)
+  let phaseCount = 0;
+  let totalPlans = 0;
+  let totalTasks = 0;
+  const accomplishments = [];
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+    for (const dir of dirs) {
+      if (!isDirInMilestone(dir)) continue;
+
+      phaseCount++;
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+      totalPlans += plans.length;
+
+      // Extract one-liners from summaries
+      for (const s of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+          const fm = extractFrontmatter(content);
+          if (fm['one-liner']) {
+            accomplishments.push(fm['one-liner']);
+          }
+          // Count tasks
+          const taskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+          totalTasks += taskMatches.length;
+        } catch (err) {
+          const { defaultLogger: logger } = require('./logger.cjs');
+          logger.warn('Failed to read phase summary', { phase: dir, summary: s, error: err.message });
+        }
+      }
+    }
+  } catch (err) {
+    const { defaultLogger: logger } = require('./logger.cjs');
+    logger.warn('Failed to scan phase summaries', { phasesDir, error: err.message });
+  }
+
+  // Archive ROADMAP.md
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    fs.writeFileSync(path.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent, 'utf-8');
+  }
+
+  // Archive REQUIREMENTS.md
+  if (fs.existsSync(reqPath)) {
+    const reqContent = fs.readFileSync(reqPath, 'utf-8');
+    const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+    fs.writeFileSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent, 'utf-8');
+  }
+
+  // Archive audit file if exists
+  const auditFile = path.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+  if (fs.existsSync(auditFile)) {
+    fs.renameSync(auditFile, path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+  }
+
+  // Create/append MILESTONES.md entry
+  const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+
+  if (fs.existsSync(milestonesPath)) {
+    const existing = fs.readFileSync(milestonesPath, 'utf-8');
+    if (!existing.trim()) {
+      // Empty file — treat like new
+      fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8');
+    } else {
+      // Insert after the header line(s) for reverse chronological order (newest first)
+      const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+      if (headerMatch) {
+        const header = headerMatch[1];
+        const rest = existing.slice(header.length);
+        fs.writeFileSync(milestonesPath, header + milestoneEntry + rest, 'utf-8');
+      } else {
+        // No recognizable header — prepend the entry
+        fs.writeFileSync(milestonesPath, milestoneEntry + existing, 'utf-8');
+      }
+    }
+  } else {
+    fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8');
+  }
+
+  // Update STATE.md
+  if (fs.existsSync(statePath)) {
+    let stateContent = fs.readFileSync(statePath, 'utf-8');
+    stateContent = stateContent.replace(
+      /(\*\*Status:\*\*\s*).*/,
+      `$1${version} milestone complete`
+    );
+    stateContent = stateContent.replace(
+      /(\*\*Last Activity:\*\*\s*).*/,
+      `$1${today}`
+    );
+    stateContent = stateContent.replace(
+      /(\*\*Last Activity Description:\*\*\s*).*/,
+      `$1${version} milestone completed and archived`
+    );
+    writeStateMd(statePath, stateContent, cwd);
+  }
+
+  // Archive phase directories if requested
+  let phasesArchived = false;
+  if (options.archivePhases) {
+    try {
+      const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
+      fs.mkdirSync(phaseArchiveDir, { recursive: true });
+
+      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of phaseDirNames) {
+        if (!isDirInMilestone(dir)) continue;
+        fs.renameSync(path.join(phasesDir, dir), path.join(phaseArchiveDir, dir));
+        archivedCount++;
+      }
+      phasesArchived = archivedCount > 0;
+    } catch {}
+  }
+
+  const result = {
+    version,
+    name: milestoneName,
+    date: today,
+    phases: phaseCount,
+    plans: totalPlans,
+    tasks: totalTasks,
+    accomplishments,
+    archived: {
+      roadmap: fs.existsSync(path.join(archiveDir, `${version}-ROADMAP.md`)),
+      requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
+      audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
+      phases: phasesArchived,
+    },
+    milestones_updated: true,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+};