error-solution-ai-buddy 0.0.0-stage → 1.0.0

package/cli/formatter.js

@@ -0,0 +1,244 @@
+/**
+ * Formatter - Pretty prints error explanations to the terminal
+ * 
+ * This module handles all output formatting to make errors
+ * easy to read at a glance.
+ * 
+ * WHY separate formatting:
+ * 1. Single responsibility (easy to maintain)
+ * 2. Easy to change styling without touching logic
+ * 3. Can support different output formats (terminal, JSON, etc.)
+ */
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+
+export class Formatter {
+  constructor(options = {}) {
+    this.useColor = options.useColor !== false;
+    this.useEmoji = options.useEmoji !== false;
+    this.boxStyle = options.boxStyle || 'round';
+  }
+
+  /**
+   * Print AI-generated explanation
+   * 
+   * Expected format from AI:
+   * {
+   *   what: "What the error is",
+   *   why: "Why it happened",
+   *   fix: "How to fix it",
+   *   example: "Code example"
+   * }
+   */
+  printAIExplanation(explanation) {
+    const header = this.useEmoji ? '🤖 Error Buddy Explanation:' : '[Error Buddy]';
+    
+    let content = '';
+    
+    // What is this?
+    if (explanation.what) {
+      content += chalk.cyan.bold(this.useEmoji ? '📘 What is this?' : '[What]') + '\n';
+      content += this.wrapText(explanation.what) + '\n\n';
+    }
+    
+    // Why it happens?
+    if (explanation.why) {
+      content += chalk.yellow.bold(this.useEmoji ? '❓ Why it happens?' : '[Why]') + '\n';
+      content += this.wrapText(explanation.why) + '\n\n';
+    }
+    
+    // How to fix?
+    if (explanation.fix) {
+      content += chalk.green.bold(this.useEmoji ? '✅ How to fix it:' : '[Fix]') + '\n';
+      content += this.wrapText(explanation.fix) + '\n';
+    }
+    
+    // Code example
+    if (explanation.example) {
+      content += '\n' + chalk.magenta.bold(this.useEmoji ? '💡 Example:' : '[Example]') + '\n';
+      content += chalk.gray(this.formatCode(explanation.example));
+    }
+
+    // Print in a box
+    const box = boxen(content.trim(), {
+      title: header,
+      titleAlignment: 'left',
+      padding: 1,
+      margin: { top: 0, bottom: 1, left: 0, right: 0 },
+      borderStyle: this.boxStyle,
+      borderColor: 'cyan',
+    });
+
+    console.log(box);
+  }
+
+  /**
+   * Print pattern-based explanation (when AI is unavailable)
+   */
+  printPatternExplanation(analysis) {
+    if (!analysis.localExplanation) {
+      this.printGenericHelp(analysis);
+      return;
+    }
+
+    const explanation = analysis.localExplanation;
+    const header = this.useEmoji ? '📋 Quick Explanation:' : '[Quick Help]';
+    
+    let content = '';
+    
+    // Language detected
+    if (analysis.language && analysis.language !== 'unknown') {
+      content += chalk.gray(`Language: ${this.formatLanguage(analysis.language)}`) + '\n';
+      if (analysis.errorType) {
+        content += chalk.gray(`Error: ${analysis.errorType}`) + '\n';
+      }
+      content += '\n';
+    }
+
+    // What
+    content += chalk.cyan.bold(this.useEmoji ? '📘 What:' : '[What]') + '\n';
+    content += this.wrapText(explanation.what) + '\n\n';
+
+    // Why
+    content += chalk.yellow.bold(this.useEmoji ? '❓ Why:' : '[Why]') + '\n';
+    content += this.wrapText(explanation.why) + '\n\n';
+
+    // Fix
+    content += chalk.green.bold(this.useEmoji ? '✅ Fix:' : '[Fix]') + '\n';
+    content += this.wrapText(explanation.fix) + '\n';
+
+    // Example
+    if (explanation.example) {
+      content += '\n' + chalk.magenta.bold(this.useEmoji ? '💡 Example:' : '[Example]') + '\n';
+      content += chalk.gray(this.formatCode(explanation.example));
+    }
+
+    // Offline notice
+    content += '\n\n' + chalk.gray.italic('(Offline mode - start Ollama for AI explanations)');
+
+    const box = boxen(content.trim(), {
+      title: header,
+      titleAlignment: 'left',
+      padding: 1,
+      margin: { top: 0, bottom: 1, left: 0, right: 0 },
+      borderStyle: this.boxStyle,
+      borderColor: 'yellow',
+    });
+
+    console.log(box);
+  }
+
+  /**
+   * Print generic help when no pattern matches
+   */
+  printGenericHelp(analysis) {
+    const header = this.useEmoji ? '🔍 Error Detected:' : '[Error]';
+    
+    let content = '';
+    
+    if (analysis.language && analysis.language !== 'unknown') {
+      content += chalk.gray(`Language: ${this.formatLanguage(analysis.language)}`) + '\n';
+    }
+    
+    if (analysis.errorType) {
+      content += chalk.gray(`Type: ${analysis.errorType}`) + '\n';
+    }
+    
+    if (analysis.file) {
+      content += chalk.gray(`File: ${analysis.file}`) + '\n';
+    }
+    
+    if (analysis.line) {
+      content += chalk.gray(`Line: ${analysis.line}`) + '\n';
+    }
+
+    content += '\n';
+    content += chalk.cyan('Start Ollama for detailed AI explanations:') + '\n';
+    content += chalk.white('  1. Install Ollama: https://ollama.ai') + '\n';
+    content += chalk.white('  2. Run: ollama serve') + '\n';
+    content += chalk.white('  3. Try your command again') + '\n';
+
+    const box = boxen(content.trim(), {
+      title: header,
+      titleAlignment: 'left',
+      padding: 1,
+      margin: { top: 0, bottom: 1, left: 0, right: 0 },
+      borderStyle: this.boxStyle,
+      borderColor: 'gray',
+    });
+
+    console.log(box);
+  }
+
+  /**
+   * Format language name nicely
+   */
+  formatLanguage(lang) {
+    const names = {
+      javascript: 'JavaScript/Node.js',
+      java: 'Java',
+      csharp: 'C#/.NET',
+      python: 'Python',
+      unknown: 'Unknown',
+    };
+    return names[lang] || lang;
+  }
+
+  /**
+   * Wrap text to terminal width
+   */
+  wrapText(text, maxWidth = 70) {
+    if (!text) return '';
+    
+    const words = text.split(' ');
+    const lines = [];
+    let currentLine = '';
+
+    for (const word of words) {
+      if (currentLine.length + word.length + 1 <= maxWidth) {
+        currentLine += (currentLine ? ' ' : '') + word;
+      } else {
+        if (currentLine) lines.push(currentLine);
+        currentLine = word;
+      }
+    }
+    if (currentLine) lines.push(currentLine);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format code block with indentation
+   */
+  formatCode(code) {
+    if (!code) return '';
+    
+    // Add consistent indentation
+    return code
+      .split('\n')
+      .map(line => '  ' + line)
+      .join('\n');
+  }
+
+  /**
+   * Print a simple status message
+   */
+  printStatus(message, type = 'info') {
+    const icons = {
+      info: this.useEmoji ? 'ℹ️ ' : '[i] ',
+      success: this.useEmoji ? '✅ ' : '[+] ',
+      warning: this.useEmoji ? '⚠️ ' : '[!] ',
+      error: this.useEmoji ? '❌ ' : '[x] ',
+    };
+
+    const colors = {
+      info: chalk.cyan,
+      success: chalk.green,
+      warning: chalk.yellow,
+      error: chalk.red,
+    };
+
+    console.log(colors[type](icons[type] + message));
+  }
+}

package/cli/index.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+/**
+ * Error Solution AI Buddy - CLI Entry Point
+ * 
+ * This is the main entry point for the CLI tool.
+ * It wraps commands (node, npm, java, dotnet) and intercepts errors.
+ * 
+ * Usage: errbuddy <command> [args]
+ * Example: errbuddy node app.js
+ *          errbuddy npm start
+ *          errbuddy java MyApp
+ *          errbuddy dotnet run
+ */
+
+import { Command } from 'commander';
+import { spawn } from 'child_process';
+import { ErrorListener } from './error-listener.js';
+import { Formatter } from './formatter.js';
+import { AIService } from '../backend/src/ai/ollama-service.js';
+import { HistoryService } from '../backend/src/services/history-service.js';
+import chalk from 'chalk';
+
+const program = new Command();
+
+// Configuration
+const CONFIG = {
+  aiEnabled: true,
+  ollamaModel: 'qwen2.5:0.5b',  // Small model that works on low-RAM systems
+  ollamaUrl: 'http://localhost:11434',
+  showSpinner: true,
+  maxErrorLength: 2000,  // Truncate very long errors
+};
+
+program
+  .name('errbuddy')
+  .description('AI-powered error explanations directly in your terminal')
+  .version('1.0.0')
+  .enablePositionalOptions()
+  .passThroughOptions()
+  .argument('<command>', 'Command to run (node, npm, java, dotnet, etc.)')
+  .argument('[args...]', 'Arguments to pass to the command')
+  .option('--no-ai', 'Disable AI explanations (show errors only)')
+  .option('--model <model>', 'Ollama model to use', 'qwen2.5:0.5b')
+  .option('--offline', 'Force offline mode (pattern matching only)')
+  .action(async (command, args, options) => {
+    await runCommand(command, args, options);
+  });
+
+// Help command with examples
+program
+  .command('examples')
+  .description('Show usage examples')
+  .action(() => {
+    console.log(chalk.cyan('\n📚 Error Buddy Examples:\n'));
+    console.log('  ' + chalk.green('errbuddy node app.js'));
+    console.log('  ' + chalk.gray('→ Run Node.js app and explain any errors\n'));
+    console.log('  ' + chalk.green('errbuddy npm start'));
+    console.log('  ' + chalk.gray('→ Run npm script with error explanations\n'));
+    console.log('  ' + chalk.green('errbuddy java MyClass'));
+    console.log('  ' + chalk.gray('→ Run Java program with error explanations\n'));
+    console.log('  ' + chalk.green('errbuddy dotnet run'));
+    console.log('  ' + chalk.gray('→ Run .NET project with error explanations\n'));
+    console.log('  ' + chalk.green('errbuddy --no-ai node app.js'));
+    console.log('  ' + chalk.gray('→ Run without AI (pattern matching only)\n'));
+  });
+
+// Config command
+program
+  .command('config')
+  .description('Show current configuration')
+  .action(() => {
+    console.log(chalk.cyan('\n⚙️  Current Configuration:\n'));
+    console.log(`  AI Enabled:    ${CONFIG.aiEnabled ? chalk.green('Yes') : chalk.red('No')}`);
+    console.log(`  Ollama Model:  ${chalk.yellow(CONFIG.ollamaModel)}`);
+    console.log(`  Ollama URL:    ${chalk.gray(CONFIG.ollamaUrl)}`);
+    console.log('');
+  });
+
+/**
+ * Sanitize error text before sending to AI
+ * 
+ * WHY: Privacy protection - we don't want to leak:
+ * - File paths (might contain project names, usernames)
+ * - Environment variables
+ * - API keys that might appear in errors
+ */
+function sanitizeError(errorText) {
+  let sanitized = errorText;
+  
+  // Remove Windows-style absolute paths (C:\Users\...)
+  sanitized = sanitized.replace(/[A-Za-z]:\\(?:[^\\/:*?"<>|\r\n]+\\)*/g, '[path]\\');
+  
+  // Remove Unix-style absolute paths (/home/user/...)
+  sanitized = sanitized.replace(/\/(?:home|Users|var|usr|opt)\/[^\s:]+/g, '[path]');
+  
+  // Remove common secret patterns
+  sanitized = sanitized.replace(/(?:api[_-]?key|secret|password|token)\s*[:=]\s*['"]?[^'"\s]+['"]?/gi, '[REDACTED]');
+  
+  // Truncate if too long
+  if (sanitized.length > CONFIG.maxErrorLength) {
+    sanitized = sanitized.substring(0, CONFIG.maxErrorLength) + '\n... (truncated)';
+  }
+  
+  return sanitized;
+}
+
+/**
+ * Main function that runs the wrapped command
+ * 
+ * WHY we use spawn() instead of exec():
+ * - spawn() streams output in real-time (better UX)
+ * - exec() buffers everything (user waits too long)
+ */
+async function runCommand(command, args, options) {
+  const formatter = new Formatter();
+  const errorListener = new ErrorListener();
+  const aiService = new AIService(CONFIG.ollamaUrl, options.model || CONFIG.ollamaModel);
+  const history = new HistoryService();
+
+  // Check if Ollama is available (non-blocking)
+  let ollamaAvailable = false;
+  if (!options.offline && options.ai !== false) {
+    ollamaAvailable = await aiService.checkConnection();
+    if (!ollamaAvailable) {
+      console.log(chalk.yellow('⚠️  Ollama not detected. Using pattern matching only.'));
+      console.log(chalk.gray('   For AI explanations (free, runs locally):'));
+      console.log(chalk.gray('     1. Install Ollama:   https://ollama.com/download'));
+      console.log(chalk.gray(`     2. Download a model: ollama pull ${options.model || CONFIG.ollamaModel}`));
+      console.log(chalk.gray('     3. Start it:         ollama serve\n'));
+    }
+  }
+
+  // Spawn the child process
+  // stdio: ['inherit', 'pipe', 'pipe'] means:
+  // - stdin: inherited (user can type input)
+  // - stdout: piped (we capture and forward it)
+  // - stderr: piped (we capture, analyze, then forward it)
+  // 
+  // We join command + args into a single shell string to avoid Node.js 24+
+  // DEP0190 warning ("Passing args to a child process with shell option true
+  // can lead to security vulnerabilities"). This is safe here because the
+  // user controls the input (they typed the command themselves).
+  const fullCommand = [command, ...args].join(' ');
+  const child = spawn(fullCommand, [], {
+    stdio: ['inherit', 'pipe', 'pipe'],
+    shell: true,  // Required for Windows compatibility
+    env: { ...process.env, FORCE_COLOR: '1' }  // Preserve colors
+  });
+
+  let stderrBuffer = '';
+  let errorDetected = false;
+
+  // Forward stdout immediately (no delay)
+  child.stdout.on('data', (data) => {
+    process.stdout.write(data);
+  });
+
+  // Capture and analyze stderr
+  child.stderr.on('data', (data) => {
+    const text = data.toString();
+    
+    // Always show the original error first
+    process.stderr.write(data);
+    
+    // Buffer stderr for analysis
+    stderrBuffer += text;
+    
+    // Check if this looks like an error
+    if (errorListener.detectError(text)) {
+      errorDetected = true;
+    }
+  });
+
+  // When process ends, analyze collected errors
+  child.on('close', async (exitCode) => {
+    if (errorDetected && stderrBuffer.trim()) {
+      // Analyze the error
+      const analysis = errorListener.analyzeError(stderrBuffer);
+      
+      if (analysis.isError) {
+        console.log(''); // Blank line for readability
+        
+        // Try AI explanation if available
+        if (ollamaAvailable && options.ai !== false) {
+          const explanation = await explainWithAI(stderrBuffer, analysis, aiService, formatter);
+          try { history.saveError({ ...analysis, fullText: stderrBuffer }, explanation, `${command} ${args.join(' ')}`); } catch {}
+        } else {
+          // Fall back to pattern-based explanation
+          formatter.printPatternExplanation(analysis);
+          try { history.saveError({ ...analysis, fullText: stderrBuffer }, analysis.localExplanation, `${command} ${args.join(' ')}`); } catch {}
+        }
+      }
+    }
+    
+    // Exit with the same code as the child process
+    process.exit(exitCode);
+  });
+
+  // Handle spawn errors (command not found, etc.)
+  child.on('error', (err) => {
+    console.error(chalk.red(`\n❌ Failed to run command: ${command}`));
+    console.error(chalk.gray(`   ${err.message}`));
+    
+    if (err.code === 'ENOENT') {
+      console.error(chalk.yellow(`\n💡 Tip: Make sure "${command}" is installed and in your PATH.`));
+    }
+    
+    process.exit(1);
+  });
+}
+
+/**
+ * Get AI explanation for an error
+ */
+async function explainWithAI(errorText, analysis, aiService, formatter) {
+  const ora = (await import('ora')).default;
+  const spinner = ora({
+    text: 'Getting AI explanation...',
+    color: 'cyan'
+  }).start();
+
+  try {
+    // Sanitize the error before sending to AI
+    const sanitizedError = sanitizeError(errorText);
+    
+    const explanation = await aiService.explainError(sanitizedError, analysis.language);
+    spinner.stop();
+    
+    formatter.printAIExplanation(explanation);
+    return explanation;
+  } catch (err) {
+    spinner.stop();
+    console.log(chalk.yellow('⚠️  AI explanation failed. Showing pattern-based help:'));
+    formatter.printPatternExplanation(analysis);
+    return analysis.localExplanation;
+  }
+}
+
+// Run the CLI
+program.parse();

package/cli/package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "cli",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

package/cli/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "error-solution-ai-buddy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "AI-powered error explanation tool for developers - works directly in your terminal",
+  "type": "module",
+  "main": "cli/index.js",
+  "bin": {
+    "errbuddy": "./cli/index.js"
+  },
+  "files": [
+    "cli",
+    "backend",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node cli/index.js",
+    "test": "node --test tests/*.js",
+    "lint": "eslint cli/ backend/",
+    "demo": "node tests/samples/js-errors.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "error",
+    "debugging",
+    "ai",
+    "developer-tools",
+    "terminal",
+    "ollama",
+    "cli",
+    "llm",
+    "error-explainer",
+    "local-ai"
+  ],
+  "author": "Sithija Harshana Jayasinghe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sithija-jayasinghe/solution-ai-buddy-v1.git",
+    "directory": "error-solution-ai-buddy"
+  },
+  "homepage": "https://github.com/sithija-jayasinghe/solution-ai-buddy-v1#readme",
+  "bugs": {
+    "url": "https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "ora": "^7.0.1",
+    "boxen": "^7.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}