ai-error-solution 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-31
+
+### Added
+- Initial release of ai-error-solution
+- Core error handling with `fixError()` function
+- OpenAI integration using native curl (zero dependencies)
+- Middleware pattern with `initAutoErrorSolution()` for one-time API key setup
+- Beautiful console logging with colors and emojis
+- Support for ESM (ES Modules)
+- Error analysis with AI-powered:
+  - Plain-English explanations
+  - Likely causes identification
+  - Suggested fixes with code snippets
+  - Relevant documentation links
+- Timeout handling and retry mechanism
+- Silent mode for programmatic access to analysis results
+- Function wrapper utility `wrapWithErrorHandler()`
+- Global error handler setup with `setupGlobalHandler()`
+- Graceful failure handling when API calls fail
+- Comprehensive README with examples
+- MIT License
+- Publishing guide
+
+### Technical Details
+- Node.js 18+ support
+- Zero npm dependencies
+- Uses native `child_process` with curl
+- ESM-first architecture
+- Production-ready error handling
+- Privacy-focused (no telemetry, no data storage)
+
+### Documentation
+- Complete API reference
+- Usage examples
+- Environment setup guide
+- Troubleshooting section
+- Best practices and disclaimers
+
+---
+
+## [Unreleased]
+
+### Planned Features
+- TypeScript type definitions (.d.ts files)
+- Support for custom AI prompts
+- Batch error analysis
+- Local caching of similar errors
+- Support for other LLM providers (Anthropic, etc.)
+- Configuration file support (.autoerrorrc)
+
+---
+
+## Version History
+
+- **1.0.0** (2025-12-31) - Initial release
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
+
+## Support
+
+For issues and questions, please visit:
+- GitHub Issues: https://github.com/yourusername/ai-error-solution/issues
+- npm Page: https://www.npmjs.com/package/ai-error-solution
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ai-error-solution
+
+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

@@ -0,0 +1,408 @@
+# 🤖 ai-error-solution
+
+**Lightweight, AI-powered error analysis for Node.js**
+
+Automatically capture runtime errors and get instant AI-generated explanations, causes, fixes, and documentation links—all in your console.
+
+[![npm version](https://img.shields.io/npm/v/ai-error-solution.svg)](https://www.npmjs.com/package/ai-error-solution)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+
+---
+
+## ✨ Features
+
+- 🎯 **Zero Dependencies** - Uses native `curl` via `child_process` (no heavy HTTP libraries)
+- 🚀 **Lightweight** - Minimal package size, maximum efficiency
+- 🧠 **AI-Powered Analysis** - Leverages OpenAI to explain errors in plain English
+- 🔐 **Privacy-First** - No telemetry, no data storage, direct API calls only
+- ⚡ **ESM Native** - Modern ES Module support
+- 🎨 **Beautiful Output** - Clean, colorized console logging
+- 🛠️ **Production-Ready** - Timeout handling, retries, graceful failures
+
+---
+
+## 📦 Installation
+
+```bash
+npm install ai-error-solution
+```
+
+**Requirements:**
+- Node.js 18 or higher
+- `curl` installed on your system (usually pre-installed on macOS/Linux, available on Windows)
+- OpenAI API key ([get one here](https://platform.openai.com/api-keys))
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize Once
+
+Set up the package with your OpenAI API key in your main application file:
+
+```javascript
+import { initAutoErrorSolution, fixError } from 'ai-error-solution';
+
+// Initialize with your API key (do this once at app startup)
+initAutoErrorSolution({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o-mini' // Optional: defaults to gpt-4o-mini
+});
+```
+
+### 2. Use Anywhere
+
+Wrap your error handling with `fixError()`:
+
+```javascript
+try {
+  // Your code that might throw errors
+  const result = riskyFunction();
+} catch (err) {
+  // Get AI-powered analysis
+  await fixError(err);
+}
+```
+
+### 3. Enjoy AI-Powered Debugging! 🎉
+
+You'll see beautiful, formatted output like this:
+
+```
+================================================================================
+❌ Error Detected: TypeError
+Cannot read property 'map' of undefined
+
+🧠 AI Explanation:
+  This error occurs when you try to call the .map() method on a variable
+  that is undefined. The JavaScript engine expected an array but received
+  undefined instead.
+
+⚠️  Likely Causes:
+  - The variable was never initialized
+  - An async function hasn't resolved yet
+  - The API response didn't include expected data
+
+🔧 Suggested Fixes:
+  - Add optional chaining: data?.map(...)
+  - Provide a default value: (data || []).map(...)
+  - Check existence first: if (data) { data.map(...) }
+
+📚 References:
+  - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors
+  - https://javascript.info/optional-chaining
+
+💡 Note: AI suggestions may not be 100% accurate. Always verify fixes before applying.
+================================================================================
+```
+
+---
+
+## 📖 API Reference
+
+### `initAutoErrorSolution(options)`
+
+Initialize the package with your OpenAI credentials. **Must be called before using `fixError()`.**
+
+**Parameters:**
+- `options.apiKey` (string, **required**) - Your OpenAI API key
+- `options.model` (string, optional) - OpenAI model to use (default: `'gpt-4o-mini'`)
+- `options.timeout` (number, optional) - API request timeout in milliseconds (default: `30000`)
+- `options.maxRetries` (number, optional) - Maximum retry attempts (default: `1`)
+
+**Example:**
+```javascript
+initAutoErrorSolution({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o-mini',
+  timeout: 30000,
+  maxRetries: 2
+});
+```
+
+---
+
+### `fixError(error, options)`
+
+Analyze an error using OpenAI and display formatted results.
+
+**Parameters:**
+- `error` (Error | string, **required**) - Error object or error message
+- `options.silent` (boolean, optional) - Return analysis without logging (default: `false`)
+
+**Returns:**
+- `Promise<null>` - When logging to console (default)
+- `Promise<Object>` - When `silent: true`, returns analysis object
+
+**Example:**
+```javascript
+// Standard usage (logs to console)
+try {
+  dangerousCode();
+} catch (err) {
+  await fixError(err);
+}
+
+// Silent mode (returns data)
+const analysis = await fixError(err, { silent: true });
+console.log(analysis.analysis.explanation);
+```
+
+---
+
+### `wrapWithErrorHandler(fn)`
+
+Wrap a function with automatic error handling.
+
+**Parameters:**
+- `fn` (Function) - Function to wrap
+
+**Returns:**
+- `Function` - Wrapped function that automatically calls `fixError()` on errors
+
+**Example:**
+```javascript
+const safeFunction = wrapWithErrorHandler(async () => {
+  // Code that might throw
+  return await riskyOperation();
+});
+
+await safeFunction(); // Errors automatically analyzed
+```
+
+---
+
+### `setupGlobalHandler(options)`
+
+Register global handlers for uncaught exceptions and unhandled promise rejections.
+
+**Parameters:**
+- `options.exitOnError` (boolean, optional) - Exit process after handling error (default: `false`)
+
+**Example:**
+```javascript
+setupGlobalHandler({ exitOnError: true });
+
+// Now all uncaught errors will be automatically analyzed
+throw new Error('This will be caught and analyzed');
+```
+
+---
+
+## 🔐 Environment Setup
+
+### Using .env file (Recommended)
+
+1. Install dotenv:
+```bash
+npm install dotenv
+```
+
+2. Create `.env`:
+```env
+OPENAI_API_KEY=sk-your-api-key-here
+```
+
+3. Load in your app:
+```javascript
+import 'dotenv/config';
+import { initAutoErrorSolution } from 'ai-error-solution';
+
+initAutoErrorSolution({
+  apiKey: process.env.OPENAI_API_KEY
+});
+```
+
+### Using environment variables directly
+
+```bash
+# Linux/macOS
+export OPENAI_API_KEY=sk-your-api-key-here
+node app.js
+
+# Windows (PowerShell)
+$env:OPENAI_API_KEY="sk-your-api-key-here"
+node app.js
+
+# Windows (CMD)
+set OPENAI_API_KEY=sk-your-api-key-here
+node app.js
+```
+
+---
+
+## 🎯 Use Cases
+
+### Express.js Error Middleware
+
+```javascript
+import express from 'express';
+import { initAutoErrorSolution, fixError } from 'ai-error-solution';
+
+const app = express();
+
+initAutoErrorSolution({
+  apiKey: process.env.OPENAI_API_KEY
+});
+
+// Error handling middleware
+app.use(async (err, req, res, next) => {
+  await fixError(err);
+  res.status(500).json({ error: 'Internal Server Error' });
+});
+```
+
+### Async Function Wrapper
+
+```javascript
+const fetchUserData = wrapWithErrorHandler(async (userId) => {
+  const response = await fetch(`/api/users/${userId}`);
+  return response.json();
+});
+
+// Automatically analyzes errors
+await fetchUserData(123);
+```
+
+### Global Error Catching
+
+```javascript
+import { initAutoErrorSolution, setupGlobalHandler } from 'ai-error-solution';
+
+initAutoErrorSolution({
+  apiKey: process.env.OPENAI_API_KEY
+});
+
+setupGlobalHandler({ exitOnError: false });
+
+// All uncaught errors are now automatically analyzed
+```
+
+---
+
+## ⚠️ Important Notes
+
+### Disclaimers
+
+- **AI Accuracy**: AI-generated suggestions may not always be correct. Always verify fixes before applying them to production code.
+- **API Costs**: Each error analysis makes an API call to OpenAI, which incurs costs based on your OpenAI plan.
+- **Privacy**: Error messages and stack traces are sent to OpenAI for analysis. Do not use in production if your errors may contain sensitive data.
+- **curl Dependency**: This package requires `curl` to be installed and accessible in your system PATH.
+
+### Best Practices
+
+- ✅ Use in **development** and **debugging** environments
+- ✅ Store API keys in environment variables (never commit them)
+- ✅ Set reasonable timeout values for production environments
+- ✅ Review AI suggestions before implementing fixes
+
+---
+
+## 🏗️ Architecture
+
+This package is built with **zero dependencies** and uses:
+
+- **ESM** - Modern ES Module system
+- **Native curl** - No heavy HTTP libraries (axios, node-fetch, etc.)
+- **child_process** - Native Node.js process execution
+- **Middleware pattern** - One-time API key initialization
+
+**Why curl?**
+- Minimal package size
+- No dependency vulnerabilities
+- Universal availability across platforms
+- Direct OpenAI API communication
+
+---
+
+## 🛠️ Troubleshooting
+
+### "curl is not installed or not in PATH"
+
+**Solution**: Install curl on your system.
+
+```bash
+# macOS (via Homebrew)
+brew install curl
+
+# Ubuntu/Debian
+sudo apt-get install curl
+
+# Windows (via Chocolatey)
+choco install curl
+
+# Windows (built-in on Windows 10+)
+# curl should already be available
+```
+
+### "Package not initialized"
+
+**Solution**: Make sure you call `initAutoErrorSolution()` before using `fixError()`.
+
+### "OpenAI API request timed out"
+
+**Solution**: Increase timeout or check your internet connection.
+
+```javascript
+initAutoErrorSolution({
+  apiKey: process.env.OPENAI_API_KEY,
+  timeout: 60000 // 60 seconds
+});
+```
+
+### "OpenAI API error: Invalid API key"
+
+**Solution**: Verify your API key is correct and has sufficient credits.
+
+---
+
+## 📄 License
+
+MIT © [Your Name]
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/ai-error-solution)
+- [GitHub Repository](https://github.com/yourusername/ai-error-solution)
+- [OpenAI API Documentation](https://platform.openai.com/docs)
+- [Report Issues](https://github.com/yourusername/ai-error-solution/issues)
+
+---
+
+## 💡 What This Package Does NOT Do
+
+- ❌ **No auto-fixing** - Does not modify your code automatically
+- ❌ **No telemetry** - Does not collect or store any usage data
+- ❌ **No remote storage** - Errors are not stored anywhere
+- ❌ **No background processes** - Only runs when you call it
+
+---
+
+## 🌟 Why This Package?
+
+Most error analysis tools either:
+- Require heavy dependencies (bloated package size)
+- Send data to third-party services (privacy concerns)
+- Auto-modify code (risky in production)
+
+**ai-error-solution** is different:
+- ✅ **Lightweight** - No dependencies, tiny package size
+- ✅ **Private** - Direct API calls, no intermediaries
+- ✅ **Safe** - Never modifies your code
+- ✅ **Transparent** - Open source, audit the code yourself
+
+---
+
+**Made with ❤️ for developers who value simplicity and privacy**
+
+*Star ⭐ this project if you find it helpful!*
+

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "ai-error-solution",
+  "version": "1.0.0",
+  "description": "Lightweight Node.js error handler that uses OpenAI to provide explanations, causes, fixes, and documentation links for runtime errors",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "error-handling",
+    "debugging",
+    "openai",
+    "error-analysis",
+    "ai-debugging",
+    "error-solution",
+    "runtime-errors",
+    "stack-trace"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/ai-error-solution.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/ai-error-solution/issues"
+  },
+  "homepage": "https://github.com/yourusername/ai-error-solution#readme"
+}
+

package/src/fixError.js

@@ -0,0 +1,178 @@
+/**
+ * Main error handler - captures error and requests AI analysis
+ */
+
+import { getConfig } from './init.js';
+import { callOpenAI, parseAIResponse } from './openaiCurl.js';
+import { logErrorAnalysis, logAnalysisFailure } from './logger.js';
+
+/**
+ * Analyze an error using OpenAI and display results
+ * @param {Error|string} error - Error object or error message
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.silent=false] - If true, returns analysis without logging
+ * @returns {Promise<Object|null>} Analysis object if silent=true, null otherwise
+ */
+export async function fixError(error, options = {}) {
+  try {
+    // Get global configuration
+    const config = getConfig();
+
+    // Normalize error input
+    const errorObj = normalizeError(error);
+    const errorMessage = errorObj.message || 'Unknown error';
+    const stackTrace = errorObj.stack || 'No stack trace available';
+
+    // Call OpenAI API
+    let aiResponse;
+    let lastError;
+    
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+      try {
+        aiResponse = await callOpenAI(
+          config.apiKey,
+          config.model,
+          errorMessage,
+          stackTrace,
+          config.timeout
+        );
+        break; // Success, exit retry loop
+      } catch (err) {
+        lastError = err;
+        if (attempt < config.maxRetries) {
+          // Wait before retry (exponential backoff)
+          await sleep(1000 * Math.pow(2, attempt));
+        }
+      }
+    }
+
+    if (!aiResponse) {
+      throw lastError || new Error('Failed to get response from OpenAI');
+    }
+
+    // Parse AI response
+    const analysis = parseAIResponse(aiResponse.content);
+
+    // Log results or return silently
+    if (options.silent) {
+      return {
+        error: {
+          name: errorObj.name,
+          message: errorMessage,
+          stack: stackTrace
+        },
+        analysis,
+        model: aiResponse.model,
+        usage: aiResponse.usage
+      };
+    } else {
+      logErrorAnalysis(errorObj, analysis);
+      return null;
+    }
+
+  } catch (analysisError) {
+    // Handle failures gracefully
+    const errorObj = normalizeError(error);
+    
+    if (options.silent) {
+      return {
+        error: {
+          name: errorObj.name,
+          message: errorObj.message,
+          stack: errorObj.stack
+        },
+        analysis: null,
+        analysisError: analysisError.message
+      };
+    } else {
+      logAnalysisFailure(errorObj, analysisError.message);
+      return null;
+    }
+  }
+}
+
+/**
+ * Normalize error input to Error object
+ * @private
+ */
+function normalizeError(error) {
+  // Already an Error object
+  if (error instanceof Error) {
+    return error;
+  }
+
+  // String message
+  if (typeof error === 'string') {
+    const err = new Error(error);
+    err.name = 'Error';
+    return err;
+  }
+
+  // Object with message property
+  if (error && typeof error === 'object' && error.message) {
+    const err = new Error(error.message);
+    err.name = error.name || 'Error';
+    err.stack = error.stack || err.stack;
+    return err;
+  }
+
+  // Fallback
+  const err = new Error(String(error));
+  err.name = 'Error';
+  return err;
+}
+
+/**
+ * Sleep utility for retry delays
+ * @private
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Wrap a function with automatic error handling
+ * @param {Function} fn - Function to wrap
+ * @returns {Function} Wrapped function
+ */
+export function wrapWithErrorHandler(fn) {
+  return async function(...args) {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      await fixError(error);
+      throw error; // Re-throw after analysis
+    }
+  };
+}
+
+/**
+ * Create a global error handler for uncaught exceptions
+ * @param {Object} [options] - Configuration options
+ * @param {boolean} [options.exitOnError=false] - Exit process after handling
+ */
+export function setupGlobalHandler(options = {}) {
+  const { exitOnError = false } = options;
+
+  process.on('uncaughtException', async (error) => {
+    console.error('\n🚨 Uncaught Exception:');
+    await fixError(error);
+    
+    if (exitOnError) {
+      process.exit(1);
+    }
+  });
+
+  process.on('unhandledRejection', async (reason, promise) => {
+    console.error('\n🚨 Unhandled Promise Rejection:');
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    await fixError(error);
+    
+    if (exitOnError) {
+      process.exit(1);
+    }
+  });
+
+  console.log('✅ Global error handlers registered');
+}
+

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * ai-error-solution - Lightweight error analysis using OpenAI
+ * 
+ * A minimal, production-ready package that captures JavaScript/Node.js runtime errors
+ * and provides AI-powered explanations, causes, fixes, and documentation links.
+ * 
+ * @module ai-error-solution
+ * @version 1.0.0
+ */
+
+export { initAutoErrorSolution, isInitialized } from './init.js';
+export { fixError, wrapWithErrorHandler, setupGlobalHandler } from './fixError.js';
+export { log } from './logger.js';
+
+// Package metadata
+export const version = '1.0.0';
+export const name = 'ai-error-solution';
+

package/src/init.js

@@ -0,0 +1,73 @@
+/**
+ * Global configuration storage for ai-error-solution
+ * Stores API key and model settings after initialization
+ */
+
+// Global configuration object
+let config = {
+  apiKey: null,
+  model: 'gpt-4o-mini',
+  timeout: 30000, // 30 seconds default timeout
+  maxRetries: 1,
+  initialized: false
+};
+
+/**
+ * Initialize the ai-error-solution package with OpenAI credentials
+ * @param {Object} options - Configuration options
+ * @param {string} options.apiKey - OpenAI API key (required)
+ * @param {string} [options.model='gpt-4o-mini'] - OpenAI model to use
+ * @param {number} [options.timeout=30000] - API request timeout in milliseconds
+ * @param {number} [options.maxRetries=1] - Maximum number of retry attempts
+ * @throws {Error} If apiKey is not provided
+ */
+export function initAutoErrorSolution(options = {}) {
+  if (!options.apiKey) {
+    throw new Error('ai-error-solution: API key is required. Please provide your OpenAI API key.');
+  }
+
+  config.apiKey = options.apiKey;
+  config.model = options.model || 'gpt-4o-mini';
+  config.timeout = options.timeout || 30000;
+  config.maxRetries = options.maxRetries !== undefined ? options.maxRetries : 1;
+  config.initialized = true;
+
+  console.log('✅ ai-error-solution initialized successfully');
+}
+
+/**
+ * Get the current configuration
+ * @returns {Object} Current configuration
+ * @throws {Error} If package is not initialized
+ */
+export function getConfig() {
+  if (!config.initialized) {
+    throw new Error(
+      'ai-error-solution: Package not initialized. Please call initAutoErrorSolution() first with your API key.'
+    );
+  }
+  return { ...config };
+}
+
+/**
+ * Check if package is initialized
+ * @returns {boolean}
+ */
+export function isInitialized() {
+  return config.initialized;
+}
+
+/**
+ * Reset configuration (useful for testing)
+ * @private
+ */
+export function resetConfig() {
+  config = {
+    apiKey: null,
+    model: 'gpt-4o-mini',
+    timeout: 30000,
+    maxRetries: 1,
+    initialized: false
+  };
+}
+

package/src/logger.js

@@ -0,0 +1,146 @@
+/**
+ * Formatted console logger for error analysis results
+ * Provides clean, developer-friendly output
+ */
+
+/**
+ * ANSI color codes for terminal output
+ */
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m'
+};
+
+/**
+ * Format and log error analysis to console
+ * @param {Error} error - Original error object
+ * @param {Object} analysis - Parsed AI analysis
+ */
+export function logErrorAnalysis(error, analysis) {
+  console.log('\n' + '='.repeat(80));
+  
+  // Error header
+  console.log(`${colors.red}${colors.bright}❌ Error Detected: ${error.name || 'Error'}${colors.reset}`);
+  console.log(`${colors.red}${error.message}${colors.reset}`);
+  console.log('');
+
+  // AI Explanation
+  if (analysis.explanation) {
+    console.log(`${colors.cyan}${colors.bright}🧠 AI Explanation:${colors.reset}`);
+    console.log(formatText(analysis.explanation, colors.white));
+    console.log('');
+  }
+
+  // Likely Causes
+  if (analysis.causes) {
+    console.log(`${colors.yellow}${colors.bright}⚠️  Likely Causes:${colors.reset}`);
+    console.log(formatText(analysis.causes, colors.yellow));
+    console.log('');
+  }
+
+  // Suggested Fixes
+  if (analysis.fixes) {
+    console.log(`${colors.green}${colors.bright}🔧 Suggested Fixes:${colors.reset}`);
+    console.log(formatText(analysis.fixes, colors.green));
+    console.log('');
+  }
+
+  // Documentation References
+  if (analysis.references && analysis.references.length > 0) {
+    console.log(`${colors.blue}${colors.bright}📚 References:${colors.reset}`);
+    analysis.references.forEach(ref => {
+      console.log(`${colors.blue}  - ${ref}${colors.reset}`);
+    });
+    console.log('');
+  }
+
+  // Footer with disclaimer
+  console.log(`${colors.gray}${colors.dim}💡 Note: AI suggestions may not be 100% accurate. Always verify fixes before applying.${colors.reset}`);
+  console.log('='.repeat(80) + '\n');
+}
+
+/**
+ * Log error when AI analysis fails
+ * @param {Error} error - Original error
+ * @param {string} reason - Reason for failure
+ */
+export function logAnalysisFailure(error, reason) {
+  console.log('\n' + '='.repeat(80));
+  console.log(`${colors.red}${colors.bright}❌ Error Detected: ${error.name || 'Error'}${colors.reset}`);
+  console.log(`${colors.red}${error.message}${colors.reset}`);
+  console.log('');
+  console.log(`${colors.yellow}${colors.bright}⚠️  AI Analysis Failed${colors.reset}`);
+  console.log(`${colors.yellow}Reason: ${reason}${colors.reset}`);
+  console.log('');
+  console.log(`${colors.gray}Stack trace:${colors.reset}`);
+  console.log(`${colors.gray}${error.stack || 'No stack trace available'}${colors.reset}`);
+  console.log('='.repeat(80) + '\n');
+}
+
+/**
+ * Format text with proper indentation and wrapping
+ * @private
+ */
+function formatText(text, color) {
+  const lines = text.split('\n');
+  const formatted = lines.map(line => {
+    const trimmed = line.trim();
+    if (!trimmed) return '';
+    
+    // Code blocks
+    if (trimmed.startsWith('```') || trimmed.match(/^[a-z]+\(/)) {
+      return `  ${colors.dim}${trimmed}${colors.reset}`;
+    }
+    
+    // Bullet points
+    if (trimmed.match(/^[-•*]\s/)) {
+      return `  ${color}${trimmed}${colors.reset}`;
+    }
+    
+    // Numbered lists
+    if (trimmed.match(/^\d+\.\s/)) {
+      return `  ${color}${trimmed}${colors.reset}`;
+    }
+    
+    // Regular text
+    return `  ${color}${trimmed}${colors.reset}`;
+  });
+  
+  return formatted.join('\n');
+}
+
+/**
+ * Log a simple message
+ * @param {string} message - Message to log
+ * @param {string} type - Message type: 'info', 'success', 'warning', 'error'
+ */
+export function log(message, type = 'info') {
+  const icons = {
+    info: 'ℹ️',
+    success: '✅',
+    warning: '⚠️',
+    error: '❌'
+  };
+
+  const colorMap = {
+    info: colors.cyan,
+    success: colors.green,
+    warning: colors.yellow,
+    error: colors.red
+  };
+
+  const icon = icons[type] || icons.info;
+  const color = colorMap[type] || colors.white;
+
+  console.log(`${color}${icon} ${message}${colors.reset}`);
+}
+

package/src/openaiCurl.js

@@ -0,0 +1,194 @@
+/**
+ * OpenAI API communication using curl via child_process
+ * Minimal implementation without external HTTP libraries
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * System prompt for error analysis
+ */
+const SYSTEM_PROMPT = `You are a senior JavaScript debugging assistant.
+Analyze the following runtime error and provide:
+
+1. Plain-English explanation
+2. Likely causes
+3. Suggested fixes with short code snippets
+4. Helpful documentation links
+
+Keep response concise and practical.`;
+
+/**
+ * Call OpenAI API using curl
+ * @param {string} apiKey - OpenAI API key
+ * @param {string} model - Model name (e.g., 'gpt-4o-mini')
+ * @param {string} errorMessage - Error message
+ * @param {string} stackTrace - Stack trace
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<Object>} Parsed AI response
+ */
+export async function callOpenAI(apiKey, model, errorMessage, stackTrace, timeout) {
+  const endpoint = 'https://api.openai.com/v1/chat/completions';
+  
+  // Construct user message with error details
+  const userMessage = `Runtime Error:
+Message: ${errorMessage}
+
+Stack Trace:
+${stackTrace}
+
+Please analyze this error and provide actionable debugging guidance.`;
+
+  // Build request payload
+  const payload = {
+    model: model,
+    messages: [
+      { role: 'system', content: SYSTEM_PROMPT },
+      { role: 'user', content: userMessage }
+    ],
+    temperature: 0.7,
+    max_tokens: 1000
+  };
+
+  // Escape JSON for shell (Windows-compatible)
+  const payloadJson = JSON.stringify(payload);
+  const escapedPayload = payloadJson.replace(/"/g, '\\"');
+
+  // Build curl command (Windows-compatible)
+  const curlCommand = `curl -X POST "${endpoint}" ` +
+    `-H "Content-Type: application/json" ` +
+    `-H "Authorization: Bearer ${apiKey}" ` +
+    `--max-time ${Math.floor(timeout / 1000)} ` +
+    `--data "${escapedPayload}"`;
+
+  try {
+    const { stdout, stderr } = await execAsync(curlCommand, {
+      timeout: timeout,
+      maxBuffer: 1024 * 1024 * 10 // 10MB buffer
+    });
+
+    if (stderr && !stdout) {
+      throw new Error(`curl error: ${stderr}`);
+    }
+
+    // Parse response
+    const response = JSON.parse(stdout);
+
+    // Check for API errors
+    if (response.error) {
+      throw new Error(`OpenAI API error: ${response.error.message || JSON.stringify(response.error)}`);
+    }
+
+    // Extract AI response
+    if (!response.choices || !response.choices[0] || !response.choices[0].message) {
+      throw new Error('Unexpected API response format');
+    }
+
+    return {
+      success: true,
+      content: response.choices[0].message.content,
+      model: response.model,
+      usage: response.usage
+    };
+
+  } catch (error) {
+    // Handle timeout
+    if (error.killed && error.signal === 'SIGTERM') {
+      throw new Error(`OpenAI API request timed out after ${timeout}ms`);
+    }
+
+    // Handle curl not found
+    if (error.message.includes('curl') && error.message.includes('not recognized')) {
+      throw new Error('curl is not installed or not in PATH. Please install curl to use this package.');
+    }
+
+    // Re-throw other errors
+    throw error;
+  }
+}
+
+/**
+ * Parse AI response into structured format
+ * @param {string} content - Raw AI response content
+ * @returns {Object} Structured response
+ */
+export function parseAIResponse(content) {
+  const lines = content.split('\n').filter(line => line.trim());
+  
+  return {
+    explanation: extractSection(content, ['explanation', 'plain-english', 'what happened']),
+    causes: extractSection(content, ['causes', 'likely causes', 'reasons']),
+    fixes: extractSection(content, ['fixes', 'suggested fixes', 'solutions', 'fix']),
+    references: extractReferences(content),
+    raw: content
+  };
+}
+
+/**
+ * Extract section from AI response
+ * @private
+ */
+function extractSection(content, keywords) {
+  const lines = content.split('\n');
+  let capturing = false;
+  let result = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lowerLine = line.toLowerCase();
+
+    // Check if this line starts a section we're interested in
+    const isKeywordLine = keywords.some(kw => 
+      lowerLine.includes(kw) && (lowerLine.includes(':') || lowerLine.includes('**'))
+    );
+
+    if (isKeywordLine) {
+      capturing = true;
+      continue;
+    }
+
+    // Check if we hit another section header
+    if (capturing && line.match(/^\d+\.|^-|^•|^[A-Z][^:]{3,}:/)) {
+      if (line.toLowerCase().includes('documentation') || 
+          line.toLowerCase().includes('reference') ||
+          line.toLowerCase().includes('link')) {
+        break; // Stop if we hit references section
+      }
+    }
+
+    // Stop capturing if we hit another numbered section
+    if (capturing && line.match(/^\d+\.\s+[A-Z]/)) {
+      // Check if it's not part of our current section
+      const nextKeywordMatch = keywords.some(kw => line.toLowerCase().includes(kw));
+      if (!nextKeywordMatch) {
+        break;
+      }
+    }
+
+    if (capturing && line.trim()) {
+      result.push(line.trim());
+      
+      // Look ahead - if next few lines are empty, stop capturing
+      if (i + 1 < lines.length && !lines[i + 1].trim() && 
+          i + 2 < lines.length && !lines[i + 2].trim()) {
+        break;
+      }
+    }
+  }
+
+  return result.join('\n') || content.substring(0, 200) + '...';
+}
+
+/**
+ * Extract documentation links from AI response
+ * @private
+ */
+function extractReferences(content) {
+  const urlRegex = /(https?:\/\/[^\s]+)/g;
+  const matches = content.match(urlRegex) || [];
+  return matches.map(url => url.replace(/[),.\]>]+$/, '')); // Clean trailing punctuation
+}
+