agileflow 2.90.7 → 2.92.0

package/lib/correlation.js

@@ -0,0 +1,277 @@
+/**
+ * AgileFlow CLI - Correlation ID Management
+ *
+ * Generates and propagates trace IDs and session IDs for event correlation.
+ * Enables filtering and tracing events across complex workflows.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// Global context for correlation IDs
+let currentContext = {
+  traceId: null,
+  sessionId: null,
+  spanId: null,
+  parentSpanId: null,
+};
+
+/**
+ * Generate a unique trace ID (16 hex chars, like OpenTelemetry standard)
+ * @returns {string} Unique trace ID
+ */
+function generateTraceId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * Generate a span ID (8 hex chars)
+ * @returns {string} Unique span ID
+ */
+function generateSpanId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+/**
+ * Generate a session ID based on timestamp and random component
+ * Format: session_YYYYMMDD_HHMMSS_XXXX
+ * @returns {string} Session ID
+ */
+function generateSessionId() {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
+  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
+  const random = crypto.randomBytes(2).toString('hex');
+  return `session_${date}_${time}_${random}`;
+}
+
+/**
+ * Get current correlation context
+ * @returns {{ traceId: string | null, sessionId: string | null, spanId: string | null }}
+ */
+function getContext() {
+  return { ...currentContext };
+}
+
+/**
+ * Set correlation context
+ * @param {Object} context
+ * @param {string} [context.traceId] - Trace ID
+ * @param {string} [context.sessionId] - Session ID
+ * @param {string} [context.spanId] - Span ID
+ * @param {string} [context.parentSpanId] - Parent span ID
+ */
+function setContext(context) {
+  if (context.traceId !== undefined) currentContext.traceId = context.traceId;
+  if (context.sessionId !== undefined) currentContext.sessionId = context.sessionId;
+  if (context.spanId !== undefined) currentContext.spanId = context.spanId;
+  if (context.parentSpanId !== undefined) currentContext.parentSpanId = context.parentSpanId;
+}
+
+/**
+ * Start a new trace (generates new trace_id)
+ * @param {Object} [options]
+ * @param {string} [options.sessionId] - Existing session ID to use
+ * @returns {{ traceId: string, sessionId: string, spanId: string }}
+ */
+function startTrace(options = {}) {
+  const traceId = generateTraceId();
+  const sessionId = options.sessionId || currentContext.sessionId || generateSessionId();
+  const spanId = generateSpanId();
+
+  setContext({
+    traceId,
+    sessionId,
+    spanId,
+    parentSpanId: null,
+  });
+
+  return { traceId, sessionId, spanId };
+}
+
+/**
+ * Start a new span within current trace
+ * @returns {{ traceId: string, sessionId: string, spanId: string, parentSpanId: string | null }}
+ */
+function startSpan() {
+  const parentSpanId = currentContext.spanId;
+  const spanId = generateSpanId();
+
+  setContext({
+    spanId,
+    parentSpanId,
+  });
+
+  return {
+    traceId: currentContext.traceId,
+    sessionId: currentContext.sessionId,
+    spanId,
+    parentSpanId,
+  };
+}
+
+/**
+ * Inject correlation IDs into an event object
+ * @param {Object} event - Event to inject into
+ * @returns {Object} Event with correlation IDs
+ */
+function injectCorrelation(event) {
+  const ctx = getContext();
+  return {
+    ...event,
+    ...(ctx.traceId && { trace_id: ctx.traceId }),
+    ...(ctx.sessionId && { session_id: ctx.sessionId }),
+    ...(ctx.spanId && { span_id: ctx.spanId }),
+    ...(ctx.parentSpanId && { parent_span_id: ctx.parentSpanId }),
+  };
+}
+
+/**
+ * Clear correlation context (for testing or new sessions)
+ */
+function clearContext() {
+  currentContext = {
+    traceId: null,
+    sessionId: null,
+    spanId: null,
+    parentSpanId: null,
+  };
+}
+
+/**
+ * Load session ID from session-state.json if available
+ * @param {string} projectDir - Project directory
+ * @returns {string | null} Session ID or null
+ */
+function loadSessionId(projectDir) {
+  try {
+    const sessionStatePath = path.join(projectDir, 'docs', '09-agents', 'session-state.json');
+    if (fs.existsSync(sessionStatePath)) {
+      const data = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+      return data.session_id || null;
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}
+
+/**
+ * Save session ID to session-state.json
+ * @param {string} projectDir - Project directory
+ * @param {string} sessionId - Session ID to save
+ */
+function saveSessionId(projectDir, sessionId) {
+  try {
+    const sessionStatePath = path.join(projectDir, 'docs', '09-agents', 'session-state.json');
+    let data = {};
+
+    if (fs.existsSync(sessionStatePath)) {
+      data = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+    }
+
+    data.session_id = sessionId;
+    data.updated_at = new Date().toISOString();
+
+    const dir = path.dirname(sessionStatePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(sessionStatePath, JSON.stringify(data, null, 2) + '\n');
+  } catch {
+    // Ignore errors - session ID is not critical
+  }
+}
+
+/**
+ * Initialize correlation context for a project
+ * Loads existing session ID or creates new one
+ * @param {string} projectDir - Project directory
+ * @param {Object} [options]
+ * @param {boolean} [options.newTrace=true] - Start new trace
+ * @returns {{ traceId: string, sessionId: string }}
+ */
+function initializeForProject(projectDir, options = {}) {
+  const { newTrace = true } = options;
+
+  // Load or create session ID
+  let sessionId = loadSessionId(projectDir);
+  if (!sessionId) {
+    sessionId = generateSessionId();
+    saveSessionId(projectDir, sessionId);
+  }
+
+  setContext({ sessionId });
+
+  if (newTrace) {
+    const trace = startTrace({ sessionId });
+    return { traceId: trace.traceId, sessionId };
+  }
+
+  return {
+    traceId: currentContext.traceId || generateTraceId(),
+    sessionId,
+  };
+}
+
+/**
+ * Extract correlation IDs from an event
+ * @param {Object} event - Event object
+ * @returns {{ traceId: string | null, sessionId: string | null, spanId: string | null }}
+ */
+function extractCorrelation(event) {
+  return {
+    traceId: event.trace_id || null,
+    sessionId: event.session_id || null,
+    spanId: event.span_id || null,
+  };
+}
+
+/**
+ * Filter events by trace ID
+ * @param {Array} events - Array of events
+ * @param {string} traceId - Trace ID to filter by
+ * @returns {Array} Filtered events
+ */
+function filterByTraceId(events, traceId) {
+  return events.filter(e => e.trace_id === traceId);
+}
+
+/**
+ * Filter events by session ID
+ * @param {Array} events - Array of events
+ * @param {string} sessionId - Session ID to filter by
+ * @returns {Array} Filtered events
+ */
+function filterBySessionId(events, sessionId) {
+  return events.filter(e => e.session_id === sessionId);
+}
+
+module.exports = {
+  // ID generation
+  generateTraceId,
+  generateSpanId,
+  generateSessionId,
+
+  // Context management
+  getContext,
+  setContext,
+  clearContext,
+  startTrace,
+  startSpan,
+
+  // Event injection/extraction
+  injectCorrelation,
+  extractCorrelation,
+
+  // Project integration
+  initializeForProject,
+  loadSessionId,
+  saveSessionId,
+
+  // Filtering
+  filterByTraceId,
+  filterBySessionId,
+};

package/lib/error-codes.js

@@ -524,6 +524,48 @@ function formatError(error, options = {}) {
   return lines.join('\n');
 }
 
+/**
+ * Create an error result with standardized metadata
+ * This factory produces Result objects compatible with result-schema.js
+ * @param {string} errorCode - Error code (e.g., 'ENOENT', 'ECONFIG')
+ * @param {string} [message] - Optional custom error message
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.context] - Additional context about the error
+ * @param {Error} [options.cause] - Original error that caused this failure
+ * @returns {{ ok: false, error: string, errorCode: string, severity: string, category: string, recoverable: boolean, suggestedFix: string, autoFix: string|null, context?: Object, cause?: Error }}
+ */
+function createErrorResult(errorCode, message, options = {}) {
+  const codeData = ErrorCodes[errorCode] || ErrorCodes.EUNKNOWN;
+
+  return {
+    ok: false,
+    error: message || codeData.message,
+    errorCode: codeData.code,
+    severity: codeData.severity,
+    category: codeData.category,
+    recoverable: codeData.recoverable,
+    suggestedFix: codeData.suggestedFix,
+    autoFix: codeData.autoFix || null,
+    context: options.context,
+    cause: options.cause,
+  };
+}
+
+/**
+ * Create a success result
+ * @template T
+ * @param {T} data - The success data
+ * @param {Object} [meta] - Optional metadata
+ * @returns {{ ok: true, data: T }}
+ */
+function createSuccessResult(data, meta = {}) {
+  return {
+    ok: true,
+    data,
+    ...meta,
+  };
+}
+
 module.exports = {
   // Enums
   Severity,
@@ -541,4 +583,8 @@ module.exports = {
   getSuggestedFix,
   getAutoFix,
   formatError,
+
+  // Result factories (for result-schema.js compatibility)
+  createErrorResult,
+  createSuccessResult,
 };

package/lib/errors.js

@@ -236,10 +236,13 @@ function getCharName(char) {
  * @param {string} filePath - Absolute path to JSON file
  * @param {object} options - Optional settings
  * @param {*} options.defaultValue - Value to return if file doesn't exist (makes missing file not an error)
- * @returns {{ ok: boolean, data?: any, error?: string }}
+ * @param {boolean} options.hidePathInError - Hide file path in error messages (security: default false)
+ * @param {string} options.context - Context for error messages (alternative to exposing path)
+ * @returns {{ ok: boolean, data?: any, error?: string, errorCode?: string }}
  */
 function safeReadJSON(filePath, options = {}) {
-  const { defaultValue } = options;
+  const { defaultValue, hidePathInError = false, context } = options;
+  const pathDisplay = hidePathInError ? context || 'configuration file' : filePath;
 
   try {
     if (!fs.existsSync(filePath)) {
@@ -247,19 +250,58 @@ function safeReadJSON(filePath, options = {}) {
         debugLog('safeReadJSON', { filePath, status: 'missing, using default' });
         return { ok: true, data: defaultValue };
       }
-      const error = `File not found: ${filePath}`;
+      const error = `File not found: ${pathDisplay}`;
       debugLog('safeReadJSON', { filePath, error });
-      return { ok: false, error };
+      return { ok: false, error, errorCode: 'ENOENT' };
     }
 
     const content = fs.readFileSync(filePath, 'utf8');
+
+    // Handle empty files gracefully
+    if (!content.trim()) {
+      if (defaultValue !== undefined) {
+        debugLog('safeReadJSON', { filePath, status: 'empty, using default' });
+        return { ok: true, data: defaultValue };
+      }
+      const error = `File is empty: ${pathDisplay}`;
+      debugLog('safeReadJSON', { filePath, error: 'empty file' });
+      return { ok: false, error, errorCode: 'EPARSE' };
+    }
+
     const data = JSON.parse(content);
     debugLog('safeReadJSON', { filePath, status: 'success' });
     return { ok: true, data };
   } catch (err) {
-    const error = `Failed to read JSON from ${filePath}: ${err.message}`;
+    // Detect specific JSON parse errors
+    let errorCode = 'EPARSE';
+    let errorMessage = `Failed to parse JSON`;
+
+    if (err.code === 'EACCES' || err.code === 'EPERM') {
+      errorCode = 'EACCES';
+      errorMessage = `Permission denied reading file`;
+    } else if (err.message && err.message.includes('Unexpected')) {
+      // JSON syntax error - don't expose full content
+      errorMessage = `Invalid JSON syntax`;
+      if (err.message.includes('position')) {
+        // Extract position info but not content
+        const posMatch = err.message.match(/position (\d+)/);
+        if (posMatch) {
+          errorMessage = `Invalid JSON syntax near position ${posMatch[1]}`;
+        }
+      }
+    } else if (err.message && err.message.includes('token')) {
+      errorMessage = `Invalid JSON: unexpected token`;
+    }
+
+    // Add context if not hiding path
+    if (!hidePathInError) {
+      errorMessage = `${errorMessage} in ${pathDisplay}`;
+    } else if (context) {
+      errorMessage = `${errorMessage} in ${context}`;
+    }
+
     debugLog('safeReadJSON', { filePath, error: err.message });
-    return { ok: false, error };
+    return { ok: false, error: errorMessage, errorCode };
   }
 }
 

package/lib/file-cache.js

@@ -336,6 +336,180 @@ function readProjectFiles(rootDir, options = {}) {
   };
 }
 
+// =============================================================================
+// Command Caching (for git and other shell commands)
+// =============================================================================
+
+const { execSync } = require('child_process');
+
+// Separate cache for command output with shorter TTL
+const commandCache = new LRUCache({
+  maxSize: 50,
+  ttlMs: 30000, // 30 seconds default
+});
+
+/**
+ * Execute and cache a shell command
+ * @param {string} command - Shell command to execute
+ * @param {Object} [options]
+ * @param {string} [options.cwd] - Working directory
+ * @param {boolean} [options.force=false] - Skip cache and force execution
+ * @param {number} [options.ttlMs] - Custom TTL for this command
+ * @param {string} [options.cacheKey] - Custom cache key (default: auto-generated)
+ * @returns {{ ok: boolean, data?: string, error?: string, cached?: boolean }}
+ */
+function execCached(command, options = {}) {
+  const { cwd = process.cwd(), force = false, ttlMs, cacheKey } = options;
+  const key = cacheKey || `cmd:${command}:${cwd}`;
+
+  // Check cache first (unless force)
+  if (!force) {
+    const cached = commandCache.get(key);
+    if (cached !== undefined) {
+      return { ok: true, data: cached, cached: true };
+    }
+  }
+
+  // Execute command
+  try {
+    const output = execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 10000, // 10 second timeout
+    }).trim();
+
+    // Cache the result
+    commandCache.set(key, output, ttlMs);
+
+    return { ok: true, data: output, cached: false };
+  } catch (error) {
+    // Cache errors briefly to avoid repeated failures
+    const errMsg = error.message || 'Command failed';
+    return { ok: false, error: errMsg, cached: false };
+  }
+}
+
+/**
+ * Execute and cache a git command
+ * Helper with git-specific cache key format
+ * @param {string} gitCommand - Git subcommand (e.g., 'status --short')
+ * @param {Object} [options]
+ * @param {string} [options.cwd] - Working directory
+ * @param {boolean} [options.force=false] - Skip cache
+ * @param {number} [options.ttlMs=30000] - TTL (default 30s)
+ * @returns {{ ok: boolean, data?: string, error?: string, cached?: boolean }}
+ */
+function gitCached(gitCommand, options = {}) {
+  const { cwd = process.cwd(), ttlMs = 30000, force = false } = options;
+  const command = `git ${gitCommand}`;
+  const cacheKey = `git:${gitCommand}:${cwd}`;
+
+  return execCached(command, {
+    cwd,
+    force,
+    ttlMs,
+    cacheKey,
+  });
+}
+
+/**
+ * Common git commands with caching
+ */
+const gitCommands = {
+  /**
+   * Get current branch name (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  branch(cwd, options = {}) {
+    return gitCached('branch --show-current', { cwd, ...options });
+  },
+
+  /**
+   * Get short status (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  status(cwd, options = {}) {
+    return gitCached('status --short', { cwd, ...options });
+  },
+
+  /**
+   * Get recent commits (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @param {number} [options.count=5] - Number of commits
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  log(cwd, options = {}) {
+    const { count = 5, ...rest } = options;
+    return gitCached(`log -${count} --oneline`, { cwd, ...rest });
+  },
+
+  /**
+   * Get diff summary (cached with shorter TTL)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  diff(cwd, options = {}) {
+    return gitCached('diff --stat', { cwd, ttlMs: 15000, ...options });
+  },
+
+  /**
+   * Get last commit short hash (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  commitHash(cwd, options = {}) {
+    return gitCached('log -1 --format="%h"', { cwd, ...options });
+  },
+
+  /**
+   * Get last commit message (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  commitMessage(cwd, options = {}) {
+    return gitCached('log -1 --format="%s"', { cwd, ...options });
+  },
+};
+
+/**
+ * Invalidate all git caches for a directory
+ * Call this after git operations that modify state
+ * @param {string} [cwd] - Working directory
+ */
+function invalidateGitCache(cwd = process.cwd()) {
+  const prefix = `git:`;
+  const suffix = `:${cwd}`;
+  for (const key of commandCache.cache.keys()) {
+    if (key.startsWith(prefix) && key.endsWith(suffix)) {
+      commandCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get command cache statistics
+ * @returns {Object} Cache stats
+ */
+function getCommandCacheStats() {
+  return commandCache.getStats();
+}
+
+/**
+ * Clear command cache
+ */
+function clearCommandCache() {
+  commandCache.clear();
+}
+
 module.exports = {
   // Core LRU Cache class (for custom usage)
   LRUCache,
@@ -356,4 +530,12 @@ module.exports = {
   readMetadata,
   readRegistry,
   readProjectFiles,
+
+  // Command caching
+  execCached,
+  gitCached,
+  gitCommands,
+  invalidateGitCache,
+  getCommandCacheStats,
+  clearCommandCache,
 };