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

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,196 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# errbuddy
+
+**Plain-English explanations for errors, right in your terminal.**
+
+Stop copying stack traces into a browser. Prefix your command with `errbuddy` and get *what* went wrong, *why*, and *how to fix it* — from an AI model that runs on your own machine.
+
+[![npm version](https://img.shields.io/npm/v/error-solution-ai-buddy?color=cb3837&logo=npm)](https://www.npmjs.com/package/error-solution-ai-buddy)
+[![npm downloads](https://img.shields.io/npm/dm/error-solution-ai-buddy)](https://www.npmjs.com/package/error-solution-ai-buddy)
+![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)
+![AI](https://img.shields.io/badge/AI-local%20via%20Ollama-black)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/blob/main/error-solution-ai-buddy/LICENSE)
+
+</div>
+
+```text
+$ 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 call .map() on a variable that is undefined.        │
+│                                                                   │
+│  ❓ Why it happens                                                │
+│  The data you expected (probably from an API) wasn't there yet.   │
+│                                                                   │
+│  ✅ How to fix it                                                 │
+│  Check that the variable exists before calling .map().            │
+│                                                                   │
+│  💡 Example                                                       │
+│    if (data) {                                                    │
+│      data.map(...)                                                │
+│    }                                                              │
+│                                                                   │
+╰───────────────────────────────────────────────────────────────────╯
+```
+
+## Why errbuddy
+
+When an error shows up, most of us copy it, open a browser, paste it into a search engine or chatbot, read, switch back, and lose our train of thought. errbuddy removes every one of those steps.
+
+- **Zero context switching.** The explanation appears right under the error.
+- **Private by default.** The AI runs locally through [Ollama](https://ollama.com). Your code and errors never leave your computer.
+- **Free.** No API keys, no accounts, no usage limits.
+- **Works offline, and without AI.** If Ollama isn't running, errbuddy falls back to built-in explanations for common errors.
+- **Drop-in.** Your program runs exactly as before: same output, same input, same exit code.
+
+## Quick start
+
+```bash
+npm install -g error-solution-ai-buddy
+errbuddy node app.js
+```
+
+That's it. You'll get pattern-based explanations straight away.
+
+### Turn on AI explanations (optional)
+
+1. Install Ollama from [ollama.com/download](https://ollama.com/download)
+2. Download the default model (about 400 MB, runs fine on low-RAM laptops):
+   ```bash
+   ollama pull qwen2.5:0.5b
+   ```
+3. Make sure Ollama is running: open the Ollama app, or run `ollama serve`
+
+The next time you run `errbuddy`, it detects Ollama automatically. If the default model isn't installed but another one is, errbuddy uses that instead.
+
+## Usage
+
+Put `errbuddy` in front of the command you normally run:
+
+```bash
+errbuddy node app.js        # instead of: node app.js
+errbuddy npm start          # instead of: npm start
+errbuddy java MyApp         # instead of: java MyApp
+errbuddy dotnet run         # instead of: dotnet run
+```
+
+### Options
+
+| Option | What it does |
+|---|---|
+| `--model <name>` | Use a different Ollama model, e.g. `--model llama3.2` for richer answers |
+| `--offline` | Skip AI and use built-in pattern matching only |
+| `--no-ai` | Show errors without any explanation |
+| `-V, --version` | Show the installed version |
+| `-h, --help` | Show help |
+
+| Command | What it does |
+|---|---|
+| `errbuddy examples` | Show usage examples |
+| `errbuddy config` | Show the current model and Ollama URL |
+
+> Put errbuddy's own options **before** your command: `errbuddy --model llama3.2 node app.js`. Anything after the command is passed straight through to it.
+
+## Supported languages
+
+| Language | Detected errors include |
+|---|---|
+| JavaScript / Node.js | `TypeError`, `ReferenceError`, `SyntaxError`, missing modules |
+| Java | `NullPointerException`, `ArrayIndexOutOfBoundsException`, `ClassNotFoundException`, compile errors |
+| C# / .NET | `NullReferenceException`, `IndexOutOfRangeException`, `CSxxxx` compiler errors |
+
+With AI enabled, errbuddy can explain other errors too; pattern matching covers the cases above.
+
+## How it works
+
+```text
+errbuddy node app.js
+        │
+        ▼
+ Runs your command ──► stdout is shown as normal
+        │              stderr is shown AND captured
+        ▼
+ Error detector ──► finds the language, error type, file and line
+        │
+        ▼
+ Sanitizer ──► strips file paths and anything that looks like a secret
+        │
+        ├── Ollama running? ──► local AI explains WHAT / WHY / FIX / EXAMPLE
+        └── Not running?    ──► built-in pattern explanation
+        │
+        ▼
+ Formatted explanation printed under the error, then your exit code is returned
+```
+
+Want the design reasoning? See [architecture](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/blob/main/error-solution-ai-buddy/docs/architecture.md) and [design decisions](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/blob/main/error-solution-ai-buddy/docs/decisions.md).
+
+## Privacy
+
+- The AI runs **100% locally** through Ollama. Nothing is sent to the cloud.
+- Before an error reaches the model, absolute file paths (`/Users/...`, `C:\Users\...`) are replaced with `[path]` and values that look like API keys, tokens or passwords are replaced with `[REDACTED]`.
+- No telemetry, no analytics, no account.
+- A local history of errors and explanations is kept in `~/.errbuddy/history.json`. Delete that file at any time to clear it.
+
+## VS Code extension
+
+The repo also includes an Error Buddy extension for VS Code that explains errors from the integrated terminal or from selected text. It isn't on the Marketplace yet. To try it, install [`error-buddy-1.0.0.vsix`](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/tree/main/error-solution-ai-buddy/extension) with **Extensions → … → Install from VSIX**.
+
+Commands: *Explain Selected Error*, *Explain Last Terminal Error*, *Toggle Auto-Explain*, *Open Error Buddy Terminal*, *Show Error History*.
+
+## Troubleshooting
+
+**"Ollama not detected"**
+1. Open the Ollama app, or run `ollama serve`
+2. Check it responds: `curl http://localhost:11434/api/tags`
+3. Make sure you have a model: `ollama pull qwen2.5:0.5b`
+
+**The AI explanation timed out**
+Your machine may be busy or the model too large. Use the default `qwen2.5:0.5b`, or run with `--offline`.
+
+**`errbuddy: command not found`**
+Restart your terminal. If it still fails, check that npm's global bin folder is on your `PATH` (`npm prefix -g` shows where it is).
+
+## Development
+
+```bash
+git clone https://github.com/sithija-jayasinghe/solution-ai-buddy-v1.git
+cd solution-ai-buddy-v1/error-solution-ai-buddy
+npm install
+npm test          # 62 tests, Node's built-in test runner
+npm link          # use your local copy as the global `errbuddy`
+```
+
+```text
+error-solution-ai-buddy/
+├── cli/
+│   ├── index.js            # CLI entry: runs the command, wires everything together
+│   ├── error-listener.js   # language detection and error patterns
+│   └── formatter.js        # terminal output
+├── backend/src/
+│   ├── ai/ollama-service.js            # Ollama client, prompt and response parsing
+│   └── services/history-service.js     # local error history
+├── extension/              # VS Code extension (TypeScript)
+├── docs/                   # architecture and design decisions
+└── tests/
+```
+
+## Roadmap
+
+- [ ] Python and Go error patterns
+- [ ] Optional cloud models (bring your own API key) for people who don't want to run Ollama
+- [ ] `errbuddy history` command to search past errors
+- [ ] Publish the VS Code extension to the Marketplace
+
+## Contributing
+
+Issues and pull requests are welcome. If errbuddy explained something badly, [open an issue](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/issues) with the error text so the patterns and prompts can improve.
+
+## License
+
+[MIT](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/blob/main/error-solution-ai-buddy/LICENSE) © Sithija Harshana Jayasinghe

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
+        }
+      }
+    }
+  }
+}

package/backend/src/services/history-service.js

@@ -0,0 +1,194 @@
+/**
+ * Error History Service - Stores and retrieves past errors
+ * 
+ * WHY JSON file instead of SQLite:
+ * 1. No native compilation needed (works on all systems without Visual Studio)
+ * 2. Simple to understand and debug
+ * 3. Good enough for local history
+ * 4. Can be upgraded to SQLite later if needed
+ * 
+ * This service allows:
+ * - Saving errors and their explanations for later reference
+ * - Searching past errors ("have I seen this before?")
+ * - Learning which errors are most common
+ */
+
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
+
+export class HistoryService {
+  constructor(filePath = null) {
+    // Default location: ~/.errbuddy/history.json
+    if (!filePath) {
+      const errbuddyDir = join(homedir(), '.errbuddy');
+      if (!existsSync(errbuddyDir)) {
+        mkdirSync(errbuddyDir, { recursive: true });
+      }
+      filePath = join(errbuddyDir, 'history.json');
+    }
+
+    this.filePath = filePath;
+    this.data = this.load();
+  }
+
+  /**
+   * Load history from file
+   */
+  load() {
+    try {
+      if (existsSync(this.filePath)) {
+        const content = readFileSync(this.filePath, 'utf-8');
+        return JSON.parse(content);
+      }
+    } catch (err) {
+      // Silently fail and use default
+    }
+    
+    // Return default structure
+    return {
+      errors: [],
+      nextId: 1
+    };
+  }
+
+  /**
+   * Save history to file
+   */
+  save() {
+    try {
+      writeFileSync(this.filePath, JSON.stringify(this.data, null, 2));
+    } catch (err) {
+      // Silently fail - history is not critical
+    }
+  }
+
+  /**
+   * Save an error and its explanation
+   */
+  saveError(error, explanation, command = null) {
+    const entry = {
+      id: this.data.nextId++,
+      timestamp: new Date().toISOString(),
+      language: error.language || null,
+      errorType: error.errorType || null,
+      errorMessage: error.errorMessage || null,
+      errorFull: (error.fullText && error.fullText.length > 2000) ? error.fullText.substring(0, 2000) + '... (truncated)' : (error.fullText || null),
+      filePath: error.file || null,
+      lineNumber: error.line || null,
+      explanationWhat: explanation?.what || null,
+      explanationWhy: explanation?.why || null,
+      explanationFix: explanation?.fix || null,
+      explanationExample: explanation?.example || null,
+      command: command,
+      helpful: null
+    };
+
+    this.data.errors.push(entry);
+    
+    // Keep only last 500 errors to prevent file from growing too large
+    if (this.data.errors.length > 500) {
+      this.data.errors = this.data.errors.slice(-500);
+    }
+    
+    this.save();
+    return entry.id;
+  }
+
+  /**
+   * Mark an explanation as helpful or not
+   */
+  markHelpful(id, helpful) {
+    const entry = this.data.errors.find(e => e.id === id);
+    if (entry) {
+      entry.helpful = helpful;
+      this.save();
+    }
+  }
+
+  /**
+   * Get recent errors
+   */
+  getRecent(limit = 10) {
+    return this.data.errors
+      .slice(-limit)
+      .reverse();
+  }
+
+  /**
+   * Search errors by type or message
+   */
+  search(query, limit = 20) {
+    const lowerQuery = query.toLowerCase();
+    return this.data.errors
+      .filter(e => 
+        (e.errorType && e.errorType.toLowerCase().includes(lowerQuery)) ||
+        (e.errorMessage && e.errorMessage.toLowerCase().includes(lowerQuery))
+      )
+      .slice(-limit)
+      .reverse();
+  }
+
+  /**
+   * Find similar errors (useful for "have I seen this before?")
+   */
+  findSimilar(errorType, language) {
+    return this.data.errors
+      .filter(e => e.errorType === errorType && e.language === language)
+      .slice(-5)
+      .reverse();
+  }
+
+  /**
+   * Get error statistics
+   */
+  getStats() {
+    const errors = this.data.errors;
+    
+    // Count by language
+    const byLanguage = {};
+    errors.forEach(e => {
+      if (e.language) {
+        byLanguage[e.language] = (byLanguage[e.language] || 0) + 1;
+      }
+    });
+
+    // Count by error type
+    const byType = {};
+    errors.forEach(e => {
+      if (e.errorType) {
+        byType[e.errorType] = (byType[e.errorType] || 0) + 1;
+      }
+    });
+
+    // Sort and format
+    const sortedByLanguage = Object.entries(byLanguage)
+      .map(([language, count]) => ({ language, count }))
+      .sort((a, b) => b.count - a.count);
+
+    const sortedByType = Object.entries(byType)
+      .map(([errorType, count]) => ({ errorType, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10);
+
+    // Helpful stats
+    const helpful = errors.filter(e => e.helpful === true).length;
+    const notHelpful = errors.filter(e => e.helpful === false).length;
+    const noFeedback = errors.filter(e => e.helpful === null).length;
+
+    return {
+      total: errors.length,
+      byLanguage: sortedByLanguage,
+      topErrors: sortedByType,
+      feedback: { helpful, notHelpful, noFeedback }
+    };
+  }
+
+  /**
+   * Clear all history
+   */
+  clearHistory() {
+    this.data = { errors: [], nextId: 1 };
+    this.save();
+  }
+}