nodewise 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gourab Das
+
+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,97 @@
+# nodewise
+
+> Node.js error explainer with AI-powered clarity
+
+A production-ready CLI dev tool that intercepts and explains runtime errors in your Node.js applications. It works like nodemon but instead of just restarting on crash, it explains what went wrong in simple, natural language.
+
+---
+
+## 👨‍💻 Developer Information
+
+**Gourab Das**
+- **Email:** [dgourab574@gmail.com](mailto:dgourab574@gmail.com) | [gourab.sde@gmail.com](mailto:gourab.sde@gmail.com)
+- **LinkedIn:** [linkedin.com/in/gourab2005](https://www.linkedin.com/in/gourab2005/)
+- **GitHub:** [github.com/Gourab2005](https://github.com/Gourab2005)
+
+---
+
+## 🚀 How to Use
+
+### Installation
+
+Install `nodewise` as a development dependency in your project:
+
+```bash
+npm install -D nodewise
+```
+
+Or run it directly using `npx`:
+
+```bash
+npx nodewise your-app.js
+```
+
+### Usage
+
+1. **First-time Experience**: The first time you run it, you'll be prompted to choose between **Gemini AI** and **Normal Detection** mode.
+2. **Running Scripts**: Simply replace `node` or `nodemon` with `nodewise`:
+   ```bash
+   npx nodewise server.js
+   ```
+3. **Arguments**: Pass your app arguments as usual:
+   ```bash
+   npx nodewise server.js --port 3000
+   ```
+
+---
+
+## 🤔 Why use nodewise?
+
+Traditional error messages can be cryptic, long, or stacked with irrelevant internal module traces. **nodewise** solves this by:
+
+- **Saving Time**: No more Googling stack traces. Get the fix instantly.
+- **Smart Context**: Unlike manual searching, the AI mode understands your specific code structure.
+- **Seamless Flow**: It combines the best of `nodemon` (auto-restart) with a built-in "senior developer" who explains your mistakes.
+
+---
+
+## ✨ Features
+
+- 🤖 **Gemini Explainer**: Deep AI-powered analysis of crashes with code-specific solutions.
+- 📊 **Normal Detection**: Pattern-based error detection for 50+ common Node.js errors (offline).
+- 🔄 **Auto-Restart**: Watches `.js` and `.json` files and restarts instantly on save.
+- 📝 **Minimalist Design**: High-end, gapped terminal output that doesn't clutter your workspace.
+- ⚡ **Lightweight**: Zero heavy dependencies, keeping your dev environment fast.
+
+---
+
+## 📋 Example Output
+
+  ✦ GEMINI INTELLIGENCE
+  ─────────────────────────────────────────────
+
+    Summary: This error occurs when you try to import or require a file that doesn't exist.
+
+    Cause: Typo in the file name or path, or the file was moved/deleted.
+
+    File: src/app.js:12
+
+    Fix: 
+    1. Check the spelling of the file path.
+    2. Verify the file exists in that location.
+    3. Use an absolute path if needed: `path.join(__dirname, './config')`
+
+---
+
+## CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `nodewise --setup` | Change modes or update AI configuration. |
+| `nodewise --reset` | Reset all configurations. |
+| `nodewise --help` | Show usage manual. |
+| `nodewise -v` | Show current version. |
+
+---
+
+Made with ❤️ by [Gourab Das](https://github.com/Gourab2005)

package/USER_MANUAL.md

@@ -0,0 +1,106 @@
+# 📖 NodeWise User Manual
+
+Welcome to **NodeWise**, your AI-powered companion for Node.js development. This manual will help you get the most out of NodeWise's error explanation and auto-restart features.
+
+---
+
+## 🚀 Getting Started
+
+NodeWise is designed to be a drop-in replacement for `node` or `nodemon` during development.
+
+### Installation
+If you haven't already, you can link it globally or install it in your project:
+```bash
+# Link for local development
+npm link
+
+# Install as a dev dependency
+npm install -D nodewise
+```
+
+### Initial Setup
+The first time you run NodeWise, it will launch a setup wizard to configure your preferred explanation mode.
+```bash
+npx nodewise --setup
+```
+
+---
+
+## 🤖 Explanation Modes
+
+### 1. Gemini Explainer (AI-Powered)
+The "Top-G" mode. It uses Google's latest Gemini models to analyze your specific code and provide context-aware fixes.
+
+*   **Setup**: Requires a free Gemini API Key from [Google AI Studio](https://aistudio.google.com/app/apikey).
+*   **Best for**: Complex logic errors, obscure Node.js core errors, and step-by-step fix guides.
+*   **Features**: Beautiful minimalist terminal output with neon highlighting.
+
+### 2. Normal Detection (Offline)
+A lightning-fast, pattern-based mode that works entirely offline.
+
+*   **Setup**: No setup required.
+*   **Best for**: Common errors like `MODULE_NOT_FOUND`, `TypeError`, and `ReferenceError`.
+*   **Features**: Zero latency, works without an internet connection.
+
+---
+
+## ⌨️ Command Line Interface
+
+| Command | Description |
+| :--- | :--- |
+| `nodewise <script.js>` | Run a script with auto-restart and error explainer. |
+| `nodewise --setup` | Change modes or update your Gemini API key. |
+| `nodewise --reset` | Wipe configuration and start fresh. |
+| `nodewise --help` | Show available options and examples. |
+| `nodewise -v` | Check your current NodeWise version. |
+
+### Running with Arguments
+You can pass arguments to your script just like you would with node:
+```bash
+nodewise server.js --port 3000 --env production
+```
+
+---
+
+## ⚙️ Configuration
+NodeWise saves your preferences in `nodewise.config.json` in your project root.
+
+```json
+{
+  "mode": "gemini",
+  "gemini": {
+    "apiKey": "YOUR_KEY_HERE"
+  },
+  "autoRestart": true,
+  "ignorePatterns": ["node_modules", ".git"],
+  "timeout": 60000
+}
+```
+
+*   **autoRestart**: Set to `false` if you don't want the process to restart on file changes.
+*   **timeout**: Increase this if the AI is taking too long to respond on slow connections.
+
+---
+
+## ✨ Pro Tips
+
+### 1. Minimalist AI Insight
+When a crash occurs in Gemini mode, you'll see a clean, gapped output. We've removed bulky boxes to keep your terminal clean. Look for the **✦ GEMINI INTELLIGENCE** header.
+
+### 2. Auto-Restart
+NodeWise watches your `.js` and `.json` files. As soon as you save a fix, NodeWise will instantly restart your application, allowing for a rapid "Code-Crash-Fix-Repeat" cycle.
+
+### 3. Graceful Exit
+Use `Ctrl+C` to shut down both your application and the NodeWise watcher gracefully.
+
+---
+
+## 🆘 Troubleshooting
+
+*   **API Timeouts**: If you see "Gemini timed out," check your internet connection or increase the `timeout` in `nodewise.config.json`.
+*   **Invalid Key**: Ensure your API key is correct by re-running `nodewise --setup`.
+*   **Files not watching**: Ensure the directory you are working in doesn't have an ignore pattern matching your files.
+
+---
+
+*Made with ❤️ for Node.js developers.*

package/bin/nodewise.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+/**
+ * bin/nodewise.js
+ * 
+ * CLI entry point
+ * Handles command-line arguments and orchestrates the setup/run flow
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+const config = require('../src/config');
+const { runSetup } = require('../src/setup');
+const { Runner } = require('../src/runner');
+
+const VERSION = '1.0.0';
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const flags = {
+    help: false,
+    version: false,
+    setup: false,
+    reset: false
+  };
+  
+  let scriptPath = null;
+  const scriptArgs = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+    } else if (arg === '--setup') {
+      flags.setup = true;
+    } else if (arg === '--reset') {
+      flags.reset = true;
+    } else if (!scriptPath) {
+      scriptPath = arg;
+    } else {
+      scriptArgs.push(arg);
+    }
+  }
+
+  return { flags, scriptPath, scriptArgs };
+}
+
+/**
+ * Display help message
+ */
+function showHelp() {
+  console.log(`
+${chalk.cyan.bold('nodewise ' + VERSION)} ${chalk.gray('- Node.js error explainer with AI-powered clarity')}
+
+${chalk.bold('USAGE')}
+  npx nodewise [options] <script> [script-args]
+
+${chalk.bold('OPTIONS')}
+  -h, --help          Show this help message
+  -v, --version       Show version
+  --setup             Run setup wizard
+  --reset             Reset configuration
+
+${chalk.bold('EXAMPLES')}
+  npx nodewise app.js
+  npx nodewise server.js --port 3000
+  npx nodewise --setup       (configure explanation mode)
+  npx nodewise --reset       (reset configuration)
+
+${chalk.bold('MODES')}
+  ${chalk.cyan('Gemini Explainer')}      - AI-powered error explanations using Google Gemini
+  ${chalk.cyan('Normal Detection')}      - Pattern-based error detection (offline)
+
+${chalk.bold('CONFIGURATION')}
+  Settings are saved in ${chalk.yellow('nodewise.config.json')} in your project root.
+
+${chalk.bold('DOCUMENTATION')}
+  https://github.com/yourusername/nodewise
+  `);
+}
+
+/**
+ * Display version
+ */
+function showVersion() {
+  console.log(`nodewise ${VERSION}`);
+}
+
+/**
+ * Main CLI function
+ */
+async function main() {
+  const { flags, scriptPath, scriptArgs } = parseArgs();
+
+  // Handle info flags
+  if (flags.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (flags.version) {
+    showVersion();
+    process.exit(0);
+  }
+
+  // Handle setup flow
+  if (flags.setup || flags.reset) {
+    try {
+      await runSetup();
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('Setup failed:'), error.message);
+      process.exit(1);
+    }
+  }
+
+  // Check if script path is provided
+  if (!scriptPath) {
+    console.error(chalk.red('Error: Please provide a script to run\n'));
+    showHelp();
+    process.exit(1);
+  }
+
+  // Resolve script path
+  const resolvedScriptPath = path.resolve(process.cwd(), scriptPath);
+
+  try {
+    // Load or create configuration
+    let appConfig = config.loadConfig();
+
+    if (!appConfig) {
+      console.log(chalk.cyan('No configuration found. Running setup wizard...\n'));
+      appConfig = await runSetup();
+    }
+
+    // Start the runner
+    const runner = new Runner(resolvedScriptPath, scriptArgs, appConfig);
+
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+      runner.handleShutdown();
+    });
+
+    process.on('SIGTERM', () => {
+      runner.handleShutdown();
+    });
+
+    // Start running
+    runner.start();
+  } catch (error) {
+    console.error(chalk.red('Fatal error:'), error.message);
+    process.exit(1);
+  }
+}
+
+// Run the CLI
+main().catch((error) => {
+  console.error(chalk.red('Unexpected error:'), error);
+  process.exit(1);
+});

package/examples/express-server.js

@@ -0,0 +1,70 @@
+// examples/express-server.js
+// Express app with integrated nodewise error handling
+// This shows the correct way to set up Express for error explanation
+
+const express = require('express');
+const { nodewiseErrorHandler, asyncHandler } = require('../src/expressErrorHandler');
+
+const app = express();
+
+app.use(express.json());
+
+// =========== ROUTES ===========
+
+// Route 1: Intentional TypeError
+app.get('/error1', (req, res) => {
+  const obj = null;
+  obj.kjbvend("Hello"); // TypeError: obj.kjbvend is not a function
+  res.send('This will not run');
+});
+
+// Route 2: Intentional ReferenceError
+app.get('/error2', (req, res) => {
+  console.log(undefinedVar); // ReferenceError
+  res.send('This will not run');
+});
+
+// Route 3: JSON parsing error
+app.get('/error3', (req, res) => {
+  const json = '{ invalid }';
+  JSON.parse(json); // SyntaxError
+  res.send('This will not run');
+});
+
+// Route 4: Async error
+app.get('/error4', asyncHandler(async (req, res) => {
+  // This will throw an error
+  throw new Error('Async operation failed');
+}));
+
+// Route 5: Working route
+app.get('/', (req, res) => {
+  res.json({
+    message: 'Express server with nodewise error handling',
+    routes: [
+      'GET / - this page',
+      'GET /error1 - TypeError (obj.kjbvend)',
+      'GET /error2 - ReferenceError (undefined variable)',
+      'GET /error3 - JSON SyntaxError',
+      'GET /error4 - Async error'
+    ]
+  });
+});
+
+// =========== ERROR HANDLER ===========
+// THIS IS IMPORTANT: Add error handler middleware AFTER all routes
+// This will catch all errors and log them to stderr where nodewise catches them
+app.use(nodewiseErrorHandler);
+
+// =========== START SERVER ===========
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`\n✓ Express server running at http://localhost:${PORT}`);
+  console.log('\nTry these URLs to trigger errors:');
+  console.log(`  GET http://localhost:${PORT}/error1  (TypeError)`);
+  console.log(`  GET http://localhost:${PORT}/error2  (ReferenceError)`);
+  console.log(`  GET http://localhost:${PORT}/error3  (SyntaxError)`);
+  console.log(`  GET http://localhost:${PORT}/error4  (Async Error)\n`);
+  console.log('Run nodewise to see errors explained:');
+  console.log('  nodewise examples/express-server.js\n');
+});

package/examples/express-with-errors.js

@@ -0,0 +1,63 @@
+// examples/express-with-errors.js
+// Node.js app with integrated error handling for nodewise
+// This app demonstrates how runtime errors are caught and explained
+
+const errorWrapper = require('../src/errorWrapper');
+
+// Setup error handlers if running under nodewise
+if (process.env.NODEWISE_ACTIVE) {
+  errorWrapper.setupErrorHandlers();
+}
+
+// Simulate a server with runtime error handling
+const http = require('http');
+
+const server = http.createServer((req, res) => {
+  // Route 1: TypeError
+  if (req.url === '/error1') {
+    const obj = null;
+    obj.method(); // TypeError: Cannot read property 'method' of null
+    return;
+  }
+
+  // Route 2: ReferenceError
+  if (req.url === '/error2') {
+    console.log(undefinedVariable); // ReferenceError
+    return;
+  }
+
+  // Route 3: JSON parsing error
+  if (req.url === '/error3') {
+    const json = '{ invalid json }';
+    const parsed = JSON.parse(json); // SyntaxError
+    return;
+  }
+
+  // Route 4: Working route
+  if (req.url === '/') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      message: 'Node.js app running with nodewise error handling',
+      routes: [
+        'GET / - this page',
+        'GET /error1 - TypeError',
+        'GET /error2 - ReferenceError',
+        'GET /error3 - JSON SyntaxError'
+      ]
+    }));
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('Not Found');
+});
+
+const PORT = process.env.PORT || 3000;
+server.listen(PORT, () => {
+  console.log(`\n✓ Server running at http://localhost:${PORT}`);
+  console.log('\nTry these URLs to trigger errors:');
+  console.log(`  curl http://localhost:${PORT}/error1  (TypeError)`);
+  console.log(`  curl http://localhost:${PORT}/error2  (ReferenceError)`);
+  console.log(`  curl http://localhost:${PORT}/error3  (SyntaxError)\n`);
+});
+

package/examples/module-not-found.js

@@ -0,0 +1,9 @@
+// examples/module-not-found.js
+// This file demonstrates a MODULE_NOT_FOUND error
+
+console.log('Starting app...');
+
+// Try to require a non-existent module
+const nonExistent = require('./this-file-does-not-exist.js');
+
+console.log('This will not run');

package/examples/reference-error.js

@@ -0,0 +1,9 @@
+// examples/reference-error.js
+// This file demonstrates a ReferenceError
+
+console.log('Starting app...');
+
+// Use a variable that doesn't exist
+console.log(undefinedVariable);
+
+console.log('This will not run');

package/examples/syntax-error.js

@@ -0,0 +1,11 @@
+// examples/syntax-error.js
+// This file demonstrates a syntax error
+
+console.log('Starting app...');
+
+// Missing closing brace
+const obj = {
+  name: 'test'
+  // Missing }
+
+console.log('This will not run');

package/examples/type-error.js

@@ -0,0 +1,10 @@
+// examples/type-error.js
+// This file demonstrates a TypeError
+
+console.log('Starting app...');
+
+// Try to call a method on null
+const obj = null;
+obj.method();
+
+console.log('This will not run');

package/examples/working-app.js

@@ -0,0 +1,35 @@
+// examples/working-app.js
+// A simple working Express server example
+
+const http = require('http');
+
+const PORT = process.env.PORT || 3000;
+
+const server = http.createServer((req, res) => {
+  if (req.url === '/') {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('Hello from nodewise!\n');
+  } else if (req.url === '/api/data') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ message: 'Success', timestamp: new Date() }));
+  } else {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found\n');
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`\n✓ Server running at http://localhost:${PORT}`);
+  console.log(`  Try: curl http://localhost:${PORT}`);
+  console.log(`  Or:  curl http://localhost:${PORT}/api/data\n`);
+  console.log('Edit this file to trigger a restart...\n');
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+  console.log('\nShutting down...');
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "nodewise",
+  "version": "1.0.0",
+  "description": "Node.js error explainer with AI-powered clarity",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "bin": {
+    "nodewise": "bin/nodewise.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cli",
+    "node",
+    "error",
+    "debugging",
+    "ai",
+    "gemini",
+    "explainer"
+  ],
+  "author": "Gourab Das",
+  "license": "MIT",
+  "dependencies": {
+    "inquirer": "^9.2.15",
+    "axios": "^1.6.5",
+    "chokidar": "^3.5.3",
+    "chalk": "^4.1.2"
+  },
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "README.md",
+    "USER_MANUAL.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gourab2005/nodewise.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Gourab2005/nodewise/issues"
+  },
+  "homepage": "https://github.com/Gourab2005/nodewise#readme",
+  "devDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}