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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sithija Harshana Jayasinghe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,292 @@
-# Temporary Holding Version
+# Error → Solution AI Buddy 🤖
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> AI-powered error explanations directly in your terminal. No context switching!
+
+![Node.js](https://img.shields.io/badge/Node.js-18+-green)
+![Ollama](https://img.shields.io/badge/AI-Ollama-blue)
+![License](https://img.shields.io/badge/License-MIT-yellow)
+
+## The Problem
+
+You're coding. An error appears. You:
+1. Copy the error
+2. Open browser
+3. Paste into Google/ChatGPT
+4. Read through results
+5. Go back to terminal
+6. Forget what you were doing
+
+**That's 5+ context switches. We fix that.**
+
+## The Solution
+
+```bash
+$ errbuddy node app.js
+
+TypeError: Cannot read properties of undefined (reading 'map')
+    at app.js:12:5
+
+╭─ 🤖 Error Buddy Explanation: ─────────────────────────────────────╮
+│                                                                    │
+│  📘 What is this?                                                 │
+│  You tried to use `.map()` on a variable that is undefined.       │
+│                                                                    │
+│  ❓ Why it happens?                                                │
+│  The data you expected (probably from an API) wasn't available.   │
+│                                                                    │
+│  ✅ How to fix it:                                                 │
+│  Check if the variable exists before calling `.map()`.            │
+│                                                                    │
+│  💡 Example:                                                       │
+│    if (data) {                                                     │
+│      data.map(...)                                                 │
+│    }                                                               │
+│                                                                    │
+╰────────────────────────────────────────────────────────────────────╯
+```
+
+## Quick Start
+
+```bash
+npm install -g error-solution-ai-buddy
+errbuddy node app.js
+```
+
+That's it. Errors are explained with built-in pattern matching straight away.
+
+### Turn on AI explanations (optional, free, runs on your machine)
+
+errbuddy uses [Ollama](https://ollama.com) to run a small AI model locally, so your code and errors never leave your computer.
+
+1. Install Ollama from https://ollama.com/download
+2. Download the default model (about 400 MB):
+   ```bash
+   ollama pull qwen2.5:0.5b
+   ```
+3. Make sure Ollama is running (`ollama serve`, or open the Ollama app)
+
+Want better explanations? Use a bigger model: `errbuddy --model llama3.2 node app.js`
+
+If Ollama isn't running, errbuddy still works — it falls back to pattern matching.
+
+## Installation & Usage
+
+### 1. Download the Project
+- Clone the repository:
+  ```sh
+  git clone <your-repo-url>
+  ```
+
+### 2. Install Dependencies
+- In the project folder, run:
+  ```sh
+  npm install
+  ```
+
+### 3. Use the CLI Tool
+- Go to the CLI directory:
+  ```sh
+  cd error-solution-ai-buddy/cli
+  npm link
+  ```
+- Now you can run the CLI from anywhere:
+  ```sh
+  errbuddy <your-command>
+  # Example:
+  errbuddy node test-error.js
+  ```
+
+### 4. Use the VS Code Extension
+- Build the extension (if needed):
+  ```sh
+  cd error-solution-ai-buddy/extension
+  npm install
+  npm run build
+  ```
+- Install the extension in VS Code:
+  - Use "Install from VSIX..." if you have a packaged file.
+  - Or run:
+    ```sh
+    code --install-extension <path-to-extension-folder>
+    ```
+- Reload VS Code.
+
+### 5. Start Using
+- For CLI: Run commands with `errbuddy` prefix.
+- For extension: Use terminal and Error Buddy commands in VS Code.
+### Manual Setup
+
+#### Step 1: Install Ollama (Optional - for AI features)
+
+```bash
+# Windows: Download from https://ollama.ai
+
+# macOS
+brew install ollama
+
+# Linux
+curl -fsSL https://ollama.ai/install.sh | sh
+```
+
+### 2. Start Ollama & Download Model
+
+```bash
+ollama serve   # Start the server (keep this running)
+ollama pull llama3.2   # Download the model (~2GB)
+```
+### 3. Install Error Buddy
+
+```bash
+# From this directory
+npm install
+npm link   # Makes 'errbuddy' available globally
+```
+
+### 4. Use It!
+
+```bash
+# Instead of: node app.js
+errbuddy node app.js
+
+# Instead of: npm start
+errbuddy npm start
+
+# Instead of: java MyApp
+errbuddy java MyApp
+
+# Instead of: dotnet run
+errbuddy dotnet run
+```
+
+## Supported Languages
+
+| Language | Status | Error Types |
+|----------|--------|-------------|
+| JavaScript/Node.js | ✅ Full | TypeError, ReferenceError, SyntaxError, Module errors |
+| Java | ✅ Full | NullPointer, ArrayIndex, ClassNotFound, Compile errors |
+| C#/.NET | ✅ Full | NullReference, Index, CS errors, Runtime exceptions |
+
+## CLI Options
+
+```bash
+# Disable AI (use pattern matching only)
+errbuddy --no-ai node app.js
+
+# Use a different Ollama model
+errbuddy --model codellama node app.js
+
+# Force offline mode
+errbuddy --offline node app.js
+
+# Show examples
+errbuddy examples
+
+# Show configuration
+errbuddy config
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────┐
+│  You run: errbuddy node app.js          │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│  CLI spawns: node app.js                │
+│  • stdout → displayed normally          │
+│  • stderr → captured for analysis       │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│  Error Detector                         │
+│  • Detects language (JS/Java/C#)        │
+│  • Extracts error type, file, line      │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│  Ollama AI (local)                      │
+│  • Receives sanitized error             │
+│  • Returns structured explanation       │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│  Pretty Terminal Output                 │
+│  • WHAT / WHY / FIX / EXAMPLE           │
+└─────────────────────────────────────────┘
+```
+
+## Privacy & Security
+
+Your code **never leaves your machine**:
+
+- ✅ Ollama runs 100% locally
+- ✅ File paths are stripped before AI processing
+- ✅ No telemetry or analytics
+- ✅ No API keys required
+- ✅ Works completely offline
+
+## Project Structure
+
+```
+error-solution-ai-buddy/
+├── cli/
+│   ├── index.js           # CLI entry point
+│   ├── error-listener.js  # Error detection & patterns
+│   └── formatter.js       # Terminal output formatting
+├── backend/
+│   └── src/
+│       ├── ai/
+│       │   └── ollama-service.js  # Ollama integration
+│       └── services/
+│           └── history-service.js # Error history (SQLite)
+├── docs/
+│   ├── architecture.md    # System design
+│   ├── decisions.md       # Why we made these choices
+│   └── terminal-integration.md
+├── tests/
+│   └── *.test.js
+├── package.json
+└── README.md
+```
+
+## Configuration
+
+Configuration is stored in `~/.errbuddy/config.json`:
+
+```json
+{
+  "ollamaUrl": "http://localhost:11434",
+  "model": "llama3.2",
+  "showSpinner": true,
+  "saveHistory": true
+}
+```
+
+## Troubleshooting
+
+### "Ollama not detected"
+
+1. Make sure Ollama is running: `ollama serve`
+2. Check it's accessible: `curl http://localhost:11434/api/tags`
+3. Pull a model: `ollama pull qwen2.5:0.5b`
+
+### "AI explanation timed out"
+
+- Try a smaller model: `errbuddy --model llama3.2:1b node app.js`
+- Check system resources (Ollama needs ~4GB RAM)
+
+### Command not found after `npm link`
+
+- On Windows: Restart your terminal
+- On macOS/Linux: Check your PATH includes npm global bin
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Submit a PR
+
+## License
+
+MIT © 2024

package/backend/src/ai/ollama-service.js

@@ -0,0 +1,264 @@
+/**
+ * Ollama AI Service - Handles communication with local Ollama server
+ * 
+ * WHY OLLAMA:
+ * 1. 100% free - no API keys needed
+ * 2. Runs locally - your code never leaves your machine
+ * 3. Works offline - no internet required after model download
+ * 4. Fast - local inference with no network latency
+ * 
+ * SETUP:
+ * 1. Install Ollama: https://ollama.ai
+ * 2. Run: ollama pull llama3.2
+ * 3. Run: ollama serve
+ */
+
+/**
+ * System prompt for error explanation
+ * 
+ * WHY this structure:
+ * - Forces consistent output format
+ * - Beginner-friendly language
+ * - Prevents hallucinations with explicit rules
+ */
+const SYSTEM_PROMPT = `You are an expert programming assistant that explains errors to developers.
+
+RULES (VERY IMPORTANT):
+1. Always respond in this EXACT format:
+   WHAT: [Name the specific error code/exception (e.g. "NullPointerException", "CS1061") and what it means]
+   WHY: [Explain specifically why this code causes that error]
+   FIX: [Clear steps to fix the error]
+   EXAMPLE: [Short code example if helpful]
+
+2. Use simple language a junior developer can understand
+3. Be concise - no long paragraphs
+4. Do NOT assume frameworks (like Spring, React) unless the error explicitly mentions them
+5. Focus on the most likely cause first (typos, missing variables, syntax)
+6. IF suggesting a fix involves installing a new package, ONLY do so if the error is explicitly "Module/Package not found".
+7. If the error mentions "not a statement" and looks like "variable;", explain that standalone variables are not valid statements.
+8. Never make up information - if unsure, say so
+9. Always explicitly mention the error name or code in the "WHAT" section.
+
+LANGUAGE-SPECIFIC TIPS:
+- JavaScript: Common issues are undefined/null, async/await, imports
+- Java: 
+  - "not a statement" often means a standalone variable (e.g. 'x;') which is invalid in Java. It must be an assignment ('x=1;') or method call.
+  - Common issues: NullPointer, missing variables, types
+  - Avoid suggesting @Autowired unless it's a Spring error
+- C#: Common issues are null reference, missing using, async
+
+Remember: Developers are frustrated when they see errors. Be helpful and direct.`;
+
+export class AIService {
+  constructor(baseUrl = 'http://localhost:11434', model = 'llama3.2') {
+    this.baseUrl = baseUrl;
+    this.model = model;
+    this.timeout = 30000; // 30 second timeout
+  }
+
+  /**
+   * Check if Ollama is running and accessible
+   */
+  async checkConnection() {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 3000);
+      
+      const response = await fetch(`${this.baseUrl}/api/tags`, {
+        method: 'GET',
+        signal: controller.signal, // 3 second timeout for health check
+      }).finally(() => clearTimeout(timeoutId));
+      
+      if (!response.ok) {
+        return false;
+      }
+
+      const data = await response.json();
+      
+      // Check if the model we want is available
+      const models = data.models || [];
+      const modelBaseName = this.model.split(':')[0];
+      const hasModel = models.some(m => m.name.startsWith(modelBaseName));
+      
+      if (!hasModel && models.length > 0) {
+        // Use first available model as fallback
+        this.model = models[0].name;
+      }
+
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get explanation for an error from Ollama
+   */
+  async explainError(errorText, language = 'unknown') {
+    const prompt = this.buildPrompt(errorText, language);
+    
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/api/generate`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model: this.model,
+          prompt: prompt,
+          system: SYSTEM_PROMPT,
+          stream: false,
+          options: {
+            temperature: 0.1,  // Very low to prevent hallucinations
+            top_p: 0.9,
+            num_predict: 500, // Limit response length
+          }
+        }),
+        signal: controller.signal,
+      }).finally(() => clearTimeout(timeoutId));
+
+      if (!response.ok) {
+        let errorMsg = '';
+        try {
+          const errorJson = await response.json();
+          errorMsg = errorJson.error || JSON.stringify(errorJson);
+        } catch {
+          errorMsg = await response.text();
+        }
+
+        // Check for memory error
+        if (errorMsg.includes('memory')) {
+          throw new Error('Not enough RAM. Try: errbuddy --model qwen2.5:0.5b');
+        }
+        throw new Error(`Ollama returned ${response.status}: ${errorMsg}`);
+      }
+
+      const data = await response.json();
+      
+      // Check for error in response
+      if (data.error) {
+        throw new Error(data.error);
+      }
+      
+      return this.parseResponse(data.response);
+    } catch (error) {
+      if (error.name === 'TimeoutError' || error.name === 'AbortError') {
+        throw new Error('AI explanation timed out. Try a smaller model.');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Build the prompt for the AI
+   */
+  buildPrompt(errorText, language) {
+    const langName = {
+      javascript: 'JavaScript/Node.js',
+      java: 'Java',
+      csharp: 'C#/.NET',
+      unknown: 'programming'
+    }[language] || language;
+
+    return `Explain this ${langName} error to a developer:
+
+\`\`\`
+${errorText}
+\`\`\`
+
+Remember to use the format: WHAT, WHY, FIX, EXAMPLE`;
+  }
+
+  /**
+   * Parse the AI response into structured format
+   */
+  parseResponse(response) {
+    const result = {
+      what: null,
+      why: null,
+      fix: null,
+      example: null,
+      raw: response
+    };
+
+    // Try to extract structured parts
+    const whatMatch = response.match(/WHAT:\s*(.+?)(?=WHY:|FIX:|EXAMPLE:|$)/is);
+    const whyMatch = response.match(/WHY:\s*(.+?)(?=WHAT:|FIX:|EXAMPLE:|$)/is);
+    const fixMatch = response.match(/FIX:\s*(.+?)(?=WHAT:|WHY:|EXAMPLE:|$)/is);
+    const exampleMatch = response.match(/EXAMPLE:\s*(.+?)(?=WHAT:|WHY:|FIX:|$)/is);
+
+    if (whatMatch) result.what = whatMatch[1].trim();
+    if (whyMatch) result.why = whyMatch[1].trim();
+    if (fixMatch) result.fix = fixMatch[1].trim();
+    if (exampleMatch) result.example = exampleMatch[1].trim();
+
+    // If structured parsing failed, try to make sense of the response
+    if (!result.what && !result.why && !result.fix) {
+      // Split by sentences and assign
+      const sentences = response.split(/[.!]\s+/).filter(s => s.trim());
+      if (sentences.length >= 1) result.what = sentences[0].trim() + '.';
+      if (sentences.length >= 2) result.why = sentences[1].trim() + '.';
+      if (sentences.length >= 3) result.fix = sentences.slice(2).join('. ').trim();
+    }
+
+    // Extract code blocks for example
+    if (!result.example) {
+      const codeMatch = response.match(/```[\w]*\n?([\s\S]+?)```/);
+      if (codeMatch) {
+        result.example = codeMatch[1].trim();
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Stream explanation (for future use - better UX for long responses)
+   * Currently not used but ready for implementation
+   */
+  async *streamExplanation(errorText, language = 'unknown') {
+    const prompt = this.buildPrompt(errorText, language);
+    
+    const response = await fetch(`${this.baseUrl}/api/generate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: this.model,
+        prompt: prompt,
+        system: SYSTEM_PROMPT,
+        stream: true,
+        options: {
+          temperature: 0.3,
+          num_predict: 500,
+        }
+      }),
+    });
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunk = decoder.decode(value);
+      const lines = chunk.split('\n').filter(line => line.trim());
+
+      for (const line of lines) {
+        try {
+          const data = JSON.parse(line);
+          if (data.response) {
+            yield data.response;
+          }
+        } catch {
+          // Ignore JSON parse errors for incomplete chunks
+        }
+      }
+    }
+  }
+}