@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/business-flow-mapper.cjs

@@ -0,0 +1,429 @@
+/**
+ * Business Flow Mapper — Analyzes user journeys, data flow, and integration points
+ *
+ * Provides:
+ * - map(rootPath, stack): Identifies user journeys from route/file structure
+ * - analyzeDataFlow(rootPath): Traces data flow through imports and function calls
+ * - findIntegrationPoints(stack): Identifies external API integrations from dependencies
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class BusinessFlowMapper {
+  constructor(rootPath) {
+    this.rootPath = rootPath;
+  }
+
+  /**
+   * Map business flows from codebase structure
+   * @param {string} rootPath - Root directory to analyze
+   * @param {object} stack - Stack object from StackDetector
+   * @returns {object} Object with journeys and entryPoints
+   */
+  map(rootPath = this.rootPath, stack = {}) {
+    const routes = this._findRoutes(rootPath);
+    const journeys = this._extractJourneys(routes, stack);
+    const entryPoints = this._findEntryPoints(rootPath);
+
+    return {
+      journeys,
+      entryPoints,
+      routes
+    };
+  }
+
+  /**
+   * Analyze data flow through the codebase
+   * @param {string} rootPath - Root directory to analyze
+   * @returns {object} Object with flows and dataStores
+   */
+  analyzeDataFlow(rootPath = this.rootPath) {
+    const sourceFiles = this._getSourceFiles(rootPath);
+    const flows = this._traceDataFlow(sourceFiles, rootPath);
+    const dataStores = this._findDataStores(sourceFiles, rootPath);
+
+    return {
+      flows,
+      dataStores
+    };
+  }
+
+  /**
+   * Find integration points from stack dependencies
+   * @param {object} stack - Stack object from StackDetector
+   * @returns {object} Object with integrations array
+   */
+  findIntegrationPoints(stack = {}) {
+    const integrations = [];
+    const frameworks = stack.frameworks || [];
+    const infrastructure = stack.infrastructure || [];
+    const databases = stack.databases || [];
+
+    // Payment integrations
+    if (frameworks.includes('Stripe') || infrastructure.some(i => i.includes('Stripe'))) {
+      integrations.push({
+        name: 'Stripe',
+        type: 'payment',
+        purpose: 'Payment processing and subscriptions'
+      });
+    }
+
+    // Cloud integrations
+    if (infrastructure.some(i => i.includes('AWS'))) {
+      integrations.push({
+        name: 'AWS',
+        type: 'cloud',
+        purpose: 'Cloud infrastructure and services'
+      });
+    }
+    if (infrastructure.some(i => i.includes('Azure'))) {
+      integrations.push({
+        name: 'Azure',
+        type: 'cloud',
+        purpose: 'Cloud infrastructure and services'
+      });
+    }
+    if (infrastructure.some(i => i.includes('Google Cloud'))) {
+      integrations.push({
+        name: 'Google Cloud',
+        type: 'cloud',
+        purpose: 'Cloud infrastructure and services'
+      });
+    }
+
+    // Monitoring integrations
+    if (infrastructure.some(i => i.includes('Sentry'))) {
+      integrations.push({
+        name: 'Sentry',
+        type: 'monitoring',
+        purpose: 'Error tracking and monitoring'
+      });
+    }
+    if (infrastructure.some(i => i.includes('Datadog'))) {
+      integrations.push({
+        name: 'Datadog',
+        type: 'monitoring',
+        purpose: 'Infrastructure and application monitoring'
+      });
+    }
+
+    // Email integrations
+    if (infrastructure.some(i => i.includes('SendGrid') || i.includes('Mailgun'))) {
+      integrations.push({
+        name: 'Email Service',
+        type: 'communication',
+        purpose: 'Transactional email delivery'
+      });
+    }
+
+    // Database integrations
+    for (const db of databases) {
+      integrations.push({
+        name: db,
+        type: 'database',
+        purpose: 'Data persistence'
+      });
+    }
+
+    // Auth integrations
+    if (frameworks.includes('NextAuth.js') || frameworks.includes('Auth.js')) {
+      integrations.push({
+        name: 'NextAuth.js',
+        type: 'authentication',
+        purpose: 'User authentication and authorization'
+      });
+    }
+
+    return {
+      integrations
+    };
+  }
+
+  /**
+   * Find route files in the codebase
+   * @private
+   */
+  _findRoutes(rootPath) {
+    const routes = [];
+    const routePatterns = [
+      'src/pages',
+      'src/app',
+      'src/routes',
+      'pages',
+      'app',
+      'routes',
+      'src/controllers',
+      'controllers'
+    ];
+
+    for (const pattern of routePatterns) {
+      const routeDir = path.join(rootPath, pattern);
+      if (fs.existsSync(routeDir)) {
+        this._collectRoutes(routeDir, routes, pattern);
+      }
+    }
+
+    return routes;
+  }
+
+  /**
+   * Collect routes from directory
+   * @private
+   */
+  _collectRoutes(dir, routes, basePath, depth = 0) {
+    if (depth > 5) return;
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          this._collectRoutes(fullPath, routes, basePath, depth + 1);
+        } else if (entry.isFile() && /\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+          const relativePath = path.relative(path.join(this.rootPath, basePath), fullPath);
+          const routePath = this._fileToRoute(relativePath);
+          routes.push({
+            path: routePath,
+            file: fullPath,
+            name: path.basename(entry.name, path.extname(entry.name))
+          });
+        }
+      }
+    } catch (err) {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Convert file path to route path
+   * @private
+   */
+  _fileToRoute(filePath) {
+    let route = filePath
+      .replace(/^(page|route|layout)\./, '')
+      .replace(/\.tsx?$/, '')
+      .replace(/\.jsx?$/, '')
+      .replace(/\\/g, '/')
+      .replace(/\/index$/, '')
+      .replace(/\[(\w+)\]/g, ':$1');
+
+    return '/' + route;
+  }
+
+  /**
+   * Extract user journeys from routes
+   * @private
+   */
+  _extractJourneys(routes, stack) {
+    const journeys = [];
+
+    // Group routes by prefix to identify journeys
+    const routeGroups = {};
+    for (const route of routes) {
+      const parts = route.path.split('/').filter(p => p && !p.startsWith(':'));
+      if (parts.length > 0) {
+        const prefix = parts[0];
+        if (!routeGroups[prefix]) {
+          routeGroups[prefix] = [];
+        }
+        routeGroups[prefix].push(route);
+      }
+    }
+
+    // Create journeys from route groups
+    for (const [prefix, groupRoutes] of Object.entries(routeGroups)) {
+      const journey = {
+        name: this._capitalize(prefix),
+        path: `/${prefix}`,
+        components: groupRoutes.map(r => r.name),
+        routes: groupRoutes.map(r => r.path)
+      };
+
+      // Enhance with stack-specific info
+      if (stack.frameworks?.includes('Next.js')) {
+        journey.framework = 'Next.js Pages/App Router';
+      } else if (stack.frameworks?.includes('React')) {
+        journey.framework = 'React Router';
+      }
+
+      journeys.push(journey);
+    }
+
+    return journeys;
+  }
+
+  /**
+   * Find entry points in the codebase
+   * @private
+   */
+  _findEntryPoints(rootPath) {
+    const entryPoints = [];
+    const entryPatterns = [
+      'src/index.ts',
+      'src/index.tsx',
+      'src/index.js',
+      'src/main.ts',
+      'src/main.tsx',
+      'src/app.tsx',
+      'src/app.ts',
+      'index.ts',
+      'index.tsx',
+      'index.js',
+      'main.ts',
+      'app.tsx'
+    ];
+
+    for (const pattern of entryPatterns) {
+      const entryPath = path.join(rootPath, pattern);
+      if (fs.existsSync(entryPath)) {
+        entryPoints.push(entryPath);
+      }
+    }
+
+    return entryPoints;
+  }
+
+  /**
+   * Trace data flow through source files
+   * @private
+   */
+  _traceDataFlow(sourceFiles, rootPath) {
+    const flows = [];
+
+    for (const file of sourceFiles.slice(0, 50)) { // Limit to 50 files
+      try {
+        const content = fs.readFileSync(file, 'utf8');
+
+        // Look for data flow patterns
+        const importMatches = content.match(/import\s+.*?\s+from\s+['"](.+?)['"]/g) || [];
+        const exportMatches = content.match(/export\s+(default\s+)?(function|class|const|let|var)/g) || [];
+
+        if (importMatches.length > 0 || exportMatches.length > 0) {
+          flows.push({
+            file,
+            imports: importMatches.length,
+            exports: exportMatches.length,
+            transformations: this._detectTransformations(content)
+          });
+        }
+      } catch (err) {
+        // Ignore read errors
+      }
+    }
+
+    return flows;
+  }
+
+  /**
+   * Detect data transformations in code
+   * @private
+   */
+  _detectTransformations(content) {
+    const transformations = [];
+
+    // Look for common transformation patterns
+    const patterns = {
+      map: /\.map\(/,
+      filter: /\.filter\(/,
+      reduce: /\.reduce\(/,
+      transform: /\.transform\(/,
+      parse: /\.parse\(|JSON\.parse/,
+      stringify: /\.stringify\(|JSON\.stringify/
+    };
+
+    for (const [name, regex] of Object.entries(patterns)) {
+      if (regex.test(content)) {
+        transformations.push(name);
+      }
+    }
+
+    return transformations;
+  }
+
+  /**
+   * Find data stores in the codebase
+   * @private
+   */
+  _findDataStores(sourceFiles, rootPath) {
+    const dataStores = [];
+
+    // Look for store patterns
+    const storePatterns = [
+      'src/stores',
+      'src/store',
+      'stores',
+      'store',
+      'src/models',
+      'models',
+      'src/db',
+      'db',
+      'src/database',
+      'database'
+    ];
+
+    for (const pattern of storePatterns) {
+      const storePath = path.join(rootPath, pattern);
+      if (fs.existsSync(storePath)) {
+        dataStores.push({
+          type: 'store',
+          path: storePath,
+          name: pattern.split('/').pop()
+        });
+      }
+    }
+
+    return dataStores;
+  }
+
+  /**
+   * Get source files from directory
+   * @private
+   */
+  _getSourceFiles(rootPath) {
+    const files = [];
+    const srcDir = path.join(rootPath, 'src');
+
+    if (fs.existsSync(srcDir)) {
+      this._collectSourceFiles(srcDir, files);
+    } else {
+      this._collectSourceFiles(rootPath, files);
+    }
+
+    return files;
+  }
+
+  /**
+   * Collect source files from directory
+   * @private
+   */
+  _collectSourceFiles(dir, files, depth = 0) {
+    if (depth > 5 || dir.includes('node_modules') || dir.includes('dist') || dir.includes('build')) {
+      return;
+    }
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          this._collectSourceFiles(fullPath, files, depth + 1);
+        } else if (entry.isFile() && /\.(ts|tsx|js|jsx)$/.test(entry.name)) {
+          files.push(fullPath);
+        }
+      }
+    } catch (err) {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Capitalize first letter
+   * @private
+   */
+  _capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}
+
+module.exports = { BusinessFlowMapper };

package/bin/lib/circuit-breaker.cjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Circuit Breaker — Prevent cascading failures
+ *
+ * Implements circuit breaker pattern:
+ * - CLOSED: Normal operation
+ * - OPEN: Failing, reject requests
+ * - HALF_OPEN: Testing if service recovered
+ *
+ * Persists state to .planning/circuit-breaker.json for recovery across restarts
+ *
+ * Usage:
+ *   const CircuitBreaker = require('./circuit-breaker.cjs');
+ *   const breaker = new CircuitBreaker({ failureThreshold: 5, cwd });
+ *   const result = await breaker.execute(() => riskyOperation());
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { withLock } = require('./file-lock.cjs');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+class CircuitBreaker {
+  /**
+   * Create circuit breaker
+   * @param {Object} options - Configuration
+   * @param {number} [options.failureThreshold=5] - Number of failures before opening circuit
+   * @param {number} [options.resetTimeout=60000] - Time in ms before trying to recover
+   * @param {boolean} [options.persistState=true] - Whether to persist state to disk
+   * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
+   * @param {string} [options.agentType] - Agent type identifier for per-agent state
+   */
+  constructor(options = {}) {
+    this.failureThreshold = options.failureThreshold || 5;
+    this.resetTimeout = options.resetTimeout || 60000;
+    this.persistState = options.persistState !== false;
+    this.cwd = options.cwd || process.cwd();
+    this.agentType = options.agentType || 'default';
+    this.state = 'CLOSED';
+    this.failures = 0;
+    this.lastFailureTime = null;
+    this.successes = 0;
+    this.lastStateChange = new Date().toISOString();
+
+    // Load persisted state if available
+    if (this.persistState) {
+      this.loadState();
+    }
+  }
+
+  /**
+   * Get state file path
+   * @returns {string} - Path to circuit-breaker.json
+   */
+  getStateFile() {
+    return path.join(this.cwd, '.planning', 'circuit-breaker.json');
+  }
+
+  /**
+   * Load state from disk
+   * @returns {void}
+   */
+  loadState() {
+    const stateFile = this.getStateFile();
+    if (!fs.existsSync(stateFile)) {
+      return;
+    }
+
+    try {
+      const data = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      const agentState = data[this.agentType];
+
+      if (agentState) {
+        this.state = agentState.state || 'CLOSED';
+        this.failures = agentState.failures || 0;
+        this.successes = agentState.successes || 0;
+        this.lastFailureTime = agentState.lastFailureTime || null;
+        this.lastStateChange = agentState.lastStateChange || new Date().toISOString();
+      }
+    } catch (err) {
+      logger.warn('circuit-breaker: failed to load state', { error: err.message });
+    }
+  }
+
+  /**
+   * Save state to disk
+   * @returns {Promise<void>}
+   */
+  async saveState() {
+    if (!this.persistState) {
+      return;
+    }
+
+    const stateFile = this.getStateFile();
+    const planningDir = path.join(this.cwd, '.planning');
+
+    // Ensure .planning directory exists
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    await withLock(stateFile, async () => {
+      let data = {};
+      if (fs.existsSync(stateFile)) {
+        try {
+          data = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+        } catch (e) {
+          data = {};
+        }
+      }
+
+      data[this.agentType] = {
+        state: this.state,
+        failures: this.failures,
+        successes: this.successes,
+        failureThreshold: this.failureThreshold,
+        resetTimeout: this.resetTimeout,
+        lastFailureTime: this.lastFailureTime,
+        lastStateChange: this.lastStateChange
+      };
+
+      fs.writeFileSync(stateFile, JSON.stringify(data, null, 2), 'utf8');
+    });
+  }
+
+  /**
+   * Log state transition to metrics
+   * @param {string} fromState - Previous state
+   * @param {string} toState - New state
+   * @private
+   */
+  _logStateTransition(fromState, toState) {
+    const metricsPath = path.join(this.cwd, '.planning', 'metrics.json');
+    const event = {
+      event: 'circuit_breaker_state_change',
+      timestamp: new Date().toISOString(),
+      agentType: this.agentType,
+      fromState,
+      toState
+    };
+
+    try {
+      let metrics = { events: [] };
+      if (fs.existsSync(metricsPath)) {
+        try {
+          metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+          if (!Array.isArray(metrics.events)) metrics.events = [];
+        } catch (e) {
+          metrics = { events: [] };
+        }
+      }
+
+      metrics.events.push(event);
+      fs.writeFileSync(metricsPath, JSON.stringify(metrics, null, 2), 'utf8');
+    } catch (err) {
+      logger.error('circuit-breaker: failed to log state transition', { error: err.message });
+    }
+  }
+
+  /**
+   * Change state and persist
+   * @param {string} newState - New state
+   * @private
+   */
+  async _changeState(newState) {
+    if (this.state === newState) {
+      return;
+    }
+
+    const oldState = this.state;
+    this.state = newState;
+    this.lastStateChange = new Date().toISOString();
+
+    this._logStateTransition(oldState, newState);
+    await this.saveState();
+  }
+
+  /**
+   * Execute operation with circuit breaker protection
+   * @param {Function} operation - Async function to execute
+   * @returns {Promise<any>} - Result of operation
+   */
+  async execute(operation) {
+    // Check if circuit is OPEN
+    if (this.state === 'OPEN') {
+      const timeSinceFailure = Date.now() - this.lastFailureTime;
+
+      if (timeSinceFailure > this.resetTimeout) {
+        // Try to recover
+        await this._changeState('HALF_OPEN');
+        this.failures = 0;
+        logger.info('Circuit breaker HALF_OPEN - testing recovery');
+      } else {
+        const waitTime = Math.round((this.resetTimeout - timeSinceFailure) / 1000);
+        logger.warn('Circuit breaker OPEN - rejecting request', { waitTime });
+        throw new Error(`Circuit breaker is OPEN. Try again in ${waitTime}s`);
+      }
+    }
+
+    try {
+      const result = await operation();
+
+      // Success - reset counters if in HALF_OPEN
+      if (this.state === 'HALF_OPEN') {
+        await this._changeState('CLOSED');
+        this.failures = 0;
+        logger.info('Circuit breaker CLOSED - service recovered');
+      }
+
+      this.successes++;
+      await this.saveState();
+      return result;
+    } catch (err) {
+      this.failures++;
+      this.lastFailureTime = Date.now();
+
+      // Open circuit if threshold reached
+      if (this.failures >= this.failureThreshold) {
+        await this._changeState('OPEN');
+        logger.error('Circuit breaker OPEN - failure threshold reached', {
+          failures: this.failures
+        });
+      } else {
+        await this.saveState();
+      }
+
+      throw err;
+    }
+  }
+
+  /**
+   * Get current state
+   * @returns {string} - CLOSED, OPEN, or HALF_OPEN
+   */
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * Get stats
+   * @returns {Object} - Statistics
+   */
+  getStats() {
+    return {
+      state: this.state,
+      failures: this.failures,
+      successes: this.successes,
+      failureThreshold: this.failureThreshold,
+      resetTimeout: this.resetTimeout,
+      lastFailureTime: this.lastFailureTime,
+      lastStateChange: this.lastStateChange,
+      agentType: this.agentType
+    };
+  }
+
+  /**
+   * Reset circuit breaker
+   * @returns {Promise<void>}
+   */
+  async reset() {
+    const oldState = this.state;
+    this.state = 'CLOSED';
+    this.failures = 0;
+    this.successes = 0;
+    this.lastFailureTime = null;
+    this.lastStateChange = new Date().toISOString();
+
+    this._logStateTransition(oldState, 'CLOSED');
+    await this.saveState();
+    logger.info('Circuit breaker reset');
+  }
+}
+
+module.exports = CircuitBreaker;