systemlens 1.0.0

package/src/collectors/process.collector.js

@@ -0,0 +1,65 @@
+// ─── Process Data Collector ──────────────────────────────────────
+import si from 'systeminformation';
+import pidusage from 'pidusage';
+import { TOP_PROCESSES_COUNT } from '../utils/constants.js';
+import { formatBytes } from '../utils/helpers.js';
+
+export class ProcessCollector {
+    /**
+     * Collect top processes by CPU and memory usage
+     * @returns {Object} Process list sorted by resource usage
+     */
+    async collect() {
+        const processes = await si.processes();
+
+        const allProcs = processes.list || [];
+
+        // Sort by CPU usage descending
+        const byCpu = [...allProcs]
+            .sort((a, b) => (b.cpu || 0) - (a.cpu || 0))
+            .slice(0, TOP_PROCESSES_COUNT * 2); // Get extra for deduplication
+
+        // Sort by memory usage descending
+        const byMem = [...allProcs]
+            .sort((a, b) => (b.mem || 0) - (a.mem || 0))
+            .slice(0, TOP_PROCESSES_COUNT * 2);
+
+        // Merge and deduplicate
+        const seenPids = new Set();
+        const topProcesses = [];
+
+        for (const proc of [...byCpu, ...byMem]) {
+            if (seenPids.has(proc.pid)) continue;
+            seenPids.add(proc.pid);
+
+            topProcesses.push({
+                pid: proc.pid,
+                parentPid: proc.parentPid,
+                name: proc.name || 'unknown',
+                command: proc.command || '',
+                cpu: parseFloat((proc.cpu || 0).toFixed(1)),
+                mem: parseFloat((proc.mem || 0).toFixed(1)),
+                memRss: proc.memRss ? proc.memRss * 1024 : 0, // Convert KB to bytes
+                memRssFormatted: proc.memRss ? formatBytes(proc.memRss * 1024) : '0 B',
+                state: proc.state || 'unknown',
+                started: proc.started || '',
+                user: proc.user || 'unknown',
+                path: proc.path || '',
+            });
+        }
+
+        // Re-sort the merged list by CPU
+        topProcesses.sort((a, b) => b.cpu - a.cpu);
+
+        return {
+            total: processes.all || 0,
+            running: processes.running || 0,
+            sleeping: processes.sleeping || 0,
+            blocked: processes.blocked || 0,
+            topByCpu: topProcesses.slice(0, TOP_PROCESSES_COUNT),
+            topByMemory: [...topProcesses].sort((a, b) => b.mem - a.mem).slice(0, TOP_PROCESSES_COUNT),
+            all: topProcesses,
+            timestamp: Date.now(),
+        };
+    }
+}

package/src/engines/ai.engine.js

@@ -0,0 +1,105 @@
+// ─── AI Explanation Engine ───────────────────────────────────────
+// Enhances rule-based explanations with AI-powered insights
+import OpenAI from 'openai';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export class AIEngine {
+    constructor() {
+        this.enabled = !!process.env.OPENAI_API_KEY;
+        this.client = this.enabled ? new OpenAI({ apiKey: process.env.OPENAI_API_KEY }) : null;
+        this.lastAICall = 0;
+        this.cooldownMs = 15000; // Rate limit: max 1 AI call per 15 seconds
+    }
+
+    /**
+     * Check if AI engine is available
+     */
+    isAvailable() {
+        return this.enabled && this.client !== null;
+    }
+
+    /**
+     * Generate AI-enhanced explanation
+     * @param {Object} analysis - Full system analysis
+     * @param {Object} explanation - Rule-based explanation
+     * @returns {Object|null} AI insights or null if unavailable/cooldown
+     */
+    async enhance(analysis, explanation) {
+        if (!this.isAvailable()) return null;
+
+        // Enforce cooldown to avoid excessive API calls
+        const now = Date.now();
+        if (now - this.lastAICall < this.cooldownMs) return null;
+
+        try {
+            this.lastAICall = now;
+
+            const prompt = this._buildPrompt(analysis, explanation);
+
+            const response = await this.client.chat.completions.create({
+                model: 'gpt-4o-mini',
+                messages: [
+                    {
+                        role: 'system',
+                        content: `You are an expert systems engineer who explains computer behavior to users in simple, clear language. You are SystemLens — a tool that helps people understand why their computer is behaving the way it is. Be concise but insightful. Focus on "why" not just "what". Use analogies when helpful. Never use jargon without explaining it. Your response must be in JSON format with keys: "deepInsight" (a deeper explanation), "prediction" (what might happen next), "proTip" (a power-user tip).`,
+                    },
+                    {
+                        role: 'user',
+                        content: prompt,
+                    },
+                ],
+                max_tokens: 400,
+                temperature: 0.7,
+                response_format: { type: 'json_object' },
+            });
+
+            const content = response.choices[0]?.message?.content;
+            if (!content) return null;
+
+            const parsed = JSON.parse(content);
+
+            return {
+                deepInsight: parsed.deepInsight || null,
+                prediction: parsed.prediction || null,
+                proTip: parsed.proTip || null,
+                source: 'ai',
+                model: 'gpt-4o-mini',
+            };
+        } catch (error) {
+            // Silently fail — AI is enhancement, not critical
+            return null;
+        }
+    }
+
+    /**
+     * Build a structured prompt for the AI
+     */
+    _buildPrompt(analysis, explanation) {
+        const { cpu, memory, process: pa } = analysis;
+
+        const data = {
+            cpuUsage: `${cpu.overall}%`,
+            cpuSeverity: cpu.severity.label,
+            memoryUsage: `${memory.usedPercent}%`,
+            memorySeverity: memory.severity.label,
+            totalProcesses: pa.summary.totalProcesses,
+            systemHealth: explanation.health.status,
+            headline: explanation.headline,
+            topIssues: [...cpu.issues, ...memory.issues, ...pa.issues].map(i => i.message).slice(0, 5),
+            topProcesses: analysis.rawProcesses?.topByCpu?.slice(0, 5).map(p => ({
+                name: p.name,
+                cpu: `${p.cpu}%`,
+                mem: `${p.mem}%`,
+                category: p.classification?.label || 'Unknown',
+            })) || [],
+            patterns: analysis.patterns ? {
+                cpuTrend: analysis.patterns.cpu?.trend,
+                memTrend: analysis.patterns.memory?.trend,
+            } : null,
+        };
+
+        return `Here is the current system state:\n${JSON.stringify(data, null, 2)}\n\nProvide a deeper insight, prediction, and pro tip in JSON format.`;
+    }
+}

package/src/engines/explanation.engine.js

@@ -0,0 +1,348 @@
+// ─── Explanation Engine ──────────────────────────────────────────
+// The CORE DIFFERENTIATOR: converts analysis into human-readable explanations
+// Thinks like a senior engineer explaining to a beginner
+
+export class ExplanationEngine {
+    /**
+     * Generate a full system explanation from all analysis results
+     * @param {Object} analysis - Combined analysis results
+     * @returns {Object} Human-readable explanation
+     */
+    explain(analysis) {
+        const { cpu, memory, process: processAnalysis, patterns, devEnvironment } = analysis;
+
+        const systemHealth = this._assessOverallHealth(cpu, memory);
+        const mainExplanation = this._buildMainExplanation(cpu, memory, processAnalysis);
+        const causeEffect = this._buildCauseEffect(cpu, memory, processAnalysis);
+        const devInsights = this._buildDevInsights(devEnvironment, processAnalysis);
+        const patternNarrative = this._buildPatternNarrative(patterns);
+
+        return {
+            health: systemHealth,
+            headline: this._generateHeadline(cpu, memory, processAnalysis),
+            explanation: mainExplanation,
+            causeAndEffect: causeEffect,
+            devInsights,
+            patternNarrative,
+            timestamp: Date.now(),
+        };
+    }
+
+    /**
+     * Assess overall system health in human terms
+     */
+    _assessOverallHealth(cpu, memory) {
+        const cpuLoad = cpu.overall;
+        const memUsed = memory.usedPercent;
+
+        // Combined health score (weighted: CPU 60%, Memory 40%)
+        const healthScore = (cpuLoad * 0.6) + (memUsed * 0.4);
+
+        if (healthScore < 30) {
+            return {
+                status: 'excellent',
+                emoji: '🟢',
+                label: 'System Healthy',
+                description: 'Your system is running smoothly. All resources are well within normal limits.',
+            };
+        } else if (healthScore < 55) {
+            return {
+                status: 'good',
+                emoji: '🟡',
+                label: 'Lightly Loaded',
+                description: 'Your system has some load but is handling it fine. No action needed.',
+            };
+        } else if (healthScore < 75) {
+            return {
+                status: 'stressed',
+                emoji: '🟠',
+                label: 'Under Pressure',
+                description: 'Your system is working hard. You may notice some slowness. Consider closing unnecessary apps.',
+            };
+        } else {
+            return {
+                status: 'critical',
+                emoji: '🔴',
+                label: 'System Struggling',
+                description: 'Your system is under heavy load. Performance is likely degraded. Immediate action recommended.',
+            };
+        }
+    }
+
+    /**
+     * Generate a concise headline for the current state
+     */
+    _generateHeadline(cpu, memory, processAnalysis) {
+        const cpuLoad = cpu.overall;
+        const memUsed = memory.usedPercent;
+        const issues = [...cpu.issues, ...memory.issues, ...processAnalysis.issues];
+
+        if (issues.length === 0) {
+            return '✨ Everything looks great — your system is running efficiently.';
+        }
+
+        // Single dominant process
+        if (processAnalysis.primaryCause === 'single_process' && processAnalysis.responsibilities.length > 0) {
+            const resp = processAnalysis.responsibilities[0];
+            return `⚠️ ${resp.process.name} is dominating your system resources (${resp.process.cpu}% CPU).`;
+        }
+
+        // Multiple hogs
+        if (processAnalysis.primaryCause === 'multiple_processes') {
+            return `⚠️ Several processes are competing for resources, causing system strain.`;
+        }
+
+        // Distributed load
+        if (processAnalysis.primaryCause === 'distributed') {
+            return `⚠️ Many background processes are collectively putting pressure on your system.`;
+        }
+
+        // CPU-specific
+        if (cpuLoad >= 80) {
+            return `🔴 CPU usage is critically high at ${cpuLoad}% — your system is likely slow right now.`;
+        }
+
+        // Memory-specific
+        if (memUsed >= 80) {
+            return `🔴 Memory is nearly full at ${memUsed}% — your system may start swapping and freezing.`;
+        }
+
+        if (cpuLoad >= 60 || memUsed >= 60) {
+            return `🟡 System is under moderate load — CPU at ${cpuLoad}%, Memory at ${memUsed}%.`;
+        }
+
+        return `ℹ️ Minor issues detected but system is generally stable.`;
+    }
+
+    /**
+     * Build the main explanation paragraph
+     */
+    _buildMainExplanation(cpu, memory, processAnalysis) {
+        const paragraphs = [];
+        const cpuLoad = cpu.overall;
+        const memUsed = memory.usedPercent;
+
+        // ── Opening context ──
+        if (cpuLoad >= 80 && memUsed >= 80) {
+            paragraphs.push(
+                `Your system is under heavy pressure on both CPU and memory. CPU usage is at ${cpuLoad}% and memory is at ${memUsed}%. This combination means your computer is struggling to keep up — you'll notice slow app launches, delayed responses, and possibly temporary freezes.`
+            );
+        } else if (cpuLoad >= 80) {
+            paragraphs.push(
+                `Your CPU is working very hard at ${cpuLoad}% usage. This means your processor — the brain of your computer — is nearly at capacity. You'll likely experience sluggish performance, laggy mouse movements, and slow application responses.`
+            );
+        } else if (memUsed >= 80) {
+            paragraphs.push(
+                `Your memory (RAM) is nearly full at ${memUsed}%. RAM is like your computer's short-term workspace — when it fills up, the computer starts using your hard drive as overflow storage (called "swap"), which is dramatically slower. This causes significant slowdowns.`
+            );
+        } else if (cpuLoad >= 60 || memUsed >= 60) {
+            paragraphs.push(
+                `Your system is moderately loaded. CPU is at ${cpuLoad}% and memory at ${memUsed}%. This isn't critical, but if more applications are opened, performance could start degrading.`
+            );
+        } else {
+            paragraphs.push(
+                `Your system is running efficiently. CPU and memory usage are well within normal limits. Your computer has plenty of capacity for additional work.`
+            );
+        }
+
+        // ── Process responsibility explanation ──
+        if (processAnalysis.responsibilities.length > 0) {
+            const respExplanations = processAnalysis.responsibilities.map(r => {
+                if (r.type === 'single_cpu_dominant') {
+                    return `The process "${r.process.name}" is the primary resource consumer, using ${r.process.cpu}% of your CPU. ${this._getProcessContext(r.process)}`;
+                }
+                if (r.type === 'multiple_cpu_hogs') {
+                    return `Multiple processes are competing for CPU: ${r.processes.map(p => `"${p.name}" (${p.cpu}%)`).join(', ')}. This competition for processor time is slowing everything down.`;
+                }
+                if (r.type === 'memory_hog') {
+                    return `"${r.process.name}" is using a large amount of memory (${r.process.memRssFormatted}). ${this._getMemoryContext(r.process)}`;
+                }
+                return r.message;
+            });
+
+            paragraphs.push(respExplanations.join(' '));
+        }
+
+        // ── Core imbalance explanation ──
+        const coreIssue = cpu.issues.find(i => i.type === 'core_imbalance');
+        if (coreIssue) {
+            paragraphs.push(
+                `Interestingly, your CPU cores are not sharing the work evenly. One core is much busier than the others. This usually means a single program is doing intensive work that can't be split across multiple cores — like a single-threaded calculation, file compression, or a tight loop.`
+            );
+        }
+
+        return paragraphs.join('\n\n');
+    }
+
+    /**
+     * Build cause-and-effect chains
+     */
+    _buildCauseEffect(cpu, memory, processAnalysis) {
+        const chains = [];
+
+        // Browser causing high memory
+        const browserIssue = processAnalysis.issues.find(i => i.type === 'browser_heavy');
+        if (browserIssue && memory.usedPercent >= 60) {
+            const estimatedTabs = browserIssue.estimatedTabs || Math.round(browserIssue.processes.length / 2);
+            chains.push({
+                cause: `Browser with ~${estimatedTabs} open tabs using significant resources`,
+                effect: `Using ${browserIssue.processes.reduce((s, p) => s + p.mem, 0).toFixed(1)}% memory and ${browserIssue.processes.reduce((s, p) => s + p.cpu, 0).toFixed(1)}% CPU`,
+                consequence: 'System memory pressure and possible sluggishness across all apps',
+                emoji: '🌐',
+            });
+        }
+
+        // Distributed load
+        const distributedIssue = processAnalysis.issues.find(i => i.type === 'distributed_load');
+        if (distributedIssue) {
+            chains.push({
+                cause: `${distributedIssue.processes.length} background processes running simultaneously`,
+                effect: `Collectively consuming ${distributedIssue.processes.reduce((s, p) => s + p.cpu, 0).toFixed(1)}% CPU`,
+                consequence: 'No single process to blame, but the combined load is significant. Like traffic — each car isn\'t the problem, but together they cause gridlock.',
+                emoji: '🔄',
+            });
+        }
+
+        // Swap active
+        const swapIssue = memory.issues.find(i => i.type === 'swap_active');
+        if (swapIssue) {
+            chains.push({
+                cause: 'RAM is full — too many applications consuming memory',
+                effect: 'System is using swap (disk as memory)',
+                consequence: 'Significant performance degradation — disk is 100-1000x slower than RAM. You\'ll notice freezes and delays.',
+                emoji: '💾',
+            });
+        }
+
+        // High CPU temp
+        const tempIssue = cpu.issues.find(i => i.type === 'cpu_temp_high');
+        if (tempIssue) {
+            chains.push({
+                cause: 'CPU is running at high temperature',
+                effect: 'Processor may throttle (reduce speed) to prevent damage',
+                consequence: 'Even with available CPU capacity, performance may be capped by thermal limits. Ensure good ventilation.',
+                emoji: '🌡️',
+            });
+        }
+
+        return chains;
+    }
+
+    /**
+     * Build developer-specific insights
+     */
+    _buildDevInsights(devEnvironment, processAnalysis) {
+        if (!devEnvironment?.isDevActive) return null;
+
+        const insights = [];
+
+        if (devEnvironment.hasHotReload) {
+            const devHighCpu = processAnalysis.insights.filter(i => i.type === 'dev_process_high_cpu');
+            if (devHighCpu.length > 0) {
+                insights.push({
+                    emoji: '🔥',
+                    insight: 'Development server with hot reload detected. Hot reload watches for file changes and rebuilds — this is CPU-intensive during saves, especially with large projects.',
+                    actionable: true,
+                });
+            } else {
+                insights.push({
+                    emoji: '🔄',
+                    insight: 'Development server with hot reload is running. Normal CPU usage detected — no concerns.',
+                    actionable: false,
+                });
+            }
+        }
+
+        if (devEnvironment.hasNodeServer) {
+            insights.push({
+                emoji: '🟢',
+                insight: 'Node.js development server is running. If CPU usage is unexpectedly high, check for: infinite loops, unoptimized database queries, or memory leaks in your code.',
+                actionable: true,
+            });
+        }
+
+        if (devEnvironment.hasTests) {
+            insights.push({
+                emoji: '🧪',
+                insight: 'Test runner detected. Test suites can be CPU-intensive, especially with large test files or file-watching mode. This is expected behavior.',
+                actionable: false,
+            });
+        }
+
+        if (devEnvironment.editorActive) {
+            insights.push({
+                emoji: '📝',
+                insight: `Code editor is active. Modern editors with extensions (TypeScript, ESLint, Prettier) can use significant CPU during indexing and code analysis.`,
+                actionable: false,
+            });
+        }
+
+        return insights.length > 0 ? insights : null;
+    }
+
+    /**
+     * Build pattern narrative from spike detector results
+     */
+    _buildPatternNarrative(patterns) {
+        if (!patterns) return null;
+
+        const narratives = [];
+
+        // CPU patterns
+        if (patterns.cpu) {
+            if (patterns.cpu.trend === 'rising') {
+                narratives.push('📈 CPU usage has been trending upward — something is gradually consuming more processing power.');
+            } else if (patterns.cpu.trend === 'falling') {
+                narratives.push('📉 CPU usage is decreasing — the system is settling down from a period of high activity.');
+            }
+
+            for (const pattern of patterns.cpu.patterns) {
+                narratives.push(`⚡ ${pattern.message}`);
+            }
+        }
+
+        // Memory patterns
+        if (patterns.memory) {
+            if (patterns.memory.trend === 'rising') {
+                narratives.push('📈 Memory usage has been climbing — applications may be accumulating data or leaking memory.');
+            }
+
+            for (const pattern of patterns.memory.patterns) {
+                narratives.push(`⚡ ${pattern.message}`);
+            }
+        }
+
+        return narratives.length > 0 ? narratives : null;
+    }
+
+    /**
+     * Get human-friendly context for a process
+     */
+    _getProcessContext(process) {
+        const cat = process.classification;
+        if (cat.isBrowser) {
+            return 'Browsers can be heavy — especially with many tabs, video playback, or web apps like Google Docs.';
+        }
+        if (cat.isDev) {
+            return 'This is a development tool — it may be compiling code, running a dev server, or performing file watching.';
+        }
+        if (cat.isSystem) {
+            return 'This is a system process — it handles internal OS operations. If it\'s consistently high, it may indicate driver issues or system maintenance.';
+        }
+        return '';
+    }
+
+    /**
+     * Get memory context for a process
+     */
+    _getMemoryContext(process) {
+        const cat = process.classification;
+        if (cat.isBrowser) {
+            return 'Each browser tab uses its own pool of memory. Tabs with rich content (videos, complex web apps) use more.';
+        }
+        if (cat.isDev) {
+            return 'Development tools often load large project files into memory. Node.js applications may also accumulate memory during development (memory leaks).';
+        }
+        return 'This process has allocated a large amount of memory. If it continues to grow, it may indicate a memory leak.';
+    }
+}