wiggum-cli 0.2.6 → 0.3.1

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) => {

package/src/commands/init.ts

@@ -1,10 +1,10 @@
 /**
  * Init Command
- * Initialize Ralph in the current project - scans and generates configuration
+ * Initialize Ralph in the current project - BYOK multi-agent AI analysis
  */
 
 import { logger } from '../utils/logger.js';
-import { Scanner, formatScanResult, type ScanResult } from '../scanner/index.js';
+import { Scanner, type ScanResult } from '../scanner/index.js';
 import { Generator, formatGenerationResult } from '../generator/index.js';
 import {
   AIEnhancer,
@@ -12,7 +12,15 @@ import {
   type AIProvider,
   type EnhancedScanResult,
 } from '../ai/index.js';
-import { hasApiKey, getApiKeyEnvVar, getAvailableProvider, AVAILABLE_MODELS } from '../ai/providers.js';
+import {
+  hasApiKey,
+  getApiKeyEnvVar,
+  getAvailableProvider,
+  AVAILABLE_MODELS,
+  OPTIONAL_SERVICE_ENV_VARS,
+  hasTavilyKey,
+  hasContext7Key,
+} from '../ai/providers.js';
 import * as prompts from '@clack/prompts';
 import pc from 'picocolors';
 import fs from 'fs';
@@ -20,16 +28,225 @@ import path from 'path';
 import { simpson, sectionHeader, drawLine } from '../utils/colors.js';
 
 export interface InitOptions {
-  ai?: boolean;
   provider?: AIProvider;
   yes?: boolean;
-  /** Use agentic mode for deep codebase exploration */
-  agentic?: boolean;
+}
+
+/**
+ * Save API keys to .env.local file
+ */
+function saveKeysToEnvLocal(
+  projectRoot: string,
+  keys: Record<string, string>
+): void {
+  const envLocalPath = path.join(projectRoot, '.env.local');
+  let envContent = '';
+
+  // Read existing content if file exists
+  if (fs.existsSync(envLocalPath)) {
+    envContent = fs.readFileSync(envLocalPath, 'utf-8');
+  }
+
+  // Update or add each key
+  for (const [envVar, value] of Object.entries(keys)) {
+    if (!value) continue;
+
+    const keyRegex = new RegExp(`^${envVar}=.*$`, 'm');
+    if (keyRegex.test(envContent)) {
+      // Replace existing key
+      envContent = envContent.replace(keyRegex, `${envVar}=${value}`);
+    } else {
+      // Append new key
+      envContent = envContent.trimEnd() + (envContent ? '\n' : '') + `${envVar}=${value}\n`;
+    }
+  }
+
+  fs.writeFileSync(envLocalPath, envContent);
+}
+
+/**
+ * Get the default model for a provider (the one marked as 'recommended' or first)
+ */
+function getDefaultModel(provider: AIProvider): string {
+  const models = AVAILABLE_MODELS[provider];
+  const recommended = models.find(m => m.hint?.includes('recommended'));
+  return recommended?.value || models[0].value;
+}
+
+/**
+ * BYOK Flow: Collect API keys from user
+ */
+async function collectApiKeys(
+  projectRoot: string,
+  options: InitOptions
+): Promise<{
+  provider: AIProvider;
+  model: string;
+  tavilyKey?: string;
+  context7Key?: string;
+} | null> {
+  // Check if we already have an LLM key
+  let provider: AIProvider = options.provider || 'anthropic';
+  const existingProvider = getAvailableProvider();
+  let hadLlmKeyBefore = options.provider ? hasApiKey(options.provider) : !!existingProvider;
+  let llmKeyEnteredThisSession = false;
+
+  if (!hadLlmKeyBefore) {
+    // In --yes mode, fail if no API key is available
+    if (options.yes) {
+      logger.error('No API key found. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.');
+      return null;
+    }
+
+    // Need to collect LLM API key interactively
+    console.log('');
+    console.log(simpson.yellow('─── API Key Setup ───'));
+    console.log('');
+    console.log('Ralph uses AI to analyze your codebase and generate configuration.');
+    console.log('');
+
+    // Select provider
+    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: 'openrouter', label: 'OpenRouter', hint: 'multiple providers' },
+      ],
+    });
+
+    if (prompts.isCancel(providerChoice)) {
+      return null;
+    }
+
+    provider = providerChoice as AIProvider;
+    const envVar = getApiKeyEnvVar(provider);
+
+    // Get API key
+    const apiKeyInput = await prompts.password({
+      message: `Enter your ${envVar}:`,
+    });
+
+    if (prompts.isCancel(apiKeyInput) || !apiKeyInput) {
+      logger.error('LLM API key is required to use Ralph.');
+      return null;
+    }
+
+    // Set in process.env for this session
+    process.env[envVar] = apiKeyInput;
+    llmKeyEnteredThisSession = true;
+  } else if (!options.provider) {
+    // Use the available provider
+    provider = existingProvider || 'anthropic';
+  }
+
+  // Select model (skip in --yes mode, use default)
+  let selectedModel: string;
+
+  if (options.yes) {
+    selectedModel = getDefaultModel(provider);
+  } else {
+    const modelOptions = AVAILABLE_MODELS[provider];
+    const modelChoice = await prompts.select({
+      message: 'Select model:',
+      options: modelOptions.map(m => ({
+        value: m.value,
+        label: m.label,
+        hint: m.hint,
+      })),
+    });
+
+    if (prompts.isCancel(modelChoice)) {
+      return null;
+    }
+
+    selectedModel = modelChoice as string;
+  }
+
+  // Collect optional Tavily API key (skip in --yes mode)
+  let tavilyKey: string | undefined;
+  let tavilyKeyEnteredThisSession = false;
+
+  if (hasTavilyKey()) {
+    tavilyKey = process.env[OPTIONAL_SERVICE_ENV_VARS.tavily];
+  } else if (!options.yes) {
+    console.log('');
+    console.log(pc.dim('Tavily enables web search for current best practices (optional)'));
+
+    const tavilyInput = await prompts.password({
+      message: `Enter ${OPTIONAL_SERVICE_ENV_VARS.tavily} (press Enter to skip):`,
+    });
+
+    if (!prompts.isCancel(tavilyInput) && tavilyInput) {
+      tavilyKey = tavilyInput;
+      tavilyKeyEnteredThisSession = true;
+      process.env[OPTIONAL_SERVICE_ENV_VARS.tavily] = tavilyInput;
+    }
+  }
+
+  // Collect optional Context7 API key (skip in --yes mode)
+  let context7Key: string | undefined;
+  let context7KeyEnteredThisSession = false;
+
+  if (hasContext7Key()) {
+    context7Key = process.env[OPTIONAL_SERVICE_ENV_VARS.context7];
+  } else if (!options.yes) {
+    console.log(pc.dim('Context7 enables documentation lookup for your stack (optional)'));
+
+    const context7Input = await prompts.password({
+      message: `Enter ${OPTIONAL_SERVICE_ENV_VARS.context7} (press Enter to skip):`,
+    });
+
+    if (!prompts.isCancel(context7Input) && context7Input) {
+      context7Key = context7Input;
+      context7KeyEnteredThisSession = true;
+      process.env[OPTIONAL_SERVICE_ENV_VARS.context7] = context7Input;
+    }
+  }
+
+  // Save keys entered this session to .env.local
+  const keysToSave: Record<string, string> = {};
+
+  if (llmKeyEnteredThisSession) {
+    const llmEnvVar = getApiKeyEnvVar(provider);
+    keysToSave[llmEnvVar] = process.env[llmEnvVar]!;
+  }
+  if (tavilyKeyEnteredThisSession && tavilyKey) {
+    keysToSave[OPTIONAL_SERVICE_ENV_VARS.tavily] = tavilyKey;
+  }
+  if (context7KeyEnteredThisSession && context7Key) {
+    keysToSave[OPTIONAL_SERVICE_ENV_VARS.context7] = context7Key;
+  }
+
+  if (Object.keys(keysToSave).length > 0) {
+    // In --yes mode, auto-save keys
+    if (options.yes) {
+      saveKeysToEnvLocal(projectRoot, keysToSave);
+      logger.success('API keys saved to .env.local');
+    } else {
+      const saveKeys = await prompts.confirm({
+        message: 'Save API keys to .env.local?',
+        initialValue: true,
+      });
+
+      if (!prompts.isCancel(saveKeys) && saveKeys) {
+        saveKeysToEnvLocal(projectRoot, keysToSave);
+        logger.success('API keys saved to .env.local');
+      }
+    }
+  }
+
+  return {
+    provider,
+    model: selectedModel,
+    tavilyKey,
+    context7Key,
+  };
 }
 
 /**
  * Initialize Ralph in the current project
- * Scans the project and generates configuration
+ * Uses BYOK (Bring Your Own Keys) model with multi-agent AI analysis
  */
 export async function initCommand(options: InitOptions): Promise<void> {
   const projectRoot = process.cwd();
@@ -38,7 +255,20 @@ export async function initCommand(options: InitOptions): Promise<void> {
   logger.info(`Project: ${projectRoot}`);
   console.log('');
 
-  // Step 1: Scan the project
+  // Step 1: Collect API keys (BYOK)
+  const apiKeys = await collectApiKeys(projectRoot, options);
+
+  if (!apiKeys) {
+    // In --yes mode, null means missing API key (hard failure)
+    // In interactive mode, null means user cancelled
+    if (options.yes) {
+      process.exit(1);
+    }
+    logger.info('Initialization cancelled');
+    return;
+  }
+
+  // Step 2: Scan the project (background)
   const spinner = prompts.spinner();
   spinner.start('Scanning project...');
 
@@ -47,189 +277,64 @@ export async function initCommand(options: InitOptions): Promise<void> {
 
   try {
     scanResult = await scanner.scan(projectRoot);
-    spinner.stop('Project scanned successfully');
+    spinner.stop('Project scanned');
   } catch (error) {
     spinner.stop('Scan failed');
     logger.error(`Failed to scan project: ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
   }
 
-  // Display scan results
-  console.log('');
-  console.log(simpson.yellow('─── Scan Results ───'));
-  console.log(formatScanResult(scanResult));
+  // Step 3: Run multi-agent AI analysis
   console.log('');
+  const modelLabel = AVAILABLE_MODELS[apiKeys.provider].find(m => m.value === apiKeys.model)?.label || apiKeys.model;
 
-  // Step 2: AI Enhancement
-  let enhancedResult: EnhancedScanResult | undefined;
-  let useAI = options.ai;
-  let provider: AIProvider = options.provider || 'anthropic';
+  // Show capabilities status
+  const capabilities: string[] = ['Codebase Analysis'];
+  if (apiKeys.tavilyKey) capabilities.push('Web Research');
+  if (apiKeys.context7Key) capabilities.push('Doc Lookup');
 
-  // Ask about AI enhancement if not specified via --ai flag and not in --yes mode
-  if (!options.ai && !options.yes) {
-    const wantAI = await prompts.confirm({
-      message: 'Enable AI-enhanced analysis?',
-      initialValue: true,
-    });
+  console.log(simpson.yellow(`─── AI Analysis (${apiKeys.provider} / ${modelLabel}) ───`));
+  console.log(pc.dim(`Capabilities: ${capabilities.join(' • ')}`));
+  console.log('');
 
-    if (prompts.isCancel(wantAI)) {
-      logger.info('Initialization cancelled');
-      return;
-    }
+  spinner.start('Running AI analysis...');
 
-    useAI = wantAI;
-  }
+  const aiEnhancer = new AIEnhancer({
+    provider: apiKeys.provider,
+    model: apiKeys.model,
+    verbose: true,
+    agentic: true, // Always use agentic mode for deeper analysis
+    tavilyApiKey: apiKeys.tavilyKey,
+    context7ApiKey: apiKeys.context7Key,
+  });
+
+  let enhancedResult: EnhancedScanResult;
 
-  if (useAI) {
-    // Check if we have an API key for the selected provider or any provider
-    let hasKey = options.provider ? hasApiKey(options.provider) : !!getAvailableProvider();
+  try {
+    enhancedResult = await aiEnhancer.enhance(scanResult);
 
-    // If no API key found, prompt for one
-    if (!hasKey) {
+    if (enhancedResult.aiEnhanced && enhancedResult.aiAnalysis) {
+      spinner.stop('AI analysis complete');
       console.log('');
-      console.log(simpson.pink('No API key found for AI enhancement.'));
+      console.log(formatAIAnalysis(enhancedResult.aiAnalysis));
+    } else if (enhancedResult.aiError) {
+      spinner.stop('AI analysis failed');
+      logger.warn(`AI error: ${enhancedResult.aiError}`);
       console.log('');
 
-      // Ask which provider to use
-      const providerChoice = await prompts.select({
-        message: 'Which AI provider would you like to use?',
-        options: [
-          { value: 'anthropic', label: 'Anthropic (Claude)', hint: 'recommended' },
-          { value: 'openai', label: 'OpenAI (GPT-4)' },
-          { value: 'openrouter', label: 'OpenRouter' },
-        ],
-      });
-
-      if (prompts.isCancel(providerChoice)) {
-        logger.info('Initialization cancelled');
-        return;
-      }
-
-      provider = providerChoice as AIProvider;
-      const envVar = getApiKeyEnvVar(provider);
-
-      // Prompt for API key
-      const apiKeyInput = await prompts.password({
-        message: `Enter your ${envVar}:`,
-      });
-
-      if (prompts.isCancel(apiKeyInput) || !apiKeyInput) {
-        logger.warn('No API key provided, skipping AI enhancement');
-        useAI = false;
-      } else {
-        // Set the API key in process.env for current session
-        process.env[envVar] = apiKeyInput;
-        hasKey = true;
-
-        // Offer to save to .env.local
-        const saveKey = await prompts.confirm({
-          message: 'Save API key to .env.local?',
-          initialValue: true,
-        });
-
-        if (!prompts.isCancel(saveKey) && saveKey) {
-          const envLocalPath = path.join(projectRoot, '.env.local');
-          let envContent = '';
-
-          // Read existing content if file exists
-          if (fs.existsSync(envLocalPath)) {
-            envContent = fs.readFileSync(envLocalPath, 'utf-8');
-            // Check if key already exists
-            const keyRegex = new RegExp(`^${envVar}=.*$`, 'm');
-            if (keyRegex.test(envContent)) {
-              // Replace existing key
-              envContent = envContent.replace(keyRegex, `${envVar}=${apiKeyInput}`);
-            } else {
-              // Append new key
-              envContent = envContent.trimEnd() + '\n' + `${envVar}=${apiKeyInput}\n`;
-            }
-          } else {
-            envContent = `${envVar}=${apiKeyInput}\n`;
-          }
-
-          fs.writeFileSync(envLocalPath, envContent);
-          logger.success(`API key saved to .env.local`);
-        }
-      }
-    } else if (!options.provider) {
-      // If we have a key but no provider specified, use the available one
-      provider = getAvailableProvider() || 'anthropic';
+      // Fall back to basic scan result
+      enhancedResult = { ...scanResult, aiEnhanced: false };
     }
+  } catch (error) {
+    spinner.stop('AI analysis failed');
+    logger.warn(`AI error: ${error instanceof Error ? error.message : String(error)}`);
+    console.log('');
 
-    // Run AI enhancement if we have a key
-    if (useAI && hasKey) {
-      // Ask which model to use
-      const modelOptions = AVAILABLE_MODELS[provider];
-      const modelChoice = await prompts.select({
-        message: 'Which model would you like to use?',
-        options: modelOptions.map(m => ({
-          value: m.value,
-          label: m.label,
-          hint: m.hint,
-        })),
-      });
-
-      if (prompts.isCancel(modelChoice)) {
-        logger.info('Initialization cancelled');
-        return;
-      }
-
-      const selectedModel = modelChoice as string;
-      const modelLabel = modelOptions.find(m => m.value === selectedModel)?.label || selectedModel;
-
-      // Ask about agentic mode (deep exploration)
-      let useAgentic = options.agentic;
-      if (useAgentic === undefined && !options.yes) {
-        const wantAgentic = await prompts.confirm({
-          message: 'Enable deep codebase exploration? (AI will search files and directories)',
-          initialValue: true,
-        });
-
-        if (prompts.isCancel(wantAgentic)) {
-          logger.info('Initialization cancelled');
-          return;
-        }
-
-        useAgentic = wantAgentic;
-      }
-
-      console.log('');
-      const modeLabel = useAgentic ? 'agentic' : 'simple';
-      console.log(simpson.yellow(`─── AI Enhancement (${provider} / ${modelLabel} / ${modeLabel}) ───`));
-
-      const aiEnhancer = new AIEnhancer({
-        provider,
-        model: selectedModel,
-        verbose: true,
-        agentic: useAgentic,
-      });
-
-      spinner.start('Running AI analysis...');
-
-      try {
-        enhancedResult = await aiEnhancer.enhance(scanResult);
-
-        if (enhancedResult.aiEnhanced && enhancedResult.aiAnalysis) {
-          spinner.stop('AI analysis complete');
-          console.log('');
-          console.log(formatAIAnalysis(enhancedResult.aiAnalysis));
-
-          // Use enhanced result for generation
-          scanResult = enhancedResult;
-        } else if (enhancedResult.aiError) {
-          spinner.stop('AI analysis failed');
-          logger.warn(`AI enhancement error: ${enhancedResult.aiError}`);
-          console.log('');
-        }
-      } catch (error) {
-        spinner.stop('AI analysis failed');
-        logger.warn(`AI enhancement error: ${error instanceof Error ? error.message : String(error)}`);
-        console.log('');
-      }
-    }
+    // Fall back to basic scan result
+    enhancedResult = { ...scanResult, aiEnhanced: false };
   }
 
-  // Step 3: Confirm with user (unless --yes)
+  // Step 4: Confirm with user (unless --yes)
   if (!options.yes) {
     const shouldContinue = await prompts.confirm({
       message: 'Generate Ralph configuration files?',
@@ -242,7 +347,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
     }
   }
 
-  // Step 4: Generate configuration files
+  // Step 5: Generate configuration files
   console.log('');
   spinner.start('Generating configuration files...');
 
@@ -253,7 +358,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
   });
 
   try {
-    const generationResult = await generator.generate(scanResult);
+    const generationResult = await generator.generate(enhancedResult);
     spinner.stop('Configuration files generated');
 
     console.log('');