systemlens 1.0.0

package/.env.example

@@ -0,0 +1,5 @@
+# SystemLens Environment Variables
+
+# Optional: Enable AI-enhanced explanations
+# Get your API key from https://platform.openai.com
+OPENAI_API_KEY=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neeraj — CreatedBYNJ5.0
+
+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,160 @@
+# 🔬 SystemLens
+
+**An intelligent system explainer that converts raw metrics into human-readable insights.**
+
+> _CreatedBYNJ5.0_
+
+SystemLens doesn't just show numbers — it tells you *why* your system is slow, *what* is responsible, and *what you should do about it*. It acts like a senior engineer explaining system behavior to a beginner.
+
+**Works on Linux, macOS, and Windows.**
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Run instantly with npx (no install needed)
+npx systemlens
+
+# Or install globally
+npm install -g systemlens
+systemlens
+```
+
+That's it. One command.
+
+---
+
+## 📋 Commands
+
+| Command | Description |
+|---------|-------------|
+| `systemlens` | Start real-time CLI monitoring |
+| `systemlens --once` | Single analysis snapshot |
+| `systemlens --web` | Launch beautiful web dashboard |
+| `systemlens --web --port 4000` | Web dashboard on custom port |
+| `systemlens --help` | Show all options |
+| `systemlens --version` | Print version |
+
+---
+
+## ✨ Features
+
+🧠 **Intelligent Explanations** — Not just "CPU is 85%", but "Chrome is consuming high CPU due to multiple open tabs"  
+🔗 **Cause & Effect Chains** — Links symptoms to causes with clear reasoning  
+🛠️ **Developer Mode** — Detects dev servers, hot-reload, and possible infinite loops  
+📈 **Pattern Detection** — Identifies sustained high usage, spikes, and trends over time  
+✅ **Actionable Suggestions** — Prioritized actions with impact ratings  
+🤖 **Optional AI Enhancement** — GPT-powered deeper insights (set `OPENAI_API_KEY`)  
+🌐 **Web Dashboard** — Real-time glassmorphic dark-mode UI  
+⚡ **CLI Mode** — Terminal-based monitoring with colored output and progress bars  
+
+---
+
+## 🖥️ CLI Output
+
+```
+  ╔═══════════════════════════════════════════════════════════╗
+  ║          🔬  S Y S T E M L E N S                         ║
+  ║          CreatedBYNJ5.0                                   ║
+  ╚═══════════════════════════════════════════════════════════╝
+
+   🟡  SYSTEM STATUS: LIGHTLY LOADED  
+
+  📊 System Summary
+  CPU    ████░░░░░░░░░░░░░░░░  15%
+  Memory ███████████████░░░░░  62%
+
+  💬 What's Happening
+  Your system is moderately loaded...
+
+  🔗 Cause & Effect
+  🌐 Cause: Browser with ~4 open tabs using significant resources
+     Effect: Using 22% memory and 1% CPU
+
+  ✅ Suggested Actions
+  🌐 1. Close unused browser tabs and disable heavy extensions
+```
+
+---
+
+## 🌐 Web Dashboard
+
+```bash
+systemlens --web
+# Open http://localhost:3777
+```
+
+A premium dark-mode real-time dashboard with:
+- Live metric cards with sparkline charts
+- Natural language explanation panel
+- Cause & Effect visualization  
+- Process table with categories
+- Developer insights panel
+- Prioritized suggestions
+
+---
+
+## 🤖 AI Enhancement (Optional)
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY=sk-your-key-here
+
+# Run with AI insights
+systemlens
+```
+
+AI adds:
+- Deeper contextual insights
+- Performance predictions  
+- Power-user tips
+
+---
+
+## 🏗️ Architecture
+
+```
+Collection → Classification → Analysis → Explanation → Suggestion → Rendering
+```
+
+| Layer | Purpose |
+|-------|---------|
+| **4 Collectors** | CPU, Memory, Disk, Process data |
+| **Classifier** | Categorizes processes (Browser/Dev/System/Media) |
+| **4 Analyzers** | Detects issues, spikes, core imbalance, swap pressure |
+| **Explanation Engine** | Converts analysis → human-language narratives |
+| **Suggestion Engine** | Prioritized, actionable recommendations |
+| **Spike Detector** | Time-series pattern detection |
+| **AI Engine** | Optional GPT-powered enhancement |
+
+---
+
+## 🔧 Configuration
+
+All thresholds are configurable in `src/utils/constants.js`:
+
+| Threshold | Default | Description |
+|-----------|---------|-------------|
+| `CPU_HIGH` | 80% | Triggers critical alert |
+| `MEMORY_HIGH` | 80% | Triggers critical alert |
+| `SPIKE_THRESHOLD` | 20% | Jump size for spike detection |
+| `MONITORING_INTERVAL` | 3000ms | Data refresh rate |
+
+---
+
+## 🖥️ Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Linux | ✅ Fully supported |
+| macOS | ✅ Fully supported |
+| Windows | ✅ Fully supported |
+
+Requires **Node.js 18+** — uses ES modules and top-level await.
+
+---
+
+## 📄 License
+
+MIT — CreatedBYNJ5.0

package/bin/systemlens.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+// ─── SystemLens CLI ──────────────────────────────────────────────
+// Single entry point for all SystemLens modes.
+// Works on Windows, macOS, and Linux.
+//
+// Usage:
+//   systemlens              → Start real-time CLI monitoring
+//   systemlens --once       → Run a single analysis
+//   systemlens --web        → Start web dashboard on localhost:3777
+//   systemlens --help       → Show help
+
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+// ─── Resolve package root (cross-platform) ──────────────────────
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = join(__dirname, '..');
+
+// ─── Read version from package.json ─────────────────────────────
+let version = '1.0.0';
+try {
+  const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
+  version = pkg.version;
+} catch { }
+
+// ─── Parse args ─────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const hasFlag = (flag) => args.includes(flag);
+
+// ─── Version ────────────────────────────────────────────────────
+if (hasFlag('--version') || hasFlag('-v')) {
+  console.log(`systemlens v${version}`);
+  process.exit(0);
+}
+
+// ─── Help ───────────────────────────────────────────────────────
+if (hasFlag('--help') || hasFlag('-h')) {
+  console.log(chalk.cyan.bold(`
+  🔬 SystemLens v${version} — Intelligent System Explainer
+  CreatedBYNJ5.0
+
+  Usage:
+    systemlens                Start real-time CLI monitoring
+    systemlens --once         Run a single analysis snapshot
+    systemlens --web          Start web dashboard (localhost:3777)
+    systemlens --version      Show version
+    systemlens --help         Show this help message
+
+  Options:
+    --once, -o                Single analysis (no continuous monitoring)
+    --web, -w                 Launch web dashboard with real-time updates
+    --port <number>           Port for web dashboard (default: 3777)
+    --version, -v             Print version
+    --help, -h                Show help
+
+  Environment:
+    OPENAI_API_KEY            Optional: Enable AI-enhanced explanations
+
+  Examples:
+    npx systemlens                        # Monitor your system
+    npx systemlens --once                 # Quick snapshot
+    npx systemlens --web                  # Beautiful web dashboard
+    npx systemlens --web --port 4000      # Custom port
+    OPENAI_API_KEY=sk-... npx systemlens  # With AI insights
+
+  Platforms:
+    ✅ Linux  ✅ macOS  ✅ Windows
+  `));
+  process.exit(0);
+}
+
+// ─── Splash ─────────────────────────────────────────────────────
+function showSplash() {
+  console.log(chalk.cyan(`
+  ███████╗██╗   ██╗███████╗████████╗███████╗███╗   ███╗
+  ██╔════╝╚██╗ ██╔╝██╔════╝╚══██╔══╝██╔════╝████╗ ████║
+  ███████╗ ╚████╔╝ ███████╗   ██║   █████╗  ██╔████╔██║
+  ╚════██║  ╚██╔╝  ╚════██║   ██║   ██╔══╝  ██║╚██╔╝██║
+  ███████║   ██║   ███████║   ██║   ███████╗██║ ╚═╝ ██║
+  ╚══════╝   ╚═╝   ╚══════╝   ╚═╝   ╚══════╝╚═╝     ╚═╝
+
+  ██╗     ███████╗███╗   ██╗███████╗
+  ██║     ██╔════╝████╗  ██║██╔════╝
+  ██║     █████╗  ██╔██╗ ██║███████╗
+  ██║     ██╔══╝  ██║╚██╗██║╚════██║
+  ███████╗███████╗██║ ╚████║███████║
+  ╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝
+  `));
+  console.log(chalk.bold.hex('#8B5CF6')(`  CreatedBYNJ5.0  •  v${version}\n`));
+}
+
+// ─── Web Mode ───────────────────────────────────────────────────
+if (hasFlag('--web') || hasFlag('-w')) {
+  showSplash();
+
+  // Parse custom port
+  const portIdx = args.indexOf('--port');
+  const customPort = portIdx !== -1 && args[portIdx + 1]
+    ? parseInt(args[portIdx + 1], 10)
+    : null;
+
+  if (customPort) {
+    process.env.PORT = String(customPort);
+  }
+
+  // Import and run the web server
+  await import(join(PKG_ROOT, 'server.js'));
+
+} else {
+  // ─── CLI Mode ───────────────────────────────────────────────
+  showSplash();
+  console.log(chalk.dim('  Initializing system analysis...\n'));
+
+  // Dynamic import to avoid loading everything upfront
+  const { SystemLens } = await import(join(PKG_ROOT, 'src', 'index.js'));
+  const lens = new SystemLens();
+
+  if (hasFlag('--once') || hasFlag('-o')) {
+    await lens.runOnce();
+  } else {
+    await lens.startMonitoring();
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "systemlens",
+  "version": "1.0.0",
+  "description": "An intelligent system explainer that converts raw metrics into human-readable insights. Not a monitor — a system mentor.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "systemlens": "bin/systemlens.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "web/",
+    "server.js",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/systemlens.js",
+    "cli": "node bin/systemlens.js",
+    "once": "node bin/systemlens.js --once",
+    "web": "node bin/systemlens.js --web"
+  },
+  "keywords": [
+    "system",
+    "monitor",
+    "explainer",
+    "diagnostics",
+    "insights",
+    "cpu",
+    "memory",
+    "process",
+    "system-info",
+    "system-monitor",
+    "cli",
+    "dashboard",
+    "devtools",
+    "performance",
+    "linux",
+    "macos",
+    "windows",
+    "cross-platform"
+  ],
+  "author": "Neeraj — CreatedBYNJ5.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neeraj/systemlens"
+  },
+  "homepage": "https://github.com/neeraj/systemlens#readme",
+  "bugs": {
+    "url": "https://github.com/neeraj/systemlens/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "openai": "^6.33.0",
+    "pidusage": "^4.0.1",
+    "systeminformation": "^5.31.5",
+    "ws": "^8.20.0"
+  }
+}

package/server.js

@@ -0,0 +1,106 @@
+// ─── SystemLens Web Server ───────────────────────────────────────
+// Express + WebSocket server that streams system analysis to the browser
+import express from 'express';
+import { WebSocketServer } from 'ws';
+import { createServer } from 'http';
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { SystemLens } from './src/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const app = express();
+const server = createServer(app);
+const wss = new WebSocketServer({ server });
+
+// Serve static files from /web
+app.use(express.static(join(__dirname, 'web')));
+
+// Initialize SystemLens
+const lens = new SystemLens();
+
+// ─── REST API ────────────────────────────────────────────────────
+app.get('/api/analyze', async (req, res) => {
+    try {
+        const result = await lens.analyze();
+        res.json(result);
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+app.get('/api/history', (req, res) => {
+    res.json(lens.historyTracker.getSummary());
+});
+
+// ─── WebSocket Real-Time Stream ──────────────────────────────────
+const BROADCAST_INTERVAL = 3000;
+let broadcastTimer = null;
+
+wss.on('connection', (ws) => {
+    console.log('🔌 Client connected');
+
+    // Send initial data immediately
+    sendAnalysis(ws);
+
+    ws.on('close', () => {
+        console.log('🔌 Client disconnected');
+    });
+
+    ws.on('error', (err) => {
+        console.error('WebSocket error:', err.message);
+    });
+});
+
+async function sendAnalysis(ws) {
+    try {
+        const result = await lens.analyze();
+        if (ws.readyState === 1) { // OPEN
+            ws.send(JSON.stringify(result));
+        }
+    } catch (error) {
+        console.error('Analysis error:', error.message);
+    }
+}
+
+function broadcastToAll() {
+    if (wss.clients.size === 0) return;
+
+    lens.analyze().then(result => {
+        const data = JSON.stringify(result);
+        wss.clients.forEach(client => {
+            if (client.readyState === 1) {
+                client.send(data);
+            }
+        });
+    }).catch(err => {
+        console.error('Broadcast error:', err.message);
+    });
+}
+
+// Start broadcasting when we have clients
+broadcastTimer = setInterval(broadcastToAll, BROADCAST_INTERVAL);
+
+// ─── Start Server ────────────────────────────────────────────────
+const PORT = process.env.PORT || 3777;
+
+server.listen(PORT, () => {
+    console.log(`
+  🔬 SystemLens Web Dashboard
+  ───────────────────────────
+  🌐 Dashboard: http://localhost:${PORT}
+  📡 API:       http://localhost:${PORT}/api/analyze
+  🔌 WebSocket: ws://localhost:${PORT}
+  
+  Press Ctrl+C to stop
+  `);
+});
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+    clearInterval(broadcastTimer);
+    wss.close();
+    server.close();
+    process.exit(0);
+});

package/src/analyzers/cpu.analyzer.js

@@ -0,0 +1,124 @@
+// ─── CPU Analyzer ────────────────────────────────────────────────
+// Analyzes CPU data and produces structured insights
+import { THRESHOLDS, SEVERITY } from '../utils/constants.js';
+
+export class CpuAnalyzer {
+    /**
+     * Analyze CPU data and return insights
+     * @param {Object} cpuData - From CpuCollector
+     * @param {Object|null} previousData - Previous snapshot for comparison
+     * @returns {Object} Analysis results
+     */
+    analyze(cpuData, previousData = null) {
+        const load = cpuData.load.overall;
+        const issues = [];
+        const insights = [];
+
+        // ── Severity classification ──
+        let severity;
+        if (load >= THRESHOLDS.CPU_HIGH) {
+            severity = SEVERITY.CRITICAL;
+            issues.push({
+                type: 'cpu_high',
+                severity: 'critical',
+                message: `CPU usage is critically high at ${load}%`,
+                value: load,
+            });
+        } else if (load >= THRESHOLDS.CPU_WARNING) {
+            severity = SEVERITY.WARNING;
+            issues.push({
+                type: 'cpu_warning',
+                severity: 'warning',
+                message: `CPU usage is elevated at ${load}%`,
+                value: load,
+            });
+        } else if (load >= THRESHOLDS.CPU_MODERATE) {
+            severity = SEVERITY.INFO;
+            insights.push({
+                type: 'cpu_moderate',
+                message: `CPU load is moderate at ${load}%`,
+                value: load,
+            });
+        } else {
+            severity = SEVERITY.OK;
+            insights.push({
+                type: 'cpu_ok',
+                message: `CPU usage is healthy at ${load}%`,
+                value: load,
+            });
+        }
+
+        // ── Core imbalance detection ──
+        const coreLoads = cpuData.load.perCore.map(c => c.load);
+        const maxCore = Math.max(...coreLoads);
+        const minCore = Math.min(...coreLoads);
+        const coreSpread = maxCore - minCore;
+
+        if (coreSpread > 50) {
+            issues.push({
+                type: 'core_imbalance',
+                severity: 'warning',
+                message: `Core load imbalance detected (spread: ${coreSpread.toFixed(0)}%). One core is heavily loaded while others are idle — possible single-threaded bottleneck.`,
+                value: coreSpread,
+            });
+        }
+
+        // ── System vs User load ──
+        const systemLoadRatio = cpuData.load.system / (load || 1);
+        if (systemLoadRatio > 0.5 && load > THRESHOLDS.CPU_MODERATE) {
+            insights.push({
+                type: 'system_heavy',
+                message: `System (kernel) tasks are consuming ${cpuData.load.system}% of CPU — this may indicate heavy I/O, driver activity, or system maintenance.`,
+                value: cpuData.load.system,
+            });
+        }
+
+        // ── Spike detection (compare with previous) ──
+        if (previousData) {
+            const prevLoad = previousData.load.overall;
+            const delta = load - prevLoad;
+
+            if (delta >= THRESHOLDS.SPIKE_THRESHOLD) {
+                issues.push({
+                    type: 'cpu_spike',
+                    severity: 'warning',
+                    message: `CPU usage spiked by ${delta.toFixed(1)}% (from ${prevLoad}% to ${load}%)`,
+                    value: delta,
+                    previousValue: prevLoad,
+                });
+            } else if (delta <= -THRESHOLDS.SPIKE_THRESHOLD) {
+                insights.push({
+                    type: 'cpu_drop',
+                    message: `CPU usage dropped by ${Math.abs(delta).toFixed(1)}% — load is settling down`,
+                    value: delta,
+                });
+            }
+        }
+
+        // ── Temperature insight ──
+        if (cpuData.temperature?.main && cpuData.temperature.main > 80) {
+            issues.push({
+                type: 'cpu_temp_high',
+                severity: 'warning',
+                message: `CPU temperature is high at ${cpuData.temperature.main}°C — may cause thermal throttling`,
+                value: cpuData.temperature.main,
+            });
+        }
+
+        return {
+            overall: load,
+            severity,
+            issues,
+            insights,
+            details: {
+                user: cpuData.load.user,
+                system: cpuData.load.system,
+                idle: cpuData.load.idle,
+                coreSpread,
+                maxCoreLoad: maxCore,
+                minCoreLoad: minCore,
+                temperature: cpuData.temperature?.main || null,
+            },
+        };
+    }
+}