wiggum-cli 0.3.2 → 0.4.0

package/src/ai/agents/index.ts

@@ -1,10 +1,26 @@
 /**
  * Agents Index
- * Exports all agent types and functions
+ * Multi-agent analysis with Orchestrator-Worker + Evaluator-Optimizer pattern
+ *
+ * Architecture:
+ * Phase 1: Planning Orchestrator (creates analysis plan)
+ * Phase 2: Parallel Workers (context enricher + tech researchers)
+ * Phase 3: Synthesis (merge results + MCP detection)
+ * Phase 4: Evaluator-Optimizer (QA loop)
  */
 
-// Types
+// Types - export all for consumers
 export type {
+  // New architecture types
+  AnalysisPlan,
+  EnrichedContext,
+  TechResearchResult,
+  RalphMcpServers,
+  EvaluationResult,
+  ContextEnricherInput,
+  TechResearcherInput,
+  SynthesisInput,
+  // Legacy types (backward compatibility)
   CodebaseAnalysis,
   StackResearch,
   McpRecommendations,
@@ -16,26 +32,45 @@ export type {
   OrchestratorInput,
 } from './types.js';
 
-// Agents
+// New architecture exports
+export { runPlanningOrchestrator } from './planning-orchestrator.js';
+export { runContextEnricher } from './context-enricher.js';
+export { runTechResearcher, runTechResearchPool } from './tech-researcher.js';
+export { detectRalphMcpServers, convertToLegacyMcpRecommendations } from './mcp-detector.js';
+export { runSynthesisAgent } from './synthesis-agent.js';
+export { runEvaluatorOptimizer } from './evaluator-optimizer.js';
+export { detectProjectType } from './stack-utils.js';
+
+// Legacy exports (for backward compatibility during migration)
 export { runCodebaseAnalyst } from './codebase-analyst.js';
 export { runStackResearcher } from './stack-researcher.js';
 export { runOrchestrator, mergeAgentResults } from './orchestrator.js';
 
-// Re-export for convenience
+// Main orchestration
 import type { LanguageModel } from 'ai';
-import type { ScanResult, DetectedStack } from '../../scanner/types.js';
+import type { ScanResult } from '../../scanner/types.js';
 import type {
   MultiAgentAnalysis,
   AgentCapabilities,
   AgentOptions,
+  EnrichedContext,
 } from './types.js';
-import { runCodebaseAnalyst } from './codebase-analyst.js';
-import { runStackResearcher } from './stack-researcher.js';
-import { runOrchestrator, mergeAgentResults } from './orchestrator.js';
+import { runPlanningOrchestrator } from './planning-orchestrator.js';
+import { runContextEnricher } from './context-enricher.js';
+import { runTechResearchPool } from './tech-researcher.js';
+import { detectRalphMcpServers } from './mcp-detector.js';
+import { runSynthesisAgent } from './synthesis-agent.js';
+import { runEvaluatorOptimizer } from './evaluator-optimizer.js';
+import { detectProjectType } from './stack-utils.js';
 import { logger } from '../../utils/logger.js';
 
 /**
- * Run the full multi-agent analysis pipeline
+ * Run the full multi-agent analysis pipeline (new architecture)
+ *
+ * Phase 1: Planning Orchestrator - Creates focused analysis plan
+ * Phase 2: Parallel Workers - Context enricher + tech researchers run concurrently
+ * Phase 3: Synthesis - Merges results + detects MCPs
+ * Phase 4: Evaluator-Optimizer - QA loop (max 2 iterations)
  */
 export async function runMultiAgentAnalysis(
   model: LanguageModel,
@@ -52,131 +87,189 @@ export async function runMultiAgentAnalysis(
   };
 
   if (verbose) {
-    logger.info('Starting multi-agent analysis...');
+    logger.info('Starting multi-agent analysis (4-phase architecture)...');
     logger.info(`Capabilities: Tavily=${capabilities.hasTavily}, Context7=${capabilities.hasContext7}`);
   }
 
-  // Run Codebase Analyst
-  if (verbose) {
-    logger.info('Running Codebase Analyst...');
-  }
+  try {
+    // ═══════════════════════════════════════════════════════════════
+    // PHASE 1: Planning Orchestrator
+    // ═══════════════════════════════════════════════════════════════
+    if (verbose) {
+      logger.info('Phase 1: Creating analysis plan...');
+    }
 
-  let codebaseAnalysis = await runCodebaseAnalyst(
-    model,
-    modelId,
-    {
-      scanResult,
-      projectRoot: scanResult.projectRoot,
-    },
-    verbose
-  );
+    const plan = await runPlanningOrchestrator(model, modelId, scanResult, verbose);
 
-  if (!codebaseAnalysis) {
     if (verbose) {
-      logger.warn('Codebase Analyst failed, using defaults');
+      logger.info(`Plan: ${plan.areasToExplore.length} areas, ${plan.technologiesToResearch.length} techs, complexity=${plan.estimatedComplexity}`);
     }
-    // Use defaults instead of aborting the pipeline
-    codebaseAnalysis = getDefaultCodebaseAnalysis(scanResult);
-  }
 
-  // Run Stack Researcher
-  if (verbose) {
-    logger.info('Running Stack Researcher...');
-  }
+    // ═══════════════════════════════════════════════════════════════
+    // PHASE 2: Parallel Workers
+    // ═══════════════════════════════════════════════════════════════
+    if (verbose) {
+      logger.info('Phase 2: Running parallel workers...');
+    }
 
-  const stackResearch = await runStackResearcher(
-    model,
-    modelId,
-    {
-      stack: scanResult.stack,
-      projectType: codebaseAnalysis.projectContext.projectType,
-      capabilities,
-    },
-    { tavilyApiKey, context7ApiKey },
-    verbose
-  );
+    // Run context enricher and tech researchers in parallel with error recovery
+    const [contextResult, researchResult] = await Promise.allSettled([
+      runContextEnricher(
+        model,
+        modelId,
+        {
+          scanResult,
+          areasToExplore: plan.areasToExplore,
+          questionsToAnswer: plan.questionsToAnswer,
+        },
+        verbose
+      ),
+      runTechResearchPool(
+        model,
+        modelId,
+        plan.technologiesToResearch,
+        { tavilyApiKey, context7ApiKey },
+        verbose
+      ),
+    ]);
+
+    // Extract results with fallbacks for failed workers
+    const enrichedContext = contextResult.status === 'fulfilled'
+      ? contextResult.value
+      : getDefaultEnrichedContext(scanResult);
+
+    const techResearch = researchResult.status === 'fulfilled'
+      ? researchResult.value
+      : [];
+
+    // Log any worker failures
+    if (contextResult.status === 'rejected') {
+      logger.warn(`Context Enricher failed: ${contextResult.reason instanceof Error ? contextResult.reason.message : String(contextResult.reason)}`);
+    }
+    if (researchResult.status === 'rejected') {
+      logger.warn(`Tech Research Pool failed: ${researchResult.reason instanceof Error ? researchResult.reason.message : String(researchResult.reason)}`);
+    }
 
-  if (!stackResearch) {
     if (verbose) {
-      logger.warn('Stack Researcher failed, using defaults');
+      logger.info(`Context: ${enrichedContext.entryPoints.length} entry points, type=${enrichedContext.projectType}`);
+      logger.info(`Research: ${techResearch.length} technologies researched`);
     }
-    // Continue with defaults - stack research is optional
-  }
 
-  // Run Orchestrator to merge results
-  if (verbose) {
-    logger.info('Running Orchestrator...');
-  }
+    // ═══════════════════════════════════════════════════════════════
+    // PHASE 3: Synthesis + MCP Detection
+    // ═══════════════════════════════════════════════════════════════
+    if (verbose) {
+      logger.info('Phase 3: Synthesizing results...');
+    }
 
-  const mcpServers = await runOrchestrator(
-    model,
-    modelId,
-    {
-      codebaseAnalysis,
-      stackResearch: stackResearch || getDefaultStackResearch(),
-      stack: scanResult.stack,
-    },
-    verbose
-  );
+    // Detect MCPs (pure function, no LLM)
+    const mcpServers = detectRalphMcpServers(scanResult.stack);
+
+    if (verbose) {
+      logger.info(`MCPs: e2e=${mcpServers.e2eTesting}, db=${mcpServers.database || 'none'}, additional=${mcpServers.additional.length}`);
+    }
 
-  // Merge all results
-  const finalResult = mergeAgentResults(
-    codebaseAnalysis,
-    stackResearch || getDefaultStackResearch(),
-    mcpServers
-  );
+    // Run synthesis agent
+    const synthesizedResult = await runSynthesisAgent(
+      model,
+      modelId,
+      {
+        enrichedContext,
+        techResearch,
+        mcpServers,
+        plan,
+        stack: scanResult.stack,
+      },
+      verbose
+    );
 
-  if (verbose) {
-    logger.info('Multi-agent analysis complete');
-  }
+    // ═══════════════════════════════════════════════════════════════
+    // PHASE 4: Evaluator-Optimizer QA Loop
+    // ═══════════════════════════════════════════════════════════════
+    if (verbose) {
+      logger.info('Phase 4: Running QA evaluation...');
+    }
 
-  return finalResult;
+    const finalResult = await runEvaluatorOptimizer(
+      model,
+      modelId,
+      synthesizedResult,
+      scanResult,
+      2, // Max 2 iterations
+      verbose
+    );
+
+    if (verbose) {
+      logger.info('Multi-agent analysis complete (4-phase architecture)');
+    }
+
+    return finalResult;
+  } catch (error) {
+    logger.error(`Multi-agent analysis failed: ${error instanceof Error ? error.message : String(error)}`);
+
+    // Fall back to default result
+    return getDefaultMultiAgentAnalysis(scanResult);
+  }
 }
 
 /**
- * Get default codebase analysis when agent fails
+ * Get default analysis result when pipeline fails
  */
-function getDefaultCodebaseAnalysis(scanResult: ScanResult) {
-  // Detect project type from scan result
-  let projectType = 'Unknown';
-  if (scanResult.stack.mcp?.isProject) {
-    projectType = 'MCP Server';
-  } else if (scanResult.stack.framework?.name.includes('Next')) {
-    projectType = 'Next.js App';
-  } else if (scanResult.stack.framework?.name.includes('React')) {
-    projectType = 'React SPA';
-  } else if (scanResult.stack.framework?.name) {
-    projectType = `${scanResult.stack.framework.name} Project`;
-  }
+function getDefaultMultiAgentAnalysis(scanResult: ScanResult): MultiAgentAnalysis {
+  const projectType = detectProjectType(scanResult.stack);
 
   return {
-    projectContext: {
-      entryPoints: ['src/index.ts'],
-      keyDirectories: { 'src': 'Source code' },
-      namingConventions: 'camelCase',
-      projectType,
+    codebaseAnalysis: {
+      projectContext: {
+        entryPoints: ['src/index.ts'],
+        keyDirectories: { src: 'Source code' },
+        namingConventions: 'camelCase',
+        projectType,
+      },
+      commands: {
+        test: 'npm test',
+        lint: 'npm run lint',
+        build: 'npm run build',
+        dev: 'npm run dev',
+      },
+      implementationGuidelines: [
+        'Follow existing patterns',
+        'Run tests after changes',
+        'Use TypeScript strict mode',
+      ],
+      possibleMissedTechnologies: [],
     },
-    commands: {
-      test: 'npm test',
-      lint: 'npm run lint',
-      build: 'npm run build',
-      dev: 'npm run dev',
+    stackResearch: {
+      bestPractices: ['Follow project conventions'],
+      antiPatterns: ['Avoid skipping tests'],
+      testingTools: ['npm test'],
+      debuggingTools: ['console.log'],
+      documentationHints: ['Check official docs'],
+      researchMode: 'knowledge-only',
+    },
+    mcpServers: {
+      essential: ['filesystem', 'git', 'playwright'],
+      recommended: [],
     },
-    implementationGuidelines: ['Follow existing patterns', 'Run tests after changes'],
-    possibleMissedTechnologies: [],
   };
 }
 
 /**
- * Get default stack research when agent fails
+ * Get default enriched context when Context Enricher fails
  */
-function getDefaultStackResearch() {
+function getDefaultEnrichedContext(scanResult: ScanResult): EnrichedContext {
+  const projectType = detectProjectType(scanResult.stack);
+
   return {
-    bestPractices: ['Follow project conventions'],
-    antiPatterns: ['Avoid skipping tests'],
-    testingTools: ['npm test'],
-    debuggingTools: ['console.log'],
-    documentationHints: ['Check official docs'],
-    researchMode: 'knowledge-only' as const,
+    entryPoints: ['src/index.ts'],
+    keyDirectories: { src: 'Source code' },
+    namingConventions: 'camelCase',
+    commands: {
+      test: 'npm test',
+      build: 'npm run build',
+      dev: 'npm run dev',
+    },
+    answeredQuestions: {},
+    projectType,
   };
 }

package/src/ai/agents/mcp-detector.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Tests for MCP Detector
+ *
+ * Run with: npx vitest run src/ai/agents/mcp-detector.test.ts
+ * (Requires vitest to be installed: npm install -D vitest)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { detectRalphMcpServers, convertToLegacyMcpRecommendations } from './mcp-detector.js';
+import type { DetectedStack } from '../../scanner/types.js';
+
+/**
+ * Helper to create a DetectionResult
+ */
+function detection(name: string) {
+  return { name, confidence: 1, evidence: [`detected ${name}`] };
+}
+
+/**
+ * Helper to create a minimal DetectedStack for testing
+ */
+function createStack(overrides: Partial<DetectedStack> = {}): DetectedStack {
+  return {
+    language: detection('TypeScript'),
+    ...overrides,
+  } as DetectedStack;
+}
+
+describe('detectRalphMcpServers', () => {
+  describe('e2eTesting', () => {
+    it('always returns playwright for e2eTesting', () => {
+      const result = detectRalphMcpServers(createStack());
+      expect(result.e2eTesting).toBe('playwright');
+    });
+  });
+
+  describe('database detection', () => {
+    it('detects Supabase', () => {
+      const stack = createStack({
+        database: detection('Supabase'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('supabase');
+    });
+
+    it('detects PostgreSQL', () => {
+      const stack = createStack({
+        database: detection('PostgreSQL'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('postgres');
+    });
+
+    it('detects Neon as postgres', () => {
+      const stack = createStack({
+        database: detection('Neon'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('postgres');
+    });
+
+    it('detects SQLite', () => {
+      const stack = createStack({
+        database: detection('SQLite'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('sqlite');
+    });
+
+    it('detects Turso as sqlite', () => {
+      const stack = createStack({
+        database: detection('Turso'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('sqlite');
+    });
+
+    it('detects Firebase/Firestore', () => {
+      const stack = createStack({
+        database: detection('Firestore'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('firebase');
+    });
+
+    it('detects MongoDB', () => {
+      const stack = createStack({
+        database: detection('MongoDB'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBe('mongodb');
+    });
+
+    it('returns undefined for unknown database', () => {
+      const stack = createStack({
+        database: detection('UnknownDB'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.database).toBeUndefined();
+    });
+
+    it('returns undefined when no database is detected', () => {
+      const result = detectRalphMcpServers(createStack());
+      expect(result.database).toBeUndefined();
+    });
+  });
+
+  describe('framework detection', () => {
+    it('adds vercel for Next.js projects', () => {
+      const stack = createStack({
+        framework: detection('Next.js'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('vercel');
+    });
+
+    it('does not add vercel for non-Next.js projects', () => {
+      const stack = createStack({
+        framework: detection('React'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).not.toContain('vercel');
+    });
+  });
+
+  describe('deployment detection', () => {
+    it('detects Docker deployment', () => {
+      const stack = createStack({
+        deployment: [detection('Docker')],
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('docker');
+    });
+
+    it('detects Vercel deployment', () => {
+      const stack = createStack({
+        deployment: [detection('Vercel')],
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('vercel');
+    });
+
+    it('detects multiple deployments', () => {
+      const stack = createStack({
+        deployment: [
+          detection('Docker'),
+          detection('Railway'),
+        ],
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('docker');
+      expect(result.additional).toContain('railway');
+    });
+  });
+
+  describe('auth provider detection', () => {
+    it('detects Clerk auth', () => {
+      const stack = createStack({
+        auth: detection('Clerk'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('clerk');
+    });
+
+    it('detects Auth0', () => {
+      const stack = createStack({
+        auth: detection('Auth0'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('auth0');
+    });
+  });
+
+  describe('analytics detection', () => {
+    it('detects PostHog analytics', () => {
+      const stack = createStack({
+        analytics: [detection('PostHog')],
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('posthog');
+    });
+
+    it('detects Sentry', () => {
+      const stack = createStack({
+        analytics: [detection('Sentry')],
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('sentry');
+    });
+  });
+
+  describe('payments detection', () => {
+    it('detects Stripe payments', () => {
+      const stack = createStack({
+        payments: detection('Stripe'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('stripe');
+    });
+  });
+
+  describe('scanner recommendations', () => {
+    it('includes scanner MCP recommendations', () => {
+      const stack = createStack({
+        mcp: {
+          isProject: false,
+          recommended: ['custom-mcp', 'another-mcp'],
+        },
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.additional).toContain('custom-mcp');
+      expect(result.additional).toContain('another-mcp');
+    });
+
+    it('deduplicates scanner recommendations', () => {
+      const stack = createStack({
+        database: detection('Supabase'),
+        mcp: {
+          isProject: false,
+          recommended: ['supabase', 'other-mcp'],
+        },
+      });
+      const result = detectRalphMcpServers(stack);
+      // supabase should be in database, not duplicated in additional
+      expect(result.database).toBe('supabase');
+      expect(result.additional).toContain('other-mcp');
+      expect(result.additional).not.toContain('supabase');
+    });
+  });
+
+  describe('deduplication', () => {
+    it('does not duplicate MCPs in additional', () => {
+      const stack = createStack({
+        framework: detection('Next.js'),
+        deployment: [detection('Vercel')],
+      });
+      const result = detectRalphMcpServers(stack);
+      const vercelCount = result.additional.filter(m => m === 'vercel').length;
+      expect(vercelCount).toBe(1);
+    });
+  });
+});
+
+describe('convertToLegacyMcpRecommendations', () => {
+  it('always includes filesystem and git as essential', () => {
+    const result = convertToLegacyMcpRecommendations({
+      e2eTesting: 'playwright',
+      additional: [],
+    });
+    expect(result.essential).toContain('filesystem');
+    expect(result.essential).toContain('git');
+  });
+
+  it('includes playwright in essential', () => {
+    const result = convertToLegacyMcpRecommendations({
+      e2eTesting: 'playwright',
+      additional: [],
+    });
+    expect(result.essential).toContain('playwright');
+  });
+
+  it('includes database in essential when detected', () => {
+    const result = convertToLegacyMcpRecommendations({
+      e2eTesting: 'playwright',
+      database: 'supabase',
+      additional: [],
+    });
+    expect(result.essential).toContain('supabase');
+  });
+
+  it('moves additional MCPs to recommended', () => {
+    const result = convertToLegacyMcpRecommendations({
+      e2eTesting: 'playwright',
+      additional: ['docker', 'vercel'],
+    });
+    expect(result.recommended).toContain('docker');
+    expect(result.recommended).toContain('vercel');
+  });
+
+  it('returns correct structure for full stack', () => {
+    const result = convertToLegacyMcpRecommendations({
+      e2eTesting: 'playwright',
+      database: 'postgres',
+      additional: ['docker', 'stripe'],
+    });
+
+    expect(result.essential).toEqual(['filesystem', 'git', 'playwright', 'postgres']);
+    expect(result.recommended).toEqual(['docker', 'stripe']);
+  });
+});