wiggum-cli 0.2.6 → 0.3.1

package/src/ai/enhancer.ts

@@ -3,12 +3,15 @@
  * Uses AI to analyze the codebase for deeper insights
  */
 
-import { generateText, stepCountIs } from 'ai';
+import { stepCountIs } from 'ai';
 import type { ScanResult, DetectedStack, DetectionResult } from '../scanner/types.js';
 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';
+import { parseJsonSafe } from '../utils/json-repair.js';
+import { getTracedAI, traced } from '../utils/tracing.js';
 
 /**
  * Project context from AI analysis - key structure information
@@ -44,6 +47,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 +87,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 +112,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;
 }
 
 /**
@@ -92,46 +129,26 @@ function parseAIResponse(text: string, verbose: boolean = false): AIAnalysisResu
     return null;
   }
 
-  try {
-    // Try to extract JSON from the response
-    // The AI might wrap it in markdown code blocks
-    let jsonText = text;
-
-    // Remove markdown code blocks if present
-    const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (jsonMatch) {
-      jsonText = jsonMatch[1];
-    }
-
-    // Try to find JSON object - use greedy match for the outermost braces
-    // This handles cases where there's text before/after the JSON
-    const objectMatch = jsonText.match(/\{[\s\S]*\}/);
-    if (objectMatch) {
-      jsonText = objectMatch[0];
-    }
-
-    // Try to parse JSON
-    const result = JSON.parse(jsonText) as AIAnalysisResult;
+  // Use safe JSON parser with repair capabilities
+  const result = parseJsonSafe<AIAnalysisResult>(text);
 
-    // Validate that we got the expected structure
-    if (!result || typeof result !== 'object') {
-      if (verbose) {
-        logger.warn('AI response parsed but is not an object');
-      }
-      return null;
+  if (!result) {
+    if (verbose) {
+      logger.warn('Failed to parse AI response as JSON');
+      logger.warn(`Response preview: ${text.substring(0, 500)}...`);
     }
+    return null;
+  }
 
-    return result;
-  } catch (error) {
+  // Validate that we got the expected structure
+  if (typeof result !== 'object') {
     if (verbose) {
-      logger.warn(`Failed to parse AI response as JSON: ${error instanceof Error ? error.message : String(error)}`);
-      // Log first 500 chars of response for debugging
-      logger.warn(`Response preview: ${text.substring(0, 500)}...`);
-    } else {
-      logger.warn('Failed to parse AI response as JSON');
+      logger.warn('AI response parsed but is not an object');
     }
     return null;
   }
+
+  return result;
 }
 
 /**
@@ -173,12 +190,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;
   }
 
   /**
@@ -271,6 +292,7 @@ export class AIEnhancer {
     scanResult: ScanResult
   ): Promise<AIAnalysisResult | null> {
     const prompt = createAnalysisPrompt(scanResult);
+    const { generateText } = getTracedAI();
 
     const { text } = await generateText({
       model,
@@ -279,20 +301,54 @@ export class AIEnhancer {
       maxOutputTokens: 2000,
       // Reasoning models don't support temperature
       ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+      experimental_telemetry: {
+        isEnabled: true,
+        metadata: { phase: 'simple-analysis', projectRoot: scanResult.projectRoot },
+      },
     });
 
     return parseAIResponse(text);
   }
 
   /**
-   * 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);
+    const { generateText } = getTracedAI();
 
     const prompt = `Analyze this codebase and produce configuration for AI-assisted development.
 
@@ -325,7 +381,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,8 +388,11 @@ 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 }),
+      experimental_telemetry: {
+        isEnabled: true,
+        metadata: { phase: 'legacy-agentic', projectRoot: scanResult.projectRoot },
+      },
     });
 
     // Try to get text from the result
@@ -346,7 +404,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 +425,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,

package/src/ai/prompts.ts

@@ -100,6 +100,8 @@ Your goal is to thoroughly understand the codebase structure and produce actiona
 3. Search for key patterns: entry points, routes, components, tests
 4. Identify naming conventions by examining existing files
 5. Look for existing documentation (.md files, README)
+6. Determine the PROJECT TYPE (e.g., MCP server, REST API, React SPA, CLI tool, library)
+7. Based on project type, include TECHNOLOGY-SPECIFIC testing/debugging tools
 
 ## Tools Available
 You have these tools to explore the codebase:
@@ -110,6 +112,30 @@ You have these tools to explore the codebase:
 
 ${RIPGREP_SKILL}
 
+## Technology-Specific Guidance
+
+When you detect specific project types, include their specialized tools:
+
+**MCP Server Projects** (detected by @modelcontextprotocol dependencies):
+- Testing: "npx @anthropic-ai/mcp-inspector" for interactive debugging
+- Practices: Follow MCP protocol spec, validate tool schemas, handle resources properly
+
+**REST APIs** (Express, Fastify, Hono, etc.):
+- Testing: API testing tools (supertest, httpie, curl examples)
+- Debugging: Request logging, OpenAPI validation
+
+**React/Next.js Projects**:
+- Testing: React Testing Library patterns, Storybook for components
+- Debugging: React DevTools, component isolation
+
+**CLI Tools**:
+- Testing: Integration tests with actual CLI invocation
+- Debugging: --verbose flags, debug logging patterns
+
+**Libraries/Packages**:
+- Testing: Unit tests with high coverage, type checking
+- Practices: Semantic versioning, changelog maintenance
+
 ## Output Requirements
 After exploration, output valid JSON with:
 - projectContext: entry points, key directories, naming conventions
@@ -117,8 +143,11 @@ After exploration, output valid JSON with:
 - implementationGuidelines: short actionable rules (5-10 words each, max 7)
 - mcpServers: essential and recommended servers
 - possibleMissedTechnologies: technologies that might be in use
+- technologyTools: testing, debugging, and validation tools specific to this project type
+- technologyPractices: projectType, practices, antiPatterns, documentationHints
 
-Be concise. Focus on WHAT TO DO, not what exists.`;
+Be concise. Focus on WHAT TO DO, not what exists.
+Include SPECIFIC testing/debugging commands for the detected project type.`;
 
 /**
  * System prompt for codebase analysis (simple mode - no tools)
@@ -133,7 +162,16 @@ Rules:
 - Focus on WHAT TO DO, not what exists
 - Include specific file paths and commands
 - Max 5-7 items per array
-- No explanations, just actionable rules`;
+- No explanations, just actionable rules
+- CRITICAL: Include technology-specific testing and debugging tools
+- Identify the PROJECT TYPE and provide stack-specific practices
+
+Technology-specific tools to consider:
+- MCP servers: "npx @anthropic-ai/mcp-inspector" for testing
+- REST APIs: supertest, curl examples, OpenAPI validation
+- React apps: React Testing Library, Storybook, DevTools
+- CLI tools: integration tests, --verbose flags
+- Libraries: high coverage unit tests, semantic versioning`;
 
 /**
  * Create the codebase analysis prompt
@@ -175,16 +213,41 @@ Respond with this JSON structure (keep values SHORT - 5-10 words max per item):
     "essential": ["filesystem", "git"],
     "recommended": ["docker", "postgres"]
   },
-  "possibleMissedTechnologies": ["Redis", "WebSockets"]
+  "possibleMissedTechnologies": ["Redis", "WebSockets"],
+  "technologyTools": {
+    "testing": ["npx @anthropic-ai/mcp-inspector", "node test/test-*.js"],
+    "debugging": ["--verbose flag", "DEBUG=* env var"],
+    "validation": ["npx tsc --noEmit", "npm run lint"]
+  },
+  "technologyPractices": {
+    "projectType": "MCP Server",
+    "practices": [
+      "Validate tool input schemas with Zod",
+      "Return structured JSON from tools",
+      "Handle errors with proper MCP error codes"
+    ],
+    "antiPatterns": [
+      "Don't expose internal errors to clients",
+      "Avoid blocking operations in tool handlers"
+    ],
+    "documentationHints": [
+      "MCP spec: modelcontextprotocol.io/docs",
+      "Inspector: modelcontextprotocol.io/docs/tools/inspector"
+    ]
+  }
 }
 
-Important:
+CRITICAL:
+- Identify the PROJECT TYPE first (MCP Server, REST API, React SPA, CLI, Library, etc.)
+- Include technology-specific testing tools (e.g., MCP Inspector for MCP projects)
+- Include technology-specific debugging approaches
 - implementationGuidelines should be short rules (not analysis prompts)
 - Include actual file paths from this project
 - Infer commands from package.json patterns
 - Max 5-7 items per array`;
 }
 
+
 /**
  * Prompt for validating and improving scanner results
  */

package/src/ai/providers.ts

@@ -30,6 +30,16 @@ const API_KEY_ENV_VARS: Record<AIProvider, string> = {
   openrouter: 'OPENROUTER_API_KEY',
 };
 
+/**
+ * Environment variable names for optional services
+ */
+export const OPTIONAL_SERVICE_ENV_VARS = {
+  tavily: 'TAVILY_API_KEY',
+  context7: 'CONTEXT7_API_KEY',
+} as const;
+
+export type OptionalService = keyof typeof OPTIONAL_SERVICE_ENV_VARS;
+
 /**
  * Model option with label and value
  */
@@ -184,3 +194,41 @@ const REASONING_MODELS = [
 export function isReasoningModel(modelId: string): boolean {
   return REASONING_MODELS.some(m => modelId.startsWith(m));
 }
+
+/**
+ * Check if Tavily API key is available
+ */
+export function hasTavilyKey(): boolean {
+  return !!process.env[OPTIONAL_SERVICE_ENV_VARS.tavily];
+}
+
+/**
+ * Get the Tavily API key
+ */
+export function getTavilyKey(): string | undefined {
+  return process.env[OPTIONAL_SERVICE_ENV_VARS.tavily];
+}
+
+/**
+ * Check if Context7 API key is available
+ */
+export function hasContext7Key(): boolean {
+  return !!process.env[OPTIONAL_SERVICE_ENV_VARS.context7];
+}
+
+/**
+ * Get the Context7 API key
+ */
+export function getContext7Key(): string | undefined {
+  return process.env[OPTIONAL_SERVICE_ENV_VARS.context7];
+}
+
+/**
+ * Get the status of all optional services
+ */
+export function getOptionalServicesStatus(): Record<OptionalService, boolean> {
+  return {
+    tavily: hasTavilyKey(),
+    context7: hasContext7Key(),
+  };
+}

package/src/ai/tools/context7.ts

@@ -0,0 +1,167 @@
+/**
+ * Context7 Documentation Lookup Tool
+ * Enables documentation lookup for libraries and frameworks
+ */
+
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+
+/**
+ * Context7 library info
+ */
+export interface Context7Library {
+  id: string;
+  name: string;
+  description?: string;
+  codeSnippetCount?: number;
+}
+
+/**
+ * Context7 documentation result
+ */
+export interface Context7DocResult {
+  title: string;
+  content: string;
+  codeExamples?: string[];
+}
+
+/**
+ * Create a Context7 documentation lookup tool
+ * @param apiKey - Context7 API key
+ */
+export function createContext7Tool(apiKey: string) {
+  return tool({
+    description: `Look up documentation for libraries and frameworks.
+Use this to find:
+- API documentation for specific functions
+- Usage examples and patterns
+- Configuration options
+- Best practices from official docs`,
+    inputSchema: zodSchema(z.object({
+      library: z.string().describe('Library name (e.g., "react", "express", "prisma")'),
+      query: z.string().describe('What you want to find in the documentation'),
+    })),
+    execute: async ({ library, query }) => {
+      try {
+        // First, resolve the library ID
+        const resolveResponse = await fetch('https://api.context7.com/v1/resolve-library-id', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            libraryName: library,
+            query: query,
+          }),
+        });
+
+        if (!resolveResponse.ok) {
+          // Try alternative endpoint structure
+          return await fallbackDocLookup(apiKey, library, query);
+        }
+
+        const resolveData = await resolveResponse.json() as { libraryId?: string; libraries?: Context7Library[] };
+        const libraryId = resolveData.libraryId || resolveData.libraries?.[0]?.id;
+
+        if (!libraryId) {
+          return `No documentation found for "${library}". Try a different library name.`;
+        }
+
+        // Query the documentation
+        const queryResponse = await fetch('https://api.context7.com/v1/query-docs', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            libraryId,
+            query,
+          }),
+        });
+
+        if (!queryResponse.ok) {
+          const errorText = await queryResponse.text();
+          return `Documentation lookup failed: ${queryResponse.status} - ${errorText}`;
+        }
+
+        const docsData = await queryResponse.json() as { results?: Context7DocResult[] };
+
+        // Format results
+        const results: string[] = [];
+        results.push(`Documentation for ${library}:`);
+        results.push('');
+
+        if (docsData.results && docsData.results.length > 0) {
+          for (const doc of docsData.results.slice(0, 3)) {
+            results.push(`## ${doc.title}`);
+            results.push(doc.content.substring(0, 500));
+            if (doc.codeExamples && doc.codeExamples.length > 0) {
+              results.push('');
+              results.push('Example:');
+              results.push('```');
+              results.push(doc.codeExamples[0].substring(0, 300));
+              results.push('```');
+            }
+            results.push('');
+          }
+        } else {
+          results.push(`No specific documentation found for query: "${query}"`);
+        }
+
+        return results.join('\n');
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        return `Documentation lookup error: ${errMsg}`;
+      }
+    },
+  });
+}
+
+/**
+ * Fallback documentation lookup using alternative approach
+ */
+async function fallbackDocLookup(apiKey: string, library: string, query: string): Promise<string> {
+  try {
+    // Try a simpler query format
+    const response = await fetch(`https://api.context7.com/v1/search`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        query: `${library} ${query}`,
+        limit: 5,
+      }),
+    });
+
+    if (!response.ok) {
+      return `Unable to find documentation for "${library}". The Context7 API may not support this library or the request format has changed.`;
+    }
+
+    const data = await response.json() as { results?: Array<{ title: string; content: string }> };
+
+    if (data.results && data.results.length > 0) {
+      const results: string[] = [`Documentation for ${library}:`, ''];
+      for (const item of data.results.slice(0, 3)) {
+        results.push(`## ${item.title}`);
+        results.push(item.content.substring(0, 400));
+        results.push('');
+      }
+      return results.join('\n');
+    }
+
+    return `No documentation found for "${library}" with query "${query}"`;
+  } catch {
+    return `Documentation lookup for "${library}" failed. Please check your Context7 API key.`;
+  }
+}
+
+/**
+ * Check if Context7 can be used
+ */
+export function canUseContext7(apiKey?: string): boolean {
+  return !!apiKey && apiKey.length > 0;
+}

package/src/ai/tools/index.ts

@@ -0,0 +1,17 @@
+/**
+ * AI Tools Index
+ * Exports all tools for agent use
+ */
+
+export {
+  createTavilySearchTool,
+  canUseTavily,
+  type TavilySearchResult,
+} from './tavily.js';
+
+export {
+  createContext7Tool,
+  canUseContext7,
+  type Context7Library,
+  type Context7DocResult,
+} from './context7.js';