wiggum-cli 0.4.4 → 0.4.5

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

@@ -24,6 +24,11 @@ import { getTracedAI } from '../../utils/tracing.js';
 const synthesisOutputSchema = z.object({
   implementationGuidelines: z.array(z.string()).describe('Short, actionable implementation guidelines'),
   possibleMissedTechnologies: z.array(z.string()).describe('Technologies that may have been missed (empty array if none)'),
+  technologyTools: z.object({
+    testing: z.array(z.string()).describe('Commands to run tests (e.g., "npm test", "npx vitest")'),
+    debugging: z.array(z.string()).describe('Debug flags, env vars, tools (e.g., "DEBUG=* npm run dev")'),
+    validation: z.array(z.string()).describe('Type checking, linting commands (e.g., "npm run lint", "npx tsc --noEmit")'),
+  }).optional(),
 });
 
 /**
@@ -35,6 +40,7 @@ const SYNTHESIS_AGENT_SYSTEM_PROMPT = `You are a Synthesis Agent that merges ana
 Based on the enriched context and technology research, generate:
 1. Short implementation guidelines (5-10 words each) describing DISCOVERED patterns
 2. List any technologies that may have been missed
+3. Technology tools for testing, debugging, and validation
 
 ## Guidelines Style
 - Describe DISCOVERED patterns, not instructions to follow
@@ -48,6 +54,12 @@ Based on the enriched context and technology research, generate:
   - Bad: "Use Zod for validation"
 - Max 7 patterns, prioritize most distinctive features
 
+## Technology Tools
+Based on the detected stack and available commands, provide:
+- testing: Commands to verify changes (e.g., "npm test", "npx vitest")
+- debugging: How to debug (e.g., "DEBUG=* npm run dev", "--verbose flag", "NODE_DEBUG=http")
+- validation: Pre-commit checks (e.g., "npm run lint", "npx tsc --noEmit")
+
 ## Example Output
 {
   "implementationGuidelines": [
@@ -57,7 +69,12 @@ Based on the enriched context and technology research, generate:
     "Zod schemas in src/schemas for API validation",
     "Playwright E2E tests in tests/e2e"
   ],
-  "possibleMissedTechnologies": ["Redis caching"]
+  "possibleMissedTechnologies": ["Redis caching"],
+  "technologyTools": {
+    "testing": ["npm test", "npx vitest --watch"],
+    "debugging": ["DEBUG=* npm run dev", "--verbose flag"],
+    "validation": ["npm run lint", "npx tsc --noEmit"]
+  }
 }`;
 
 /**
@@ -121,7 +138,7 @@ Generate concise, actionable implementation guidelines based on this analysis.`;
     }
 
     // Convert to MultiAgentAnalysis format for backward compatibility
-    return buildMultiAgentAnalysis(input, synthesis.implementationGuidelines, synthesis.possibleMissedTechnologies);
+    return buildMultiAgentAnalysis(input, synthesis.implementationGuidelines, synthesis.possibleMissedTechnologies, synthesis.technologyTools);
   } catch (error) {
     if (verbose) {
       logger.error(`Synthesis Agent error: ${error instanceof Error ? error.message : String(error)}`);
@@ -132,13 +149,23 @@ Generate concise, actionable implementation guidelines based on this analysis.`;
   }
 }
 
+/**
+ * Technology tools output from synthesis
+ */
+interface TechnologyTools {
+  testing?: string[];
+  debugging?: string[];
+  validation?: string[];
+}
+
 /**
  * Build MultiAgentAnalysis from synthesis input and generated guidelines
  */
 function buildMultiAgentAnalysis(
   input: SynthesisInput,
   implementationGuidelines: string[],
-  possibleMissedTechnologies?: string[]
+  possibleMissedTechnologies?: string[],
+  technologyTools?: TechnologyTools
 ): MultiAgentAnalysis {
   // Convert EnrichedContext to CodebaseAnalysis format
   const codebaseAnalysis: CodebaseAnalysis = {
@@ -161,7 +188,7 @@ function buildMultiAgentAnalysis(
   };
 
   // Merge tech research into StackResearch format
-  const stackResearch: StackResearch = mergeTechResearch(input.techResearch);
+  const stackResearch: StackResearch = mergeTechResearch(input.techResearch, technologyTools);
 
   // Convert MCP servers to legacy format
   const mcpServers: McpRecommendations = convertToLegacyMcpRecommendations(input.mcpServers);
@@ -176,13 +203,22 @@ function buildMultiAgentAnalysis(
 /**
  * Merge multiple TechResearchResult into a single StackResearch
  */
-function mergeTechResearch(techResearch: SynthesisInput['techResearch']): StackResearch {
+function mergeTechResearch(
+  techResearch: SynthesisInput['techResearch'],
+  technologyTools?: TechnologyTools
+): StackResearch {
+  // Use technologyTools from synthesis if available
+  const synthesisTesting = technologyTools?.testing || [];
+  const synthesisDebugging = technologyTools?.debugging || [];
+  const synthesisValidation = technologyTools?.validation || [];
+
   if (techResearch.length === 0) {
     return {
       bestPractices: ['Follow project conventions'],
       antiPatterns: ['Avoid skipping tests'],
-      testingTools: ['npm test'],
-      debuggingTools: ['console.log'],
+      testingTools: synthesisTesting.length > 0 ? synthesisTesting : ['npm test'],
+      debuggingTools: synthesisDebugging.length > 0 ? synthesisDebugging : ['console.log'],
+      validationTools: synthesisValidation.length > 0 ? synthesisValidation : ['npm run lint'],
       documentationHints: ['Check official docs'],
       researchMode: 'knowledge-only',
     };
@@ -191,7 +227,7 @@ function mergeTechResearch(techResearch: SynthesisInput['techResearch']): StackR
   // Merge all research results
   const bestPractices: string[] = [];
   const antiPatterns: string[] = [];
-  const testingTips: string[] = [];
+  const testingTips: string[] = [...synthesisTesting]; // Start with synthesis testing tools
   const documentationHints: string[] = [];
   let researchMode: StackResearch['researchMode'] = 'knowledge-only';
 
@@ -212,7 +248,8 @@ function mergeTechResearch(techResearch: SynthesisInput['techResearch']): StackR
     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
+    debuggingTools: [...new Set(synthesisDebugging)].slice(0, 5),
+    validationTools: [...new Set(synthesisValidation)].slice(0, 5),
     documentationHints: [...new Set(documentationHints)].slice(0, 5),
     researchMode,
   };

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

@@ -0,0 +1,156 @@
+/**
+ * Tests for Tech Researcher
+ *
+ * Run with: npx vitest run src/ai/agents/tech-researcher.test.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getDocumentationHints, DOCUMENTATION_HINTS } from './tech-researcher.js';
+
+describe('getDocumentationHints', () => {
+  describe('direct matches', () => {
+    it('returns hints for exact match "Next.js"', () => {
+      const result = getDocumentationHints('Next.js');
+      expect(result).toEqual(DOCUMENTATION_HINTS['Next.js']);
+      expect(result).toContain('https://nextjs.org/docs/app');
+    });
+
+    it('returns hints for exact match "React"', () => {
+      const result = getDocumentationHints('React');
+      expect(result).toEqual(DOCUMENTATION_HINTS['React']);
+      expect(result).toContain('https://react.dev');
+    });
+
+    it('returns hints for exact match "MCP"', () => {
+      const result = getDocumentationHints('MCP');
+      expect(result).toEqual(DOCUMENTATION_HINTS['MCP']);
+      expect(result).toContain('https://modelcontextprotocol.io/docs');
+    });
+
+    it('returns hints for exact match "Vitest"', () => {
+      const result = getDocumentationHints('Vitest');
+      expect(result).toEqual(DOCUMENTATION_HINTS['Vitest']);
+      expect(result).toContain('https://vitest.dev/guide');
+    });
+
+    it('returns hints for exact match "TypeScript"', () => {
+      const result = getDocumentationHints('TypeScript');
+      expect(result).toEqual(DOCUMENTATION_HINTS['TypeScript']);
+      expect(result).toContain('https://www.typescriptlang.org/docs');
+    });
+  });
+
+  describe('partial matches (case-insensitive)', () => {
+    it('matches "next.js" (lowercase) to Next.js', () => {
+      const result = getDocumentationHints('next.js');
+      expect(result).toEqual(DOCUMENTATION_HINTS['Next.js']);
+    });
+
+    it('matches "REACT" (uppercase) to React', () => {
+      const result = getDocumentationHints('REACT');
+      expect(result).toEqual(DOCUMENTATION_HINTS['React']);
+    });
+
+    it('matches "typescript" (lowercase) to TypeScript', () => {
+      const result = getDocumentationHints('typescript');
+      expect(result).toEqual(DOCUMENTATION_HINTS['TypeScript']);
+    });
+
+    it('matches "vitest" (lowercase) to Vitest', () => {
+      const result = getDocumentationHints('vitest');
+      expect(result).toEqual(DOCUMENTATION_HINTS['Vitest']);
+    });
+  });
+
+  describe('partial string matches', () => {
+    it('matches "Next.js 14" to Next.js', () => {
+      const result = getDocumentationHints('Next.js 14');
+      expect(result).toEqual(DOCUMENTATION_HINTS['Next.js']);
+    });
+
+    it('matches "React 18" to React', () => {
+      const result = getDocumentationHints('React 18');
+      expect(result).toEqual(DOCUMENTATION_HINTS['React']);
+    });
+
+    it('matches "MCP Server" key exactly', () => {
+      const result = getDocumentationHints('MCP Server');
+      expect(result).toEqual(DOCUMENTATION_HINTS['MCP Server']);
+    });
+  });
+
+  describe('fallback behavior', () => {
+    it('returns generic hint for unknown technology', () => {
+      const result = getDocumentationHints('UnknownFramework');
+      expect(result).toEqual(['Check official UnknownFramework documentation']);
+    });
+
+    it('returns generic hint for empty string', () => {
+      const result = getDocumentationHints('');
+      expect(result).toEqual(['Check official  documentation']);
+    });
+
+    it('returns generic hint for technology not in mapping', () => {
+      const result = getDocumentationHints('SomeRandomLib');
+      expect(result).toEqual(['Check official SomeRandomLib documentation']);
+    });
+  });
+
+  describe('specific technology coverage', () => {
+    it('has MCP ecosystem hints', () => {
+      expect(DOCUMENTATION_HINTS['MCP']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['MCP Server']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['@modelcontextprotocol/sdk']).toBeDefined();
+    });
+
+    it('has frontend framework hints', () => {
+      expect(DOCUMENTATION_HINTS['Next.js']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['React']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Vue']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Svelte']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Nuxt']).toBeDefined();
+    });
+
+    it('has backend framework hints', () => {
+      expect(DOCUMENTATION_HINTS['Express']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Fastify']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Hono']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['NestJS']).toBeDefined();
+    });
+
+    it('has testing tool hints', () => {
+      expect(DOCUMENTATION_HINTS['Vitest']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Jest']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Playwright']).toBeDefined();
+    });
+
+    it('has database/ORM hints', () => {
+      expect(DOCUMENTATION_HINTS['Prisma']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Drizzle']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Supabase']).toBeDefined();
+    });
+
+    it('has CLI tool hints', () => {
+      expect(DOCUMENTATION_HINTS['Commander']).toBeDefined();
+      expect(DOCUMENTATION_HINTS['Yargs']).toBeDefined();
+    });
+  });
+});
+
+describe('DOCUMENTATION_HINTS', () => {
+  it('has valid URLs for all entries', () => {
+    for (const [tech, hints] of Object.entries(DOCUMENTATION_HINTS)) {
+      expect(Array.isArray(hints)).toBe(true);
+      expect(hints.length).toBeGreaterThan(0);
+      for (const hint of hints) {
+        expect(hint).toMatch(/^https?:\/\//);
+      }
+    }
+  });
+
+  it('has no duplicate entries', () => {
+    const keys = Object.keys(DOCUMENTATION_HINTS);
+    const uniqueKeys = new Set(keys);
+    expect(keys.length).toBe(uniqueKeys.size);
+  });
+});

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

@@ -13,6 +13,90 @@ import { logger } from '../../utils/logger.js';
 import { parseJsonSafe } from '../../utils/json-repair.js';
 import { getTracedAI } from '../../utils/tracing.js';
 
+/**
+ * Documentation hints mapping for common technologies
+ * Used to provide useful links when AI research fails or as supplements
+ * Exported for testing
+ */
+export const DOCUMENTATION_HINTS: Record<string, string[]> = {
+  // MCP ecosystem
+  'MCP': ['https://modelcontextprotocol.io/docs', 'https://modelcontextprotocol.io/docs/tools/inspector'],
+  'MCP Server': ['https://modelcontextprotocol.io/docs', 'https://modelcontextprotocol.io/docs/tools/inspector'],
+  '@modelcontextprotocol/sdk': ['https://modelcontextprotocol.io/docs/tools/inspector'],
+
+  // Frontend frameworks
+  'Next.js': ['https://nextjs.org/docs/app', 'https://nextjs.org/docs/app/building-your-application'],
+  'React': ['https://react.dev', 'https://react.dev/learn'],
+  'Vue': ['https://vuejs.org/guide', 'https://vuejs.org/api'],
+  'Svelte': ['https://svelte.dev/docs', 'https://kit.svelte.dev/docs'],
+  'Nuxt': ['https://nuxt.com/docs', 'https://nuxt.com/docs/api'],
+
+  // Backend frameworks
+  'Express': ['https://expressjs.com/en/guide', 'https://expressjs.com/en/api.html'],
+  'Fastify': ['https://fastify.dev/docs/latest', 'https://fastify.dev/docs/latest/Guides/Getting-Started'],
+  'Hono': ['https://hono.dev/docs', 'https://hono.dev/docs/guides'],
+  'NestJS': ['https://docs.nestjs.com', 'https://docs.nestjs.com/first-steps'],
+
+  // Testing
+  'Vitest': ['https://vitest.dev/guide', 'https://vitest.dev/api'],
+  'Jest': ['https://jestjs.io/docs/getting-started', 'https://jestjs.io/docs/api'],
+  'Playwright': ['https://playwright.dev/docs/intro', 'https://playwright.dev/docs/api/class-test'],
+
+  // Validation
+  'Zod': ['https://zod.dev', 'https://zod.dev/?id=primitives'],
+  'Yup': ['https://github.com/jquense/yup#api'],
+
+  // Database
+  'Prisma': ['https://www.prisma.io/docs', 'https://www.prisma.io/docs/orm/prisma-client'],
+  'Drizzle': ['https://orm.drizzle.team/docs/overview', 'https://orm.drizzle.team/docs/sql-schema-declaration'],
+  'Supabase': ['https://supabase.com/docs', 'https://supabase.com/docs/guides/database'],
+
+  // TypeScript
+  'TypeScript': ['https://www.typescriptlang.org/docs', 'https://www.typescriptlang.org/docs/handbook'],
+
+  // CLI tools
+  'Commander': ['https://github.com/tj/commander.js#readme'],
+  'Yargs': ['https://yargs.js.org/docs'],
+};
+
+/**
+ * Get documentation hints for a technology
+ * Exported for testing
+ */
+export function getDocumentationHints(technology: string): string[] {
+  // Direct match
+  if (DOCUMENTATION_HINTS[technology]) {
+    return DOCUMENTATION_HINTS[technology];
+  }
+
+  // Empty string should return generic fallback
+  if (!technology.trim()) {
+    return [`Check official ${technology} documentation`];
+  }
+
+  const lowerTech = technology.toLowerCase();
+
+  // Case-insensitive exact match first
+  for (const [key, hints] of Object.entries(DOCUMENTATION_HINTS)) {
+    if (key.toLowerCase() === lowerTech) {
+      return hints;
+    }
+  }
+
+  // Partial match - prefer longer keys to avoid "React" matching "React Native"
+  // Sort keys by length descending so longer/more specific matches win
+  const sortedKeys = Object.keys(DOCUMENTATION_HINTS).sort((a, b) => b.length - a.length);
+
+  for (const key of sortedKeys) {
+    const lowerKey = key.toLowerCase();
+    if (lowerTech.includes(lowerKey) || lowerKey.includes(lowerTech)) {
+      return DOCUMENTATION_HINTS[key];
+    }
+  }
+
+  return [`Check official ${technology} documentation`];
+}
+
 /**
  * Get the current year for dynamic prompt generation
  */
@@ -265,6 +349,7 @@ function parseTechResearch(
 
 /**
  * Get default tech research when parsing fails
+ * Uses the DOCUMENTATION_HINTS mapping for relevant URLs
  */
 function getDefaultTechResearch(
   technology: string,
@@ -275,7 +360,7 @@ function getDefaultTechResearch(
     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`],
+    documentationHints: getDocumentationHints(technology),
     researchMode,
   };
 }

package/src/ai/agents/types.ts

@@ -157,6 +157,8 @@ export interface StackResearch {
   testingTools: string[];
   /** Technology-specific debugging tools */
   debuggingTools: string[];
+  /** Technology-specific validation tools (linting, type checking) */
+  validationTools: string[];
   /** Documentation hints and links */
   documentationHints: string[];
   /** Whether research was performed with tools or knowledge-only */

package/src/ai/enhancer.ts

@@ -452,7 +452,7 @@ function convertMultiAgentToAIAnalysis(multiAgent: MultiAgentAnalysis): AIAnalys
     technologyTools: {
       testing: stackResearch.testingTools,
       debugging: stackResearch.debuggingTools,
-      validation: [],
+      validation: stackResearch.validationTools,
     },
     technologyPractices: {
       projectType: codebaseAnalysis.projectContext.projectType,