error-solution-ai-buddy 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +132 -228
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,292 +1,196 @@
1
- # Error → Solution AI Buddy 🤖
1
+ <div align="center">
2
2
 
3
- > AI-powered error explanations directly in your terminal. No context switching!
3
+ # errbuddy
4
4
 
5
- ![Node.js](https://img.shields.io/badge/Node.js-18+-green)
6
- ![Ollama](https://img.shields.io/badge/AI-Ollama-blue)
7
- ![License](https://img.shields.io/badge/License-MIT-yellow)
5
+ **Plain-English explanations for errors, right in your terminal.**
8
6
 
9
- ## The Problem
7
+ 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.
10
8
 
11
- You're coding. An error appears. You:
12
- 1. Copy the error
13
- 2. Open browser
14
- 3. Paste into Google/ChatGPT
15
- 4. Read through results
16
- 5. Go back to terminal
17
- 6. Forget what you were doing
9
+ [![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)
10
+ [![npm downloads](https://img.shields.io/npm/dm/error-solution-ai-buddy)](https://www.npmjs.com/package/error-solution-ai-buddy)
11
+ ![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)
12
+ ![AI](https://img.shields.io/badge/AI-local%20via%20Ollama-black)
13
+ [![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)
18
14
 
19
- **That's 5+ context switches. We fix that.**
15
+ </div>
20
16
 
21
- ## The Solution
22
-
23
- ```bash
17
+ ```text
24
18
  $ errbuddy node app.js
25
19
 
26
20
  TypeError: Cannot read properties of undefined (reading 'map')
27
21
  at app.js:12:5
28
22
 
29
- ╭─ 🤖 Error Buddy Explanation: ─────────────────────────────────────╮
30
- │ │
23
+ ╭─ 🤖 Error Buddy Explanation ──────────────────────────────────────╮
24
+ │ │
31
25
  │ 📘 What is this? │
32
- │ You tried to use `.map()` on a variable that is undefined. │
33
- │ │
34
- │ ❓ Why it happens? │
35
- │ The data you expected (probably from an API) wasn't available. │
36
- │ │
37
- │ ✅ How to fix it: │
38
- │ Check if the variable exists before calling `.map()`. │
39
- │ │
40
- │ 💡 Example: │
41
- │ if (data) { │
42
- │ data.map(...) │
43
- │ } │
44
- │ │
45
- ╰────────────────────────────────────────────────────────────────────╯
26
+ │ You tried to call .map() on a variable that is undefined. │
27
+ │ │
28
+ │ ❓ Why it happens │
29
+ │ The data you expected (probably from an API) wasn't there yet. │
30
+ │ │
31
+ │ ✅ How to fix it │
32
+ │ Check that the variable exists before calling .map(). │
33
+ │ │
34
+ │ 💡 Example │
35
+ │ if (data) { │
36
+ │ data.map(...) │
37
+ │ } │
38
+ │ │
39
+ ╰───────────────────────────────────────────────────────────────────╯
46
40
  ```
47
41
 
48
- ## Quick Start
42
+ ## Why errbuddy
43
+
44
+ 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.
45
+
46
+ - **Zero context switching.** The explanation appears right under the error.
47
+ - **Private by default.** The AI runs locally through [Ollama](https://ollama.com). Your code and errors never leave your computer.
48
+ - **Free.** No API keys, no accounts, no usage limits.
49
+ - **Works offline, and without AI.** If Ollama isn't running, errbuddy falls back to built-in explanations for common errors.
50
+ - **Drop-in.** Your program runs exactly as before: same output, same input, same exit code.
51
+
52
+ ## Quick start
49
53
 
50
54
  ```bash
51
55
  npm install -g error-solution-ai-buddy
52
56
  errbuddy node app.js
53
57
  ```
54
58
 
55
- That's it. Errors are explained with built-in pattern matching straight away.
59
+ That's it. You'll get pattern-based explanations straight away.
56
60
 
57
- ### Turn on AI explanations (optional, free, runs on your machine)
61
+ ### Turn on AI explanations (optional)
58
62
 
59
- errbuddy uses [Ollama](https://ollama.com) to run a small AI model locally, so your code and errors never leave your computer.
60
-
61
- 1. Install Ollama from https://ollama.com/download
62
- 2. Download the default model (about 400 MB):
63
+ 1. Install Ollama from [ollama.com/download](https://ollama.com/download)
64
+ 2. Download the default model (about 400 MB, runs fine on low-RAM laptops):
63
65
  ```bash
64
66
  ollama pull qwen2.5:0.5b
65
67
  ```
66
- 3. Make sure Ollama is running (`ollama serve`, or open the Ollama app)
67
-
68
- Want better explanations? Use a bigger model: `errbuddy --model llama3.2 node app.js`
69
-
70
- If Ollama isn't running, errbuddy still works — it falls back to pattern matching.
71
-
72
- ## Installation & Usage
73
-
74
- ### 1. Download the Project
75
- - Clone the repository:
76
- ```sh
77
- git clone <your-repo-url>
78
- ```
79
-
80
- ### 2. Install Dependencies
81
- - In the project folder, run:
82
- ```sh
83
- npm install
84
- ```
85
-
86
- ### 3. Use the CLI Tool
87
- - Go to the CLI directory:
88
- ```sh
89
- cd error-solution-ai-buddy/cli
90
- npm link
91
- ```
92
- - Now you can run the CLI from anywhere:
93
- ```sh
94
- errbuddy <your-command>
95
- # Example:
96
- errbuddy node test-error.js
97
- ```
98
-
99
- ### 4. Use the VS Code Extension
100
- - Build the extension (if needed):
101
- ```sh
102
- cd error-solution-ai-buddy/extension
103
- npm install
104
- npm run build
105
- ```
106
- - Install the extension in VS Code:
107
- - Use "Install from VSIX..." if you have a packaged file.
108
- - Or run:
109
- ```sh
110
- code --install-extension <path-to-extension-folder>
111
- ```
112
- - Reload VS Code.
113
-
114
- ### 5. Start Using
115
- - For CLI: Run commands with `errbuddy` prefix.
116
- - For extension: Use terminal and Error Buddy commands in VS Code.
117
- ### Manual Setup
118
-
119
- #### Step 1: Install Ollama (Optional - for AI features)
120
-
121
- ```bash
122
- # Windows: Download from https://ollama.ai
68
+ 3. Make sure Ollama is running: open the Ollama app, or run `ollama serve`
123
69
 
124
- # macOS
125
- brew install ollama
70
+ 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.
126
71
 
127
- # Linux
128
- curl -fsSL https://ollama.ai/install.sh | sh
129
- ```
72
+ ## Usage
130
73
 
131
- ### 2. Start Ollama & Download Model
74
+ Put `errbuddy` in front of the command you normally run:
132
75
 
133
76
  ```bash
134
- ollama serve # Start the server (keep this running)
135
- ollama pull llama3.2 # Download the model (~2GB)
77
+ errbuddy node app.js # instead of: node app.js
78
+ errbuddy npm start # instead of: npm start
79
+ errbuddy java MyApp # instead of: java MyApp
80
+ errbuddy dotnet run # instead of: dotnet run
136
81
  ```
137
- ### 3. Install Error Buddy
138
82
 
139
- ```bash
140
- # From this directory
141
- npm install
142
- npm link # Makes 'errbuddy' available globally
143
- ```
83
+ ### Options
144
84
 
145
- ### 4. Use It!
85
+ | Option | What it does |
86
+ |---|---|
87
+ | `--model <name>` | Use a different Ollama model, e.g. `--model llama3.2` for richer answers |
88
+ | `--offline` | Skip AI and use built-in pattern matching only |
89
+ | `--no-ai` | Show errors without any explanation |
90
+ | `-V, --version` | Show the installed version |
91
+ | `-h, --help` | Show help |
146
92
 
147
- ```bash
148
- # Instead of: node app.js
149
- errbuddy node app.js
93
+ | Command | What it does |
94
+ |---|---|
95
+ | `errbuddy examples` | Show usage examples |
96
+ | `errbuddy config` | Show the current model and Ollama URL |
150
97
 
151
- # Instead of: npm start
152
- errbuddy npm start
98
+ > 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.
153
99
 
154
- # Instead of: java MyApp
155
- errbuddy java MyApp
100
+ ## Supported languages
156
101
 
157
- # Instead of: dotnet run
158
- errbuddy dotnet run
159
- ```
102
+ | Language | Detected errors include |
103
+ |---|---|
104
+ | JavaScript / Node.js | `TypeError`, `ReferenceError`, `SyntaxError`, missing modules |
105
+ | Java | `NullPointerException`, `ArrayIndexOutOfBoundsException`, `ClassNotFoundException`, compile errors |
106
+ | C# / .NET | `NullReferenceException`, `IndexOutOfRangeException`, `CSxxxx` compiler errors |
160
107
 
161
- ## Supported Languages
108
+ With AI enabled, errbuddy can explain other errors too; pattern matching covers the cases above.
162
109
 
163
- | Language | Status | Error Types |
164
- |----------|--------|-------------|
165
- | JavaScript/Node.js | ✅ Full | TypeError, ReferenceError, SyntaxError, Module errors |
166
- | Java | ✅ Full | NullPointer, ArrayIndex, ClassNotFound, Compile errors |
167
- | C#/.NET | ✅ Full | NullReference, Index, CS errors, Runtime exceptions |
110
+ ## How it works
168
111
 
169
- ## CLI Options
112
+ ```text
113
+ errbuddy node app.js
114
+ │
115
+ ▼
116
+ Runs your command ──► stdout is shown as normal
117
+ │ stderr is shown AND captured
118
+ ▼
119
+ Error detector ──► finds the language, error type, file and line
120
+ │
121
+ ▼
122
+ Sanitizer ──► strips file paths and anything that looks like a secret
123
+ │
124
+ ├── Ollama running? ──► local AI explains WHAT / WHY / FIX / EXAMPLE
125
+ └── Not running? ──► built-in pattern explanation
126
+ │
127
+ ▼
128
+ Formatted explanation printed under the error, then your exit code is returned
129
+ ```
170
130
 
171
- ```bash
172
- # Disable AI (use pattern matching only)
173
- errbuddy --no-ai node app.js
131
+ 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).
174
132
 
175
- # Use a different Ollama model
176
- errbuddy --model codellama node app.js
133
+ ## Privacy
177
134
 
178
- # Force offline mode
179
- errbuddy --offline node app.js
135
+ - The AI runs **100% locally** through Ollama. Nothing is sent to the cloud.
136
+ - 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]`.
137
+ - No telemetry, no analytics, no account.
138
+ - A local history of errors and explanations is kept in `~/.errbuddy/history.json`. Delete that file at any time to clear it.
180
139
 
181
- # Show examples
182
- errbuddy examples
140
+ ## VS Code extension
183
141
 
184
- # Show configuration
185
- errbuddy config
186
- ```
142
+ 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**.
187
143
 
188
- ## How It Works
144
+ Commands: *Explain Selected Error*, *Explain Last Terminal Error*, *Toggle Auto-Explain*, *Open Error Buddy Terminal*, *Show Error History*.
189
145
 
190
- ```
191
- ┌─────────────────────────────────────────┐
192
- │ You run: errbuddy node app.js │
193
- └─────────────────────────────────────────┘
194
- ↓
195
- ┌─────────────────────────────────────────┐
196
- │ CLI spawns: node app.js │
197
- │ • stdout → displayed normally │
198
- │ • stderr → captured for analysis │
199
- └─────────────────────────────────────────┘
200
- ↓
201
- ┌─────────────────────────────────────────┐
202
- │ Error Detector │
203
- │ • Detects language (JS/Java/C#) │
204
- │ • Extracts error type, file, line │
205
- └─────────────────────────────────────────┘
206
- ↓
207
- ┌─────────────────────────────────────────┐
208
- │ Ollama AI (local) │
209
- │ • Receives sanitized error │
210
- │ • Returns structured explanation │
211
- └─────────────────────────────────────────┘
212
- ↓
213
- ┌─────────────────────────────────────────┐
214
- │ Pretty Terminal Output │
215
- │ • WHAT / WHY / FIX / EXAMPLE │
216
- └─────────────────────────────────────────┘
217
- ```
146
+ ## Troubleshooting
218
147
 
219
- ## Privacy & Security
148
+ **"Ollama not detected"**
149
+ 1. Open the Ollama app, or run `ollama serve`
150
+ 2. Check it responds: `curl http://localhost:11434/api/tags`
151
+ 3. Make sure you have a model: `ollama pull qwen2.5:0.5b`
220
152
 
221
- Your code **never leaves your machine**:
153
+ **The AI explanation timed out**
154
+ Your machine may be busy or the model too large. Use the default `qwen2.5:0.5b`, or run with `--offline`.
222
155
 
223
- - ✅ Ollama runs 100% locally
224
- - ✅ File paths are stripped before AI processing
225
- - ✅ No telemetry or analytics
226
- - ✅ No API keys required
227
- - ✅ Works completely offline
156
+ **`errbuddy: command not found`**
157
+ 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).
228
158
 
229
- ## Project Structure
159
+ ## Development
230
160
 
161
+ ```bash
162
+ git clone https://github.com/sithija-jayasinghe/solution-ai-buddy-v1.git
163
+ cd solution-ai-buddy-v1/error-solution-ai-buddy
164
+ npm install
165
+ npm test # 62 tests, Node's built-in test runner
166
+ npm link # use your local copy as the global `errbuddy`
231
167
  ```
168
+
169
+ ```text
232
170
  error-solution-ai-buddy/
233
171
  ├── cli/
234
- │ ├── index.js # CLI entry point
235
- │ ├── error-listener.js # Error detection & patterns
236
- │ └── formatter.js # Terminal output formatting
237
- ├── backend/
238
- │ └── src/
239
- │ ├── ai/
240
- │ │ └── ollama-service.js # Ollama integration
241
- │ └── services/
242
- │ └── history-service.js # Error history (SQLite)
243
- ├── docs/
244
- │ ├── architecture.md # System design
245
- │ ├── decisions.md # Why we made these choices
246
- │ └── terminal-integration.md
247
- ├── tests/
248
- │ └── *.test.js
249
- ├── package.json
250
- └── README.md
172
+ │ ├── index.js # CLI entry: runs the command, wires everything together
173
+ │ ├── error-listener.js # language detection and error patterns
174
+ │ └── formatter.js # terminal output
175
+ ├── backend/src/
176
+ │ ├── ai/ollama-service.js # Ollama client, prompt and response parsing
177
+ │ └── services/history-service.js # local error history
178
+ ├── extension/ # VS Code extension (TypeScript)
179
+ ├── docs/ # architecture and design decisions
180
+ └── tests/
251
181
  ```
252
182
 
253
- ## Configuration
254
-
255
- Configuration is stored in `~/.errbuddy/config.json`:
256
-
257
- ```json
258
- {
259
- "ollamaUrl": "http://localhost:11434",
260
- "model": "llama3.2",
261
- "showSpinner": true,
262
- "saveHistory": true
263
- }
264
- ```
265
-
266
- ## Troubleshooting
267
-
268
- ### "Ollama not detected"
269
-
270
- 1. Make sure Ollama is running: `ollama serve`
271
- 2. Check it's accessible: `curl http://localhost:11434/api/tags`
272
- 3. Pull a model: `ollama pull qwen2.5:0.5b`
273
-
274
- ### "AI explanation timed out"
275
-
276
- - Try a smaller model: `errbuddy --model llama3.2:1b node app.js`
277
- - Check system resources (Ollama needs ~4GB RAM)
278
-
279
- ### Command not found after `npm link`
183
+ ## Roadmap
280
184
 
281
- - On Windows: Restart your terminal
282
- - On macOS/Linux: Check your PATH includes npm global bin
185
+ - [ ] Python and Go error patterns
186
+ - [ ] Optional cloud models (bring your own API key) for people who don't want to run Ollama
187
+ - [ ] `errbuddy history` command to search past errors
188
+ - [ ] Publish the VS Code extension to the Marketplace
283
189
 
284
190
  ## Contributing
285
191
 
286
- 1. Fork the repo
287
- 2. Create a feature branch
288
- 3. Submit a PR
192
+ 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.
289
193
 
290
194
  ## License
291
195
 
292
- MIT © 2024
196
+ [MIT](https://github.com/sithija-jayasinghe/solution-ai-buddy-v1/blob/main/error-solution-ai-buddy/LICENSE) © Sithija Harshana Jayasinghe
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "error-solution-ai-buddy",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "AI-powered error explanation tool for developers - works directly in your terminal",
5
5
  "type": "module",
6
6
  "main": "cli/index.js",