systemlens 1.0.0

package/src/engines/suggestion.engine.js

@@ -0,0 +1,242 @@
+// ─── Suggestion Engine ───────────────────────────────────────────
+// Provides actionable, prioritized suggestions based on detected issues
+
+export class SuggestionEngine {
+    /**
+     * Generate prioritized suggestions based on analysis
+     * @param {Object} analysis - Full analysis results
+     * @param {Object} explanation - Explanation engine output
+     * @returns {Array} Prioritized list of suggestions
+     */
+    suggest(analysis, explanation) {
+        const suggestions = [];
+        const { cpu, memory, process: processAnalysis, devEnvironment, patterns } = analysis;
+
+        // ── CPU-related suggestions ──
+        if (cpu.overall >= 80) {
+            this._addCpuSuggestions(suggestions, cpu, processAnalysis);
+        }
+
+        // ── Memory-related suggestions ──
+        if (memory.usedPercent >= 70) {
+            this._addMemorySuggestions(suggestions, memory, processAnalysis);
+        }
+
+        // ── Process-specific suggestions ──
+        this._addProcessSuggestions(suggestions, processAnalysis);
+
+        // ── Browser suggestions ──
+        this._addBrowserSuggestions(suggestions, processAnalysis);
+
+        // ── Dev-specific suggestions ──
+        if (devEnvironment?.isDevActive) {
+            this._addDevSuggestions(suggestions, devEnvironment, processAnalysis);
+        }
+
+        // ── Pattern-based suggestions ──
+        if (patterns) {
+            this._addPatternSuggestions(suggestions, patterns);
+        }
+
+        // ── Swap suggestions ──
+        const swapIssue = memory.issues.find(i => i.type === 'swap_active');
+        if (swapIssue) {
+            suggestions.push({
+                priority: 1,
+                emoji: '💾',
+                category: 'Memory',
+                action: 'Close some applications to free up RAM',
+                reason: 'Your system is using swap (disk as memory replacement), which is extremely slow. Freeing up RAM will immediately improve performance.',
+                impact: 'high',
+            });
+        }
+
+        // ── Sort by priority ──
+        suggestions.sort((a, b) => a.priority - b.priority);
+
+        // Remove duplicates and limit
+        const seen = new Set();
+        const unique = suggestions.filter(s => {
+            const key = s.action;
+            if (seen.has(key)) return false;
+            seen.add(key);
+            return true;
+        });
+
+        return unique.slice(0, 8); // Max 8 suggestions to avoid overwhelming
+    }
+
+    _addCpuSuggestions(suggestions, cpu, processAnalysis) {
+        // Single process hogging CPU
+        const singleHog = processAnalysis.responsibilities.find(r => r.type === 'single_cpu_dominant');
+        if (singleHog) {
+            const proc = singleHog.process;
+            suggestions.push({
+                priority: 1,
+                emoji: '🎯',
+                category: 'CPU',
+                action: `Consider closing or restarting "${proc.name}" (PID: ${proc.pid})`,
+                reason: `It's consuming ${proc.cpu}% of your CPU, which is the primary cause of slowness.`,
+                impact: 'high',
+                processTarget: proc,
+            });
+        }
+
+        // Core imbalance
+        const coreIssue = cpu.issues.find(i => i.type === 'core_imbalance');
+        if (coreIssue) {
+            suggestions.push({
+                priority: 3,
+                emoji: '⚖️',
+                category: 'CPU',
+                action: 'Check for single-threaded intensive operations',
+                reason: 'One CPU core is much busier than others. If you\'re running a script or computation, consider if it can be parallelized.',
+                impact: 'medium',
+            });
+        }
+
+        // Temperature
+        const tempIssue = cpu.issues.find(i => i.type === 'cpu_temp_high');
+        if (tempIssue) {
+            suggestions.push({
+                priority: 2,
+                emoji: '🌡️',
+                category: 'Hardware',
+                action: 'Improve ventilation — ensure fans are unblocked and working',
+                reason: `CPU temperature is at ${tempIssue.value}°C. High heat causes throttling (reduced CPU speed) and can damage hardware over time.`,
+                impact: 'high',
+            });
+        }
+    }
+
+    _addMemorySuggestions(suggestions, memory, processAnalysis) {
+        const memHogs = processAnalysis.responsibilities.filter(r => r.type === 'memory_hog');
+
+        if (memHogs.length > 0) {
+            for (const hog of memHogs.slice(0, 3)) {
+                suggestions.push({
+                    priority: 2,
+                    emoji: '🧠',
+                    category: 'Memory',
+                    action: `Review "${hog.process.name}" — it's using ${hog.process.memRssFormatted} of memory`,
+                    reason: `This is a significant portion of your total RAM. If you're not actively using it, closing it will free up memory.`,
+                    impact: 'high',
+                    processTarget: hog.process,
+                });
+            }
+        }
+
+        if (memory.usedPercent >= 85) {
+            suggestions.push({
+                priority: 1,
+                emoji: '🚨',
+                category: 'Memory',
+                action: 'Urgently free up memory — close unused applications',
+                reason: 'Memory is critically low. The system will start using swap soon (or already is), causing major slowdowns.',
+                impact: 'critical',
+            });
+        }
+    }
+
+    _addProcessSuggestions(suggestions, processAnalysis) {
+        const distributed = processAnalysis.issues.find(i => i.type === 'distributed_load');
+        if (distributed) {
+            suggestions.push({
+                priority: 3,
+                emoji: '🔄',
+                category: 'System',
+                action: 'Review background applications — several are collectively causing load',
+                reason: `${distributed.processes.length} processes are each using a small amount of CPU, but together they add up. Check your startup applications and system tray.`,
+                impact: 'medium',
+            });
+        }
+    }
+
+    _addBrowserSuggestions(suggestions, processAnalysis) {
+        const browserIssue = processAnalysis.issues.find(i => i.type === 'browser_heavy');
+        if (browserIssue) {
+            suggestions.push({
+                priority: 2,
+                emoji: '🌐',
+                category: 'Browser',
+                action: 'Close unused browser tabs and disable heavy extensions',
+                reason: `Your browser is using significant resources. Browsers create multiple background processes per tab (for rendering, extensions, GPU, etc.), so even a few tabs can add up. Close tabs you're not actively using, especially video/streaming tabs.`,
+                impact: 'high',
+            });
+
+            suggestions.push({
+                priority: 4,
+                emoji: '🧩',
+                category: 'Browser',
+                action: 'Consider using a tab suspender extension',
+                reason: 'Extensions like "The Great Suspender" can automatically pause inactive tabs, significantly reducing memory and CPU usage.',
+                impact: 'medium',
+            });
+        }
+    }
+
+    _addDevSuggestions(suggestions, devEnvironment, processAnalysis) {
+        const devHighCpu = processAnalysis.insights.filter(i => i.type === 'dev_process_high_cpu');
+
+        for (const insight of devHighCpu) {
+            if (insight.process.cpu >= 80) {
+                suggestions.push({
+                    priority: 1,
+                    emoji: '🐛',
+                    category: 'Development',
+                    action: `Check your code for infinite loops or expensive operations — "${insight.process.name}" is using ${insight.process.cpu}% CPU`,
+                    reason: 'Very high CPU from a development process often indicates an infinite loop, uncontrolled recursion, or an expensive computation running repeatedly.',
+                    impact: 'critical',
+                });
+            } else if (insight.process.cpu >= 30) {
+                suggestions.push({
+                    priority: 3,
+                    emoji: '🔧',
+                    category: 'Development',
+                    action: `Restart your dev server if "${insight.process.name}" CPU usage (${insight.process.cpu}%) seems unusual`,
+                    reason: 'Dev servers can sometimes enter states of high CPU usage. A restart often resolves the issue.',
+                    impact: 'medium',
+                    processTarget: insight.process,
+                });
+            }
+        }
+
+        if (devEnvironment.hasHotReload) {
+            suggestions.push({
+                priority: 5,
+                emoji: '💡',
+                category: 'Development',
+                action: 'For faster builds, consider excluding large directories from file watching (e.g. node_modules)',
+                reason: 'Hot reload watches files for changes. The more files it tracks, the more CPU it uses. Configuring proper ignore patterns can reduce overhead.',
+                impact: 'low',
+            });
+        }
+    }
+
+    _addPatternSuggestions(suggestions, patterns) {
+        // Sustained high CPU
+        const sustainedCpu = patterns.cpu?.patterns?.find(p => p.type === 'sustained_high');
+        if (sustainedCpu && sustainedCpu.duration > 120000) {
+            suggestions.push({
+                priority: 2,
+                emoji: '⏱️',
+                category: 'Performance',
+                action: 'CPU has been high for an extended period — identify and address the root cause',
+                reason: `${sustainedCpu.message}. This isn't a temporary spike — something is consistently consuming resources.`,
+                impact: 'high',
+            });
+        }
+
+        // Rising memory trend
+        if (patterns.memory?.trend === 'rising') {
+            suggestions.push({
+                priority: 3,
+                emoji: '📈',
+                category: 'Memory',
+                action: 'Memory usage is gradually increasing — watch for memory leaks',
+                reason: 'If memory keeps climbing without you opening new apps, an application may have a memory leak. Restarting the application usually fixes it temporarily.',
+                impact: 'medium',
+            });
+        }
+    }
+}

package/src/history/history.tracker.js

@@ -0,0 +1,114 @@
+// ─── History Tracker ─────────────────────────────────────────────
+// Stores system snapshots over time for trend analysis
+import { HISTORY_MAX_ENTRIES } from '../utils/constants.js';
+
+export class HistoryTracker {
+    constructor() {
+        this.snapshots = [];
+        this.maxEntries = HISTORY_MAX_ENTRIES;
+    }
+
+    /**
+     * Record a system snapshot
+     * @param {Object} snapshot - { cpu, memory, processes, analysis, explanation }
+     */
+    record(snapshot) {
+        this.snapshots.push({
+            ...snapshot,
+            timestamp: Date.now(),
+        });
+
+        // Trim old entries
+        if (this.snapshots.length > this.maxEntries) {
+            this.snapshots = this.snapshots.slice(-this.maxEntries);
+        }
+    }
+
+    /**
+     * Get the most recent snapshot
+     * @returns {Object|null}
+     */
+    getLatest() {
+        return this.snapshots.length > 0
+            ? this.snapshots[this.snapshots.length - 1]
+            : null;
+    }
+
+    /**
+     * Get the previous snapshot (for comparison)
+     * @returns {Object|null}
+     */
+    getPrevious() {
+        return this.snapshots.length > 1
+            ? this.snapshots[this.snapshots.length - 2]
+            : null;
+    }
+
+    /**
+     * Get snapshots from the last N seconds
+     * @param {number} seconds
+     * @returns {Array}
+     */
+    getRecentSnapshots(seconds) {
+        const cutoff = Date.now() - (seconds * 1000);
+        return this.snapshots.filter(s => s.timestamp >= cutoff);
+    }
+
+    /**
+     * Get CPU history for charting
+     * @returns {Array<{time: number, value: number}>}
+     */
+    getCpuTimeline() {
+        return this.snapshots.map(s => ({
+            time: s.timestamp,
+            value: s.cpu?.load?.overall || 0,
+        }));
+    }
+
+    /**
+     * Get memory history for charting
+     * @returns {Array<{time: number, value: number}>}
+     */
+    getMemoryTimeline() {
+        return this.snapshots.map(s => ({
+            time: s.timestamp,
+            value: s.memory?.ram?.usedPercent || 0,
+        }));
+    }
+
+    /**
+     * Get a compact summary of all history
+     */
+    getSummary() {
+        if (this.snapshots.length === 0) return null;
+
+        const cpuValues = this.snapshots.map(s => s.cpu?.load?.overall || 0);
+        const memValues = this.snapshots.map(s => s.memory?.ram?.usedPercent || 0);
+
+        return {
+            totalSnapshots: this.snapshots.length,
+            timespan: this.snapshots.length > 1
+                ? this.snapshots[this.snapshots.length - 1].timestamp - this.snapshots[0].timestamp
+                : 0,
+            cpu: {
+                min: Math.min(...cpuValues),
+                max: Math.max(...cpuValues),
+                avg: parseFloat((cpuValues.reduce((s, v) => s + v, 0) / cpuValues.length).toFixed(1)),
+                current: cpuValues[cpuValues.length - 1],
+            },
+            memory: {
+                min: Math.min(...memValues),
+                max: Math.max(...memValues),
+                avg: parseFloat((memValues.reduce((s, v) => s + v, 0) / memValues.length).toFixed(1)),
+                current: memValues[memValues.length - 1],
+            },
+        };
+    }
+
+    /**
+     * Clear all history
+     */
+    clear() {
+        this.snapshots = [];
+    }
+}

package/src/index.js

@@ -0,0 +1,130 @@
+// ─── SystemLens Main Orchestrator ────────────────────────────────
+// Wires all layers together and provides the public API
+import { CpuCollector } from './collectors/cpu.collector.js';
+import { MemoryCollector } from './collectors/memory.collector.js';
+import { DiskCollector } from './collectors/disk.collector.js';
+import { ProcessCollector } from './collectors/process.collector.js';
+import { ProcessClassifier } from './classifiers/process.classifier.js';
+import { CpuAnalyzer } from './analyzers/cpu.analyzer.js';
+import { MemoryAnalyzer } from './analyzers/memory.analyzer.js';
+import { ProcessAnalyzer } from './analyzers/process.analyzer.js';
+import { SpikeDetector } from './analyzers/spike.detector.js';
+import { ExplanationEngine } from './engines/explanation.engine.js';
+import { SuggestionEngine } from './engines/suggestion.engine.js';
+import { AIEngine } from './engines/ai.engine.js';
+import { HistoryTracker } from './history/history.tracker.js';
+import { RealtimeMonitor } from './monitor/realtime.monitor.js';
+import { CliRenderer } from './renderer/cli.renderer.js';
+
+export class SystemLens {
+    constructor() {
+        // ── Data Collection Layer ──
+        this.collectors = {
+            cpu: new CpuCollector(),
+            memory: new MemoryCollector(),
+            disk: new DiskCollector(),
+            process: new ProcessCollector(),
+        };
+
+        // ── Classification Layer ──
+        this.classifier = new ProcessClassifier();
+
+        // ── Analysis Layer ──
+        this.analyzers = {
+            cpu: new CpuAnalyzer(),
+            memory: new MemoryAnalyzer(),
+            process: new ProcessAnalyzer(),
+        };
+
+        // ── Pattern Detection ──
+        this.spikeDetector = new SpikeDetector();
+
+        // ── Engine Layer ──
+        this.engines = {
+            explanation: new ExplanationEngine(),
+            suggestion: new SuggestionEngine(),
+            ai: new AIEngine(),
+        };
+
+        // ── History ──
+        this.historyTracker = new HistoryTracker();
+
+        // ── Rendering ──
+        this.renderer = new CliRenderer();
+
+        // ── Monitor ──
+        this.monitor = new RealtimeMonitor({
+            collectors: this.collectors,
+            classifier: this.classifier,
+            analyzers: this.analyzers,
+            spikeDetector: this.spikeDetector,
+            engines: this.engines,
+            historyTracker: this.historyTracker,
+            renderer: this.renderer,
+        });
+    }
+
+    /**
+     * Start real-time monitoring mode
+     */
+    async startMonitoring() {
+        await this.monitor.start();
+    }
+
+    /**
+     * Run a single analysis and print results
+     */
+    async runOnce() {
+        return await this.monitor.runOnce();
+    }
+
+    /**
+     * Get the raw analysis data (for API/web use)
+     */
+    async analyze() {
+        // Collect
+        const [cpuData, memData, diskData, processData] = await Promise.all([
+            this.collectors.cpu.collect(),
+            this.collectors.memory.collect(),
+            this.collectors.disk.collect(),
+            this.collectors.process.collect(),
+        ]);
+
+        // Classify
+        const classifiedProcesses = this.classifier.classifyAll(processData.all);
+        const devEnvironment = this.classifier.detectDevEnvironment(classifiedProcesses);
+
+        // Analyze
+        const prev = this.historyTracker.getPrevious();
+        const cpuAnalysis = this.analyzers.cpu.analyze(cpuData, prev?.cpu || null);
+        const memAnalysis = this.analyzers.memory.analyze(memData, prev?.memory || null);
+        const processAnalysis = this.analyzers.process.analyze(classifiedProcesses, cpuAnalysis, memAnalysis);
+        const patterns = this.spikeDetector.record(cpuAnalysis, memAnalysis);
+
+        const analysis = {
+            cpu: cpuAnalysis,
+            memory: memAnalysis,
+            process: processAnalysis,
+            patterns,
+            devEnvironment,
+            rawProcesses: {
+                topByCpu: classifiedProcesses.sort((a, b) => b.cpu - a.cpu).slice(0, 10),
+                topByMemory: [...classifiedProcesses].sort((a, b) => b.mem - a.mem).slice(0, 10),
+            },
+        };
+
+        const explanation = this.engines.explanation.explain(analysis);
+        const suggestions = this.engines.suggestion.suggest(analysis, explanation);
+
+        // Record
+        this.historyTracker.record({ cpu: cpuData, memory: memData, disk: diskData, processes: processData });
+
+        return {
+            analysis,
+            explanation,
+            suggestions,
+            snapshot: { cpu: cpuData, memory: memData, disk: diskData, processes: processData },
+            history: this.historyTracker.getSummary(),
+        };
+    }
+}

package/src/monitor/realtime.monitor.js

@@ -0,0 +1,145 @@
+// ─── Real-Time Monitor ───────────────────────────────────────────
+// Orchestrates continuous data collection, analysis, and rendering
+import { MONITORING_INTERVAL } from '../utils/constants.js';
+
+export class RealtimeMonitor {
+    constructor({ collectors, classifier, analyzers, spikeDetector, engines, historyTracker, renderer }) {
+        this.collectors = collectors;
+        this.classifier = classifier;
+        this.analyzers = analyzers;
+        this.spikeDetector = spikeDetector;
+        this.engines = engines;
+        this.historyTracker = historyTracker;
+        this.renderer = renderer;
+        this.intervalId = null;
+        this.isRunning = false;
+        this.cycleCount = 0;
+    }
+
+    /**
+     * Start the monitoring loop
+     */
+    async start() {
+        this.isRunning = true;
+
+        // Immediate first run
+        await this._cycle();
+
+        // Continuous monitoring
+        this.intervalId = setInterval(async () => {
+            if (!this.isRunning) return;
+            try {
+                await this._cycle();
+            } catch (error) {
+                console.error('Monitor cycle error:', error.message);
+            }
+        }, MONITORING_INTERVAL);
+
+        // Graceful shutdown
+        process.on('SIGINT', () => this.stop());
+        process.on('SIGTERM', () => this.stop());
+    }
+
+    /**
+     * Stop the monitoring loop
+     */
+    stop() {
+        this.isRunning = false;
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+        console.log('\n\n  👋 SystemLens stopped. Goodbye!\n');
+        process.exit(0);
+    }
+
+    /**
+     * Run a single collection + analysis + render cycle
+     */
+    async _cycle() {
+        this.cycleCount++;
+
+        // ─── 1. Collect Data ──────────────────────────────────
+        const [cpuData, memData, diskData, processData] = await Promise.all([
+            this.collectors.cpu.collect(),
+            this.collectors.memory.collect(),
+            this.collectors.disk.collect(),
+            this.collectors.process.collect(),
+        ]);
+
+        // ─── 2. Classify Processes ────────────────────────────
+        const classifiedProcesses = this.classifier.classifyAll(processData.all);
+        const devEnvironment = this.classifier.detectDevEnvironment(classifiedProcesses);
+
+        // ─── 3. Get Previous Data for Comparison ──────────────
+        const prev = this.historyTracker.getPrevious();
+        const previousCpu = prev?.cpu || null;
+        const previousMem = prev?.memory || null;
+
+        // ─── 4. Analyze ───────────────────────────────────────
+        const cpuAnalysis = this.analyzers.cpu.analyze(cpuData, previousCpu);
+        const memAnalysis = this.analyzers.memory.analyze(memData, previousMem);
+        const processAnalysis = this.analyzers.process.analyze(classifiedProcesses, cpuAnalysis, memAnalysis);
+
+        // ─── 5. Detect Patterns ───────────────────────────────
+        const patterns = this.spikeDetector.record(cpuAnalysis, memAnalysis);
+
+        // ─── 6. Build Full Analysis Object ────────────────────
+        const analysis = {
+            cpu: cpuAnalysis,
+            memory: memAnalysis,
+            process: processAnalysis,
+            patterns,
+            devEnvironment,
+            rawProcesses: {
+                topByCpu: classifiedProcesses.sort((a, b) => b.cpu - a.cpu).slice(0, 10),
+                topByMemory: [...classifiedProcesses].sort((a, b) => b.mem - a.mem).slice(0, 10),
+            },
+        };
+
+        // ─── 7. Generate Explanation ──────────────────────────
+        const explanation = this.engines.explanation.explain(analysis);
+
+        // ─── 8. Generate Suggestions ──────────────────────────
+        const suggestions = this.engines.suggestion.suggest(analysis, explanation);
+
+        // ─── 9. AI Enhancement (every 5th cycle) ──────────────
+        let aiInsights = null;
+        if (this.cycleCount % 5 === 0 && this.engines.ai?.isAvailable()) {
+            aiInsights = await this.engines.ai.enhance(analysis, explanation);
+        }
+
+        // ─── 10. Record History ───────────────────────────────
+        this.historyTracker.record({
+            cpu: cpuData,
+            memory: memData,
+            disk: diskData,
+            processes: processData,
+        });
+
+        // ─── 11. Render ───────────────────────────────────────
+        const report = {
+            analysis,
+            explanation,
+            suggestions,
+            aiInsights,
+            snapshot: {
+                cpu: cpuData,
+                memory: memData,
+                disk: diskData,
+                processes: processData,
+            },
+        };
+
+        this.renderer.render(report);
+
+        return report;
+    }
+
+    /**
+     * Run a single analysis (non-monitoring mode)
+     */
+    async runOnce() {
+        return await this._cycle();
+    }
+}