@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/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/ez-agents/bin/lib/logger.cjs

@@ -1,154 +1,99 @@
-#!/usr/bin/env node
-
-/**
- * EZ Logger — Centralized logging module for EZ workflow
- *
- * Provides structured logging with levels (ERROR, WARN, INFO, DEBUG)
- * Writes to .planning/logs/{category}/ez-{YYYY-MM-DD}.log
- * - One file per day per category (reduces file waste)
- * - Categories: error, warn, info, debug
- * Replaces silent catch {} blocks with proper error logging
- *
- * Usage:
- *   const Logger = require('./logger.cjs');
- *   const logger = new Logger();
- *   logger.error('Something failed', { context: 'details' });
- */
-
-const fs = require('fs');
-const path = require('path');
-
-class Logger {
-  /**
-   * Create a Logger instance
-   * @param {string} logDir - Directory for log files (default: .planning/logs)
-   */
-  constructor(logDir = '.planning/logs') {
-    this.logDir = logDir;
-    this.logFiles = {
-      error: null,
-      warn: null,
-      info: null,
-      debug: null
-    };
-    this.currentDate = null;
-  }
-
-  /**
-   * Get current date string in YYYY-MM-DD format
-   * @returns {string} - Date string
-   */
-  _getDateStr() {
-    return new Date().toISOString().split('T')[0];
-  }
-
-  /**
-   * Ensure log directory exists
-   */
-  _ensureLogDir() {
-    if (!fs.existsSync(this.logDir)) {
-      fs.mkdirSync(this.logDir, { recursive: true });
-    }
-  }
-
-  /**
-   * Get log file path for a specific category
-   * Creates new file when date changes (daily rotation)
-   * @param {string} category - Log category (error, warn, info, debug)
-   * @returns {string} - Path to log file
-   */
-  _getLogFile(category) {
-    const dateStr = this._getDateStr();
-    
-    // Rotate log file if date changed
-    if (this.currentDate !== dateStr) {
-      this.currentDate = dateStr;
-      this.logFiles = { error: null, warn: null, info: null, debug: null };
-    }
-
-    if (!this.logFiles[category]) {
-      this._ensureLogDir();
-      // Create category subdirectory
-      const categoryDir = path.join(this.logDir, category);
-      if (!fs.existsSync(categoryDir)) {
-        fs.mkdirSync(categoryDir, { recursive: true });
-      }
-      this.logFiles[category] = path.join(categoryDir, `ez-${dateStr}.log`);
-    }
-
-    return this.logFiles[category];
-  }
-
-  /**
-   * Write a log entry
-   * @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 category = level.toLowerCase();
-    const logFile = this._getLogFile(category);
-
-    const entry = {
-      timestamp: new Date().toISOString(),
-      level,
-      message,
-      context,
-      pid: process.pid
-    };
-
-    try {
-      fs.appendFileSync(logFile, JSON.stringify(entry) + '\n');
-
-      // Always output ERROR level to console for visibility
-      if (level === 'ERROR') {
-        console.error(`[EZ ${level}] ${message}`);
-      }
-    } catch (err) {
-      // Fallback: log to console if file write fails
-      console.error(`[EZ ${level}] ${message} (file write failed: ${err.message})`);
-    }
-  }
-
-  /**
-   * Log an ERROR level message
-   * @param {string} msg - Error message
-   * @param {Object} ctx - Additional context
-   */
-  error(msg, ctx) {
-    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;
+#!/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
+ *
+ * Usage:
+ *   const Logger = require('./logger.cjs');
+ *   const logger = new Logger();
+ *   logger.error('Something failed', { context: 'details' });
+ */
+
+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
+   * @param {string} msg - Error message
+   * @param {Object} ctx - Additional context
+   */
+  error(msg, ctx) {
+    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);
+  }
+
+  /**
+   * Get log file path (returns null - no file logging)
+   * @returns {null} - Always null
+   */
+  getLogFile() {
+    return null;
+  }
+}
+
+// Singleton instance for default usage
+const defaultLogger = new Logger();
+
+module.exports = Logger;
+module.exports.defaultLogger = defaultLogger;

package/ez-agents/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;