@howlil/ez-agents 3.4.2 → 4.0.0

package/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/bin/lib/assistant-adapter.cjs

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Assistant Adapters — Unified interface for AI coding assistants
+ * 
+ * Adapters for: Claude Code, OpenCode, Gemini CLI, Codex
+ * 
+ * Usage:
+ *   const { createAdapter } = require('./assistant-adapter.cjs');
+ *   const adapter = createAdapter('claude-code');
+ *   await adapter.spawnAgent('planner', { prompt: '...' });
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+const CircuitBreaker = require('./circuit-breaker.cjs');
+const ModelTierManager = require('./model-tier-manager.cjs');
+const CostTracker = require('./cost-tracker.cjs');
+
+/**
+ * Base adapter interface
+ */
+class AssistantAdapter {
+  constructor(name) {
+    if (new.target === AssistantAdapter) {
+      throw new Error('AssistantAdapter is abstract - use a concrete subclass');
+    }
+    this.name = name;
+  }
+
+  /**
+   * Spawn a subagent
+   * @param {string} type - Agent type
+   * @param {Object} options - Agent options
+   * @returns {Promise<Object>} - Agent result
+   */
+  async spawnAgent(type, options) {
+    throw new Error('spawnAgent must be implemented');
+  }
+
+  /**
+   * Call a tool/function
+   * @param {string} tool - Tool name
+   * @param {Object} params - Tool parameters
+   * @returns {Promise<any>} - Tool result
+   */
+  async callTool(tool, params) {
+    throw new Error('callTool must be implemented');
+  }
+
+  /**
+   * Select model for task
+   * @param {string} taskType - Task type (planning, execution, verification)
+   * @returns {string} - Model name
+   */
+  selectModel(taskType) {
+    throw new Error('selectModel must be implemented');
+  }
+
+  /**
+   * Get adapter info
+   * @returns {Object} - Adapter information
+   */
+  getInfo() {
+    return {
+      name: this.name,
+      type: this.constructor.name
+    };
+  }
+}
+
+/**
+ * Claude Code adapter
+ */
+class ClaudeCodeAdapter extends AssistantAdapter {
+  constructor() {
+    super('claude-code');
+  }
+
+  async spawnAgent(type, options) {
+    logger.info('Claude Code: spawning agent', { type });
+    // Would use Claude Code's Task tool in production
+    return { type, status: 'completed', result: '[Claude Code agent result]' };
+  }
+
+  async callTool(tool, params) {
+    logger.info('Claude Code: calling tool', { tool });
+    // Would use Claude Code's tool system
+    return { tool, status: 'success' };
+  }
+
+  selectModel(taskType) {
+    const models = {
+      planning: 'claude-3-opus',
+      execution: 'claude-3-sonnet',
+      verification: 'claude-3-sonnet'
+    };
+    return models[taskType] || models.execution;
+  }
+}
+
+/**
+ * OpenCode adapter
+ */
+class OpenCodeAdapter extends AssistantAdapter {
+  constructor() {
+    super('opencode');
+  }
+
+  async spawnAgent(type, options) {
+    logger.info('OpenCode: spawning agent', { type });
+    return { type, status: 'completed', result: '[OpenCode agent result]' };
+  }
+
+  async callTool(tool, params) {
+    logger.info('OpenCode: calling tool', { tool });
+    return { tool, status: 'success' };
+  }
+
+  selectModel(taskType) {
+    return 'gpt-4-turbo';
+  }
+}
+
+/**
+ * Gemini CLI adapter
+ */
+class GeminiAdapter extends AssistantAdapter {
+  constructor() {
+    super('gemini');
+  }
+
+  async spawnAgent(type, options) {
+    logger.info('Gemini: spawning agent', { type });
+    return { type, status: 'completed', result: '[Gemini agent result]' };
+  }
+
+  async callTool(tool, params) {
+    logger.info('Gemini: calling tool', { tool });
+    return { tool, status: 'success' };
+  }
+
+  selectModel(taskType) {
+    return 'gemini-pro';
+  }
+}
+
+/**
+ * Codex adapter
+ */
+class CodexAdapter extends AssistantAdapter {
+  constructor() {
+    super('codex');
+  }
+
+  async spawnAgent(type, options) {
+    logger.info('Codex: spawning agent', { type });
+    return { type, status: 'completed', result: '[Codex agent result]' };
+  }
+
+  async callTool(tool, params) {
+    logger.info('Codex: calling tool', { tool });
+    return { tool, status: 'success' };
+  }
+
+  selectModel(taskType) {
+    return 'codex-latest';
+  }
+}
+
+/**
+ * Qwen Code adapter
+ */
+class QwenAdapter extends AssistantAdapter {
+  constructor() {
+    super('qwen');
+  }
+
+  async spawnAgent(type, options) {
+    logger.info('Qwen Code: spawning agent', { type });
+    // Qwen Code uses its own agent system
+    return { type, status: 'completed', result: '[Qwen Code agent result]' };
+  }
+
+  async callTool(tool, params) {
+    logger.info('Qwen Code: calling tool', { tool });
+    return { tool, status: 'success' };
+  }
+
+  selectModel(taskType) {
+    const models = {
+      planning: 'qwen-max',
+      execution: 'qwen-plus',
+      verification: 'qwen-plus'
+    };
+    return models[taskType] || models.execution;
+  }
+}
+
+/**
+ * Kimi Code adapter
+ */
+class KimiAdapter extends AssistantAdapter {
+  constructor() {
+    super('kimi');
+  }
+
+  async spawnAgent(type, options) {
+    logger.info('Kimi Code: spawning agent', { type });
+    return { type, status: 'completed', result: '[Kimi Code agent result]' };
+  }
+
+  async callTool(tool, params) {
+    logger.info('Kimi Code: calling tool', { tool });
+    return { tool, status: 'success' };
+  }
+
+  selectModel(taskType) {
+    const models = {
+      planning: 'moonshot-v1-32k',
+      execution: 'moonshot-v1-8k',
+      verification: 'moonshot-v1-8k'
+    };
+    return models[taskType] || models.execution;
+  }
+}
+
+/**
+ * Circuit Breaker Adapter Wrapper — Wraps any adapter with circuit breaker protection
+ */
+class CircuitBreakerAdapter extends AssistantAdapter {
+  /**
+   * Create circuit breaker wrapped adapter
+   * @param {AssistantAdapter} delegate - The actual adapter to wrap
+   * @param {CircuitBreaker} breaker - Circuit breaker instance
+   */
+  constructor(delegate, breaker) {
+    super(delegate.name);
+    this.delegate = delegate;
+    this.breaker = breaker;
+  }
+
+  /**
+   * Spawn agent with circuit breaker protection
+   * @param {string} type - Agent type
+   * @param {Object} options - Agent options
+   * @returns {Promise<Object>} - Agent result
+   */
+  async spawnAgent(type, options) {
+    return this.breaker.execute(() => this.delegate.spawnAgent(type, options));
+  }
+
+  /**
+   * Call tool with circuit breaker protection
+   * @param {string} tool - Tool name
+   * @param {Object} params - Tool parameters
+   * @returns {Promise<any>} - Tool result
+   */
+  async callTool(tool, params) {
+    return this.breaker.execute(() => this.delegate.callTool(tool, params));
+  }
+
+  /**
+   * Select model with budget-aware downgrade
+   * @param {string} taskType - Task type
+   * @returns {string} - Selected model
+   */
+  selectModel(taskType) {
+    const costTracker = new CostTracker();
+    const budgetStatus = costTracker.checkBudget();
+    const percentUsed = budgetStatus.percentUsed || 0;
+
+    const modelManager = new ModelTierManager('claude');
+    const model = modelManager.selectModel(taskType, percentUsed);
+
+    // Log downgrade if not using premium model
+    if (percentUsed >= 75) {
+      const originalModel = this.delegate.selectModel(taskType);
+      if (originalModel !== model) {
+        modelManager.logDowngrade(originalModel, model, `budget pressure: ${percentUsed.toFixed(1)}%`);
+      }
+    }
+
+    return model;
+  }
+
+  /**
+   * Get adapter info
+   * @returns {Object} - Adapter information
+   */
+  getInfo() {
+    return {
+      ...this.delegate.getInfo(),
+      circuitBreaker: {
+        enabled: true,
+        state: this.breaker.getState()
+      }
+    };
+  }
+}
+
+/**
+ * Factory function to create adapter
+ * @param {string} type - Adapter type
+ * @param {Object} [options] - Adapter options
+ * @param {boolean} [options.circuitBreaker=true] - Enable circuit breaker
+ * @param {string} [options.cwd] - Working directory
+ * @returns {AssistantAdapter} - Adapter instance
+ */
+function createAdapter(type, options = {}) {
+  const adapters = {
+    'claude-code': ClaudeCodeAdapter,
+    'opencode': OpenCodeAdapter,
+    'gemini': GeminiAdapter,
+    'codex': CodexAdapter,
+    'qwen': QwenAdapter,
+    'kimi': KimiAdapter
+  };
+
+  const AdapterClass = adapters[type];
+  if (!AdapterClass) {
+    throw new Error(`Unknown adapter type: ${type}. Available: ${Object.keys(adapters).join(', ')}`);
+  }
+
+  const delegate = new AdapterClass();
+
+  // Wrap with circuit breaker if enabled
+  if (options.circuitBreaker !== false) {
+    const breaker = new CircuitBreaker({
+      failureThreshold: 5,
+      resetTimeout: 60000,
+      persistState: true,
+      cwd: options.cwd,
+      agentType: type
+    });
+    return new CircuitBreakerAdapter(delegate, breaker);
+  }
+
+  return delegate;
+}
+
+/**
+ * Get available adapters
+ * @returns {string[]} - List of adapter names
+ */
+function getAvailableAdapters() {
+  return ['claude-code', 'opencode', 'gemini', 'codex', 'qwen', 'kimi'];
+}
+
+module.exports = {
+  AssistantAdapter,
+  ClaudeCodeAdapter,
+  OpenCodeAdapter,
+  GeminiAdapter,
+  CodexAdapter,
+  QwenAdapter,
+  KimiAdapter,
+  CircuitBreakerAdapter,
+  createAdapter,
+  getAvailableAdapters
+};