wiggum-cli 0.4.3 → 0.4.5

package/src/ai/agents/context-enricher.ts

@@ -27,17 +27,18 @@ Based on the analysis plan, explore the codebase to:
 4. Find available commands (from package.json)
 5. Answer the specific questions provided
 
-## IMPORTANT: Token Efficiency
-- Make at most 4-5 tool calls total, then produce output
-- Priority: package.json → root listing → one key directory
-- Don't explore every subdirectory - sample enough to understand structure
-- ALWAYS produce JSON output even with partial information
+## CRITICAL: You have a maximum of 6 tool calls before you MUST output JSON
+- Call getPackageInfo (no field) FIRST - this returns bin, main, scripts
+- Call listDirectory on root to see actual structure
+- Maybe explore ONE key directory if needed
+- After 3-4 tool calls, STOP exploring and OUTPUT your JSON
+- Better to have partial info than no output at all
 
 ## Tools Available
-- searchCode: Search using ripgrep patterns
-- readFile: Read file contents
+- getPackageInfo: Get package.json info - call with NO field parameter to get bin, main, scripts all at once
 - listDirectory: List directory structure
-- getPackageInfo: Get package.json info (use specific fields like "bin", "main", "scripts")
+- readFile: Read file contents
+- searchCode: Search using ripgrep patterns
 
 ## Exploration Strategy
 1. Read package.json FIRST for main/bin entries - these are authoritative entry points
@@ -69,6 +70,13 @@ Based on the analysis plan, explore the codebase to:
   - Map each real directory to its purpose based on file contents
   - Example: {"src/commands": "CLI commands", "app": "Next.js app router"}
 
+## Architecture Discovery
+Identify the data/control flow and include in answeredQuestions:
+- For CLI tools: "CLI entry → command parser → handlers → output"
+- For MCP servers: "Transport → request router → tool handlers → API client"
+- For web apps: "Routes → controllers → services → database"
+- For APIs: "HTTP server → middleware → routes → handlers → data layer"
+
 ## Output Format
 Output ONLY valid JSON with discovered facts, not exploration instructions:
 {
@@ -80,7 +88,10 @@ Output ONLY valid JSON with discovered facts, not exploration instructions:
   },
   "namingConventions": "camelCase files, PascalCase components",
   "commands": {"test": "npm test", "build": "npm run build"},
-  "answeredQuestions": {"What is the auth strategy?": "NextAuth with JWT"},
+  "answeredQuestions": {
+    "What is the auth strategy?": "NextAuth with JWT",
+    "architecture": "CLI parses commands via commander → calls API handlers → outputs results"
+  },
   "projectType": "CLI Tool"
 }`;
 
@@ -115,7 +126,7 @@ Start by exploring the specified areas, then answer the questions and produce yo
       system: CONTEXT_ENRICHER_SYSTEM_PROMPT,
       prompt,
       tools,
-      stopWhen: stepCountIs(5), // Reduced from 8 to leave tokens for JSON output
+      stopWhen: stepCountIs(7), // Balance between exploration and ensuring JSON output
       maxOutputTokens: 3000,
       ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
       experimental_telemetry: {
@@ -186,17 +197,71 @@ function parseEnrichedContext(
     return getDefaultEnrichedContext(input);
   }
 
+  // Derive commands from package.json as fallback if AI didn't find them
+  const derivedCommands = input ? deriveCommandsFromScripts(input.scanResult.projectRoot) : {};
+  const commands = parsed.commands && Object.keys(parsed.commands).length > 0
+    ? parsed.commands
+    : derivedCommands;
+
   // Build result with empty defaults for missing fields (don't guess)
   return {
     entryPoints: parsed.entryPoints || [],  // Empty = not found, not guessed
     keyDirectories: parsed.keyDirectories || {},  // Empty = not found
     namingConventions: parsed.namingConventions || 'unknown',
-    commands: parsed.commands || {},
+    commands,  // Derived from package.json if AI didn't find them
     answeredQuestions: parsed.answeredQuestions || {},
     projectType: parsed.projectType || 'Unknown',
   };
 }
 
+/**
+ * Script name patterns for command detection
+ * Exported for testing
+ */
+export const SCRIPT_MAPPINGS: Record<string, string[]> = {
+  test: ['test', 'test:unit', 'vitest', 'jest'],
+  lint: ['lint', 'eslint', 'lint:fix'],
+  typecheck: ['typecheck', 'tsc', 'type-check', 'types'],
+  build: ['build', 'compile'],
+  dev: ['dev', 'start:dev', 'develop', 'watch'],
+  format: ['format', 'prettier', 'fmt'],
+};
+
+/**
+ * Derive commands from package.json scripts when AI fails to discover them
+ * Exported for testing
+ */
+export function deriveCommandsFromScripts(projectRoot: string): Record<string, string> {
+  const commands: Record<string, string> = {};
+  const packageJsonPath = join(projectRoot, 'package.json');
+
+  if (!existsSync(packageJsonPath)) {
+    return commands;
+  }
+
+  try {
+    const content = readFileSync(packageJsonPath, 'utf-8');
+    const pkg = JSON.parse(content) as Record<string, unknown>;
+    const scripts = pkg.scripts as Record<string, string> | undefined;
+
+    if (!scripts) {
+      return commands;
+    }
+
+    for (const [command, patterns] of Object.entries(SCRIPT_MAPPINGS)) {
+      for (const pattern of patterns) {
+        if (scripts[pattern]) {
+          commands[command] = `npm run ${pattern}`;
+          break;
+        }
+      }
+    }
+    return commands;
+  } catch {
+    return commands;
+  }
+}
+
 /**
  * Derive entry points from package.json when AI fails to discover them
  */
@@ -238,17 +303,18 @@ function deriveEntryPointsFromPackageJson(projectRoot: string): string[] {
 
 /**
  * Get default enriched context when parsing fails
- * Returns empty arrays instead of guesses, but derives entry points from package.json
+ * Returns empty arrays instead of guesses, but derives entry points and commands from package.json
  */
 function getDefaultEnrichedContext(input?: ContextEnricherInput): EnrichedContext {
   const projectType = detectProjectType(input?.scanResult.stack);
   const entryPoints = input ? deriveEntryPointsFromPackageJson(input.scanResult.projectRoot) : [];
+  const commands = input ? deriveCommandsFromScripts(input.scanResult.projectRoot) : {};
 
   return {
     entryPoints,  // Derived from package.json, not guessed
     keyDirectories: {},  // Empty = not discovered
     namingConventions: 'unknown',
-    commands: {},  // Empty = not discovered
+    commands,  // Derived from package.json scripts
     answeredQuestions: {},
     projectType,
   };

package/src/ai/agents/index.ts

@@ -162,8 +162,8 @@ export async function runMultiAgentAnalysis(
     // ═══════════════════════════════════════════════════════════════
     report('Phase 3/4: Synthesizing');
 
-    // Detect MCPs (pure function, no LLM)
-    const mcpServers = detectRalphMcpServers(scanResult.stack);
+    // Detect MCPs (pure function, no LLM) - pass project type for context-aware recommendations
+    const mcpServers = detectRalphMcpServers(scanResult.stack, enrichedContext.projectType);
 
     // Run synthesis agent
     const synthesizedResult = await runSynthesisAgent(
@@ -238,6 +238,7 @@ function getDefaultMultiAgentAnalysis(scanResult: ScanResult): MultiAgentAnalysi
       antiPatterns: ['Avoid skipping tests'],
       testingTools: ['npm test'],
       debuggingTools: ['console.log'],
+      validationTools: ['npm run lint', 'npx tsc --noEmit'],
       documentationHints: ['Check official docs'],
       researchMode: 'knowledge-only',
     },

package/src/ai/agents/mcp-detector.test.ts

@@ -28,10 +28,61 @@ function createStack(overrides: Partial<DetectedStack> = {}): DetectedStack {
 
 describe('detectRalphMcpServers', () => {
   describe('e2eTesting', () => {
-    it('always returns playwright for e2eTesting', () => {
+    it('returns playwright by default', () => {
       const result = detectRalphMcpServers(createStack());
       expect(result.e2eTesting).toBe('playwright');
     });
+
+    it('returns mcp-inspector for MCP projects via stack.mcp.isProject', () => {
+      const stack = createStack({
+        mcp: { isProject: true },
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.e2eTesting).toBe('mcp-inspector');
+    });
+
+    it('returns mcp-inspector for MCP projects via projectType parameter', () => {
+      const result = detectRalphMcpServers(createStack(), 'MCP Server');
+      expect(result.e2eTesting).toBe('mcp-inspector');
+    });
+
+    it('returns mcp-inspector when projectType contains "mcp" (case-insensitive)', () => {
+      const result = detectRalphMcpServers(createStack(), 'mcp tool');
+      expect(result.e2eTesting).toBe('mcp-inspector');
+    });
+
+    it('returns playwright for Next.js projects', () => {
+      const stack = createStack({
+        framework: detection('Next.js'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.e2eTesting).toBe('playwright');
+    });
+
+    it('returns playwright for React projects', () => {
+      const stack = createStack({
+        framework: detection('React'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.e2eTesting).toBe('playwright');
+    });
+
+    it('returns playwright for Vue projects', () => {
+      const stack = createStack({
+        framework: detection('Vue'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.e2eTesting).toBe('playwright');
+    });
+
+    it('prefers MCP detection over web framework detection', () => {
+      const stack = createStack({
+        mcp: { isProject: true },
+        framework: detection('Next.js'),
+      });
+      const result = detectRalphMcpServers(stack);
+      expect(result.e2eTesting).toBe('mcp-inspector');
+    });
   });
 
   describe('database detection', () => {
@@ -242,13 +293,16 @@ describe('detectRalphMcpServers', () => {
 });
 
 describe('convertToLegacyMcpRecommendations', () => {
-  it('always includes filesystem and git as essential', () => {
+  // Note: filesystem and git are assumed available in Claude Code, so not included
+  it('only includes e2eTesting in essential (no filesystem/git)', () => {
     const result = convertToLegacyMcpRecommendations({
       e2eTesting: 'playwright',
       additional: [],
     });
-    expect(result.essential).toContain('filesystem');
-    expect(result.essential).toContain('git');
+    // Ralph loop focuses on essentials only - filesystem/git assumed available
+    expect(result.essential).toEqual(['playwright']);
+    expect(result.essential).not.toContain('filesystem');
+    expect(result.essential).not.toContain('git');
   });
 
   it('includes playwright in essential', () => {
@@ -268,13 +322,13 @@ describe('convertToLegacyMcpRecommendations', () => {
     expect(result.essential).toContain('supabase');
   });
 
-  it('moves additional MCPs to recommended', () => {
+  it('keeps recommended empty to focus on Ralph loop essentials', () => {
     const result = convertToLegacyMcpRecommendations({
       e2eTesting: 'playwright',
       additional: ['docker', 'vercel'],
     });
-    expect(result.recommended).toContain('docker');
-    expect(result.recommended).toContain('vercel');
+    // Additional MCPs are not moved to recommended - keeping focus on essentials
+    expect(result.recommended).toEqual([]);
   });
 
   it('returns correct structure for full stack', () => {
@@ -284,7 +338,8 @@ describe('convertToLegacyMcpRecommendations', () => {
       additional: ['docker', 'stripe'],
     });
 
-    expect(result.essential).toEqual(['filesystem', 'git', 'playwright', 'postgres']);
-    expect(result.recommended).toEqual(['docker', 'stripe']);
+    // Only e2eTesting and database in essential, no recommended MCPs
+    expect(result.essential).toEqual(['playwright', 'postgres']);
+    expect(result.recommended).toEqual([]);
   });
 });

package/src/ai/agents/mcp-detector.ts

@@ -66,13 +66,33 @@ const SERVICE_MCP_MAP: Record<string, string> = {
  * Detect ralph-essential MCP servers from the stack
  *
  * Ralph loop essentials:
- * - Playwright: Always recommended for E2E testing
+ * - For MCP Server projects: mcp-inspector for testing
+ * - For web apps with E2E: playwright for E2E testing
  * - Database MCP: If database is detected
  * - Additional MCPs based on services and deployment
  */
-export function detectRalphMcpServers(stack: DetectedStack): RalphMcpServers {
+export function detectRalphMcpServers(stack: DetectedStack, projectType?: string): RalphMcpServers {
+  // Determine appropriate E2E testing tool based on project type
+  const isMcpProject = stack.mcp?.isProject || projectType?.toLowerCase().includes('mcp');
+  const isWebApp = stack.framework?.name?.toLowerCase().includes('next') ||
+                   stack.framework?.name?.toLowerCase().includes('react') ||
+                   stack.framework?.name?.toLowerCase().includes('vue') ||
+                   stack.framework?.name?.toLowerCase().includes('svelte') ||
+                   stack.framework?.name?.toLowerCase().includes('nuxt') ||
+                   stack.framework?.name?.toLowerCase().includes('remix');
+
+  // Choose E2E testing tool based on project type
+  let e2eTesting: string;
+  if (isMcpProject) {
+    e2eTesting = 'mcp-inspector'; // MCP projects use MCP Inspector
+  } else if (isWebApp) {
+    e2eTesting = 'playwright'; // Web apps use Playwright
+  } else {
+    e2eTesting = 'playwright'; // Default to Playwright for CLI/other projects
+  }
+
   const result: RalphMcpServers = {
-    e2eTesting: 'playwright', // Always recommend Playwright for ralph loop
+    e2eTesting,
     additional: [],
   };
 

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

@@ -295,6 +295,7 @@ function parseStackResearch(
     antiPatterns: parsed.antiPatterns || [],
     testingTools: parsed.testingTools || [],
     debuggingTools: parsed.debuggingTools || [],
+    validationTools: parsed.validationTools || [],
     documentationHints: parsed.documentationHints || [],
     researchMode: researchMode,
   };
@@ -309,6 +310,7 @@ function getDefaultStackResearch(researchMode: StackResearch['researchMode']): S
     antiPatterns: ['Avoid skipping tests', 'Don\'t ignore type errors'],
     testingTools: ['npm test'],
     debuggingTools: ['console.log', 'debugger statement'],
+    validationTools: ['npm run lint', 'npx tsc --noEmit'],
     documentationHints: ['Check package.json for dependencies'],
     researchMode,
   };

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);
+  });
+});