wiggum-cli 0.3.2 → 0.4.1

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']);
+  });
+});

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

@@ -0,0 +1,210 @@
+/**
+ * MCP Detector (Phase 3 helper)
+ * Detects ralph-essential MCP servers based on the detected stack
+ *
+ * This is a pure function (no LLM) - uses rule-based detection for efficiency
+ */
+
+import type { DetectedStack } from '../../scanner/types.js';
+import type { RalphMcpServers } from './types.js';
+
+/**
+ * Database name to MCP server mapping
+ */
+const DATABASE_MCP_MAP: Record<string, string> = {
+  supabase: 'supabase',
+  convex: 'convex',
+  postgres: 'postgres',
+  postgresql: 'postgres',
+  sqlite: 'sqlite',
+  firebase: 'firebase',
+  firestore: 'firebase',
+  mongodb: 'mongodb',
+  mysql: 'mysql',
+  redis: 'redis',
+  planetscale: 'planetscale',
+  neon: 'postgres', // Neon is PostgreSQL-compatible
+  turso: 'sqlite',  // Turso is SQLite-compatible
+};
+
+/**
+ * Framework-specific MCP recommendations
+ */
+const FRAMEWORK_MCP_MAP: Record<string, string[]> = {
+  'next.js': ['vercel'],
+  'nextjs': ['vercel'],
+  'vercel': ['vercel'],
+  'remix': [],
+  'astro': [],
+  'nuxt': [],
+  'sveltekit': [],
+};
+
+/**
+ * Service-specific MCP recommendations
+ */
+const SERVICE_MCP_MAP: Record<string, string> = {
+  stripe: 'stripe',
+  clerk: 'clerk',
+  auth0: 'auth0',
+  github: 'github',
+  gitlab: 'gitlab',
+  aws: 'aws',
+  gcp: 'gcp',
+  azure: 'azure',
+  docker: 'docker',
+  kubernetes: 'kubernetes',
+  k8s: 'kubernetes',
+  posthog: 'posthog',
+  sentry: 'sentry',
+  resend: 'resend',
+  sendgrid: 'sendgrid',
+  twilio: 'twilio',
+};
+
+/**
+ * Detect ralph-essential MCP servers from the stack
+ *
+ * Ralph loop essentials:
+ * - Playwright: Always recommended for E2E testing
+ * - Database MCP: If database is detected
+ * - Additional MCPs based on services and deployment
+ */
+export function detectRalphMcpServers(stack: DetectedStack): RalphMcpServers {
+  const result: RalphMcpServers = {
+    e2eTesting: 'playwright', // Always recommend Playwright for ralph loop
+    additional: [],
+  };
+
+  // Detect database MCP
+  if (stack.database) {
+    const dbName = stack.database.name.toLowerCase();
+
+    // Check direct mapping
+    for (const [key, mcp] of Object.entries(DATABASE_MCP_MAP)) {
+      if (dbName.includes(key)) {
+        result.database = mcp;
+        break;
+      }
+    }
+  }
+
+  // Check ORM for database hints
+  if (!result.database && stack.orm) {
+    const ormName = stack.orm.name.toLowerCase();
+    if (ormName.includes('prisma') || ormName.includes('drizzle')) {
+      // These ORMs often use PostgreSQL by default
+      // But we don't set a default - let it be detected from actual DB config
+    }
+  }
+
+  // Detect framework-specific MCPs
+  if (stack.framework) {
+    const frameworkName = stack.framework.name.toLowerCase();
+    for (const [key, mcps] of Object.entries(FRAMEWORK_MCP_MAP)) {
+      if (frameworkName.includes(key)) {
+        result.additional.push(...mcps);
+        break;
+      }
+    }
+  }
+
+  // Detect deployment MCPs
+  if (stack.deployment) {
+    for (const deploy of stack.deployment) {
+      const deployName = deploy.name.toLowerCase();
+      if (deployName.includes('docker')) {
+        addIfNotExists(result.additional, 'docker');
+      }
+      if (deployName.includes('vercel')) {
+        addIfNotExists(result.additional, 'vercel');
+      }
+      if (deployName.includes('railway')) {
+        addIfNotExists(result.additional, 'railway');
+      }
+    }
+  }
+
+  // Detect auth provider MCPs
+  if (stack.auth) {
+    const authName = stack.auth.name.toLowerCase();
+    for (const [key, mcp] of Object.entries(SERVICE_MCP_MAP)) {
+      if (authName.includes(key)) {
+        addIfNotExists(result.additional, mcp);
+        break;
+      }
+    }
+  }
+
+  // Detect analytics MCPs
+  if (stack.analytics) {
+    for (const analytics of stack.analytics) {
+      const analyticsName = analytics.name.toLowerCase();
+      for (const [key, mcp] of Object.entries(SERVICE_MCP_MAP)) {
+        if (analyticsName.includes(key)) {
+          addIfNotExists(result.additional, mcp);
+          break;
+        }
+      }
+    }
+  }
+
+  // Detect payment MCPs
+  if (stack.payments) {
+    const paymentName = stack.payments.name.toLowerCase();
+    for (const [key, mcp] of Object.entries(SERVICE_MCP_MAP)) {
+      if (paymentName.includes(key)) {
+        addIfNotExists(result.additional, mcp);
+        break;
+      }
+    }
+  }
+
+  // Add any MCP recommendations from scanner
+  if (stack.mcp?.recommended) {
+    for (const rec of stack.mcp.recommended) {
+      const normalizedRec = rec.toLowerCase();
+      // Skip if it's the database or playwright (already handled)
+      if (normalizedRec !== result.database && normalizedRec !== 'playwright') {
+        addIfNotExists(result.additional, rec);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert RalphMcpServers to the legacy McpRecommendations format
+ * for backward compatibility with existing code
+ */
+export function convertToLegacyMcpRecommendations(ralphMcp: RalphMcpServers): {
+  essential: string[];
+  recommended: string[];
+} {
+  const essential: string[] = ['filesystem', 'git'];
+
+  // Add E2E testing as essential for ralph
+  if (ralphMcp.e2eTesting) {
+    essential.push(ralphMcp.e2eTesting);
+  }
+
+  // Add database as essential if detected
+  if (ralphMcp.database) {
+    essential.push(ralphMcp.database);
+  }
+
+  return {
+    essential,
+    recommended: ralphMcp.additional,
+  };
+}
+
+/**
+ * Helper to add item to array if not already present
+ */
+function addIfNotExists(arr: string[], item: string): void {
+  if (!arr.includes(item)) {
+    arr.push(item);
+  }
+}

package/src/ai/agents/orchestrator.ts

@@ -1,6 +1,9 @@
 /**
  * Orchestrator Agent
  * Coordinates the multi-agent analysis and merges results
+ *
+ * @deprecated Use runPlanningOrchestrator + runSynthesisAgent instead.
+ * This agent is kept for backward compatibility.
  */
 
 import type { LanguageModel } from 'ai';

package/src/ai/agents/planning-orchestrator.ts

@@ -0,0 +1,140 @@
+/**
+ * Planning Orchestrator Agent (Phase 1)
+ * Creates an analysis plan that guides the parallel workers
+ */
+
+import { type LanguageModel } from 'ai';
+import { z } from 'zod';
+import type { ScanResult } from '../../scanner/types.js';
+import type { AnalysisPlan } from './types.js';
+import { isReasoningModel } from '../providers.js';
+import { logger } from '../../utils/logger.js';
+import { getTracedAI } from '../../utils/tracing.js';
+
+/**
+ * Schema for the analysis plan output
+ */
+const analysisPlanSchema = z.object({
+  areasToExplore: z.array(z.string()).describe('Key directories and files to explore'),
+  technologiesToResearch: z.array(z.string()).describe('Technologies to research in depth'),
+  questionsToAnswer: z.array(z.string()).describe('Specific questions that need answers'),
+  estimatedComplexity: z.enum(['low', 'medium', 'high']).describe('Estimated project complexity'),
+});
+
+/**
+ * System prompt for the Planning Orchestrator
+ */
+const PLANNING_ORCHESTRATOR_SYSTEM_PROMPT = `You are a senior software architect analyzing a codebase to create an analysis plan.
+
+Based on the scan result, create a focused analysis plan that identifies:
+1. Key areas to explore (directories, config files, entry points)
+2. Technologies that need in-depth research (frameworks, libraries, tools)
+3. Specific questions that need answers for implementation guidance
+
+## Guidelines
+- Focus on areas that would benefit from deeper exploration
+- Identify technologies where best practices would be valuable
+- Ask questions that would help an AI developer implement features correctly
+- Keep lists focused (3-7 items each)
+- Consider the project type when prioritizing areas
+
+## Example Output
+{
+  "areasToExplore": ["src/", "config/", "lib/auth/"],
+  "technologiesToResearch": ["Next.js 14", "Prisma", "NextAuth"],
+  "questionsToAnswer": ["What is the authentication strategy?", "How is state managed?", "What testing patterns are used?"],
+  "estimatedComplexity": "medium"
+}`;
+
+/**
+ * Run the Planning Orchestrator to create an analysis plan
+ */
+export async function runPlanningOrchestrator(
+  model: LanguageModel,
+  modelId: string,
+  scanResult: ScanResult,
+  verbose: boolean = false
+): Promise<AnalysisPlan> {
+  // Build technology summary from scan result
+  const technologies: string[] = [];
+  const stack = scanResult.stack;
+
+  if (stack.framework) technologies.push(stack.framework.name);
+  if (stack.database) technologies.push(stack.database.name);
+  if (stack.orm) technologies.push(stack.orm.name);
+  if (stack.testing?.unit) technologies.push(stack.testing.unit.name);
+  if (stack.testing?.e2e) technologies.push(stack.testing.e2e.name);
+  if (stack.stateManagement) technologies.push(stack.stateManagement.name);
+  if (stack.auth) technologies.push(stack.auth.name);
+  if (stack.styling) technologies.push(stack.styling.name);
+  if (stack.mcp?.isProject) technologies.push('MCP Server');
+
+  const prompt = `Analyze this scan result and create an analysis plan:
+
+Project: ${scanResult.projectRoot}
+Framework: ${stack.framework?.name || 'Unknown'}
+Database: ${stack.database?.name || 'None detected'}
+Testing: ${stack.testing?.unit?.name || 'None detected'}
+Package Manager: ${stack.packageManager?.name || 'npm'}
+Detected Technologies: ${technologies.join(', ') || 'None'}
+${stack.mcp?.isProject ? 'This is an MCP Server project.' : ''}
+
+Create a focused analysis plan that will help understand this codebase.`;
+
+  try {
+    const { generateObject } = getTracedAI();
+
+    const { object: plan } = await generateObject({
+      model,
+      schema: analysisPlanSchema,
+      system: PLANNING_ORCHESTRATOR_SYSTEM_PROMPT,
+      prompt,
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+      experimental_telemetry: {
+        isEnabled: true,
+        metadata: {
+          agent: 'planning-orchestrator',
+          projectRoot: scanResult.projectRoot,
+          framework: stack.framework?.name || 'unknown',
+        },
+      },
+    });
+
+    if (verbose) {
+      logger.info(`Planning Orchestrator: ${plan.areasToExplore.length} areas, ${plan.technologiesToResearch.length} techs, ${plan.questionsToAnswer.length} questions`);
+    }
+
+    return plan;
+  } catch (error) {
+    if (verbose) {
+      logger.error(`Planning Orchestrator error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    // Return a sensible default plan
+    return getDefaultPlan(scanResult);
+  }
+}
+
+/**
+ * Get a default analysis plan when the orchestrator fails
+ */
+function getDefaultPlan(scanResult: ScanResult): AnalysisPlan {
+  const stack = scanResult.stack;
+  const technologies: string[] = [];
+
+  if (stack.framework) technologies.push(stack.framework.name);
+  if (stack.database) technologies.push(stack.database.name);
+  if (stack.orm) technologies.push(stack.orm.name);
+  if (stack.testing?.unit) technologies.push(stack.testing.unit.name);
+
+  return {
+    areasToExplore: ['src/', 'package.json'],
+    technologiesToResearch: technologies.length > 0 ? technologies : ['TypeScript'],
+    questionsToAnswer: [
+      'What is the project structure?',
+      'What are the main entry points?',
+      'How are tests organized?',
+    ],
+    estimatedComplexity: 'medium',
+  };
+}

package/src/ai/agents/stack-researcher.ts

@@ -2,6 +2,9 @@
  * Stack Researcher Agent
  * Researches best practices and tools for the detected stack
  * Gracefully degrades when optional services are unavailable
+ *
+ * @deprecated Use runTechResearcher/runTechResearchPool from tech-researcher.ts instead.
+ * This agent is kept for backward compatibility.
  */
 
 import { stepCountIs, type LanguageModel, type Tool } from 'ai';

package/src/ai/agents/stack-utils.ts

@@ -0,0 +1,34 @@
+/**
+ * Stack Utilities
+ * Shared helper functions for working with DetectedStack
+ */
+
+import type { DetectedStack } from '../../scanner/types.js';
+
+/**
+ * Detect project type from the stack
+ * Returns a human-readable project type string
+ */
+export function detectProjectType(stack: DetectedStack | undefined): string {
+  if (!stack) {
+    return 'Unknown';
+  }
+
+  if (stack.mcp?.isProject) {
+    return 'MCP Server';
+  }
+
+  if (stack.framework?.name?.includes('Next')) {
+    return 'Next.js App';
+  }
+
+  if (stack.framework?.name?.includes('React')) {
+    return 'React SPA';
+  }
+
+  if (stack.framework?.name) {
+    return `${stack.framework.name} Project`;
+  }
+
+  return 'Unknown';
+}