wiggum-cli 0.1.0

package/src/ai/prompts.ts

@@ -0,0 +1,217 @@
+/**
+ * AI Analysis Prompts
+ * Defines prompts for codebase analysis and enhancement
+ */
+
+import type { ScanResult, DetectedStack } from '../scanner/types.js';
+
+/**
+ * Format the detected stack for inclusion in prompts
+ */
+export function formatStackForPrompt(stack: DetectedStack): string {
+  const sections: string[] = [];
+
+  // Core
+  if (stack.framework) {
+    const variant = stack.framework.variant ? ` (${stack.framework.variant})` : '';
+    sections.push(`Framework: ${stack.framework.name}${variant}`);
+  }
+  if (stack.packageManager) {
+    sections.push(`Package Manager: ${stack.packageManager.name}`);
+  }
+  if (stack.testing?.unit) {
+    sections.push(`Unit Testing: ${stack.testing.unit.name}`);
+  }
+  if (stack.testing?.e2e) {
+    sections.push(`E2E Testing: ${stack.testing.e2e.name}`);
+  }
+  if (stack.styling) {
+    sections.push(`Styling: ${stack.styling.name}`);
+  }
+
+  // Data Layer
+  if (stack.database) {
+    sections.push(`Database: ${stack.database.name}`);
+  }
+  if (stack.orm) {
+    sections.push(`ORM: ${stack.orm.name}`);
+  }
+  if (stack.api && stack.api.length > 0) {
+    sections.push(`API Patterns: ${stack.api.map(a => a.name).join(', ')}`);
+  }
+
+  // Frontend
+  if (stack.stateManagement) {
+    sections.push(`State Management: ${stack.stateManagement.name}`);
+  }
+  if (stack.uiComponents && stack.uiComponents.length > 0) {
+    sections.push(`UI Components: ${stack.uiComponents.map(u => u.name).join(', ')}`);
+  }
+  if (stack.formHandling && stack.formHandling.length > 0) {
+    sections.push(`Form Handling: ${stack.formHandling.map(f => f.name).join(', ')}`);
+  }
+
+  // Services
+  if (stack.auth) {
+    sections.push(`Auth: ${stack.auth.name}`);
+  }
+  if (stack.analytics && stack.analytics.length > 0) {
+    sections.push(`Analytics: ${stack.analytics.map(a => a.name).join(', ')}`);
+  }
+  if (stack.payments) {
+    sections.push(`Payments: ${stack.payments.name}`);
+  }
+  if (stack.email) {
+    sections.push(`Email: ${stack.email.name}`);
+  }
+
+  // Infrastructure
+  if (stack.deployment && stack.deployment.length > 0) {
+    sections.push(`Deployment: ${stack.deployment.map(d => d.name).join(', ')}`);
+  }
+  if (stack.monorepo) {
+    sections.push(`Monorepo: ${stack.monorepo.name}`);
+  }
+
+  // MCP
+  if (stack.mcp) {
+    if (stack.mcp.isProject) {
+      sections.push('MCP: This is an MCP server project');
+    }
+    if (stack.mcp.detected && stack.mcp.detected.length > 0) {
+      sections.push(`MCP Servers: ${stack.mcp.detected.map(m => m.name).join(', ')}`);
+    }
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * System prompt for codebase analysis
+ */
+export const SYSTEM_PROMPT = `You are an expert software architect analyzing a codebase to provide insights for AI-assisted development.
+
+Your role is to:
+1. Analyze the detected tech stack and provide deeper insights
+2. Identify architectural patterns and coding conventions
+3. Suggest improvements to the detection results
+4. Recommend MCP servers that would benefit this project
+5. Generate custom prompt suggestions for AI coding assistants
+
+Be concise and actionable. Focus on practical insights that help developers work more effectively with AI tools.
+
+Respond in valid JSON format only.`;
+
+/**
+ * Create the codebase analysis prompt
+ */
+export function createAnalysisPrompt(scanResult: ScanResult): string {
+  const stackInfo = formatStackForPrompt(scanResult.stack);
+
+  return `Analyze this codebase and provide enhanced insights.
+
+Project Root: ${scanResult.projectRoot}
+
+Detected Stack:
+${stackInfo || 'No technologies detected'}
+
+Based on this stack, provide analysis in the following JSON format:
+{
+  "frameworkInsights": {
+    "variant": "more specific variant if detectable (e.g., 'app-router', 'pages-router', 'spa', 'ssr')",
+    "confidence": "high/medium/low",
+    "notes": "any additional observations about framework usage"
+  },
+  "architecturalPatterns": [
+    {
+      "pattern": "pattern name",
+      "confidence": "high/medium/low",
+      "evidence": "why you think this pattern is used"
+    }
+  ],
+  "codingConventions": [
+    {
+      "convention": "convention name",
+      "suggestion": "how to follow this convention"
+    }
+  ],
+  "recommendedMcpServers": [
+    {
+      "name": "server name",
+      "reason": "why this would be useful"
+    }
+  ],
+  "customPromptSuggestions": [
+    "Specific prompt suggestions tailored to this codebase"
+  ],
+  "additionalDetections": {
+    "possibleMissed": ["technologies that might be in use but weren't detected"],
+    "refinements": ["suggestions to improve existing detections"]
+  }
+}
+
+Only include sections where you have meaningful insights. Keep responses focused and actionable.`;
+}
+
+/**
+ * Prompt for validating and improving scanner results
+ */
+export function createValidationPrompt(scanResult: ScanResult): string {
+  const stackInfo = formatStackForPrompt(scanResult.stack);
+
+  return `Review and validate these scanner detection results for accuracy.
+
+Detected Stack:
+${stackInfo || 'No technologies detected'}
+
+For each detection, assess if it seems accurate based on common project patterns.
+Identify any likely false positives or missing detections.
+
+Respond in JSON format:
+{
+  "validations": [
+    {
+      "technology": "name",
+      "status": "confirmed/uncertain/likely-false-positive",
+      "notes": "explanation if uncertain or false positive"
+    }
+  ],
+  "likelyMissed": [
+    {
+      "technology": "name",
+      "reason": "why this might be in use"
+    }
+  ]
+}`;
+}
+
+/**
+ * Prompt for generating stack-specific recommendations
+ */
+export function createRecommendationsPrompt(scanResult: ScanResult): string {
+  const stackInfo = formatStackForPrompt(scanResult.stack);
+
+  return `Based on this tech stack, provide specific recommendations for AI-assisted development.
+
+Detected Stack:
+${stackInfo || 'No technologies detected'}
+
+Provide recommendations in JSON format:
+{
+  "mcpServers": [
+    {
+      "name": "server identifier",
+      "priority": "high/medium/low",
+      "reason": "why this is recommended"
+    }
+  ],
+  "aiToolingTips": [
+    "Tips for working with AI tools on this codebase"
+  ],
+  "contextSuggestions": [
+    "Important context an AI should know about this stack"
+  ]
+}
+
+Focus on practical, actionable recommendations.`;
+}

package/src/ai/providers.ts

@@ -0,0 +1,136 @@
+/**
+ * AI Provider Configuration
+ * Configures AI providers (Anthropic, OpenAI, OpenRouter) for the enhancer
+ */
+
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import type { LanguageModel } from 'ai';
+
+/**
+ * Supported AI providers
+ */
+export type AIProvider = 'anthropic' | 'openai' | 'openrouter';
+
+/**
+ * Provider configuration result
+ */
+export interface ProviderConfig {
+  model: LanguageModel;
+  provider: AIProvider;
+  modelId: string;
+}
+
+/**
+ * Environment variable names for each provider
+ */
+const API_KEY_ENV_VARS: Record<AIProvider, string> = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+};
+
+/**
+ * Default models for each provider
+ * Using fast/cost-effective models for speed
+ */
+const DEFAULT_MODELS: Record<AIProvider, string> = {
+  anthropic: 'claude-sonnet-4-20250514',
+  openai: 'gpt-4o-mini',
+  openrouter: 'anthropic/claude-3.5-sonnet',
+};
+
+/**
+ * Check if an API key is available for a provider
+ */
+export function hasApiKey(provider: AIProvider): boolean {
+  const envVar = API_KEY_ENV_VARS[provider];
+  return !!process.env[envVar];
+}
+
+/**
+ * Get the API key for a provider
+ * @throws Error if API key is not set
+ */
+function getApiKey(provider: AIProvider): string {
+  const envVar = API_KEY_ENV_VARS[provider];
+  const apiKey = process.env[envVar];
+
+  if (!apiKey) {
+    throw new Error(
+      `API key not found. Set ${envVar} environment variable to use ${provider} provider.`
+    );
+  }
+
+  return apiKey;
+}
+
+/**
+ * Get a configured AI model for the specified provider
+ */
+export function getModel(provider: AIProvider = 'anthropic'): ProviderConfig {
+  const modelId = DEFAULT_MODELS[provider];
+
+  switch (provider) {
+    case 'anthropic': {
+      const anthropic = createAnthropic({
+        apiKey: getApiKey('anthropic'),
+      });
+      return {
+        model: anthropic(modelId),
+        provider,
+        modelId,
+      };
+    }
+
+    case 'openai': {
+      const openai = createOpenAI({
+        apiKey: getApiKey('openai'),
+      });
+      return {
+        model: openai(modelId),
+        provider,
+        modelId,
+      };
+    }
+
+    case 'openrouter': {
+      // OpenRouter uses OpenAI-compatible API
+      const openrouter = createOpenAI({
+        apiKey: getApiKey('openrouter'),
+        baseURL: 'https://openrouter.ai/api/v1',
+      });
+      return {
+        model: openrouter(modelId),
+        provider,
+        modelId,
+      };
+    }
+
+    default:
+      throw new Error(`Unknown provider: ${provider}`);
+  }
+}
+
+/**
+ * Get the first available provider with an API key
+ * Checks in order: anthropic, openai, openrouter
+ */
+export function getAvailableProvider(): AIProvider | null {
+  const providers: AIProvider[] = ['anthropic', 'openai', 'openrouter'];
+
+  for (const provider of providers) {
+    if (hasApiKey(provider)) {
+      return provider;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get the environment variable name for a provider's API key
+ */
+export function getApiKeyEnvVar(provider: AIProvider): string {
+  return API_KEY_ENV_VARS[provider];
+}

package/src/cli.ts

@@ -0,0 +1,255 @@
+import { Command } from 'commander';
+import { displayHeader } from './utils/header.js';
+import { initCommand } from './commands/init.js';
+import { runCommand, type RunOptions } from './commands/run.js';
+import { monitorCommand, type MonitorOptions } from './commands/monitor.js';
+import { newCommand, type NewOptions } from './commands/new.js';
+import { logger } from './utils/logger.js';
+
+/**
+ * Set up and configure the CLI
+ */
+export function createCli(): Command {
+  const program = new Command();
+
+  program
+    .name('ralph')
+    .description(
+      'AI-powered feature development loop CLI.\n\n' +
+        'Ralph auto-detects your tech stack and generates an intelligent\n' +
+        'development environment for AI-driven feature implementation.'
+    )
+    .version('0.1.0')
+    .hook('preAction', () => {
+      displayHeader();
+    })
+    .addHelpText(
+      'after',
+      `
+Examples:
+  $ ralph init                    Initialize Ralph in your project
+  $ ralph init --ai               Initialize with AI-enhanced 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
+
+Documentation:
+  https://github.com/your-org/ralph-cli#readme
+`
+    );
+
+  // ralph init
+  program
+    .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/'
+    )
+    .option('--ai', 'Enable AI-enhanced analysis for deeper project insights')
+    .option(
+      '--provider <name>',
+      'AI provider to use (anthropic, openai, openrouter)',
+      'anthropic'
+    )
+    .option('-y, --yes', 'Accept defaults and skip all confirmation prompts')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  $ ralph init                           Basic initialization
+  $ ralph init --ai                      With AI-enhanced analysis (Anthropic)
+  $ ralph init --ai --provider openai    With 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
+`
+    )
+    .action(async (options) => {
+      try {
+        await initCommand(options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  // ralph run <feature>
+  program
+    .command('run <feature>')
+    .description(
+      'Run the feature development loop for a specific feature.\n\n' +
+        'Executes the AI-driven implementation workflow using the feature\n' +
+        'spec in .ralph/specs/<feature>.md'
+    )
+    .option(
+      '--worktree',
+      'Use git worktree for isolation (enables parallel execution of multiple features)'
+    )
+    .option(
+      '--resume',
+      'Resume an interrupted loop (reuses existing branch and worktree)'
+    )
+    .option(
+      '--model <model>',
+      'Claude model to use for implementation (opus, sonnet)'
+    )
+    .option(
+      '--max-iterations <n>',
+      'Maximum number of implementation iterations (default: 50)',
+      parseInt
+    )
+    .option(
+      '--max-e2e-attempts <n>',
+      'Maximum E2E test retry attempts before giving up (default: 3)',
+      parseInt
+    )
+    .addHelpText(
+      'after',
+      `
+Examples:
+  $ ralph run user-auth                     Run the user-auth feature
+  $ ralph run payment --worktree            Run in isolated worktree
+  $ ralph run payment --resume              Resume interrupted session
+  $ ralph run my-feature --model opus       Use Claude Opus model
+  $ ralph run my-feature --max-iterations 30 --max-e2e-attempts 5
+
+Notes:
+  - Create a feature spec first with: ralph new <feature>
+  - The spec file should be at: .ralph/specs/<feature>.md
+  - Use --worktree to run multiple features in parallel
+`
+    )
+    .action(async (feature: string, options) => {
+      try {
+        const runOptions: RunOptions = {
+          worktree: options.worktree,
+          resume: options.resume,
+          model: options.model,
+          maxIterations: options.maxIterations,
+          maxE2eAttempts: options.maxE2eAttempts,
+        };
+        await runCommand(feature, runOptions);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  // ralph monitor <feature>
+  program
+    .command('monitor <feature>')
+    .description(
+      'Launch the monitoring dashboard for a feature.\n\n' +
+        'Displays real-time progress including iteration count, phase,\n' +
+        'task completion, token usage, and E2E test status.'
+    )
+    .option(
+      '--bash',
+      'Use the bash script monitor instead of the built-in dashboard'
+    )
+    .option('--python', 'Use the Python TUI monitor (if available)')
+    .option(
+      '--interval <seconds>',
+      'Dashboard refresh interval in seconds (default: 5)',
+      parseInt,
+      5
+    )
+    .addHelpText(
+      'after',
+      `
+Examples:
+  $ ralph monitor my-feature              Monitor with built-in dashboard
+  $ ralph monitor my-feature --interval 2 Refresh every 2 seconds
+  $ ralph monitor my-feature --bash       Use bash script monitor
+
+Dashboard Shows:
+  - Current phase (Planning, Implementation, E2E Testing, etc.)
+  - Iteration progress
+  - Task completion status
+  - Token usage (input/output)
+  - Git branch information
+`
+    )
+    .action(async (feature: string, options) => {
+      try {
+        const monitorOptions: MonitorOptions = {
+          bash: options.bash,
+          python: options.python,
+          interval: options.interval,
+        };
+        await monitorCommand(feature, monitorOptions);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  // ralph new <feature>
+  program
+    .command('new <feature>')
+    .description(
+      'Create a new feature specification from template.\n\n' +
+        'Generates a markdown spec file with sections for requirements,\n' +
+        'acceptance criteria, technical notes, and more.'
+    )
+    .option('-e, --edit', 'Open the spec in your editor after creation')
+    .option(
+      '--editor <editor>',
+      'Editor command to use (defaults to $EDITOR or "code")'
+    )
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .option('-f, --force', 'Overwrite existing spec file without prompting')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  $ ralph new user-dashboard              Create spec with prompts
+  $ ralph new user-dashboard --edit       Create and open in editor
+  $ ralph new user-dashboard -e --editor vim  Open in vim
+  $ ralph new user-dashboard --yes        Skip confirmations
+  $ ralph new user-dashboard --force      Overwrite if exists
+
+Output:
+  Creates: .ralph/specs/<feature>.md
+
+Template includes sections for:
+  - Purpose and user stories
+  - Functional and non-functional requirements
+  - Technical notes and dependencies
+  - Visual requirements (for UI features)
+  - API endpoints
+  - Acceptance criteria
+`
+    )
+    .action(async (feature: string, options) => {
+      try {
+        const newOptions: NewOptions = {
+          edit: options.edit,
+          editor: options.editor,
+          yes: options.yes,
+          force: options.force,
+        };
+        await newCommand(feature, newOptions);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  return program;
+}
+
+/**
+ * Handle command errors with user-friendly output
+ */
+function handleCommandError(error: unknown): void {
+  if (error instanceof Error) {
+    logger.error(error.message);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+  } else {
+    logger.error(String(error));
+  }
+  process.exit(1);
+}