wiggum-cli 0.2.5 → 0.3.0

package/src/ai/agents/codebase-analyst.ts

@@ -0,0 +1,172 @@
+/**
+ * Codebase Analyst Agent
+ * Explores the codebase to understand its structure and patterns
+ */
+
+import { generateText, stepCountIs, type LanguageModel } from 'ai';
+import type { CodebaseAnalysis, CodebaseAnalystInput } from './types.js';
+import { createExplorationTools } from '../tools.js';
+import { isReasoningModel } from '../providers.js';
+import { logger } from '../../utils/logger.js';
+
+/**
+ * System prompt for the Codebase Analyst agent
+ */
+const CODEBASE_ANALYST_SYSTEM_PROMPT = `You are a Codebase Analyst agent. Your job is to thoroughly explore a codebase and produce a structured analysis.
+
+## Your Mission
+Explore the codebase to understand:
+1. Project structure and entry points
+2. Key directories and their purposes
+3. Naming conventions
+4. Available commands (from package.json)
+5. The primary project type
+
+## Exploration Strategy
+1. First, list the root directory to understand project structure
+2. Read package.json to understand scripts and dependencies
+3. Search for key patterns: entry points, routes, components
+4. Identify the PROJECT TYPE:
+   - MCP Server: Has @modelcontextprotocol dependencies
+   - REST API: Express/Fastify/Hono with route handlers
+   - React SPA: React with components, no server-side rendering
+   - Next.js App: Next.js with app or pages directory
+   - CLI Tool: Has bin entry in package.json
+   - Library: Published package without app entry
+
+## Tools Available
+- searchCode: Search using ripgrep patterns
+- readFile: Read file contents
+- listDirectory: List directory structure
+- getPackageInfo: Get package.json info
+
+## Output Format
+After exploration, output ONLY valid JSON with this exact structure:
+{
+  "projectContext": {
+    "entryPoints": ["src/index.ts"],
+    "keyDirectories": {"src/routes": "API routes"},
+    "namingConventions": "camelCase files, PascalCase components",
+    "projectType": "MCP Server"
+  },
+  "commands": {
+    "test": "npm test",
+    "lint": "npm run lint",
+    "build": "npm run build",
+    "dev": "npm run dev"
+  },
+  "implementationGuidelines": [
+    "Run npm test after changes",
+    "Use Zod for validation"
+  ],
+  "possibleMissedTechnologies": ["Redis"]
+}
+
+Keep each guideline to 5-10 words max. Max 7 guidelines.`;
+
+/**
+ * Run the Codebase Analyst agent
+ */
+export async function runCodebaseAnalyst(
+  model: LanguageModel,
+  modelId: string,
+  input: CodebaseAnalystInput,
+  verbose: boolean = false
+): Promise<CodebaseAnalysis | null> {
+  const tools = createExplorationTools(input.projectRoot);
+
+  const prompt = `Analyze this codebase and produce a structured analysis.
+
+Project: ${input.projectRoot}
+
+Start by exploring the directory structure and package.json, then produce your analysis as JSON.`;
+
+  try {
+    const result = await generateText({
+      model,
+      system: CODEBASE_ANALYST_SYSTEM_PROMPT,
+      prompt,
+      tools,
+      stopWhen: stepCountIs(12),
+      maxOutputTokens: 3000,
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+    });
+
+    // Extract JSON from response
+    const analysis = parseCodebaseAnalysis(result.text, result.steps, verbose);
+    return analysis;
+  } catch (error) {
+    if (verbose) {
+      logger.error(`Codebase Analyst error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Parse the codebase analysis from agent response
+ */
+function parseCodebaseAnalysis(
+  text: string,
+  steps: Array<{ text?: string }> | undefined,
+  verbose: boolean
+): CodebaseAnalysis | null {
+  // Try to get text from the result or steps
+  let textToParse = text;
+
+  if (!textToParse || textToParse.trim() === '') {
+    // Look through steps for text content
+    const stepsList = steps || [];
+    for (let i = stepsList.length - 1; i >= 0; i--) {
+      const step = stepsList[i];
+      if (step.text && step.text.trim() !== '') {
+        textToParse = step.text;
+        break;
+      }
+    }
+  }
+
+  if (!textToParse || textToParse.trim() === '') {
+    if (verbose) {
+      logger.warn('Codebase Analyst: No text output found');
+    }
+    return null;
+  }
+
+  try {
+    // Remove markdown code blocks if present
+    let jsonText = textToParse;
+    const jsonMatch = textToParse.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (jsonMatch) {
+      jsonText = jsonMatch[1];
+    }
+
+    // Find JSON object
+    const objectMatch = jsonText.match(/\{[\s\S]*\}/);
+    if (objectMatch) {
+      jsonText = objectMatch[0];
+    }
+
+    const parsed = JSON.parse(jsonText) as CodebaseAnalysis;
+
+    // Validate required fields
+    if (!parsed.projectContext || !parsed.commands) {
+      if (verbose) {
+        logger.warn('Codebase Analyst: Missing required fields in response');
+      }
+      return null;
+    }
+
+    // Ensure projectType is set
+    if (!parsed.projectContext.projectType) {
+      parsed.projectContext.projectType = 'Unknown';
+    }
+
+    return parsed;
+  } catch (error) {
+    if (verbose) {
+      logger.warn(`Codebase Analyst: Failed to parse JSON - ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return null;
+  }
+}

package/src/ai/agents/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Agents Index
+ * Exports all agent types and functions
+ */
+
+// Types
+export type {
+  CodebaseAnalysis,
+  StackResearch,
+  McpRecommendations,
+  MultiAgentAnalysis,
+  AgentCapabilities,
+  AgentOptions,
+  CodebaseAnalystInput,
+  StackResearcherInput,
+  OrchestratorInput,
+} from './types.js';
+
+// Agents
+export { runCodebaseAnalyst } from './codebase-analyst.js';
+export { runStackResearcher } from './stack-researcher.js';
+export { runOrchestrator, mergeAgentResults } from './orchestrator.js';
+
+// Re-export for convenience
+import type { LanguageModel } from 'ai';
+import type { ScanResult, DetectedStack } from '../../scanner/types.js';
+import type {
+  MultiAgentAnalysis,
+  AgentCapabilities,
+  AgentOptions,
+} from './types.js';
+import { runCodebaseAnalyst } from './codebase-analyst.js';
+import { runStackResearcher } from './stack-researcher.js';
+import { runOrchestrator, mergeAgentResults } from './orchestrator.js';
+import { logger } from '../../utils/logger.js';
+
+/**
+ * Run the full multi-agent analysis pipeline
+ */
+export async function runMultiAgentAnalysis(
+  model: LanguageModel,
+  modelId: string,
+  scanResult: ScanResult,
+  options: AgentOptions = {}
+): Promise<MultiAgentAnalysis | null> {
+  const { tavilyApiKey, context7ApiKey, verbose = false } = options;
+
+  // Determine capabilities
+  const capabilities: AgentCapabilities = {
+    hasTavily: !!tavilyApiKey,
+    hasContext7: !!context7ApiKey,
+  };
+
+  if (verbose) {
+    logger.info('Starting multi-agent analysis...');
+    logger.info(`Capabilities: Tavily=${capabilities.hasTavily}, Context7=${capabilities.hasContext7}`);
+  }
+
+  // Run Codebase Analyst
+  if (verbose) {
+    logger.info('Running Codebase Analyst...');
+  }
+
+  const codebaseAnalysis = await runCodebaseAnalyst(
+    model,
+    modelId,
+    {
+      scanResult,
+      projectRoot: scanResult.projectRoot,
+    },
+    verbose
+  );
+
+  if (!codebaseAnalysis) {
+    if (verbose) {
+      logger.warn('Codebase Analyst failed, using defaults');
+    }
+    return null;
+  }
+
+  // Run Stack Researcher
+  if (verbose) {
+    logger.info('Running Stack Researcher...');
+  }
+
+  const stackResearch = await runStackResearcher(
+    model,
+    modelId,
+    {
+      stack: scanResult.stack,
+      projectType: codebaseAnalysis.projectContext.projectType,
+      capabilities,
+    },
+    { tavilyApiKey, context7ApiKey },
+    verbose
+  );
+
+  if (!stackResearch) {
+    if (verbose) {
+      logger.warn('Stack Researcher failed, using defaults');
+    }
+    // Continue with defaults - stack research is optional
+  }
+
+  // Run Orchestrator to merge results
+  if (verbose) {
+    logger.info('Running Orchestrator...');
+  }
+
+  const mcpServers = await runOrchestrator(
+    model,
+    modelId,
+    {
+      codebaseAnalysis,
+      stackResearch: stackResearch || getDefaultStackResearch(),
+      stack: scanResult.stack,
+    },
+    verbose
+  );
+
+  // Merge all results
+  const finalResult = mergeAgentResults(
+    codebaseAnalysis,
+    stackResearch || getDefaultStackResearch(),
+    mcpServers
+  );
+
+  if (verbose) {
+    logger.info('Multi-agent analysis complete');
+  }
+
+  return finalResult;
+}
+
+/**
+ * Get default stack research when agent fails
+ */
+function getDefaultStackResearch() {
+  return {
+    bestPractices: ['Follow project conventions'],
+    antiPatterns: ['Avoid skipping tests'],
+    testingTools: ['npm test'],
+    debuggingTools: ['console.log'],
+    documentationHints: ['Check official docs'],
+    researchMode: 'knowledge-only' as const,
+  };
+}

package/src/ai/agents/orchestrator.ts

@@ -0,0 +1,222 @@
+/**
+ * Orchestrator Agent
+ * Coordinates the multi-agent analysis and merges results
+ */
+
+import { generateText, type LanguageModel } from 'ai';
+import type {
+  CodebaseAnalysis,
+  StackResearch,
+  MultiAgentAnalysis,
+  McpRecommendations,
+  OrchestratorInput,
+} from './types.js';
+import type { DetectedStack } from '../../scanner/types.js';
+import { isReasoningModel } from '../providers.js';
+import { logger } from '../../utils/logger.js';
+
+/**
+ * System prompt for the Orchestrator
+ */
+const ORCHESTRATOR_SYSTEM_PROMPT = `You are an Orchestrator agent that merges analysis results into final recommendations.
+
+Your job is to:
+1. Review the codebase analysis and stack research
+2. Recommend appropriate MCP servers for the stack
+3. Produce a final merged recommendation
+
+## MCP Server Selection Guidelines
+Based on the detected stack, recommend these MCP servers:
+
+**Always Essential:**
+- filesystem: For file operations (all projects)
+- git: For version control (all projects)
+
+**By Project Type:**
+- MCP Server: memory (for context)
+- REST API: fetch (external APIs), postgres/sqlite (databases)
+- React/Next.js: fetch (data fetching), memory (state persistence)
+- CLI Tool: filesystem (primary), memory (caching)
+- Library: git (versioning)
+
+**By Technology:**
+- Docker in use → docker MCP server
+- PostgreSQL → postgres MCP server
+- SQLite → sqlite MCP server
+- AWS services → aws-kb-retrieval MCP server
+- GitHub workflows → github MCP server
+
+## Output Format
+Output ONLY valid JSON:
+{
+  "mcpServers": {
+    "essential": ["filesystem", "git"],
+    "recommended": ["docker", "postgres"]
+  }
+}`;
+
+/**
+ * Run the Orchestrator to merge results and recommend MCP servers
+ */
+export async function runOrchestrator(
+  model: LanguageModel,
+  modelId: string,
+  input: OrchestratorInput,
+  verbose: boolean = false
+): Promise<McpRecommendations> {
+  const prompt = createOrchestratorPrompt(input);
+
+  try {
+    const result = await generateText({
+      model,
+      system: ORCHESTRATOR_SYSTEM_PROMPT,
+      prompt,
+      maxOutputTokens: 1000,
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.2 }),
+    });
+
+    const mcpServers = parseMcpRecommendations(result.text, input.stack, verbose);
+    return mcpServers;
+  } catch (error) {
+    if (verbose) {
+      logger.error(`Orchestrator error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Return default recommendations based on project type
+    return getDefaultMcpRecommendations(input.codebaseAnalysis.projectContext.projectType, input.stack);
+  }
+}
+
+/**
+ * Create the orchestrator prompt
+ */
+function createOrchestratorPrompt(input: OrchestratorInput): string {
+  const { codebaseAnalysis, stackResearch, stack } = input;
+
+  // Summarize the stack
+  const stackSummary: string[] = [];
+  if (stack.framework) stackSummary.push(`Framework: ${stack.framework.name}`);
+  if (stack.database) stackSummary.push(`Database: ${stack.database.name}`);
+  if (stack.orm) stackSummary.push(`ORM: ${stack.orm.name}`);
+  if (stack.deployment?.length) stackSummary.push(`Deployment: ${stack.deployment.map(d => d.name).join(', ')}`);
+  if (stack.mcp?.isProject) stackSummary.push('This is an MCP Server project');
+
+  return `Analyze these results and recommend MCP servers:
+
+## Project Type
+${codebaseAnalysis.projectContext.projectType}
+
+## Detected Stack
+${stackSummary.join('\n') || 'Unknown'}
+
+## Testing Tools Identified
+${stackResearch.testingTools.join(', ') || 'None identified'}
+
+## Debugging Tools
+${stackResearch.debuggingTools.join(', ') || 'None identified'}
+
+Based on this analysis, recommend essential and optional MCP servers.
+Output as JSON with "mcpServers" containing "essential" and "recommended" arrays.`;
+}
+
+/**
+ * Parse MCP recommendations from orchestrator response
+ */
+function parseMcpRecommendations(
+  text: string,
+  stack: DetectedStack,
+  verbose: boolean
+): McpRecommendations {
+  if (!text || text.trim() === '') {
+    return getDefaultMcpRecommendations('Unknown', stack);
+  }
+
+  try {
+    // Remove markdown code blocks
+    let jsonText = text;
+    const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (jsonMatch) {
+      jsonText = jsonMatch[1];
+    }
+
+    // Find JSON object
+    const objectMatch = jsonText.match(/\{[\s\S]*\}/);
+    if (objectMatch) {
+      jsonText = objectMatch[0];
+    }
+
+    const parsed = JSON.parse(jsonText) as { mcpServers?: McpRecommendations };
+
+    if (parsed.mcpServers) {
+      return {
+        essential: parsed.mcpServers.essential || ['filesystem', 'git'],
+        recommended: parsed.mcpServers.recommended || [],
+      };
+    }
+
+    return getDefaultMcpRecommendations('Unknown', stack);
+  } catch (error) {
+    if (verbose) {
+      logger.warn(`Orchestrator: Failed to parse JSON - ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return getDefaultMcpRecommendations('Unknown', stack);
+  }
+}
+
+/**
+ * Get default MCP recommendations based on project type and stack
+ */
+function getDefaultMcpRecommendations(projectType: string, stack: DetectedStack): McpRecommendations {
+  const essential: string[] = ['filesystem', 'git'];
+  const recommended: string[] = [];
+
+  // Add based on project type
+  const lowerType = projectType.toLowerCase();
+
+  if (lowerType.includes('mcp')) {
+    recommended.push('memory');
+  }
+
+  if (lowerType.includes('api') || lowerType.includes('server')) {
+    recommended.push('fetch');
+  }
+
+  // Add based on detected stack
+  if (stack.database) {
+    const dbName = stack.database.name.toLowerCase();
+    if (dbName.includes('postgres')) {
+      recommended.push('postgres');
+    } else if (dbName.includes('sqlite')) {
+      recommended.push('sqlite');
+    }
+  }
+
+  if (stack.deployment?.some(d => d.name.toLowerCase().includes('docker'))) {
+    recommended.push('docker');
+  }
+
+  // Add from existing MCP recommendations in stack
+  if (stack.mcp?.recommended) {
+    for (const rec of stack.mcp.recommended) {
+      if (!essential.includes(rec) && !recommended.includes(rec)) {
+        recommended.push(rec);
+      }
+    }
+  }
+
+  return { essential, recommended };
+}
+
+/**
+ * Merge all agent results into a final MultiAgentAnalysis
+ */
+export function mergeAgentResults(
+  codebaseAnalysis: CodebaseAnalysis,
+  stackResearch: StackResearch,
+  mcpServers: McpRecommendations
+): MultiAgentAnalysis {
+  return {
+    codebaseAnalysis,
+    stackResearch,
+    mcpServers,
+  };
+}