@howlil/ez-agents 3.5.0 → 4.0.0

package/ez-agents/bin/lib/archetype-detector.cjs

@@ -0,0 +1,289 @@
+/**
+ * Archetype Detector — Project type classification from codebase patterns
+ *
+ * Provides:
+ * - detect(structure, stack, flows): Pattern-based archetype detection
+ * - calculateConfidence(archetype, evidence): Confidence scoring
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class ArchetypeDetector {
+  constructor(rootPath) {
+    this.rootPath = rootPath;
+    
+    // Archetype patterns for detection
+    this.archetypePatterns = {
+      dashboard: {
+        patterns: ['Chart', 'Metric', 'Dashboard', 'Admin', 'Analytics', 'stats', 'metrics', 'analytics', 'graph', 'widget', 'kpi', 'report'],
+        routes: ['/dashboard', '/admin', '/analytics', '/reports', '/metrics'],
+        dependencies: ['recharts', 'chart.js', 'd3', 'plotly', 'highcharts', 'apexcharts']
+      },
+      POS: {
+        patterns: ['Product', 'Order', 'Payment', 'Cart', 'Checkout', 'Inventory', 'Store', 'Register', 'Terminal', 'Receipt', 'Cashier'],
+        routes: ['/pos', '/checkout', '/register', '/inventory', '/products'],
+        dependencies: ['stripe-terminal', 'square', '@stripe/stripe-js']
+      },
+      SaaS: {
+        patterns: ['Subscription', 'Tenant', 'Plan', 'Billing', 'User', 'Account', 'Recurring', 'Invoice', 'Pricing'],
+        routes: ['/subscription', '/billing', '/pricing', '/plans', '/account', '/settings'],
+        dependencies: ['stripe', '@stripe/stripe-js', 'paddle', 'lemonsqueezy']
+      },
+      ecommerce: {
+        patterns: ['Cart', 'Checkout', 'Product', 'Order', 'Shipping', 'Payment', 'Catalog', 'Wishlist', 'Review'],
+        routes: ['/products', '/cart', '/checkout', '/orders', '/wishlist', '/reviews'],
+        dependencies: ['@stripe/stripe-js', 'stripe', 'paypal', 'snipcart']
+      },
+      LMS: {
+        patterns: ['Course', 'Lesson', 'Student', 'Teacher', 'Quiz', 'Enrollment', 'Curriculum', 'Assignment', 'Grade'],
+        routes: ['/courses', '/lessons', '/students', '/teachers', '/quiz', '/assignments'],
+        dependencies: ['video.js', 'hls.js', 'plyr']
+      },
+      booking: {
+        patterns: ['Appointment', 'Booking', 'Availability', 'Calendar', 'Reservation', 'Schedule', 'Timeslot'],
+        routes: ['/booking', '/appointments', '/calendar', '/schedule', '/availability'],
+        dependencies: ['react-big-calendar', 'fullcalendar', 'react-calendar']
+      },
+      fintech: {
+        patterns: ['Transaction', 'Account', 'Payment', 'Balance', 'Compliance', 'KYC', 'AML', 'Ledger', 'Wallet', 'Transfer'],
+        routes: ['/accounts', '/transactions', '/transfer', '/wallet', '/ledger', '/compliance'],
+        dependencies: ['stripe', 'plaid', 'dwolla', 'unit']
+      },
+      internalTools: {
+        patterns: ['Admin', 'CRUD', 'Form', 'Table', 'Dashboard', 'Report', 'Config', 'Settings', 'Management'],
+        routes: ['/admin', '/management', '/config', '/settings', '/users', '/roles'],
+        dependencies: ['@tanstack/react-table', 'ag-grid', 'handsontable']
+      },
+      cms: {
+        patterns: ['Article', 'Page', 'Post', 'Media', 'Content', 'Block', 'Editor', 'Publish'],
+        routes: ['/articles', '/pages', '/posts', '/media', '/content'],
+        dependencies: ['@tiptap', 'slate', 'draft-js', 'quill', 'ckeditor']
+      },
+      social: {
+        patterns: ['Post', 'Comment', 'Feed', 'Follow', 'Like', 'Share', 'Profile', 'Notification', 'Message'],
+        routes: ['/feed', '/posts', '/profile', '/notifications', '/messages', '/followers'],
+        dependencies: ['socket.io', 'pusher', 'stream-chat']
+      }
+    };
+  }
+
+  /**
+   * Detect project archetype from structure, stack, and flows
+   * @param {object} structure - Structure from CodebaseAnalyzer
+   * @param {object} stack - Stack from StackDetector
+   * @param {object} flows - Flows from BusinessFlowMapper
+   * @returns {object} Archetype detection result with name, confidence, evidence
+   */
+  detect(structure = {}, stack = {}, flows = {}) {
+    const scores = {};
+    const evidence = {};
+
+    // Initialize scores for each archetype
+    for (const archetype of Object.keys(this.archetypePatterns)) {
+      scores[archetype] = 0;
+      evidence[archetype] = [];
+    }
+
+    // Score based on file names
+    const files = structure.files || [];
+    for (const file of files) {
+      const fileName = path.basename(file);
+      this._scoreByFileName(fileName, scores, evidence);
+    }
+
+    // Score based on directory names
+    const directories = structure.directories || [];
+    for (const dir of directories) {
+      const dirName = path.basename(dir.path);
+      this._scoreByDirectoryName(dirName, scores, evidence);
+    }
+
+    // Score based on routes
+    const routes = flows.routes || [];
+    for (const route of routes) {
+      this._scoreByRoute(route.path, scores, evidence);
+    }
+
+    // Score based on dependencies
+    const frameworks = stack.frameworks || [];
+    const infrastructure = stack.infrastructure || [];
+    const allDeps = [...frameworks, ...infrastructure];
+    this._scoreByDependencies(allDeps, scores, evidence);
+
+    // Find the highest scoring archetype
+    let bestArchetype = 'internalTools'; // Default
+    let bestScore = 0;
+
+    for (const [archetype, score] of Object.entries(scores)) {
+      if (score > bestScore) {
+        bestScore = score;
+        bestArchetype = archetype;
+      }
+    }
+
+    const confidence = this.calculateConfidence(bestArchetype, evidence[bestArchetype]);
+
+    return {
+      archetype: bestArchetype,
+      confidence: confidence.score,
+      confidenceLevel: confidence.level,
+      scores,
+      evidence: evidence[bestArchetype],
+      allEvidence: evidence
+    };
+  }
+
+  /**
+   * Calculate confidence score for an archetype
+   * @param {string} archetype - Archetype name
+   * @param {Array} evidence - Array of evidence items
+   * @returns {object} Confidence with score (0-100) and level (High/Medium/Low)
+   */
+  calculateConfidence(archetype, evidence = []) {
+    // Base score: evidence.length * 10
+    let score = evidence.length * 10;
+
+    // Bonus for file matches: +20 per file
+    const fileMatches = evidence.filter(e => e.type === 'file').length;
+    score += fileMatches * 20;
+
+    // Bonus for dependency matches: +15 per dependency
+    const depMatches = evidence.filter(e => e.type === 'dependency').length;
+    score += depMatches * 15;
+
+    // Bonus for route matches: +10 per route
+    const routeMatches = evidence.filter(e => e.type === 'route').length;
+    score += routeMatches * 10;
+
+    // Cap at 100
+    score = Math.min(score, 100);
+
+    // Determine level
+    let level;
+    if (score >= 80) {
+      level = 'High';
+    } else if (score >= 60) {
+      level = 'Medium';
+    } else {
+      level = 'Low';
+    }
+
+    return { score, level };
+  }
+
+  /**
+   * Score archetype by file name
+   * @private
+   */
+  _scoreByFileName(fileName, scores, evidence) {
+    const nameWithoutExt = fileName.replace(/\.[^.]+$/, '');
+    
+    for (const [archetype, config] of Object.entries(this.archetypePatterns)) {
+      for (const pattern of config.patterns) {
+        if (nameWithoutExt.toLowerCase().includes(pattern.toLowerCase())) {
+          scores[archetype] += 1;
+          evidence[archetype].push({
+            type: 'file',
+            value: fileName,
+            pattern
+          });
+          break; // Don't double-count same file
+        }
+      }
+    }
+  }
+
+  /**
+   * Score archetype by directory name
+   * @private
+   */
+  _scoreByDirectoryName(dirName, scores, evidence) {
+    for (const [archetype, config] of Object.entries(this.archetypePatterns)) {
+      for (const pattern of config.patterns) {
+        if (dirName.toLowerCase().includes(pattern.toLowerCase())) {
+          scores[archetype] += 2; // Directories are stronger signals
+          evidence[archetype].push({
+            type: 'directory',
+            value: dirName,
+            pattern
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  /**
+   * Score archetype by route
+   * @private
+   */
+  _scoreByRoute(routePath, scores, evidence) {
+    for (const [archetype, config] of Object.entries(this.archetypePatterns)) {
+      for (const routePattern of config.routes) {
+        if (routePath.toLowerCase().includes(routePattern.toLowerCase())) {
+          scores[archetype] += 2;
+          evidence[archetype].push({
+            type: 'route',
+            value: routePath,
+            pattern: routePattern
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  /**
+   * Score archetype by dependencies
+   * @private
+   */
+  _scoreByDependencies(dependencies, scores, evidence) {
+    for (const [archetype, config] of Object.entries(this.archetypePatterns)) {
+      for (const depPattern of config.dependencies) {
+        for (const dep of dependencies) {
+          if (dep.toLowerCase().includes(depPattern.toLowerCase())) {
+            scores[archetype] += 3; // Dependencies are strong signals
+            evidence[archetype].push({
+              type: 'dependency',
+              value: dep,
+              pattern: depPattern
+            });
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Get all supported archetypes
+   * @returns {Array} Array of archetype names
+   */
+  getSupportedArchetypes() {
+    return Object.keys(this.archetypePatterns);
+  }
+
+  /**
+   * Get archetype description
+   * @param {string} archetype - Archetype name
+   * @returns {string} Description
+   */
+  getArchetypeDescription(archetype) {
+    const descriptions = {
+      dashboard: 'Analytics dashboard with charts, metrics, and data visualization',
+      POS: 'Point of Sale system for retail transactions and inventory management',
+      SaaS: 'Software as a Service with subscription billing and multi-tenant architecture',
+      ecommerce: 'E-commerce platform with product catalog, cart, and checkout',
+      LMS: 'Learning Management System for courses, lessons, and student tracking',
+      booking: 'Booking and appointment scheduling system',
+      fintech: 'Financial technology application for transactions and account management',
+      internalTools: 'Internal business tools and admin panels',
+      cms: 'Content Management System for articles, pages, and media',
+      social: 'Social platform with feeds, posts, and user interactions'
+    };
+    return descriptions[archetype] || 'Unknown project type';
+  }
+}
+
+module.exports = { ArchetypeDetector };

package/ez-agents/bin/lib/audit-exec.cjs

@@ -1,167 +1,166 @@
-#!/usr/bin/env node
-
-/**
- * EZ Audit Exec — Command execution with full audit logging
- * 
- * Logs all command executions to audit file for security review:
- * - Timestamp, command, arguments, context
- * - Duration and result status
- * - Error details if failed
- * 
- * Usage:
- *   const { auditExec } = require('./audit-exec.cjs');
- *   const result = await auditExec('git', ['status'], { context: 'my-module' });
- */
-
-const { execFile } = require('child_process');
-const { promisify } = require('util');
-const { appendFileSync, existsSync, mkdirSync } = require('fs');
-const { join } = require('path');
-const Logger = require('./logger.cjs');
-const logger = new Logger();
-
-const execFileAsync = promisify(execFile);
-
-// Audit log file path - lazy init
-let _AUDIT_DIR;
-let _AUDIT_FILE;
-
-function getAuditDir() {
-  if (!_AUDIT_DIR) {
-    _AUDIT_DIR = join('.planning', 'logs');
-    if (!existsSync(_AUDIT_DIR)) {
-      mkdirSync(_AUDIT_DIR, { recursive: true });
-    }
-  }
-  return _AUDIT_DIR;
-}
-
-function getAuditFile() {
-  if (!_AUDIT_FILE) {
-    _AUDIT_FILE = join(getAuditDir(), `audit-${new Date().toISOString().split('T')[0]}.jsonl`);
-  }
-  return _AUDIT_FILE;
-}
-
-/**
- * Write audit log entry
- * @param {Object} entry - Audit entry
- */
-function writeAudit(entry) {
-  try {
-    const line = JSON.stringify(entry) + '\n';
-    appendFileSync(getAuditFile(), line, 'utf-8');
-  } catch (err) {
-    // Silently ignore audit write failures - logging is best-effort
-    // This can happen in temp test directories or when .planning doesn't exist
-  }
-}
-
-/**
- * Execute command with full audit logging
- * @param {string} cmd - Command to execute
- * @param {string[]} args - Command arguments
- * @param {Object} options - Execution options
- * @param {string} options.context - Calling context (which module/function)
- * @param {string} options.user - User identifier
- * @returns {Promise<string>} - Command stdout
- */
-async function auditExec(cmd, args = [], options = {}) {
-  const { context = 'unknown', user = 'system', timeout = 30000 } = options;
-  
-  const entry = {
-    timestamp: new Date().toISOString(),
-    cmd,
-    args,
-    context,
-    user,
-    status: 'started'
-  };
-  
-  // Log start
-  writeAudit(entry);
-  logger.info('Audit: command started', { cmd, args: args.join(' '), context });
-  
-  const startTime = Date.now();
-  
-  try {
-    const result = await execFileAsync(cmd, args, { 
-      timeout,
-      maxBuffer: 10 * 1024 * 1024
-    });
-    
-    const duration = Date.now() - startTime;
-    
-    // Log success
-    const successEntry = {
-      ...entry,
-      status: 'success',
-      duration,
-      stdout_length: result.stdout?.length || 0
-    };
-    writeAudit(successEntry);
-    
-    logger.debug('Audit: command completed', { cmd, duration, context });
-    
-    return result.stdout.trim();
-  } catch (err) {
-    const duration = Date.now() - startTime;
-    
-    // Log failure
-    const errorEntry = {
-      ...entry,
-      status: 'error',
-      duration,
-      error: err.message,
-      code: err.code,
-      signal: err.signal
-    };
-    writeAudit(errorEntry);
-    
-    logger.error('Audit: command failed', { cmd, error: err.message, duration, context });
-    
-    throw err;
-  }
-}
-
-/**
- * Get today's audit log path
- * @returns {string} - Audit file path
- */
-function getAuditFilePath() {
-  return AUDIT_FILE;
-}
-
-/**
- * Read audit log entries for a specific date
- * @param {string} date - Date string (YYYY-MM-DD)
- * @returns {Object[]} - Array of audit entries
- */
-function readAuditLog(date = new Date().toISOString().split('T')[0]) {
-  const filePath = join(AUDIT_DIR, `audit-${date}.jsonl`);
-  
-  if (!existsSync(filePath)) {
-    return [];
-  }
-  
-  const content = require('fs').readFileSync(filePath, 'utf-8');
-  return content.trim().split('\n').map(line => JSON.parse(line));
-}
-
-/**
- * Search audit log for specific command
- * @param {string} cmdFilter - Command to filter by
- * @param {string} date - Date string
- * @returns {Object[]} - Matching entries
- */
-function searchAuditLog(cmdFilter, date) {
-  const entries = readAuditLog(date);
-  return entries.filter(e => e.cmd === cmdFilter);
-}
-
-module.exports = {
-  auditExec,
-  getAuditFilePath,
-  readAuditLog,
-  searchAuditLog
-};
+#!/usr/bin/env node
+
+/**
+ * EZ Audit Exec — Command execution with full audit logging
+ * 
+ * Logs all command executions to audit file for security review:
+ * - Timestamp, command, arguments, context
+ * - Duration and result status
+ * - Error details if failed
+ * 
+ * Usage:
+ *   const { auditExec } = require('./audit-exec.cjs');
+ *   const result = await auditExec('git', ['status'], { context: 'my-module' });
+ */
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const { appendFileSync, existsSync, mkdirSync } = require('fs');
+const { join } = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+const execFileAsync = promisify(execFile);
+
+// Audit log file path - lazy init
+let _AUDIT_DIR;
+let _AUDIT_FILE;
+
+function getAuditDir() {
+  if (!_AUDIT_DIR) {
+    _AUDIT_DIR = join('.planning', 'logs');
+    if (!existsSync(_AUDIT_DIR)) {
+      mkdirSync(_AUDIT_DIR, { recursive: true });
+    }
+  }
+  return _AUDIT_DIR;
+}
+
+function getAuditFile() {
+  if (!_AUDIT_FILE) {
+    _AUDIT_FILE = join(getAuditDir(), `audit-${new Date().toISOString().split('T')[0]}.jsonl`);
+  }
+  return _AUDIT_FILE;
+}
+
+/**
+ * Write audit log entry
+ * @param {Object} entry - Audit entry
+ */
+function writeAudit(entry) {
+  try {
+    const line = JSON.stringify(entry) + '\n';
+    appendFileSync(getAuditFile(), line, 'utf-8');
+  } catch (err) {
+    // Silently ignore audit write failures - logging is best-effort
+    // This can happen in temp test directories or when .planning doesn't exist
+  }
+}
+
+/**
+ * Execute command with full audit logging
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {Object} options - Execution options
+ * @param {string} options.context - Calling context (which module/function)
+ * @param {string} options.user - User identifier
+ * @returns {Promise<string>} - Command stdout
+ */
+async function auditExec(cmd, args = [], options = {}) {
+  const { context = 'unknown', user = 'system', timeout = 30000, cwd } = options;
+  
+  const entry = {
+    timestamp: new Date().toISOString(),
+    cmd,
+    args,
+    context,
+    user,
+    status: 'started'
+  };
+  
+  // Log start
+  writeAudit(entry);
+  logger.info('Audit: command started', { cmd, args: args.join(' '), context });
+  
+  const startTime = Date.now();
+  
+  try {
+    const execOpts = { timeout, maxBuffer: 10 * 1024 * 1024 };
+    if (cwd) execOpts.cwd = cwd;
+    const result = await execFileAsync(cmd, args, execOpts);
+    
+    const duration = Date.now() - startTime;
+    
+    // Log success
+    const successEntry = {
+      ...entry,
+      status: 'success',
+      duration,
+      stdout_length: result.stdout?.length || 0
+    };
+    writeAudit(successEntry);
+    
+    logger.debug('Audit: command completed', { cmd, duration, context });
+    
+    return result.stdout.trim();
+  } catch (err) {
+    const duration = Date.now() - startTime;
+    
+    // Log failure
+    const errorEntry = {
+      ...entry,
+      status: 'error',
+      duration,
+      error: err.message,
+      code: err.code,
+      signal: err.signal
+    };
+    writeAudit(errorEntry);
+    
+    logger.error('Audit: command failed', { cmd, error: err.message, duration, context });
+    
+    throw err;
+  }
+}
+
+/**
+ * Get today's audit log path
+ * @returns {string} - Audit file path
+ */
+function getAuditFilePath() {
+  return AUDIT_FILE;
+}
+
+/**
+ * Read audit log entries for a specific date
+ * @param {string} date - Date string (YYYY-MM-DD)
+ * @returns {Object[]} - Array of audit entries
+ */
+function readAuditLog(date = new Date().toISOString().split('T')[0]) {
+  const filePath = join(AUDIT_DIR, `audit-${date}.jsonl`);
+  
+  if (!existsSync(filePath)) {
+    return [];
+  }
+  
+  const content = require('fs').readFileSync(filePath, 'utf-8');
+  return content.trim().split('\n').map(line => JSON.parse(line));
+}
+
+/**
+ * Search audit log for specific command
+ * @param {string} cmdFilter - Command to filter by
+ * @param {string} date - Date string
+ * @returns {Object[]} - Matching entries
+ */
+function searchAuditLog(cmdFilter, date) {
+  const entries = readAuditLog(date);
+  return entries.filter(e => e.cmd === cmdFilter);
+}
+
+module.exports = {
+  auditExec,
+  getAuditFilePath,
+  readAuditLog,
+  searchAuditLog
+};