errlens 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Maintain dependencies for npm
+  - package-ecosystem: "npm"
+    directory: "/" # Location of package.json
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    # Label PRs so they are easy to filter
+    labels:
+      - "dependencies"
+      - "javascript"
+
+  # Maintain GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "ci/cd"

package/.github/workflow/nodejs.yml

@@ -0,0 +1,23 @@
+# .github/workflows/nodejs.yml
+name: Node.js CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js 18
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - run: npm install
+      - run: npm run lint || echo "Skipping lint if not set"
+      - run: npm test || echo "Skipping test if not set"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BeyteFlow
+
+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,115 @@
+# ErrLens 🔍  
+> **Translate cryptic JavaScript errors into human-readable solutions instantly.**
+
+<p align="left">
+  <img src="https://img.shields.io/npm/v/errlens?style=flat-square&color=007acc" alt="npm version">
+  <img src="https://img.shields.io/github/license/BeyteFlow/errlens?style=flat-square&color=42b883" alt="license">
+  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome">
+</p>
+
+**ErrLens** is a professional-grade CLI utility designed to eliminate developer frustration. It intercepts Node.js crashes, analyzes stack traces, and delivers plain-English explanations with actionable fixes—directly in your terminal.
+
+---
+
+## 🌟 Key Features
+
+- 🚀 **Instant Diagnostics** – No more context-switching to Google or StackOverflow.  
+- 🔄 **Live Monitoring** – Catch errors in real-time using the `errlens run` command.  
+- 🧠 **Fuzzy Logic Engine** – Matches messy stack traces and typos using `Fuse.js`.  
+- 🎨 **Beautiful UI** – High-visibility terminal output powered by `boxen` and `chalk`.  
+- 🤖 **CI/CD Ready** – Export raw data via `--json` for automated error reporting.  
+
+---
+
+## 📦 Installation
+
+Install globally via npm to use the `errlens` command anywhere in your terminal:
+
+```bash
+npm install -g errlens
+```
+
+---
+
+## 🛠 Usage
+
+### 1️⃣ Automatic Monitoring (The "Pro" Way)
+
+Run your script through ErrLens. If it crashes, ErrLens intercepts the error and explains the fix before the process exits.
+
+```bash
+errlens run your-app.js
+```
+
+---
+
+### 2️⃣ Manual Analysis
+
+Found a weird error in your logs? Just paste the message:
+
+```bash
+errlens "TypeError: Cannot read properties of undefined"
+```
+
+---
+
+### 3️⃣ Pipeline Integration
+
+Get machine-readable results for your own tooling or automated reports:
+
+```bash
+errlens "is not a function" --json
+```
+
+---
+
+## 🧠 System Architecture
+
+ErrLens operates on a three-stage intelligent pipeline to turn confusion into clarity:
+
+| Phase          | Component       | Description |
+|---------------|----------------|-------------|
+| Interception  | `auto.js`      | Hooks into the `uncaughtException` event via a preload script. |
+| Matching      | `matcher.js`   | Uses fuzzy search against `database.json` to find the root cause. |
+| Formatting    | `formatter.js` | Wraps the diagnosis in a clean, color-coded terminal interface. |
+
+---
+
+## 📁 Project Structure
+
+```
+errlens/
+├── bin/index.js       # CLI Entry point & Command routing
+├── lib/
+│   ├── matcher.js     # Fuzzy search & Logic engine
+│   ├── formatter.js   # UI & Terminal styling
+│   ├── auto.js        # Automation & Error interception
+│   └── database.json  # The "Knowledge Base" (Dictionary)
+├── package.json       # Dependencies & Metadata
+└── README.md          # Documentation
+```
+
+---
+
+## 🤝 Contributing
+
+We are building the world's most comprehensive dictionary of JavaScript errors, and we need your help!
+
+1. Fork the repository.  
+2. Add a new error entry to `lib/database.json`.  
+3. Submit a Pull Request.  
+
+💡 **Tip:** Every error you add helps another developer save valuable time. Join the mission!
+
+---
+
+## 📝 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+<p align="center">
+  Built with ❤️ by <b>BeyteFlow</b><br>
+  <i>Making the terminal a friendlier place, one error at a time.</i>
+</p>

package/bin/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+const { Command } = require("commander");
+const ora = require("ora");
+const chalk = require("chalk");
+const { findError } = require("../lib/matcher");
+const { formatError } = require("../lib/formatter");
+
+const program = new Command();
+
+program
+  .name("errlens")
+  .description("Professional JS error analysis for the terminal")
+  .version("1.1.0")
+  .argument("[error]", "The error message to analyze")
+  .option("-j, --json", "Output results in raw JSON format") // For automation
+  .action((errorInput, options) => {
+    // If no argument is provided, show help and exit
+    if (!errorInput) {
+      program.help();
+      return;
+    }
+
+    // JSON Mode (No spinner, no colors, just data)
+    if (options.json) {
+      const result = findError(errorInput);
+      console.log(JSON.stringify(result || { error: "No match found" }, null, 2));
+      return;
+    }
+
+    // Standard Mode
+    const spinner = ora({ text: "Analyzing error trace...", color: "cyan" }).start();
+
+    setTimeout(() => {
+      const result = findError(errorInput);
+
+      if (!result) {
+        spinner.fail(chalk.red(" Analysis Failed: Error not found in database."));
+        console.log(chalk.dim("\nTry searching a shorter snippet of the error message."));
+        return;
+      }
+
+      spinner.succeed(chalk.bold("Analysis complete!"));
+      console.log(formatError(result));
+    }, 500);
+  });
+
+program.parse(process.argv);

package/lib/auto.js

@@ -0,0 +1,16 @@
+// lib/auto.js
+const { findError } = require("./matcher");
+const { formatError } = require("./formatter");
+
+// This listens for any crash that wasn't caught by a try/catch
+process.on("uncaughtException", (err) => {
+  const result = findError(err.message);
+  
+  if (result) {
+    console.log("\n--- ErrLens Auto-Detection ---");
+    console.log(formatError(result));
+  } else {
+    console.error(err);
+  }
+  process.exit(1);
+});

package/lib/database.json

@@ -0,0 +1,38 @@
+[
+  {
+    "name": "TypeError: Cannot read properties of undefined",
+    "match": "Cannot read properties of undefined",
+    "explanation": "You are trying to access a property (like .map, .length, or .id) on a variable that currently holds no value.",
+    "why": "The variable wasn't initialized, an API call hasn't finished yet, or a function returned nothing.",
+    "fixes": [
+      "Use optional chaining: user?.profile",
+      "Set a default value: const list = data || []",
+      "Check if the variable exists: if (data) { ... }"
+    ],
+    "example": "const name = user?.info?.name || 'Guest';"
+  },
+  {
+    "name": "ReferenceError: x is not defined",
+    "match": "is not defined",
+    "explanation": "You're trying to use a variable that hasn't been declared in the current scope.",
+    "why": "Possible typo in the variable name, or the variable is scoped inside another function/block.",
+    "fixes": [
+      "Check for typos in the variable name",
+      "Ensure the variable is declared with const, let, or var",
+      "Check if the variable is defined outside the current function"
+    ],
+    "example": "const myVar = 10;\nconsole.log(myVar); // Ensure name matches exactly"
+  },
+  {
+    "name": "TypeError: x is not a function",
+    "match": "is not a function",
+    "explanation": "You tried to call a variable as if it were a function, but it's a different data type (like a String or Object).",
+    "why": "Often happens when an import fails or when a callback isn't passed correctly.",
+    "fixes": [
+      "Verify the variable is actually a function with typeof",
+      "Check your imports/requires",
+      "Ensure you aren't overwriting the function name with a value"
+    ],
+    "example": "if (typeof callback === 'function') {\n  callback();\n}"
+  }
+]

package/lib/formatter.js

@@ -0,0 +1,35 @@
+const chalk = require("chalk");
+const boxen = require("boxen");
+
+function formatError(error) {
+  const fixList = error.fixes
+    .map(fix => chalk.green(`  ✔ ${fix}`))
+    .join("\n");
+
+  const content = `
+${chalk.cyan.bold("ID:")} ${error.name}
+
+${chalk.yellow.bold("🔍 WHAT HAPPENED:")}
+${error.explanation}
+
+${chalk.magenta.bold("💥 WHY:")}
+${error.why}
+
+${chalk.green.bold("✅ COMMON FIXES:")}
+${fixList}
+
+${chalk.blue.bold("📘 EXAMPLE:")}
+${chalk.gray(error.example)}
+  `;
+
+  return boxen(content, {
+    padding: 1,
+    margin: 1,
+    borderStyle: "round",
+    borderColor: "cyan",
+    title: "ErrLens Analysis",
+    titleAlignment: "center"
+  });
+}
+
+module.exports = { formatError };

package/lib/matcher.js

@@ -0,0 +1,25 @@
+const Fuse = require("fuse.js");
+const database = require("./database.json");
+
+function findError(input) {
+  if (!input) return null;
+
+  // Clean the input:
+  // 1. Take only the first line (the error message).
+  // 2. Remove common noise like 'Uncaught' or file paths.
+  const coreError = input.split('\n')[0]
+    .replace(/^Uncaught\s+/, '')
+    .split(' at ')[0]
+    .trim();
+
+  const fuse = new Fuse(database, {
+    keys: ["match", "name"],
+    threshold: 0.4, // Balance between strict and loose
+    distance: 100
+  });
+
+  const result = fuse.search(coreError);
+  return result.length > 0 ? result[0].item : null;
+}
+
+module.exports = { findError };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "errlens",
+  "version": "1.0.0",
+  "description": "A CLI tool that explains JavaScript/Node.js errors in plain English.",
+  "main": "./bin/index.js",
+  "author": "BeyteFlow (https://github.com/BeyteFlow)",
+  "license": "MIT",
+  "bin": {
+    "errlens": "./bin/index.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BeyteFlow/errlens.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BeyteFlow/errlens/issues"
+  },
+  "homepage": "https://github.com/BeyteFlow/errlens#readme",
+  "dependencies": {
+    "boxen": "^5.1.2",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fuse.js": "^7.0.0",
+    "ora": "^5.4.1"
+  }
+}