wiggum-cli 0.2.6 → 0.3.0

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

@@ -0,0 +1,298 @@
+/**
+ * Stack Researcher Agent
+ * Researches best practices and tools for the detected stack
+ * Gracefully degrades when optional services are unavailable
+ */
+
+import { generateText, stepCountIs, type LanguageModel, type Tool } from 'ai';
+import type { StackResearch, StackResearcherInput, AgentCapabilities } from './types.js';
+import type { DetectedStack } from '../../scanner/types.js';
+import { createTavilySearchTool } from '../tools/tavily.js';
+import { createContext7Tool } from '../tools/context7.js';
+import { isReasoningModel } from '../providers.js';
+import { logger } from '../../utils/logger.js';
+
+/**
+ * System prompt for Stack Researcher with tools
+ */
+const STACK_RESEARCHER_WITH_TOOLS_PROMPT = `You are a Stack Researcher agent with access to web search and documentation lookup tools.
+
+## Your Mission
+Research the detected technology stack to find:
+1. Current best practices
+2. Common anti-patterns to avoid
+3. Testing tools and patterns
+4. Debugging approaches
+5. Useful documentation links
+
+## Tools Available
+- tavilySearch: Search the web for current best practices and patterns
+- context7Lookup: Look up library documentation
+
+## Research Strategy
+1. Search for "[technology] best practices 2024"
+2. Search for "[project type] testing patterns"
+3. Look up documentation for key dependencies
+4. Search for "[framework] anti-patterns"
+
+## Output Format
+After research, output ONLY valid JSON with this structure:
+{
+  "bestPractices": [
+    "Use TypeScript strict mode",
+    "Implement proper error boundaries"
+  ],
+  "antiPatterns": [
+    "Don't use any type",
+    "Avoid prop drilling"
+  ],
+  "testingTools": [
+    "npx vitest",
+    "npx playwright test"
+  ],
+  "debuggingTools": [
+    "React DevTools",
+    "DEBUG=* npm run dev"
+  ],
+  "documentationHints": [
+    "React docs: react.dev",
+    "Vitest: vitest.dev"
+  ],
+  "researchMode": "full"
+}
+
+Keep each item concise (5-15 words max). Max 5 items per array.`;
+
+/**
+ * System prompt for Stack Researcher without tools (knowledge-only)
+ */
+const STACK_RESEARCHER_KNOWLEDGE_ONLY_PROMPT = `You are a Stack Researcher agent. You don't have web access, so rely on your training knowledge.
+
+## Your Mission
+Based on your knowledge, provide:
+1. Best practices for the detected technologies
+2. Common anti-patterns to avoid
+3. Testing tools commonly used with this stack
+4. Debugging approaches
+5. Documentation hints
+
+## Important Notes
+- Be explicit about what you're confident about vs uncertain
+- Focus on well-established practices from your training
+- Mention if something might be outdated
+
+## Output Format
+Output ONLY valid JSON with this structure:
+{
+  "bestPractices": [
+    "Use TypeScript strict mode",
+    "Implement proper error boundaries"
+  ],
+  "antiPatterns": [
+    "Don't use any type",
+    "Avoid prop drilling"
+  ],
+  "testingTools": [
+    "npm test",
+    "npx vitest"
+  ],
+  "debuggingTools": [
+    "console.log debugging",
+    "Node.js inspector"
+  ],
+  "documentationHints": [
+    "Check official docs for updates",
+    "Framework docs: [URL]"
+  ],
+  "researchMode": "knowledge-only"
+}
+
+Keep each item concise (5-15 words max). Max 5 items per array.
+Note: Research mode should reflect that you're using training knowledge only.`;
+
+/**
+ * Create the research prompt based on stack and project type
+ */
+function createResearchPrompt(stack: DetectedStack, projectType: string, hasTools: boolean): string {
+  const technologies: string[] = [];
+
+  // Collect all detected technologies
+  if (stack.framework) technologies.push(stack.framework.name);
+  if (stack.testing?.unit) technologies.push(stack.testing.unit.name);
+  if (stack.testing?.e2e) technologies.push(stack.testing.e2e.name);
+  if (stack.orm) technologies.push(stack.orm.name);
+  if (stack.database) technologies.push(stack.database.name);
+  if (stack.stateManagement) technologies.push(stack.stateManagement.name);
+  if (stack.auth) technologies.push(stack.auth.name);
+  if (stack.mcp?.isProject) technologies.push('MCP Server');
+
+  const techList = technologies.length > 0 ? technologies.join(', ') : 'Unknown stack';
+
+  if (hasTools) {
+    return `Research best practices for this stack:
+
+Project Type: ${projectType}
+Technologies: ${techList}
+
+Use the available tools to search for:
+1. Current best practices for ${projectType} projects
+2. Testing patterns for ${techList}
+3. Common anti-patterns to avoid
+
+Then produce your research findings as JSON.`;
+  }
+
+  return `Based on your knowledge, provide best practices for this stack:
+
+Project Type: ${projectType}
+Technologies: ${techList}
+
+Provide:
+1. Best practices for ${projectType} projects
+2. Testing tools commonly used with ${techList}
+3. Anti-patterns to avoid
+4. Debugging approaches
+
+Output your findings as JSON. Be clear this is based on training knowledge.`;
+}
+
+/**
+ * Determine research mode based on capabilities
+ */
+function getResearchMode(capabilities: AgentCapabilities): StackResearch['researchMode'] {
+  if (capabilities.hasTavily && capabilities.hasContext7) return 'full';
+  if (capabilities.hasTavily) return 'web-only';
+  if (capabilities.hasContext7) return 'docs-only';
+  return 'knowledge-only';
+}
+
+/**
+ * Run the Stack Researcher agent
+ */
+export async function runStackResearcher(
+  model: LanguageModel,
+  modelId: string,
+  input: StackResearcherInput,
+  options: { tavilyApiKey?: string; context7ApiKey?: string },
+  verbose: boolean = false
+): Promise<StackResearch | null> {
+  const tools: Record<string, Tool> = {};
+
+  // Add tools based on available keys
+  if (options.tavilyApiKey) {
+    tools.tavilySearch = createTavilySearchTool(options.tavilyApiKey);
+  }
+  if (options.context7ApiKey) {
+    tools.context7Lookup = createContext7Tool(options.context7ApiKey);
+  }
+
+  const hasTools = Object.keys(tools).length > 0;
+  const researchMode = getResearchMode(input.capabilities);
+
+  if (verbose) {
+    logger.info(`Stack Researcher running in ${researchMode} mode`);
+  }
+
+  const systemPrompt = hasTools
+    ? STACK_RESEARCHER_WITH_TOOLS_PROMPT
+    : STACK_RESEARCHER_KNOWLEDGE_ONLY_PROMPT;
+
+  const prompt = createResearchPrompt(input.stack, input.projectType, hasTools);
+
+  try {
+    const result = await generateText({
+      model,
+      system: systemPrompt,
+      prompt,
+      ...(hasTools ? { tools, stopWhen: stepCountIs(8) } : {}),
+      maxOutputTokens: 2000,
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+    });
+
+    // Parse the response
+    const research = parseStackResearch(result.text, result.steps, researchMode, verbose);
+    return research;
+  } catch (error) {
+    if (verbose) {
+      logger.error(`Stack Researcher error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Parse the stack research from agent response
+ */
+function parseStackResearch(
+  text: string,
+  steps: Array<{ text?: string }> | undefined,
+  researchMode: StackResearch['researchMode'],
+  verbose: boolean
+): StackResearch | null {
+  // Try to get text from the result or steps
+  let textToParse = text;
+
+  if (!textToParse || textToParse.trim() === '') {
+    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('Stack Researcher: No text output found');
+    }
+    return getDefaultStackResearch(researchMode);
+  }
+
+  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 Partial<StackResearch>;
+
+    // Build result with defaults for missing fields
+    return {
+      bestPractices: parsed.bestPractices || [],
+      antiPatterns: parsed.antiPatterns || [],
+      testingTools: parsed.testingTools || [],
+      debuggingTools: parsed.debuggingTools || [],
+      documentationHints: parsed.documentationHints || [],
+      researchMode: researchMode,
+    };
+  } catch (error) {
+    if (verbose) {
+      logger.warn(`Stack Researcher: Failed to parse JSON - ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return getDefaultStackResearch(researchMode);
+  }
+}
+
+/**
+ * Get default stack research when parsing fails
+ */
+function getDefaultStackResearch(researchMode: StackResearch['researchMode']): StackResearch {
+  return {
+    bestPractices: ['Follow project conventions', 'Write tests for new code'],
+    antiPatterns: ['Avoid skipping tests', 'Don\'t ignore type errors'],
+    testingTools: ['npm test'],
+    debuggingTools: ['console.log', 'debugger statement'],
+    documentationHints: ['Check package.json for dependencies'],
+    researchMode,
+  };
+}

package/src/ai/agents/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Agent Types and Interfaces
+ * Defines the structure for multi-agent analysis
+ */
+
+import type { ScanResult, DetectedStack } from '../../scanner/types.js';
+
+/**
+ * Codebase analysis result from the Codebase Analyst agent
+ */
+export interface CodebaseAnalysis {
+  /** Project structure and context */
+  projectContext: {
+    /** Key entry point files */
+    entryPoints: string[];
+    /** Important directories and their purposes */
+    keyDirectories: Record<string, string>;
+    /** Naming conventions used */
+    namingConventions?: string;
+    /** The primary project type (MCP Server, REST API, React SPA, CLI, Library) */
+    projectType: string;
+  };
+  /** Detected commands from package.json */
+  commands: {
+    test?: string;
+    lint?: string;
+    typecheck?: string;
+    build?: string;
+    dev?: string;
+    format?: string;
+  };
+  /** Short, actionable implementation guidelines */
+  implementationGuidelines: string[];
+  /** Additional technologies that may have been missed */
+  possibleMissedTechnologies?: string[];
+}
+
+/**
+ * Stack research result from the Stack Researcher agent
+ */
+export interface StackResearch {
+  /** Best practices for the detected stack */
+  bestPractices: string[];
+  /** Anti-patterns to avoid */
+  antiPatterns: string[];
+  /** Technology-specific testing tools */
+  testingTools: string[];
+  /** Technology-specific debugging tools */
+  debuggingTools: string[];
+  /** Documentation hints and links */
+  documentationHints: string[];
+  /** Whether research was performed with tools or knowledge-only */
+  researchMode: 'full' | 'web-only' | 'docs-only' | 'knowledge-only';
+}
+
+/**
+ * MCP server recommendations
+ */
+export interface McpRecommendations {
+  /** Essential MCP servers for this stack */
+  essential: string[];
+  /** Recommended but optional MCP servers */
+  recommended: string[];
+}
+
+/**
+ * Combined result from all agents
+ */
+export interface MultiAgentAnalysis {
+  /** Codebase analysis from the Codebase Analyst */
+  codebaseAnalysis: CodebaseAnalysis;
+  /** Stack research from the Stack Researcher */
+  stackResearch: StackResearch;
+  /** MCP server recommendations (merged from both agents) */
+  mcpServers: McpRecommendations;
+}
+
+/**
+ * Agent capabilities based on available API keys
+ */
+export interface AgentCapabilities {
+  /** Tavily web search available */
+  hasTavily: boolean;
+  /** Context7 documentation lookup available */
+  hasContext7: boolean;
+}
+
+/**
+ * Options for running agents
+ */
+export interface AgentOptions {
+  /** Tavily API key (optional) */
+  tavilyApiKey?: string;
+  /** Context7 API key (optional) */
+  context7ApiKey?: string;
+  /** Enable verbose logging */
+  verbose?: boolean;
+}
+
+/**
+ * Input for the Codebase Analyst agent
+ */
+export interface CodebaseAnalystInput {
+  /** The scan result from the scanner */
+  scanResult: ScanResult;
+  /** Project root directory */
+  projectRoot: string;
+}
+
+/**
+ * Input for the Stack Researcher agent
+ */
+export interface StackResearcherInput {
+  /** The detected stack */
+  stack: DetectedStack;
+  /** The identified project type */
+  projectType: string;
+  /** Agent capabilities */
+  capabilities: AgentCapabilities;
+}
+
+/**
+ * Input for the Orchestrator agent
+ */
+export interface OrchestratorInput {
+  /** Codebase analysis result */
+  codebaseAnalysis: CodebaseAnalysis;
+  /** Stack research result */
+  stackResearch: StackResearch;
+  /** The detected stack */
+  stack: DetectedStack;
+}

package/src/ai/enhancer.ts

@@ -8,6 +8,7 @@ import type { ScanResult, DetectedStack, DetectionResult } from '../scanner/type
 import { getModel, type AIProvider, hasApiKey, getApiKeyEnvVar, isReasoningModel } from './providers.js';
 import { SYSTEM_PROMPT, SYSTEM_PROMPT_AGENTIC, createAnalysisPrompt } from './prompts.js';
 import { createExplorationTools } from './tools.js';
+import { runMultiAgentAnalysis, type MultiAgentAnalysis } from './agents/index.js';
 import { logger } from '../utils/logger.js';
 
 /**
@@ -44,6 +45,32 @@ export interface McpRecommendations {
   recommended?: string[];
 }
 
+/**
+ * Technology-specific testing and debugging tools
+ */
+export interface TechnologyTools {
+  /** Testing commands specific to the detected technologies */
+  testing?: string[];
+  /** Debugging/inspection tools for the stack */
+  debugging?: string[];
+  /** Linting/validation tools beyond the standard ones */
+  validation?: string[];
+}
+
+/**
+ * Technology-specific best practices
+ */
+export interface TechnologyPractices {
+  /** The primary project type (e.g., "MCP Server", "REST API", "React SPA") */
+  projectType?: string;
+  /** Practices specific to the detected technologies */
+  practices?: string[];
+  /** Anti-patterns to avoid for this stack */
+  antiPatterns?: string[];
+  /** Links to relevant documentation (optional) */
+  documentationHints?: string[];
+}
+
 /**
  * AI analysis result - focused on actionable outputs
  */
@@ -58,6 +85,10 @@ export interface AIAnalysisResult {
   mcpServers?: McpRecommendations;
   /** Additional technologies that may have been missed */
   possibleMissedTechnologies?: string[];
+  /** Technology-specific tools for testing/debugging */
+  technologyTools?: TechnologyTools;
+  /** Technology-specific best practices based on detected stack */
+  technologyPractices?: TechnologyPractices;
 }
 
 /**
@@ -79,6 +110,10 @@ export interface EnhancerOptions {
   verbose?: boolean;
   /** Use agentic mode with tools for deeper codebase exploration */
   agentic?: boolean;
+  /** Tavily API key for web search (optional) */
+  tavilyApiKey?: string;
+  /** Context7 API key for documentation lookup (optional) */
+  context7ApiKey?: string;
 }
 
 /**
@@ -173,12 +208,16 @@ export class AIEnhancer {
   private model?: string;
   private verbose: boolean;
   private agentic: boolean;
+  private tavilyApiKey?: string;
+  private context7ApiKey?: string;
 
   constructor(options: EnhancerOptions = {}) {
     this.provider = options.provider || 'anthropic';
     this.model = options.model;
     this.verbose = options.verbose || false;
     this.agentic = options.agentic || false;
+    this.tavilyApiKey = options.tavilyApiKey;
+    this.context7ApiKey = options.context7ApiKey;
   }
 
   /**
@@ -285,12 +324,41 @@ export class AIEnhancer {
   }
 
   /**
-   * Agentic enhancement mode - use tools to explore codebase
+   * Agentic enhancement mode - use multi-agent system to explore codebase
    */
   private async enhanceAgentic(
     model: ReturnType<typeof getModel>['model'],
     modelId: string,
     scanResult: ScanResult
+  ): Promise<AIAnalysisResult | null> {
+    // Use the multi-agent system for deeper analysis
+    const multiAgentResult = await runMultiAgentAnalysis(
+      model,
+      modelId,
+      scanResult,
+      {
+        tavilyApiKey: this.tavilyApiKey,
+        context7ApiKey: this.context7ApiKey,
+        verbose: this.verbose,
+      }
+    );
+
+    if (!multiAgentResult) {
+      // Fall back to simple agentic mode
+      return this.enhanceLegacyAgentic(model, modelId, scanResult);
+    }
+
+    // Convert MultiAgentAnalysis to AIAnalysisResult for backward compatibility
+    return convertMultiAgentToAIAnalysis(multiAgentResult);
+  }
+
+  /**
+   * Legacy agentic mode (fallback when multi-agent fails)
+   */
+  private async enhanceLegacyAgentic(
+    model: ReturnType<typeof getModel>['model'],
+    modelId: string,
+    scanResult: ScanResult
   ): Promise<AIAnalysisResult | null> {
     const tools = createExplorationTools(scanResult.projectRoot);
 
@@ -325,7 +393,6 @@ When done exploring, output your final analysis as valid JSON matching this stru
 }`;
 
     // Use agentic loop - AI will call tools until it has enough info
-    // stopWhen: stepCountIs(10) allows up to 10 tool-calling steps
     const result = await generateText({
       model,
       system: SYSTEM_PROMPT_AGENTIC,
@@ -333,7 +400,6 @@ When done exploring, output your final analysis as valid JSON matching this stru
       tools,
       stopWhen: stepCountIs(10),
       maxOutputTokens: 4000,
-      // Reasoning models don't support temperature
       ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
     });
 
@@ -346,7 +412,6 @@ When done exploring, output your final analysis as valid JSON matching this stru
         logger.info(`No direct text output, checking ${result.steps?.length || 0} steps...`);
       }
 
-      // Look through steps for text content (from last to first)
       const steps = result.steps || [];
       for (let i = steps.length - 1; i >= 0; i--) {
         const step = steps[i];
@@ -368,6 +433,39 @@ When done exploring, output your final analysis as valid JSON matching this stru
   }
 }
 
+/**
+ * Convert MultiAgentAnalysis to AIAnalysisResult for backward compatibility
+ */
+function convertMultiAgentToAIAnalysis(multiAgent: MultiAgentAnalysis): AIAnalysisResult {
+  const { codebaseAnalysis, stackResearch, mcpServers } = multiAgent;
+
+  return {
+    projectContext: {
+      entryPoints: codebaseAnalysis.projectContext.entryPoints,
+      keyDirectories: codebaseAnalysis.projectContext.keyDirectories,
+      namingConventions: codebaseAnalysis.projectContext.namingConventions,
+    },
+    commands: codebaseAnalysis.commands,
+    implementationGuidelines: codebaseAnalysis.implementationGuidelines,
+    mcpServers: {
+      essential: mcpServers.essential,
+      recommended: mcpServers.recommended,
+    },
+    possibleMissedTechnologies: codebaseAnalysis.possibleMissedTechnologies,
+    technologyTools: {
+      testing: stackResearch.testingTools,
+      debugging: stackResearch.debuggingTools,
+      validation: [],
+    },
+    technologyPractices: {
+      projectType: codebaseAnalysis.projectContext.projectType,
+      practices: stackResearch.bestPractices,
+      antiPatterns: stackResearch.antiPatterns,
+      documentationHints: stackResearch.documentationHints,
+    },
+  };
+}
+
 /**
  * Convenience function to enhance scan results with AI
  */

package/src/ai/index.ts

@@ -7,10 +7,17 @@
 export {
   type AIProvider,
   type ProviderConfig,
+  type OptionalService,
   getModel,
   hasApiKey,
   getAvailableProvider,
   getApiKeyEnvVar,
+  OPTIONAL_SERVICE_ENV_VARS,
+  hasTavilyKey,
+  getTavilyKey,
+  hasContext7Key,
+  getContext7Key,
+  getOptionalServicesStatus,
 } from './providers.js';
 
 // Analysis prompts
@@ -29,11 +36,34 @@ export {
   RIPGREP_SKILL,
 } from './tools.js';
 
+// New tools (Tavily, Context7)
+export {
+  createTavilySearchTool,
+  canUseTavily,
+  createContext7Tool,
+  canUseContext7,
+} from './tools/index.js';
+
+// Agents
+export {
+  runMultiAgentAnalysis,
+  runCodebaseAnalyst,
+  runStackResearcher,
+  runOrchestrator,
+  mergeAgentResults,
+  type CodebaseAnalysis,
+  type StackResearch,
+  type McpRecommendations,
+  type MultiAgentAnalysis,
+  type AgentCapabilities,
+  type AgentOptions,
+} from './agents/index.js';
+
 // AI enhancer
 export {
   type ProjectContext,
   type DetectedCommands,
-  type McpRecommendations,
+  type McpRecommendations as McpRecommendationsLegacy,
   type AIAnalysisResult,
   type EnhancedScanResult,
   type EnhancerOptions,