wiggum-cli 0.2.5 → 0.3.0

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';

package/src/ai/tools/tavily.ts

@@ -0,0 +1,101 @@
+/**
+ * Tavily Web Search Tool
+ * Enables web search for current best practices and documentation
+ */
+
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+
+/**
+ * Tavily search result
+ */
+export interface TavilySearchResult {
+  title: string;
+  url: string;
+  content: string;
+  score: number;
+}
+
+/**
+ * Tavily API response
+ */
+interface TavilyApiResponse {
+  results: TavilySearchResult[];
+  query: string;
+  answer?: string;
+}
+
+/**
+ * Create a Tavily web search tool
+ * @param apiKey - Tavily API key
+ */
+export function createTavilySearchTool(apiKey: string) {
+  return tool({
+    description: `Search the web for current best practices, documentation, and recent information.
+Use this to find:
+- Current best practices for technologies
+- Testing patterns and tools
+- Library documentation and examples
+- Recent updates and changes`,
+    inputSchema: zodSchema(z.object({
+      query: z.string().describe('Search query - be specific about what you want to find'),
+      searchDepth: z.enum(['basic', 'advanced']).optional()
+        .describe('Search depth - use "advanced" for comprehensive results'),
+      maxResults: z.number().min(1).max(10).optional()
+        .describe('Maximum number of results (default 5)'),
+    })),
+    execute: async ({ query, searchDepth, maxResults }) => {
+      try {
+        const response = await fetch('https://api.tavily.com/search', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            api_key: apiKey,
+            query,
+            search_depth: searchDepth || 'basic',
+            max_results: maxResults || 5,
+            include_answer: true,
+            include_raw_content: false,
+          }),
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          return `Search failed: ${response.status} - ${errorText}`;
+        }
+
+        const data = await response.json() as TavilyApiResponse;
+
+        // Format results for the AI
+        const results: string[] = [];
+
+        if (data.answer) {
+          results.push(`Summary: ${data.answer}`);
+          results.push('');
+        }
+
+        results.push('Sources:');
+        for (const result of data.results) {
+          results.push(`- ${result.title}`);
+          results.push(`  URL: ${result.url}`);
+          results.push(`  ${result.content.substring(0, 300)}...`);
+          results.push('');
+        }
+
+        return results.join('\n');
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        return `Search error: ${errMsg}`;
+      }
+    },
+  });
+}
+
+/**
+ * Create a function that checks if Tavily search can be performed
+ */
+export function canUseTavily(apiKey?: string): boolean {
+  return !!apiKey && apiKey.length > 0;
+}

package/src/cli.ts

@@ -27,8 +27,7 @@ export function createCli(): Command {
       'after',
       `
 Examples:
-  $ ralph init                    Initialize Ralph in your project
-  $ ralph init --ai               Initialize with AI-enhanced analysis
+  $ ralph init                    Initialize Ralph with AI analysis
   $ ralph new my-feature          Create a new feature specification
   $ ralph run my-feature          Run the feature development loop
   $ ralph monitor my-feature      Monitor progress in real-time
@@ -43,10 +42,9 @@ Documentation:
     .command('init')
     .description(
       'Initialize Ralph in the current project.\n\n' +
-        'Scans your codebase to detect the tech stack (framework, testing,\n' +
-        'database, auth, etc.) and generates configuration files in .ralph/'
+        'Uses AI to analyze your codebase, detect the tech stack, and generate\n' +
+        'intelligent configuration files in .ralph/'
     )
-    .option('--ai', 'Enable AI-enhanced analysis for deeper project insights')
     .option(
       '--provider <name>',
       'AI provider to use (anthropic, openai, openrouter)',
@@ -57,15 +55,19 @@ Documentation:
       'after',
       `
 Examples:
-  $ ralph init                           Basic initialization
-  $ ralph init --ai                      With AI-enhanced analysis (Anthropic)
-  $ ralph init --ai --provider openai    With OpenAI provider
+  $ ralph init                           Initialize with AI analysis
+  $ ralph init --provider openai         Use OpenAI provider
   $ ralph init --yes                     Non-interactive mode
 
-Environment Variables:
-  ANTHROPIC_API_KEY    Required for --ai with anthropic provider
-  OPENAI_API_KEY       Required for --ai with openai provider
-  OPENROUTER_API_KEY   Required for --ai with openrouter provider
+API Keys (BYOK - Bring Your Own Keys):
+  Required (one of):
+    ANTHROPIC_API_KEY    For Anthropic (Claude) provider
+    OPENAI_API_KEY       For OpenAI provider
+    OPENROUTER_API_KEY   For OpenRouter provider
+
+  Optional (for enhanced research):
+    TAVILY_API_KEY       Enable web search for best practices
+    CONTEXT7_API_KEY     Enable documentation lookup
 `
     )
     .action(async (options) => {