agileflow 2.87.0 → 2.89.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.89.0] - 2026-01-14
+
+### Added
+- Security hardening, LRU file caching, and comprehensive test coverage
+
+## [2.88.0] - 2026-01-13
+
+### Fixed
+- Security and code quality improvements from EP-0012 ideation
+
 ## [2.87.0] - 2026-01-13
 
 ### Added

package/lib/file-cache.js

@@ -0,0 +1,358 @@
+/**
+ * File Cache - LRU Cache for frequently read JSON files
+ *
+ * Optimizes performance by caching frequently accessed JSON files
+ * with configurable TTL (Time To Live).
+ *
+ * Features:
+ * - LRU (Least Recently Used) eviction when max size reached
+ * - TTL-based automatic expiration
+ * - Separate caches for different data types
+ * - Thread-safe for single-process Node.js usage
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * LRU Cache implementation with TTL support
+ */
+class LRUCache {
+  /**
+   * Create a new LRU Cache
+   * @param {Object} options
+   * @param {number} [options.maxSize=100] - Maximum number of entries
+   * @param {number} [options.ttlMs=30000] - Time to live in milliseconds (default 30s)
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || 100;
+    this.ttlMs = options.ttlMs || 30000;
+    this.cache = new Map();
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+    };
+  }
+
+  /**
+   * Get a value from cache
+   * @param {string} key - Cache key
+   * @returns {*} Cached value or undefined if not found/expired
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      this.stats.misses++;
+      return undefined;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      this.stats.misses++;
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    this.stats.hits++;
+    return entry.value;
+  }
+
+  /**
+   * Set a value in cache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @param {number} [ttlMs] - Optional custom TTL for this entry
+   */
+  set(key, value, ttlMs = this.ttlMs) {
+    // Remove existing entry if present
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Evict oldest entries if at capacity
+    while (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      this.cache.delete(oldestKey);
+      this.stats.evictions++;
+    }
+
+    // Add new entry
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs,
+      cachedAt: Date.now(),
+    });
+  }
+
+  /**
+   * Check if key exists and is not expired
+   * @param {string} key - Cache key
+   * @returns {boolean}
+   */
+  has(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Remove a key from cache
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key was removed
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {Object} Stats object
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hitRate: this.stats.hits + this.stats.misses > 0
+        ? (this.stats.hits / (this.stats.hits + this.stats.misses) * 100).toFixed(1) + '%'
+        : '0%',
+    };
+  }
+
+  /**
+   * Get number of entries in cache
+   * @returns {number}
+   */
+  get size() {
+    return this.cache.size;
+  }
+}
+
+// =============================================================================
+// File Cache Singleton
+// =============================================================================
+
+// Global cache instance (persists across requires in same process)
+const fileCache = new LRUCache({
+  maxSize: 50,
+  ttlMs: 30000, // 30 seconds
+});
+
+/**
+ * Read and cache a JSON file
+ * @param {string} filePath - Absolute path to JSON file
+ * @param {Object} [options]
+ * @param {boolean} [options.force=false] - Skip cache and force read
+ * @param {number} [options.ttlMs] - Custom TTL for this file
+ * @returns {Object|null} Parsed JSON or null if error
+ */
+function readJSONCached(filePath, options = {}) {
+  const { force = false, ttlMs } = options;
+  const cacheKey = `json:${filePath}`;
+
+  // Check cache first (unless force reload)
+  if (!force) {
+    const cached = fileCache.get(cacheKey);
+    if (cached !== undefined) {
+      return cached;
+    }
+  }
+
+  // Read from disk
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = JSON.parse(content);
+
+    // Cache the result
+    fileCache.set(cacheKey, data, ttlMs);
+
+    return data;
+  } catch (error) {
+    // Cache null to avoid repeated failed reads
+    fileCache.set(cacheKey, null, 5000); // 5s TTL for errors
+    return null;
+  }
+}
+
+/**
+ * Read and cache a text file
+ * @param {string} filePath - Absolute path to file
+ * @param {Object} [options]
+ * @param {boolean} [options.force=false] - Skip cache and force read
+ * @param {number} [options.ttlMs] - Custom TTL for this file
+ * @returns {string|null} File content or null if error
+ */
+function readFileCached(filePath, options = {}) {
+  const { force = false, ttlMs } = options;
+  const cacheKey = `file:${filePath}`;
+
+  // Check cache first (unless force reload)
+  if (!force) {
+    const cached = fileCache.get(cacheKey);
+    if (cached !== undefined) {
+      return cached;
+    }
+  }
+
+  // Read from disk
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Cache the result
+    fileCache.set(cacheKey, content, ttlMs);
+
+    return content;
+  } catch (error) {
+    // Cache null to avoid repeated failed reads
+    fileCache.set(cacheKey, null, 5000); // 5s TTL for errors
+    return null;
+  }
+}
+
+/**
+ * Invalidate cache for a specific file
+ * Call this after writing to a cached file
+ * @param {string} filePath - Absolute path to file
+ */
+function invalidate(filePath) {
+  fileCache.delete(`json:${filePath}`);
+  fileCache.delete(`file:${filePath}`);
+}
+
+/**
+ * Invalidate cache for all files in a directory
+ * @param {string} dirPath - Directory path
+ */
+function invalidateDir(dirPath) {
+  const normalizedDir = path.normalize(dirPath);
+  for (const key of fileCache.cache.keys()) {
+    const keyPath = key.replace(/^(json|file):/, '');
+    if (keyPath.startsWith(normalizedDir)) {
+      fileCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Clear entire cache
+ */
+function clearCache() {
+  fileCache.clear();
+}
+
+/**
+ * Get cache statistics
+ * @returns {Object} Cache stats
+ */
+function getCacheStats() {
+  return fileCache.getStats();
+}
+
+// =============================================================================
+// Convenience Methods for Common Files
+// =============================================================================
+
+/**
+ * Read status.json with caching
+ * @param {string} rootDir - Project root directory
+ * @param {Object} [options]
+ * @returns {Object|null}
+ */
+function readStatus(rootDir, options = {}) {
+  const filePath = path.join(rootDir, 'docs', '09-agents', 'status.json');
+  return readJSONCached(filePath, options);
+}
+
+/**
+ * Read session-state.json with caching
+ * @param {string} rootDir - Project root directory
+ * @param {Object} [options]
+ * @returns {Object|null}
+ */
+function readSessionState(rootDir, options = {}) {
+  const filePath = path.join(rootDir, 'docs', '09-agents', 'session-state.json');
+  return readJSONCached(filePath, options);
+}
+
+/**
+ * Read agileflow-metadata.json with caching
+ * @param {string} rootDir - Project root directory
+ * @param {Object} [options]
+ * @returns {Object|null}
+ */
+function readMetadata(rootDir, options = {}) {
+  const filePath = path.join(rootDir, 'docs', '00-meta', 'agileflow-metadata.json');
+  return readJSONCached(filePath, options);
+}
+
+/**
+ * Read registry.json with caching
+ * @param {string} rootDir - Project root directory
+ * @param {Object} [options]
+ * @returns {Object|null}
+ */
+function readRegistry(rootDir, options = {}) {
+  const filePath = path.join(rootDir, '.agileflow', 'sessions', 'registry.json');
+  return readJSONCached(filePath, options);
+}
+
+/**
+ * Batch read multiple common files
+ * More efficient than reading each individually
+ * @param {string} rootDir - Project root directory
+ * @param {Object} [options]
+ * @returns {Object} Object with status, sessionState, metadata, registry
+ */
+function readProjectFiles(rootDir, options = {}) {
+  return {
+    status: readStatus(rootDir, options),
+    sessionState: readSessionState(rootDir, options),
+    metadata: readMetadata(rootDir, options),
+    registry: readRegistry(rootDir, options),
+  };
+}
+
+module.exports = {
+  // Core LRU Cache class (for custom usage)
+  LRUCache,
+
+  // File reading with caching
+  readJSONCached,
+  readFileCached,
+
+  // Cache management
+  invalidate,
+  invalidateDir,
+  clearCache,
+  getCacheStats,
+
+  // Convenience methods for common files
+  readStatus,
+  readSessionState,
+  readMetadata,
+  readRegistry,
+  readProjectFiles,
+};

package/lib/progress.js

@@ -0,0 +1,331 @@
+/**
+ * progress.js - Progress Indicators for Long-Running Operations
+ *
+ * Provides animated spinners and micro-progress indicators that meet
+ * the Doherty Threshold (<400ms feels instant).
+ *
+ * Features:
+ * - Animated braille spinner
+ * - Micro-progress with current/total counts
+ * - TTY detection (no animation in non-TTY)
+ * - Minimal overhead for fast operations
+ */
+
+const { c } = require('./colors');
+
+// Braille spinner characters (smooth animation)
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+// Doherty Threshold - operations faster than this feel instant
+const DOHERTY_THRESHOLD_MS = 400;
+
+/**
+ * Progress spinner for long-running operations.
+ * Automatically handles TTY detection and cleanup.
+ */
+class Spinner {
+  /**
+   * Create a new spinner
+   * @param {string} message - Initial message to display
+   * @param {Object} [options={}] - Spinner options
+   * @param {number} [options.interval=80] - Animation interval in ms
+   * @param {boolean} [options.enabled=true] - Whether spinner is enabled
+   */
+  constructor(message, options = {}) {
+    this.message = message;
+    this.interval = options.interval || 80;
+    this.enabled = options.enabled !== false && process.stdout.isTTY;
+    this.frameIndex = 0;
+    this.timer = null;
+    this.startTime = null;
+    this.current = 0;
+    this.total = 0;
+  }
+
+  /**
+   * Start the spinner animation
+   * @returns {Spinner} this for chaining
+   */
+  start() {
+    if (!this.enabled) {
+      // In non-TTY, just print the message once
+      console.log(`${c.dim}${this.message}${c.reset}`);
+      return this;
+    }
+
+    this.startTime = Date.now();
+    this.render();
+    this.timer = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % SPINNER_FRAMES.length;
+      this.render();
+    }, this.interval);
+
+    return this;
+  }
+
+  /**
+   * Update the spinner message
+   * @param {string} message - New message
+   * @returns {Spinner} this for chaining
+   */
+  update(message) {
+    this.message = message;
+    if (this.enabled && this.timer) {
+      this.render();
+    }
+    return this;
+  }
+
+  /**
+   * Update micro-progress (current/total)
+   * @param {number} current - Current item number
+   * @param {number} total - Total items
+   * @param {string} [action] - Action being performed (e.g., 'Archiving')
+   * @returns {Spinner} this for chaining
+   */
+  progress(current, total, action = null) {
+    this.current = current;
+    this.total = total;
+    if (action) {
+      this.message = `${action}... ${current}/${total}`;
+    } else {
+      this.message = `${this.message.split('...')[0]}... ${current}/${total}`;
+    }
+    if (this.enabled && this.timer) {
+      this.render();
+    }
+    return this;
+  }
+
+  /**
+   * Render the current spinner frame
+   * @private
+   */
+  render() {
+    if (!this.enabled) return;
+
+    const frame = SPINNER_FRAMES[this.frameIndex];
+    const line = `${c.cyan}${frame}${c.reset} ${this.message}`;
+
+    // Clear line and write new content
+    process.stdout.clearLine(0);
+    process.stdout.cursorTo(0);
+    process.stdout.write(line);
+  }
+
+  /**
+   * Stop the spinner with a success message
+   * @param {string} [message] - Success message (defaults to original message)
+   * @returns {Spinner} this for chaining
+   */
+  succeed(message = null) {
+    return this.stop('✓', message || this.message, c.green);
+  }
+
+  /**
+   * Stop the spinner with a failure message
+   * @param {string} [message] - Failure message (defaults to original message)
+   * @returns {Spinner} this for chaining
+   */
+  fail(message = null) {
+    return this.stop('✗', message || this.message, c.red);
+  }
+
+  /**
+   * Stop the spinner with a warning message
+   * @param {string} [message] - Warning message (defaults to original message)
+   * @returns {Spinner} this for chaining
+   */
+  warn(message = null) {
+    return this.stop('⚠', message || this.message, c.yellow);
+  }
+
+  /**
+   * Stop the spinner with an info message
+   * @param {string} [message] - Info message (defaults to original message)
+   * @returns {Spinner} this for chaining
+   */
+  info(message = null) {
+    return this.stop('ℹ', message || this.message, c.blue);
+  }
+
+  /**
+   * Stop the spinner with a custom symbol
+   * @param {string} symbol - Symbol to display
+   * @param {string} message - Final message
+   * @param {string} [color=''] - ANSI color code
+   * @returns {Spinner} this for chaining
+   */
+  stop(symbol, message, color = '') {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+
+    if (this.enabled) {
+      process.stdout.clearLine(0);
+      process.stdout.cursorTo(0);
+    }
+
+    const elapsed = this.startTime ? Date.now() - this.startTime : 0;
+    const suffix = elapsed > DOHERTY_THRESHOLD_MS ? ` ${c.dim}(${formatDuration(elapsed)})${c.reset}` : '';
+
+    console.log(`${color}${symbol}${c.reset} ${message}${suffix}`);
+    return this;
+  }
+
+  /**
+   * Check if operation was fast (under Doherty Threshold)
+   * @returns {boolean}
+   */
+  wasFast() {
+    return this.startTime && (Date.now() - this.startTime) < DOHERTY_THRESHOLD_MS;
+  }
+}
+
+/**
+ * Format duration for display
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Formatted duration
+ */
+function formatDuration(ms) {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  const seconds = (ms / 1000).toFixed(1);
+  return `${seconds}s`;
+}
+
+/**
+ * Create and start a new spinner
+ * @param {string} message - Message to display
+ * @param {Object} [options={}] - Spinner options
+ * @returns {Spinner} Started spinner instance
+ */
+function createSpinner(message, options = {}) {
+  return new Spinner(message, options).start();
+}
+
+/**
+ * Run an async operation with a spinner
+ * @param {string} message - Message to display
+ * @param {Function} fn - Async function to execute
+ * @param {Object} [options={}] - Spinner options
+ * @returns {Promise<any>} Result of the async function
+ */
+async function withSpinner(message, fn, options = {}) {
+  const spinner = createSpinner(message, options);
+  try {
+    const result = await fn(spinner);
+    spinner.succeed();
+    return result;
+  } catch (error) {
+    spinner.fail(error.message);
+    throw error;
+  }
+}
+
+/**
+ * Progress bar for operations with known total
+ */
+class ProgressBar {
+  /**
+   * Create a new progress bar
+   * @param {string} label - Label to display
+   * @param {number} total - Total items
+   * @param {Object} [options={}] - Bar options
+   * @param {number} [options.width=30] - Bar width in characters
+   */
+  constructor(label, total, options = {}) {
+    this.label = label;
+    this.total = total;
+    this.current = 0;
+    this.width = options.width || 30;
+    this.enabled = process.stdout.isTTY;
+    this.startTime = Date.now();
+  }
+
+  /**
+   * Update progress
+   * @param {number} current - Current item number
+   * @param {string} [item] - Current item being processed
+   * @returns {ProgressBar} this for chaining
+   */
+  update(current, item = null) {
+    this.current = current;
+
+    if (!this.enabled) {
+      // Non-TTY: print every 10% or on completion
+      const percent = Math.floor((current / this.total) * 100);
+      if (percent % 10 === 0 || current === this.total) {
+        console.log(`${this.label}: ${percent}% (${current}/${this.total})`);
+      }
+      return this;
+    }
+
+    const percent = this.total > 0 ? (current / this.total) : 0;
+    const filled = Math.round(this.width * percent);
+    const empty = this.width - filled;
+
+    const bar = `${c.green}${'█'.repeat(filled)}${c.dim}${'░'.repeat(empty)}${c.reset}`;
+    const percentStr = `${Math.round(percent * 100)}%`.padStart(4);
+    const countStr = `${current}/${this.total}`;
+    const itemStr = item ? ` ${c.dim}${item}${c.reset}` : '';
+
+    process.stdout.clearLine(0);
+    process.stdout.cursorTo(0);
+    process.stdout.write(`${this.label} ${bar} ${percentStr} (${countStr})${itemStr}`);
+
+    return this;
+  }
+
+  /**
+   * Increment progress by 1
+   * @param {string} [item] - Current item being processed
+   * @returns {ProgressBar} this for chaining
+   */
+  increment(item = null) {
+    return this.update(this.current + 1, item);
+  }
+
+  /**
+   * Complete the progress bar
+   * @param {string} [message] - Completion message
+   * @returns {ProgressBar} this for chaining
+   */
+  complete(message = null) {
+    if (this.enabled) {
+      process.stdout.clearLine(0);
+      process.stdout.cursorTo(0);
+    }
+
+    const elapsed = Date.now() - this.startTime;
+    const suffix = elapsed > DOHERTY_THRESHOLD_MS ? ` ${c.dim}(${formatDuration(elapsed)})${c.reset}` : '';
+    const msg = message || `${this.label} complete`;
+
+    console.log(`${c.green}✓${c.reset} ${msg} (${this.total} items)${suffix}`);
+    return this;
+  }
+}
+
+/**
+ * Create a progress bar
+ * @param {string} label - Label to display
+ * @param {number} total - Total items
+ * @param {Object} [options={}] - Bar options
+ * @returns {ProgressBar}
+ */
+function createProgressBar(label, total, options = {}) {
+  return new ProgressBar(label, total, options);
+}
+
+module.exports = {
+  Spinner,
+  ProgressBar,
+  createSpinner,
+  createProgressBar,
+  withSpinner,
+  formatDuration,
+  DOHERTY_THRESHOLD_MS,
+  SPINNER_FRAMES,
+};