wiggum-cli 0.3.2 → 0.4.0

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

@@ -0,0 +1,262 @@
+/**
+ * Tech Researcher Worker (Phase 2)
+ * Researches best practices for a specific technology
+ * Multiple instances run in parallel via runTechResearchPool
+ */
+
+import { stepCountIs, type LanguageModel, type Tool } from 'ai';
+import type { TechResearcherInput, TechResearchResult, AgentCapabilities, AgentOptions } from './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';
+import { parseJsonSafe } from '../../utils/json-repair.js';
+import { getTracedAI } from '../../utils/tracing.js';
+
+/**
+ * System prompt for Tech Researcher with tools
+ */
+const TECH_RESEARCHER_WITH_TOOLS_PROMPT = `You are a Tech Researcher worker focused on a single technology.
+
+## Your Mission
+Research the specified technology to find:
+1. Current best practices (2024+)
+2. Common anti-patterns to avoid
+3. Testing tips and patterns
+4. Useful documentation links
+
+## Tools Available
+- tavilySearch: Search the web for current best practices
+- context7Lookup: Look up library documentation
+
+## Research Strategy
+1. Search for "[technology] best practices 2024"
+2. Search for "[technology] testing patterns"
+3. Look up documentation for key features
+
+## Output Format
+Output ONLY valid JSON:
+{
+  "technology": "Next.js 14",
+  "bestPractices": ["Use App Router for new projects", "Enable strict TypeScript"],
+  "antiPatterns": ["Don't use pages/ and app/ together", "Avoid client components for static content"],
+  "testingTips": ["Use @testing-library/react", "Mock next/navigation for routing tests"],
+  "documentationHints": ["App Router: nextjs.org/docs/app", "Data Fetching: nextjs.org/docs/app/building-your-application/data-fetching"],
+  "researchMode": "full"
+}
+
+Keep each item concise (5-15 words max). Max 5 items per array.`;
+
+/**
+ * System prompt for Tech Researcher without tools (knowledge-only)
+ */
+const TECH_RESEARCHER_KNOWLEDGE_ONLY_PROMPT = `You are a Tech Researcher worker. You don't have web access, so rely on your training knowledge.
+
+## Your Mission
+Based on your knowledge of the specified technology, provide:
+1. Best practices (note if potentially outdated)
+2. Common anti-patterns to avoid
+3. Testing tips
+4. Documentation hints
+
+## Output Format
+Output ONLY valid JSON:
+{
+  "technology": "React",
+  "bestPractices": ["Use functional components with hooks", "Memoize expensive computations"],
+  "antiPatterns": ["Don't mutate state directly", "Avoid prop drilling"],
+  "testingTips": ["Use React Testing Library", "Test behavior not implementation"],
+  "documentationHints": ["React docs: react.dev", "Testing: testing-library.com"],
+  "researchMode": "knowledge-only"
+}
+
+Keep each item concise (5-15 words max). Max 5 items per array.`;
+
+/**
+ * Determine research mode based on capabilities
+ */
+function getResearchMode(capabilities: AgentCapabilities): TechResearchResult['researchMode'] {
+  if (capabilities.hasTavily && capabilities.hasContext7) return 'full';
+  if (capabilities.hasTavily) return 'web-only';
+  if (capabilities.hasContext7) return 'docs-only';
+  return 'knowledge-only';
+}
+
+/**
+ * Run a single Tech Researcher worker for one technology
+ */
+export async function runTechResearcher(
+  model: LanguageModel,
+  modelId: string,
+  input: TechResearcherInput,
+  options: AgentOptions,
+  verbose: boolean = false
+): Promise<TechResearchResult> {
+  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(`Tech Researcher [${input.technology}]: ${researchMode} mode`);
+  }
+
+  const systemPrompt = hasTools
+    ? TECH_RESEARCHER_WITH_TOOLS_PROMPT
+    : TECH_RESEARCHER_KNOWLEDGE_ONLY_PROMPT;
+
+  const prompt = `Research best practices for: ${input.technology}
+
+Provide current best practices, anti-patterns to avoid, testing tips, and documentation hints.
+Output your findings as JSON.`;
+
+  try {
+    const { generateText } = getTracedAI();
+
+    const result = await generateText({
+      model,
+      system: systemPrompt,
+      prompt,
+      ...(hasTools ? { tools, stopWhen: stepCountIs(3) } : {}),
+      maxOutputTokens: 2000,
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+      experimental_telemetry: {
+        isEnabled: true,
+        metadata: {
+          agent: 'tech-researcher',
+          technology: input.technology,
+          researchMode,
+        },
+      },
+    });
+
+    const research = parseTechResearch(result.text, result.steps, input.technology, researchMode, verbose);
+    return research;
+  } catch (error) {
+    if (verbose) {
+      logger.error(`Tech Researcher [${input.technology}] error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    return getDefaultTechResearch(input.technology, researchMode);
+  }
+}
+
+/**
+ * Run multiple Tech Researchers in parallel for a list of technologies
+ */
+export async function runTechResearchPool(
+  model: LanguageModel,
+  modelId: string,
+  technologies: string[],
+  options: AgentOptions,
+  verbose: boolean = false
+): Promise<TechResearchResult[]> {
+  if (technologies.length === 0) {
+    return [];
+  }
+
+  // Determine capabilities once
+  const capabilities: AgentCapabilities = {
+    hasTavily: !!options.tavilyApiKey,
+    hasContext7: !!options.context7ApiKey,
+  };
+
+  if (verbose) {
+    logger.info(`Tech Research Pool: Starting ${technologies.length} parallel researchers`);
+  }
+
+  // Run all researchers in parallel
+  const results = await Promise.all(
+    technologies.map(technology =>
+      runTechResearcher(
+        model,
+        modelId,
+        { technology, capabilities },
+        options,
+        verbose
+      )
+    )
+  );
+
+  if (verbose) {
+    logger.info(`Tech Research Pool: Completed ${results.length} research tasks`);
+  }
+
+  return results;
+}
+
+/**
+ * Parse tech research from agent response
+ */
+function parseTechResearch(
+  text: string,
+  steps: Array<{ text?: string }> | undefined,
+  technology: string,
+  researchMode: TechResearchResult['researchMode'],
+  verbose: boolean
+): TechResearchResult {
+  // 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(`Tech Researcher [${technology}]: No text output found`);
+    }
+    return getDefaultTechResearch(technology, researchMode);
+  }
+
+  // Use safe JSON parser with repair capabilities
+  const parsed = parseJsonSafe<Partial<TechResearchResult>>(textToParse);
+
+  if (!parsed) {
+    if (verbose) {
+      logger.warn(`Tech Researcher [${technology}]: Failed to parse JSON response`);
+    }
+    return getDefaultTechResearch(technology, researchMode);
+  }
+
+  return {
+    technology,
+    bestPractices: parsed.bestPractices || [],
+    antiPatterns: parsed.antiPatterns || [],
+    testingTips: parsed.testingTips || [],
+    documentationHints: parsed.documentationHints || [],
+    researchMode,
+  };
+}
+
+/**
+ * Get default tech research when parsing fails
+ */
+function getDefaultTechResearch(
+  technology: string,
+  researchMode: TechResearchResult['researchMode']
+): TechResearchResult {
+  return {
+    technology,
+    bestPractices: ['Follow official documentation', 'Use TypeScript for type safety'],
+    antiPatterns: ['Avoid deprecated APIs', 'Don\'t skip error handling'],
+    testingTips: ['Write unit tests for core logic', 'Test edge cases'],
+    documentationHints: [`Check official ${technology} documentation`],
+    researchMode,
+  };
+}

package/src/ai/agents/types.ts

@@ -1,12 +1,122 @@
 /**
  * Agent Types and Interfaces
  * Defines the structure for multi-agent analysis
+ *
+ * Architecture: Orchestrator-Worker + Evaluator-Optimizer
+ * Phase 1: Planning Orchestrator (creates analysis plan)
+ * Phase 2: Parallel Workers (context enricher + tech researchers)
+ * Phase 3: Synthesis (merge results + MCP detection)
+ * Phase 4: Evaluator-Optimizer (QA loop)
  */
 
 import type { ScanResult, DetectedStack } from '../../scanner/types.js';
 
+// ============================================================
+// Phase 1: Planning Orchestrator Types
+// ============================================================
+
+/**
+ * Analysis plan created by the Planning Orchestrator
+ * Guides the parallel workers in Phase 2
+ */
+export interface AnalysisPlan {
+  /** Key areas to explore in the codebase */
+  areasToExplore: string[];
+  /** Technologies to research in depth */
+  technologiesToResearch: string[];
+  /** Specific questions that need answers for implementation guidance */
+  questionsToAnswer: string[];
+  /** Estimated complexity of the project */
+  estimatedComplexity: 'low' | 'medium' | 'high';
+}
+
+// ============================================================
+// Phase 2: Worker Types
+// ============================================================
+
+/**
+ * Enriched context from codebase exploration
+ * Output from the Context Enricher worker
+ */
+export interface EnrichedContext {
+  /** Key entry point files */
+  entryPoints: string[];
+  /** Important directories and their purposes */
+  keyDirectories: Record<string, string>;
+  /** Naming conventions used */
+  namingConventions: string;
+  /** Detected commands from package.json */
+  commands: Record<string, string>;
+  /** Answers to the orchestrator's questions */
+  answeredQuestions: Record<string, string>;
+  /** The primary project type detected */
+  projectType: string;
+}
+
+/**
+ * Research result for a single technology
+ * Output from a Tech Researcher worker
+ */
+export interface TechResearchResult {
+  /** Technology that was researched */
+  technology: string;
+  /** Best practices for this technology */
+  bestPractices: string[];
+  /** Anti-patterns to avoid */
+  antiPatterns: string[];
+  /** Testing tips and tools */
+  testingTips: string[];
+  /** Documentation hints and links */
+  documentationHints: string[];
+  /** Whether research used tools or knowledge only */
+  researchMode: 'full' | 'web-only' | 'docs-only' | 'knowledge-only';
+}
+
+// ============================================================
+// Phase 3: Synthesis Types
+// ============================================================
+
+/**
+ * MCP servers focused on ralph loop essentials
+ */
+export interface RalphMcpServers {
+  /** Database MCP server if applicable */
+  database?: string;
+  /** E2E testing MCP (always playwright for ralph) */
+  e2eTesting: string;
+  /** Any additional recommended MCPs */
+  additional: string[];
+}
+
+// ============================================================
+// Phase 4: Evaluator-Optimizer Types
+// ============================================================
+
+/**
+ * Evaluation result from the QA evaluator
+ */
+export interface EvaluationResult {
+  /** Quality score from 1-10 */
+  qualityScore: number;
+  /** Whether entry points were identified */
+  hasEntryPoints: boolean;
+  /** Whether implementation guidelines were provided */
+  hasImplementationGuidelines: boolean;
+  /** Whether relevant MCP servers were recommended */
+  hasRelevantMcpServers: boolean;
+  /** Specific issues found */
+  specificIssues: string[];
+  /** Suggestions for improvement */
+  improvementSuggestions: string[];
+}
+
+// ============================================================
+// Legacy Types (kept for backward compatibility)
+// ============================================================
+
 /**
  * Codebase analysis result from the Codebase Analyst agent
+ * @deprecated Use EnrichedContext for new code
  */
 export interface CodebaseAnalysis {
   /** Project structure and context */
@@ -121,6 +231,7 @@ export interface StackResearcherInput {
 
 /**
  * Input for the Orchestrator agent
+ * @deprecated Use new agent architecture
  */
 export interface OrchestratorInput {
   /** Codebase analysis result */
@@ -130,3 +241,45 @@ export interface OrchestratorInput {
   /** The detected stack */
   stack: DetectedStack;
 }
+
+// ============================================================
+// New Agent Input Types
+// ============================================================
+
+/**
+ * Input for the Context Enricher worker
+ */
+export interface ContextEnricherInput {
+  /** The scan result from the scanner */
+  scanResult: ScanResult;
+  /** Areas to explore from the analysis plan */
+  areasToExplore: string[];
+  /** Questions to answer from the analysis plan */
+  questionsToAnswer: string[];
+}
+
+/**
+ * Input for a Tech Researcher worker
+ */
+export interface TechResearcherInput {
+  /** Technology to research */
+  technology: string;
+  /** Agent capabilities (determines which tools are available) */
+  capabilities: AgentCapabilities;
+}
+
+/**
+ * Input for the Synthesis agent
+ */
+export interface SynthesisInput {
+  /** Enriched context from codebase exploration */
+  enrichedContext: EnrichedContext;
+  /** Research results for each technology */
+  techResearch: TechResearchResult[];
+  /** Detected MCP servers */
+  mcpServers: RalphMcpServers;
+  /** The original analysis plan */
+  plan: AnalysisPlan;
+  /** The detected stack from scanner */
+  stack: DetectedStack;
+}

package/src/ai/index.ts

@@ -44,19 +44,40 @@ export {
   canUseContext7,
 } from './tools/index.js';
 
-// Agents
+// Agents - New 4-phase architecture
 export {
+  // Main orchestration
   runMultiAgentAnalysis,
-  runCodebaseAnalyst,
-  runStackResearcher,
-  runOrchestrator,
-  mergeAgentResults,
+  // Phase 1: Planning
+  runPlanningOrchestrator,
+  // Phase 2: Parallel workers
+  runContextEnricher,
+  runTechResearcher,
+  runTechResearchPool,
+  // Phase 3: Synthesis + MCP detection
+  runSynthesisAgent,
+  detectRalphMcpServers,
+  convertToLegacyMcpRecommendations,
+  // Phase 4: QA loop
+  runEvaluatorOptimizer,
+  // New types
+  type AnalysisPlan,
+  type EnrichedContext,
+  type TechResearchResult,
+  type RalphMcpServers,
+  type EvaluationResult,
+  // Legacy types (backward compatibility)
   type CodebaseAnalysis,
   type StackResearch,
   type McpRecommendations,
   type MultiAgentAnalysis,
   type AgentCapabilities,
   type AgentOptions,
+  // Legacy agents (deprecated, kept for backward compatibility)
+  runCodebaseAnalyst,
+  runStackResearcher,
+  runOrchestrator,
+  mergeAgentResults,
 } from './agents/index.js';
 
 // AI enhancer

package/src/commands/init.ts

@@ -26,6 +26,7 @@ import pc from 'picocolors';
 import fs from 'fs';
 import path from 'path';
 import { simpson, sectionHeader, drawLine } from '../utils/colors.js';
+import { flushTracing } from '../utils/tracing.js';
 
 export interface InitOptions {
   provider?: AIProvider;
@@ -109,8 +110,8 @@ async function collectApiKeys(
     const providerChoice = await prompts.select({
       message: 'Select your AI provider:',
       options: [
-        { value: 'anthropic', label: 'Anthropic (Claude)', hint: 'recommended' },
-        { value: 'openai', label: 'OpenAI (GPT-4/5)' },
+        { value: 'anthropic', label: 'Anthropic', hint: 'recommended' },
+        { value: 'openai', label: 'OpenAI' },
         { value: 'openrouter', label: 'OpenRouter', hint: 'multiple providers' },
       ],
     });
@@ -261,6 +262,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
   if (!apiKeys) {
     // In --yes mode, null means missing API key (hard failure)
     // In interactive mode, null means user cancelled
+    await flushTracing();
     if (options.yes) {
       process.exit(1);
     }
@@ -281,6 +283,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
   } catch (error) {
     spinner.stop('Scan failed');
     logger.error(`Failed to scan project: ${error instanceof Error ? error.message : String(error)}`);
+    await flushTracing();
     process.exit(1);
   }
 
@@ -342,6 +345,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
     });
 
     if (prompts.isCancel(shouldContinue) || !shouldContinue) {
+      await flushTracing();
       logger.info('Initialization cancelled');
       return;
     }
@@ -365,6 +369,9 @@ export async function initCommand(options: InitOptions): Promise<void> {
     console.log(simpson.yellow('─── Generation Results ───'));
     console.log(formatGenerationResult(generationResult));
 
+    // Flush tracing spans before completing
+    await flushTracing();
+
     if (generationResult.success) {
       console.log('');
       logger.success('Ralph initialized successfully!');
@@ -380,6 +387,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
   } catch (error) {
     spinner.stop('Generation failed');
     logger.error(`Failed to generate files: ${error instanceof Error ? error.message : String(error)}`);
+    await flushTracing();
     process.exit(1);
   }
 }

package/src/utils/tracing.ts

@@ -3,7 +3,7 @@
  * Provides AI call tracing for debugging and analysis
  */
 
-import { initLogger, wrapAISDK } from 'braintrust';
+import { initLogger, wrapAISDK, flush as braintrustFlush } from 'braintrust';
 import * as ai from 'ai';
 
 // Re-export traced utilities
@@ -13,6 +13,7 @@ export { traced, currentSpan, wrapTraced } from 'braintrust';
  * Initialize Braintrust logger if API key is available
  */
 let loggerInitialized = false;
+let exitHandlersRegistered = false;
 
 export function initTracing(): void {
   if (loggerInitialized) return;
@@ -29,11 +30,53 @@ export function initTracing(): void {
       projectName: process.env.BRAINTRUST_PROJECT_NAME || 'wiggum-cli',
     });
     loggerInitialized = true;
+
+    // Register exit handlers to flush spans before process exits
+    registerExitHandlers();
   } catch {
     // Silently fail if tracing can't be initialized
   }
 }
 
+/**
+ * Register process exit handlers to flush tracing spans
+ */
+function registerExitHandlers(): void {
+  if (exitHandlersRegistered) return;
+  exitHandlersRegistered = true;
+
+  // Flush on normal exit
+  process.on('beforeExit', async () => {
+    await flushTracing();
+  });
+
+  // Flush on SIGINT (Ctrl+C)
+  process.on('SIGINT', async () => {
+    await flushTracing();
+    process.exit(0);
+  });
+
+  // Flush on SIGTERM
+  process.on('SIGTERM', async () => {
+    await flushTracing();
+    process.exit(0);
+  });
+}
+
+/**
+ * Flush all pending tracing spans to Braintrust
+ * Call this before process exit to ensure all spans are recorded
+ */
+export async function flushTracing(): Promise<void> {
+  if (!loggerInitialized) return;
+
+  try {
+    await braintrustFlush();
+  } catch {
+    // Silently fail if flush fails
+  }
+}
+
 /**
  * Check if tracing is enabled
  */

package/tsconfig.json

@@ -15,5 +15,5 @@
     "resolveJsonModule": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+});