wiggum-cli 0.3.2 → 0.4.0

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

package/src/ai/agents/synthesis-agent.ts

@@ -0,0 +1,240 @@
+/**
+ * Synthesis Agent (Phase 3)
+ * Merges results from parallel workers and generates implementation guidelines
+ */
+
+import { type LanguageModel } from 'ai';
+import { z } from 'zod';
+import type {
+  SynthesisInput,
+  MultiAgentAnalysis,
+  CodebaseAnalysis,
+  StackResearch,
+  McpRecommendations,
+} from './types.js';
+import { convertToLegacyMcpRecommendations } from './mcp-detector.js';
+import { isReasoningModel } from '../providers.js';
+import { logger } from '../../utils/logger.js';
+import { parseJsonSafe } from '../../utils/json-repair.js';
+import { getTracedAI } from '../../utils/tracing.js';
+
+/**
+ * Schema for synthesis output (implementation guidelines)
+ */
+const synthesisOutputSchema = z.object({
+  implementationGuidelines: z.array(z.string()).describe('Short, actionable implementation guidelines'),
+  possibleMissedTechnologies: z.array(z.string()).optional().describe('Technologies that may have been missed'),
+});
+
+/**
+ * System prompt for the Synthesis Agent
+ */
+const SYNTHESIS_AGENT_SYSTEM_PROMPT = `You are a Synthesis Agent that merges analysis results into actionable implementation guidelines.
+
+## Your Mission
+Based on the enriched context and technology research, generate:
+1. Short, actionable implementation guidelines (5-10 words each)
+2. List any technologies that may have been missed
+
+## Guidelines Style
+- Start with action verbs: "Run", "Use", "Follow", "Avoid"
+- Be specific to the detected stack
+- Include testing commands
+- Mention key patterns from the research
+- Max 7 guidelines, prioritize the most important
+
+## Example Output
+{
+  "implementationGuidelines": [
+    "Run npm test after changes",
+    "Use App Router for new pages",
+    "Follow existing component patterns in src/components",
+    "Use Zod for API validation",
+    "Run npx playwright test for E2E"
+  ],
+  "possibleMissedTechnologies": ["Redis caching"]
+}`;
+
+/**
+ * Run the Synthesis Agent to merge results and generate guidelines
+ */
+export async function runSynthesisAgent(
+  model: LanguageModel,
+  modelId: string,
+  input: SynthesisInput,
+  verbose: boolean = false
+): Promise<MultiAgentAnalysis> {
+  // Build context summary for the LLM
+  const techSummary = input.techResearch
+    .map(r => `### ${r.technology}\nBest practices: ${r.bestPractices.slice(0, 3).join(', ')}\nAnti-patterns: ${r.antiPatterns.slice(0, 2).join(', ')}`)
+    .join('\n\n');
+
+  const prompt = `Synthesize these analysis results into implementation guidelines.
+
+## Project Context
+- Type: ${input.enrichedContext.projectType}
+- Entry Points: ${input.enrichedContext.entryPoints.join(', ')}
+- Key Directories: ${Object.entries(input.enrichedContext.keyDirectories).map(([k, v]) => `${k} (${v})`).join(', ')}
+
+## Commands Available
+${Object.entries(input.enrichedContext.commands).map(([k, v]) => `- ${k}: ${v}`).join('\n')}
+
+## Technology Research
+${techSummary || 'No specific technology research available.'}
+
+## MCP Servers
+- E2E Testing: ${input.mcpServers.e2eTesting}
+- Database: ${input.mcpServers.database || 'None detected'}
+- Additional: ${input.mcpServers.additional.join(', ') || 'None'}
+
+## Analysis Plan Questions & Answers
+${Object.entries(input.enrichedContext.answeredQuestions).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n') || 'No questions answered.'}
+
+Generate concise, actionable implementation guidelines based on this analysis.`;
+
+  try {
+    const { generateObject } = getTracedAI();
+
+    const { object: synthesis } = await generateObject({
+      model,
+      schema: synthesisOutputSchema,
+      system: SYNTHESIS_AGENT_SYSTEM_PROMPT,
+      prompt,
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+      experimental_telemetry: {
+        isEnabled: true,
+        metadata: {
+          agent: 'synthesis-agent',
+          projectType: input.enrichedContext.projectType,
+          techCount: input.techResearch.length,
+        },
+      },
+    });
+
+    if (verbose) {
+      logger.info(`Synthesis Agent: Generated ${synthesis.implementationGuidelines.length} guidelines`);
+    }
+
+    // Convert to MultiAgentAnalysis format for backward compatibility
+    return buildMultiAgentAnalysis(input, synthesis.implementationGuidelines, synthesis.possibleMissedTechnologies);
+  } catch (error) {
+    if (verbose) {
+      logger.error(`Synthesis Agent error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    // Return with default guidelines
+    return buildMultiAgentAnalysis(input, getDefaultGuidelines(input), []);
+  }
+}
+
+/**
+ * Build MultiAgentAnalysis from synthesis input and generated guidelines
+ */
+function buildMultiAgentAnalysis(
+  input: SynthesisInput,
+  implementationGuidelines: string[],
+  possibleMissedTechnologies?: string[]
+): MultiAgentAnalysis {
+  // Convert EnrichedContext to CodebaseAnalysis format
+  const codebaseAnalysis: CodebaseAnalysis = {
+    projectContext: {
+      entryPoints: input.enrichedContext.entryPoints,
+      keyDirectories: input.enrichedContext.keyDirectories,
+      namingConventions: input.enrichedContext.namingConventions,
+      projectType: input.enrichedContext.projectType,
+    },
+    commands: {
+      test: input.enrichedContext.commands.test,
+      lint: input.enrichedContext.commands.lint,
+      typecheck: input.enrichedContext.commands.typecheck,
+      build: input.enrichedContext.commands.build,
+      dev: input.enrichedContext.commands.dev,
+      format: input.enrichedContext.commands.format,
+    },
+    implementationGuidelines,
+    possibleMissedTechnologies,
+  };
+
+  // Merge tech research into StackResearch format
+  const stackResearch: StackResearch = mergeTechResearch(input.techResearch);
+
+  // Convert MCP servers to legacy format
+  const mcpServers: McpRecommendations = convertToLegacyMcpRecommendations(input.mcpServers);
+
+  return {
+    codebaseAnalysis,
+    stackResearch,
+    mcpServers,
+  };
+}
+
+/**
+ * Merge multiple TechResearchResult into a single StackResearch
+ */
+function mergeTechResearch(techResearch: SynthesisInput['techResearch']): StackResearch {
+  if (techResearch.length === 0) {
+    return {
+      bestPractices: ['Follow project conventions'],
+      antiPatterns: ['Avoid skipping tests'],
+      testingTools: ['npm test'],
+      debuggingTools: ['console.log'],
+      documentationHints: ['Check official docs'],
+      researchMode: 'knowledge-only',
+    };
+  }
+
+  // Merge all research results
+  const bestPractices: string[] = [];
+  const antiPatterns: string[] = [];
+  const testingTips: string[] = [];
+  const documentationHints: string[] = [];
+  let researchMode: StackResearch['researchMode'] = 'knowledge-only';
+
+  for (const research of techResearch) {
+    bestPractices.push(...research.bestPractices);
+    antiPatterns.push(...research.antiPatterns);
+    testingTips.push(...research.testingTips);
+    documentationHints.push(...research.documentationHints);
+
+    // Use the most complete research mode
+    if (research.researchMode === 'full') researchMode = 'full';
+    else if (research.researchMode === 'web-only' && researchMode !== 'full') researchMode = 'web-only';
+    else if (research.researchMode === 'docs-only' && researchMode === 'knowledge-only') researchMode = 'docs-only';
+  }
+
+  // Deduplicate and limit
+  return {
+    bestPractices: [...new Set(bestPractices)].slice(0, 10),
+    antiPatterns: [...new Set(antiPatterns)].slice(0, 10),
+    testingTools: [...new Set(testingTips)].slice(0, 5),
+    debuggingTools: [], // Not collected in new format
+    documentationHints: [...new Set(documentationHints)].slice(0, 5),
+    researchMode,
+  };
+}
+
+/**
+ * Get default implementation guidelines when synthesis fails
+ */
+function getDefaultGuidelines(input: SynthesisInput): string[] {
+  const guidelines: string[] = [];
+
+  // Add test command if available
+  if (input.enrichedContext.commands.test) {
+    guidelines.push(`Run ${input.enrichedContext.commands.test} after changes`);
+  }
+
+  // Add build command if available
+  if (input.enrichedContext.commands.build) {
+    guidelines.push(`Run ${input.enrichedContext.commands.build} before committing`);
+  }
+
+  // Add E2E testing
+  guidelines.push(`Run npx playwright test for E2E testing`);
+
+  // Add generic guidelines
+  guidelines.push('Follow existing code patterns');
+  guidelines.push('Use TypeScript strict mode');
+
+  return guidelines.slice(0, 7);
+}