nodewise 1.0.0

package/src/errorWrapper.js

@@ -0,0 +1,43 @@
+/**
+ * errorWrapper.js
+ * 
+ * Optional error wrapper that can be required in user's app
+ * to ensure all runtime errors are logged to stderr where nodewise can catch them
+ */
+
+/**
+ * Setup global error handlers
+ * Call this at the very start of your app:
+ * 
+ * if (process.env.NODEWISE_ACTIVE) {
+ *   require('./path/to/errorWrapper').setupErrorHandlers();
+ * }
+ */
+function setupErrorHandlers() {
+  // Catch all uncaught exceptions
+  process.on('uncaughtException', (error) => {
+    console.error('Uncaught Exception:');
+    console.error(error);
+    process.exit(1);
+  });
+
+  // Catch all unhandled promise rejections
+  process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled Rejection at:', promise);
+    console.error('Reason:', reason);
+    process.exit(1);
+  });
+
+  // For Express apps - catch all errors
+  if (global.app) {
+    global.app.use((err, req, res, next) => {
+      console.error('Express Error:');
+      console.error(err);
+      res.status(500).send('Server Error');
+    });
+  }
+}
+
+module.exports = {
+  setupErrorHandlers
+};

package/src/explainer/gemini.js

@@ -0,0 +1,212 @@
+/**
+ * explainer/gemini.js
+ * 
+ * Gemini AI explainer - Uses Google Generative AI (Gemini)
+ * Sends errors to Google Gemini API for intelligent AI-powered explanations
+ * 
+ * API Documentation: https://ai.google.dev/tutorials/rest_quickstart
+ * Model: gemini-1.5-flash (fast, efficient model)
+ */
+
+const axios = require('axios');
+
+/**
+ * Default Gemini API endpoint - no need to change unless using custom proxy
+ */
+const DEFAULT_ENDPOINT = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent';
+
+/**
+ * Clean markdown formatting from text
+ * Removes ###, **, `, etc to get plain text
+ */
+function cleanMarkdown(text) {
+  return text
+    // Remove markdown headings: ###, ##, #
+    .replace(/^#+\s+/gm, '')
+    // Remove bold: **text** → text
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    // Remove italic: *text* or _text_
+    .replace(/[*_]([^*_]+)[*_]/g, '$1')
+    // Remove inline code: `text` → text
+    .replace(/`([^`]+)`/g, '$1')
+    // Remove code blocks: ```...``` 
+    .replace(/```[\s\S]*?```/g, '')
+    // Remove links: [text](url) → text
+    .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1')
+    // Remove multiple spaces, leading/trailing
+    .trim()
+    // Clean up extra blank lines
+    .split('\n')
+    .filter(line => line.trim() !== '')
+    .join('\n');
+}
+
+/**
+ * Create the prompt for Gemini - concise, focused on solutions, plain text
+ */
+function createSystemPrompt() {
+  return `You are a Node.js debugging assistant. Answer in plain text only. No markdown.`;
+}
+
+/**
+ * Truncate error text to a small, focused snippet to save tokens
+ */
+function truncateError(text, maxLines = 6, maxChars = 800) {
+
+  function truncateString(s, max = 1000) {
+    if (!s) return '';
+    const str = typeof s === 'string' ? s : JSON.stringify(s);
+    if (str.length <= max) return str;
+    return str.slice(0, max) + '... (truncated)';
+  }
+  if (!text) return '';
+  const cleaned = text.toString().trim();
+  const lines = cleaned.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  const selected = lines.slice(0, maxLines);
+  let out = selected.join('\n');
+  if (out.length > maxChars) out = out.slice(0, maxChars) + '... (truncated)';
+  if (lines.length > maxLines && out.indexOf('...') === -1) out += '\n... (truncated)';
+  return out;
+}
+
+/**
+ * Explain error using Gemini API
+ * 
+ * @param {string} errorText - The error message/stack trace
+ * @param {object} geminiConfig - Configuration object with { apiKey: 'your-api-key' }
+ * @returns {Promise<string>} - The explanation with problem analysis and exact solution
+ * 
+ * Example:
+ *   const config = { apiKey: 'AIzaSy...' }
+ *   const explanation = await explainWithGemini('TypeError: Cannot read property', config)
+ */
+async function explainWithGemini(errorText, geminiConfig) {
+  // Validate API key is provided
+  if (!geminiConfig || !geminiConfig.apiKey) {
+    throw new Error('Gemini API key not configured. Run: nodewise --setup');
+  }
+
+  const apiKey = geminiConfig.apiKey.trim();
+
+  try {
+    // Build the full API URL with just the API key
+    const url = `${DEFAULT_ENDPOINT}?key=${apiKey}`;
+
+    // Exact structure matching the curl example you provided
+    // Minimal, token-efficient prompt — send a truncated error to reduce tokens
+    const snippet = truncateError(errorText, 6, 800);
+    const payload = {
+      contents: [
+        {
+          parts: [
+            {
+              text: `${createSystemPrompt()}\n\nBriefly explain the error in plain text: one-line summary; cause; file:line to change; minimal code fix.\n\nError snippet:\n${snippet}`
+            }
+          ]
+        }
+      ]
+    };
+
+    // Make the exact same request structure as shown in curl
+    const response = await axios.post(url, payload, {
+      timeout: geminiConfig.timeout || 60000,
+      headers: {
+        'Content-Type': 'application/json',
+        'x-goog-api-key': apiKey  // Also send as header (optional but explicit)
+      }
+    });
+
+    // Extract explanation from Gemini response
+    if (response.data?.candidates?.[0]?.content?.parts?.[0]?.text) {
+      let explanation = response.data.candidates[0].content.parts[0].text.trim();
+      // Clean any markdown formatting that might have been included
+      explanation = cleanMarkdown(explanation);
+      return explanation;
+    }
+
+    throw new Error('Empty response from Gemini API');
+  } catch (error) {
+    // Log detailed info to stderr for debugging (without exposing API key)
+    try {
+      const resp = error.response;
+      const cfg = error.config || {};
+      const reqBody = cfg.data || payload || {};
+      const respBody = resp?.data;
+
+      const logLines = [];
+      logLines.push('--- Gemini request failed (debug) ---');
+      if (resp) logLines.push(`Status: ${resp.status} ${resp.statusText || ''}`);
+      if (error.code) logLines.push(`Error code: ${error.code}`);
+      logLines.push('Request snippet:');
+      // show only the text portion of the payload to save tokens
+      const textPart = (reqBody && reqBody.contents && reqBody.contents[0] && reqBody.contents[0].parts && reqBody.contents[0].parts[0] && reqBody.contents[0].parts[0].text) ? reqBody.contents[0].parts[0].text : truncateString(reqBody, 600);
+      logLines.push(truncateString(textPart, 1000));
+      if (respBody) {
+        logLines.push('Response (truncated):');
+        logLines.push(truncateString(respBody, 1000));
+      }
+
+      // Provide a curl equivalent without the API key value
+      const curl = `curl "${DEFAULT_ENDPOINT}" \\
+  -H "x-goog-api-key: $GEMINI_API_KEY" \\
+  -H 'Content-Type: application/json' \\
+  -X POST \\
+  -d '${truncateString(reqBody, 1000)}'`;
+      logLines.push('Curl (use env var GEMINI_API_KEY):');
+      logLines.push(curl);
+
+      // Print to stderr so normal output stays clean
+      console.error('\n' + logLines.join('\n') + '\n');
+    } catch (logErr) {
+      // ignore logging errors
+    }
+    // Provide helpful error messages for common issues
+    // Short, plain fallback errors (keeps CLI concise)
+    if (error.response?.status === 401 || error.response?.status === 403) {
+      throw new Error('Gemini API Key Error: invalid or expired key');
+    }
+
+    if (error.response?.status === 429) {
+      throw new Error('Gemini rate limit (429)');
+    }
+
+    if (error.response?.status === 503 || error.response?.status === 500) {
+      throw new Error('Gemini service unavailable');
+    }
+
+    if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND') {
+      throw new Error('Network error: cannot reach Gemini');
+    }
+
+    if (error.code === 'ETIMEDOUT' || error.code === 'EHOSTUNREACH') {
+      throw new Error('Timeout: Gemini did not respond');
+    }
+
+    // Generic fallback
+    throw new Error(`Gemini API Error: ${error.message}`);
+  }
+}
+
+/**
+ * Get API key setup instructions
+ */
+function getSetupInstructions() {
+  return `
+🔑 Gemini API Setup:
+1. Visit: https://makersuite.google.com/app/apikey
+2. Click "Create API Key"
+3. Copy the API key
+4. Paste when prompted: nodewise --setup
+
+That's it! You only need to provide the API key.
+The endpoint is automatically configured.
+  `;
+}
+
+module.exports = {
+  explainWithGemini,
+  createSystemPrompt,
+  cleanMarkdown,
+  getSetupInstructions,
+  DEFAULT_ENDPOINT
+};

package/src/explainer/index.js

@@ -0,0 +1,51 @@
+/**
+ * explainer/index.js
+ * 
+ * Main explainer abstraction layer
+ * Routes to appropriate explainer based on configuration
+ * Handles fallback from Gemini to Normal mode on failure
+ */
+
+const { explainWithGemini } = require('./gemini');
+const { explainWithNormal } = require('./normal');
+const chalk = require('chalk');
+
+/**
+ * Main explain function - routes based on config
+ * 
+ * @param {string} errorText - The error message/stack
+ * @param {object} config - Configuration object with mode setting
+ * @returns {Promise<string>} - The explanation
+ */
+async function explain(errorText, config) {
+  if (!config) {
+    throw new Error('Configuration is required');
+  }
+
+  // If no mode specified, default to normal
+  const mode = config.mode || 'normal';
+
+  try {
+    if (mode === 'gemini') {
+      try {
+        const geminiOptions = { ...config.gemini, timeout: config.timeout };
+        return await explainWithGemini(errorText, geminiOptions);
+      } catch (geminiError) {
+        // Gemini failed — fall back to normal mode (concise)
+        const reason = (geminiError && geminiError.message) ? geminiError.message.split('\n')[0] : 'unknown';
+        console.warn(chalk.yellow(`Gemini failed, using normal mode: ${reason}`));
+        return await explainWithNormal(errorText);
+      }
+    } else if (mode === 'normal') {
+      return await explainWithNormal(errorText);
+    } else {
+      throw new Error(`Unknown explanation mode: ${mode}`);
+    }
+  } catch (error) {
+    throw error;
+  }
+}
+
+module.exports = {
+  explain
+};

package/src/explainer/interactive.js

@@ -0,0 +1,123 @@
+/**
+ * explainer/interactive.js
+ *
+ * Minimal interactive UI for error explanations
+ */
+
+const chalk = require('chalk');
+const readline = require('readline');
+const { explain } = require('./index');
+
+async function showInteractiveExplainer(errorText, config) {
+  console.log('\n');
+  const summary = (errorText || '').toString().split('\n')[0] || 'Unknown error';
+
+  // Header with soft border
+  console.log(chalk.hex('#FF5F5F')('  ┌' + '─'.repeat(58)));
+  console.log(chalk.hex('#FF5F5F')('  │ ') + chalk.white.bold('CRASH DETECTED'));
+  console.log(chalk.hex('#FF5F5F')('  └' + '─'.repeat(58)));
+  console.log();
+  console.log(chalk.white('    ' + summary));
+  console.log();
+
+  // Compact, modern prompt
+  console.log(chalk.cyan.bold('    ? ') + chalk.white('Would you like an AI explanation?'));
+  console.log(chalk.gray('      [y] Yes, explain it  [n] No, just skip'));
+  console.log();
+
+  const answer = await getUserInput();
+
+  if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes' || answer === '') {
+    await explainErrorInteractively(errorText, config);
+  } else {
+    console.log(chalk.gray('    Skipped.\n'));
+  }
+}
+
+function getUserInput() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true
+    });
+
+    process.stdout.write(chalk.cyan('    > '));
+
+    rl.on('line', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function showThinking() {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let frameIndex = 0;
+
+  process.stdout.write('\n');
+  const interval = setInterval(() => {
+    process.stdout.write(`\r    ${chalk.hex('#00D7FF')(frames[frameIndex])} ${chalk.gray('Consulting Gemini...')}`);
+    frameIndex = (frameIndex + 1) % frames.length;
+  }, 80);
+
+  return interval;
+}
+
+function clearThinking(interval) {
+  clearInterval(interval);
+  process.stdout.write('\r' + ' '.repeat(50) + '\r');
+}
+
+function displayExplanation(explanation) {
+  console.log('\n');
+
+  // Minimalist header with a simple horizontal rule
+  console.log(chalk.hex('#00FF87').bold('  ✦ GEMINI INTELLIGENCE'));
+  console.log(chalk.gray('  ' + '─'.repeat(45)));
+  console.log();
+
+  const lines = explanation.split('\n');
+  lines.forEach((line) => {
+    let content = line.trim();
+    if (!content) {
+      console.log(); // Add a gap for empty lines (double-spacing)
+      return;
+    }
+
+    // High-end minimalist styling
+    // If it starts with a keyword, add a line break before it to create gaps between sections
+    if (/^(Summary|Problem|Cause|Solution|Fix|Where|Why|File|Line|Note|Suggestion):/i.test(content)) {
+      console.log();
+    }
+
+    content = content
+      .replace(/^(Summary|Problem|Cause|Solution|Fix|Where|Why|File|Line|Note|Suggestion):/i, (match) => chalk.hex('#FFAF00').bold(match))
+      .replace(/`([^`]+)`/g, (match) => chalk.hex('#00FF87')(match))
+      .replace(/'([^']+)'/g, (match) => chalk.hex('#00FF87')(match));
+
+    console.log('    ' + content);
+  });
+
+  console.log('\n');
+}
+
+async function explainErrorInteractively(errorText, config) {
+  let thinkingInterval = showThinking();
+
+  try {
+    const explanation = await explain(errorText, config);
+    clearThinking(thinkingInterval);
+    displayExplanation(explanation);
+  } catch (error) {
+    clearThinking(thinkingInterval);
+    console.log(chalk.red.bold('  ✗ Failed to explain'));
+    console.log(chalk.red(`  ${error.message}`));
+    console.log();
+  }
+}
+
+module.exports = {
+  showInteractiveExplainer,
+  displayExplanation
+};

package/src/explainer/normal.js

@@ -0,0 +1,27 @@
+/**
+ * explainer/normal.js
+ * 
+ * Normal mode explainer using pattern-based detection
+ * Lightweight, offline, no API calls required
+ */
+
+const { getErrorExplanation } = require('../errorPatterns');
+
+/**
+ * Explain error using pattern matching
+ * 
+ * @param {string} errorText - The error message/stack
+ * @returns {Promise<string>} - The explanation
+ */
+async function explainWithNormal(errorText) {
+  try {
+    const explanation = getErrorExplanation(errorText);
+    return explanation;
+  } catch (error) {
+    return `Unable to explain this error. Here's what we know:\n${errorText}`;
+  }
+}
+
+module.exports = {
+  explainWithNormal
+};

package/src/expressErrorHandler.js

@@ -0,0 +1,68 @@
+/**
+ * expressErrorHandler.js
+ * 
+ * Express error handling for nodewise
+ * Provides utilities to ensure all errors are logged to stderr where nodewise can catch them
+ */
+
+/**
+ * Error handler middleware for Express
+ * Place this AFTER all other middleware and route handlers
+ * 
+ * Example:
+ *   const app = express();
+ *   app.get('/', (req, res) => { ... });
+ *   app.use(nodewiseErrorHandler);  // <-- Add at the end
+ *   app.listen(3000);
+ */
+function nodewiseErrorHandler(err, req, res, next) {
+  // Always log errors to stderr so nodewise captures them
+  console.error('Caught Error in Express:');
+  console.error(err.stack || err.toString());
+  
+  // Send response to client
+  res.status(err.status || 500).json({
+    error: err.message,
+    status: err.status || 500
+  });
+}
+
+/**
+ * Wrapper to catch errors in async route handlers
+ * Use this to wrap async route handlers to catch thrown errors
+ * 
+ * Example:
+ *   app.get('/', asyncHandler(async (req, res) => {
+ *     const data = await risky();
+ *     res.send(data);
+ *   }));
+ */
+function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+/**
+ * Setup global uncaught error handlers
+ * Call this at app startup to catch all unhandled errors
+ */
+function setupGlobalErrorHandlers() {
+  process.on('uncaughtException', (err) => {
+    console.error('Uncaught Exception:');
+    console.error(err.stack || err);
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled Promise Rejection:');
+    console.error(reason);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  nodewiseErrorHandler,
+  asyncHandler,
+  setupGlobalErrorHandlers
+};

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * index.js
+ * 
+ * Main entry point for nodewise
+ * Exports the Runner class for programmatic use
+ */
+
+const { Runner } = require('./runner');
+const { explain } = require('./explainer');
+
+module.exports = {
+  Runner,
+  explain
+};