node-loop-detective 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,124 @@
+# node-loop-detective 🔍
+
+Detect event loop blocking & lag in **running** Node.js apps — without code changes or restarts.
+
+```
+$ loop-detective 12345
+
+✔ Connected to Node.js process
+  Profiling for 10s with 50ms lag threshold...
+
+⚠ Event loop lag: 312ms at 2025-01-15T10:23:45.123Z
+⚠ Event loop lag: 156ms at 2025-01-15T10:23:48.456Z
+
+────────────────────────────────────────────────────────────
+  Event Loop Detective Report
+────────────────────────────────────────────────────────────
+  Duration:  10023ms
+  Samples:   4521
+  Hot funcs: 12
+
+  Diagnosis
+────────────────────────────────────────────────────────────
+   HIGH  cpu-hog
+         Function "heavyComputation" consumed 62.3% of CPU time (6245ms)
+         at /app/server.js:42
+         → Consider breaking this into smaller async chunks or moving to a worker thread
+
+   1. heavyComputation
+      ██████████████░░░░░░ 6245ms (62.3%)
+      /app/server.js:42:1
+```
+
+## How It Works
+
+1. Sends `SIGUSR1` to activate the Node.js built-in inspector (or connects to `--port`)
+2. Connects via Chrome DevTools Protocol (CDP)
+3. Injects a lightweight event loop lag monitor
+4. Captures a CPU profile to identify blocking code
+5. Analyzes the profile for common blocking patterns
+6. Disconnects cleanly — minimal impact on your running app
+
+## Install
+
+```bash
+npm install -g node-loop-detective
+```
+
+## Usage
+
+```bash
+# Basic: profile a running Node.js process by PID
+loop-detective <pid>
+
+# Connect to an already-open inspector port
+loop-detective --port 9229
+
+# Profile for 30 seconds with 100ms lag threshold
+loop-detective -p 12345 -d 30 -t 100
+
+# Continuous monitoring mode
+loop-detective -p 12345 --watch
+
+# JSON output (for piping to other tools)
+loop-detective -p 12345 --json
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --pid <pid>` | Target Node.js process ID | — |
+| `-P, --port <port>` | Inspector port (skip SIGUSR1) | — |
+| `-d, --duration <sec>` | Profiling duration in seconds | 10 |
+| `-t, --threshold <ms>` | Event loop lag threshold | 50 |
+| `-i, --interval <ms>` | Lag sampling interval | 100 |
+| `-j, --json` | Output as JSON | false |
+| `-w, --watch` | Continuous monitoring | false |
+
+## What It Detects
+
+| Pattern | Description |
+|---------|-------------|
+| `cpu-hog` | Single function consuming >50% CPU |
+| `json-heavy` | Excessive JSON parse/stringify |
+| `regex-heavy` | RegExp backtracking |
+| `gc-pressure` | High garbage collection time |
+| `sync-io` | Synchronous file I/O calls |
+| `crypto-heavy` | CPU-intensive crypto operations |
+
+## Programmatic API
+
+```js
+const { Detective } = require('node-loop-detective');
+
+const detective = new Detective({
+  pid: 12345,
+  duration: 10000,
+  threshold: 50,
+  interval: 100,
+});
+
+detective.on('lag', (data) => console.log('Lag:', data.lag, 'ms'));
+detective.on('profile', (analysis) => {
+  console.log('Heavy functions:', analysis.heavyFunctions);
+  console.log('Patterns:', analysis.blockingPatterns);
+});
+
+await detective.start();
+```
+
+## Requirements
+
+- Node.js >= 16
+- Target process must be running Node.js
+- On Linux/macOS: permission to send signals to the target process
+- On Windows: target must be started with `--inspect` flag (SIGUSR1 not available)
+
+## How is this different from clinic.js / 0x?
+
+Those are great tools, but they require you to **start** your app through them. `loop-detective` attaches to an **already running** process — perfect for production debugging.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { parseArgs } = require('node:util');
+const { Detective } = require('../src/detective');
+const { Reporter } = require('../src/reporter');
+
+const options = {
+  pid: { type: 'string', short: 'p' },
+  port: { type: 'string', short: 'P', default: '' },
+  duration: { type: 'string', short: 'd', default: '10' },
+  threshold: { type: 'string', short: 't', default: '50' },
+  interval: { type: 'string', short: 'i', default: '100' },
+  json: { type: 'boolean', short: 'j', default: false },
+  watch: { type: 'boolean', short: 'w', default: false },
+  help: { type: 'boolean', short: 'h', default: false },
+  version: { type: 'boolean', short: 'v', default: false },
+};
+
+let parsed;
+try {
+  parsed = parseArgs({ options, allowPositionals: true });
+} catch (err) {
+  console.error(`Error: ${err.message}\n`);
+  printUsage();
+  process.exit(1);
+}
+
+const { values, positionals } = parsed;
+
+if (values.version) {
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (values.help) {
+  printUsage();
+  process.exit(0);
+}
+
+const pid = values.pid || positionals[0];
+const inspectorPort = values.port ? parseInt(values.port, 10) : null;
+
+if (!pid && !inspectorPort) {
+  console.error('Error: Please provide a target PID or --port\n');
+  printUsage();
+  process.exit(1);
+}
+
+function printUsage() {
+  console.log(`
+  loop-detective - Detect event loop blocking in running Node.js apps
+
+  USAGE
+    loop-detective <pid>
+    loop-detective --pid <pid>
+    loop-detective --port <inspector-port>
+
+  OPTIONS
+    -p, --pid <pid>          Target Node.js process ID
+    -P, --port <port>        Connect to an already-open inspector port
+    -d, --duration <sec>     Profiling duration in seconds (default: 10)
+    -t, --threshold <ms>     Event loop lag threshold in ms (default: 50)
+    -i, --interval <ms>      Sampling interval in ms (default: 100)
+    -j, --json               Output results as JSON
+    -w, --watch              Continuous monitoring mode
+    -h, --help               Show this help
+    -v, --version            Show version
+
+  EXAMPLES
+    loop-detective 12345
+    loop-detective --pid 12345 --duration 30 --threshold 100
+    loop-detective --port 9229 --watch
+    loop-detective -p 12345 -d 5 -j
+
+  HOW IT WORKS
+    1. Sends SIGUSR1 to activate the Node.js inspector (or connects to --port)
+    2. Connects via Chrome DevTools Protocol (CDP)
+    3. Profiles CPU usage and monitors event loop lag
+    4. Reports blocking functions with file locations and durations
+    5. Disconnects cleanly — zero impact on your running app
+  `);
+}
+
+async function main() {
+  const config = {
+    pid: pid ? parseInt(pid, 10) : null,
+    inspectorPort,
+    duration: parseInt(values.duration, 10) * 1000,
+    threshold: parseInt(values.threshold, 10),
+    interval: parseInt(values.interval, 10),
+    watch: values.watch,
+    json: values.json,
+  };
+
+  const reporter = new Reporter(config);
+  const detective = new Detective(config);
+
+  detective.on('connected', () => reporter.onConnected());
+  detective.on('lag', (data) => reporter.onLag(data));
+  detective.on('profile', (data) => reporter.onProfile(data));
+  detective.on('error', (err) => reporter.onError(err));
+  detective.on('disconnected', () => reporter.onDisconnected());
+
+  process.on('SIGINT', async () => {
+    reporter.onInfo('Shutting down...');
+    await detective.stop();
+    process.exit(0);
+  });
+
+  try {
+    await detective.start();
+  } catch (err) {
+    reporter.onError(err);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "node-loop-detective",
+  "version": "1.0.0",
+  "description": "Detect event loop blocking & lag in running Node.js apps without code changes or restarts",
+  "main": "src/index.js",
+  "bin": {
+    "loop-detective": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "nodejs",
+    "event-loop",
+    "blocking",
+    "lag",
+    "diagnostics",
+    "profiler",
+    "inspector",
+    "performance",
+    "debugging"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iwtxokhtd83/node-loop-detective.git"
+  },
+  "homepage": "https://github.com/iwtxokhtd83/node-loop-detective#readme",
+  "bugs": {
+    "url": "https://github.com/iwtxokhtd83/node-loop-detective/issues"
+  },
+  "dependencies": {
+    "ws": "^8.16.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/analyzer.js

@@ -0,0 +1,247 @@
+'use strict';
+
+class Analyzer {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Analyze a V8 CPU profile to find blocking functions
+   *
+   * V8 CPU profile format:
+   * - nodes: array of { id, callFrame: { functionName, url, lineNumber, columnNumber }, hitCount, children }
+   * - startTime, endTime: microseconds
+   * - samples: array of node IDs (sampled at each tick)
+   * - timeDeltas: array of time deltas between samples (microseconds)
+   */
+  analyzeProfile(profile) {
+    const { nodes, samples, timeDeltas, startTime, endTime } = profile;
+
+    const nodeMap = new Map();
+    for (const node of nodes) {
+      nodeMap.set(node.id, node);
+    }
+
+    // Calculate total time per node
+    const timings = new Map();
+    for (let i = 0; i < samples.length; i++) {
+      const nodeId = samples[i];
+      const delta = timeDeltas[i] || 0;
+      timings.set(nodeId, (timings.get(nodeId) || 0) + delta);
+    }
+
+    // Build results: find heavy functions
+    const totalDuration = endTime - startTime; // microseconds
+    const heavyFunctions = [];
+
+    for (const [nodeId, selfTime] of timings) {
+      const node = nodeMap.get(nodeId);
+      if (!node) continue;
+
+      const { functionName, url, lineNumber, columnNumber } = node.callFrame;
+
+      // Skip internal/idle nodes
+      if (!url && !functionName) continue;
+      if (functionName === '(idle)' || functionName === '(program)') continue;
+      if (functionName === '(garbage collector)') {
+        // GC is interesting — keep it
+      }
+
+      const selfTimeMs = selfTime / 1000;
+      const percentage = totalDuration > 0 ? (selfTime / totalDuration) * 100 : 0;
+
+      if (selfTimeMs < 1) continue; // skip trivial entries
+
+      heavyFunctions.push({
+        functionName: functionName || '(anonymous)',
+        url: url || '(native)',
+        lineNumber: lineNumber + 1, // V8 uses 0-based
+        columnNumber: columnNumber + 1,
+        selfTimeMs: Math.round(selfTimeMs * 100) / 100,
+        percentage: Math.round(percentage * 100) / 100,
+      });
+    }
+
+    // Sort by self time descending
+    heavyFunctions.sort((a, b) => b.selfTimeMs - a.selfTimeMs);
+
+    // Build call tree for the top blockers
+    const callStacks = this._buildCallStacks(nodeMap, timings, heavyFunctions.slice(0, 5));
+
+    // Detect event loop blocking patterns
+    const blockingPatterns = this._detectPatterns(heavyFunctions, profile);
+
+    return {
+      summary: {
+        totalDurationMs: Math.round(totalDuration / 1000),
+        samplesCount: samples.length,
+        heavyFunctionCount: heavyFunctions.length,
+      },
+      heavyFunctions: heavyFunctions.slice(0, 20),
+      callStacks,
+      blockingPatterns,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Build call stacks for the heaviest functions
+   */
+  _buildCallStacks(nodeMap, timings, topFunctions) {
+    const stacks = [];
+
+    // Build parent map
+    const parentMap = new Map();
+    for (const node of nodeMap.values()) {
+      if (node.children) {
+        for (const childId of node.children) {
+          parentMap.set(childId, node.id);
+        }
+      }
+    }
+
+    for (const fn of topFunctions) {
+      // Find the node matching this function
+      let targetNode = null;
+      for (const node of nodeMap.values()) {
+        const cf = node.callFrame;
+        if (cf.functionName === fn.functionName &&
+            cf.url === (fn.url === '(native)' ? '' : fn.url) &&
+            cf.lineNumber === fn.lineNumber - 1) {
+          targetNode = node;
+          break;
+        }
+      }
+
+      if (!targetNode) continue;
+
+      // Walk up the call stack
+      const stack = [];
+      let current = targetNode;
+      while (current) {
+        const cf = current.callFrame;
+        if (cf.functionName || cf.url) {
+          stack.push({
+            functionName: cf.functionName || '(anonymous)',
+            url: cf.url || '(native)',
+            lineNumber: cf.lineNumber + 1,
+            columnNumber: cf.columnNumber + 1,
+          });
+        }
+        const parentId = parentMap.get(current.id);
+        current = parentId ? nodeMap.get(parentId) : null;
+      }
+
+      stacks.push({
+        target: fn.functionName,
+        selfTimeMs: fn.selfTimeMs,
+        stack: stack.reverse(),
+      });
+    }
+
+    return stacks;
+  }
+
+  /**
+   * Detect common event loop blocking patterns
+   */
+  _detectPatterns(heavyFunctions, profile) {
+    const patterns = [];
+    const totalMs = (profile.endTime - profile.startTime) / 1000;
+
+    // Pattern: Single function dominating CPU
+    const topFn = heavyFunctions[0];
+    if (topFn && topFn.percentage > 50) {
+      patterns.push({
+        type: 'cpu-hog',
+        severity: 'high',
+        message: `Function "${topFn.functionName}" consumed ${topFn.percentage}% of CPU time (${topFn.selfTimeMs}ms)`,
+        location: `${topFn.url}:${topFn.lineNumber}`,
+        suggestion: 'Consider breaking this into smaller async chunks or moving to a worker thread',
+      });
+    }
+
+    // Pattern: JSON parsing / serialization
+    const jsonFns = heavyFunctions.filter(
+      (f) => f.functionName.includes('JSON') || f.functionName.includes('parse') || f.functionName.includes('stringify')
+    );
+    const jsonTime = jsonFns.reduce((sum, f) => sum + f.selfTimeMs, 0);
+    if (jsonTime > totalMs * 0.1) {
+      patterns.push({
+        type: 'json-heavy',
+        severity: 'medium',
+        message: `JSON operations took ${Math.round(jsonTime)}ms (${Math.round((jsonTime / totalMs) * 100)}% of profile)`,
+        suggestion: 'Consider streaming JSON parsing or processing smaller payloads',
+      });
+    }
+
+    // Pattern: RegExp heavy
+    const regexFns = heavyFunctions.filter(
+      (f) => f.functionName.includes('RegExp') || f.functionName.includes('exec') || f.functionName.includes('match')
+    );
+    const regexTime = regexFns.reduce((sum, f) => sum + f.selfTimeMs, 0);
+    if (regexTime > totalMs * 0.1) {
+      patterns.push({
+        type: 'regex-heavy',
+        severity: 'medium',
+        message: `RegExp operations took ${Math.round(regexTime)}ms`,
+        suggestion: 'Check for catastrophic backtracking in regex patterns. Consider simpler string operations.',
+      });
+    }
+
+    // Pattern: GC pressure
+    const gcFns = heavyFunctions.filter((f) => f.functionName.includes('garbage collector'));
+    const gcTime = gcFns.reduce((sum, f) => sum + f.selfTimeMs, 0);
+    if (gcTime > totalMs * 0.05) {
+      patterns.push({
+        type: 'gc-pressure',
+        severity: 'medium',
+        message: `Garbage collection took ${Math.round(gcTime)}ms (${Math.round((gcTime / totalMs) * 100)}% of profile)`,
+        suggestion: 'Reduce object allocations. Reuse buffers. Check for memory leaks.',
+      });
+    }
+
+    // Pattern: Synchronous file I/O
+    const syncFns = heavyFunctions.filter(
+      (f) => f.functionName.includes('Sync') || f.url.includes('fs.js') || f.url.includes('node:fs')
+    );
+    if (syncFns.length > 0) {
+      const syncTime = syncFns.reduce((sum, f) => sum + f.selfTimeMs, 0);
+      patterns.push({
+        type: 'sync-io',
+        severity: 'high',
+        message: `Synchronous I/O detected: ${syncFns.map((f) => f.functionName).join(', ')} (${Math.round(syncTime)}ms)`,
+        suggestion: 'Replace synchronous file operations with async alternatives',
+      });
+    }
+
+    // Pattern: Crypto operations
+    const cryptoFns = heavyFunctions.filter(
+      (f) => f.url.includes('crypto') || f.functionName.includes('pbkdf') || f.functionName.includes('hash')
+    );
+    if (cryptoFns.length > 0) {
+      const cryptoTime = cryptoFns.reduce((sum, f) => sum + f.selfTimeMs, 0);
+      if (cryptoTime > totalMs * 0.1) {
+        patterns.push({
+          type: 'crypto-heavy',
+          severity: 'medium',
+          message: `Crypto operations took ${Math.round(cryptoTime)}ms`,
+          suggestion: 'Consider offloading heavy crypto to worker threads',
+        });
+      }
+    }
+
+    if (patterns.length === 0) {
+      patterns.push({
+        type: 'healthy',
+        severity: 'low',
+        message: 'No obvious event loop blocking patterns detected in this sample',
+        suggestion: 'Try profiling for a longer duration or during peak load',
+      });
+    }
+
+    return patterns;
+  }
+}
+
+module.exports = { Analyzer };

package/src/detective.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const { EventEmitter } = require('node:events');
+const { Inspector } = require('./inspector');
+const { Analyzer } = require('./analyzer');
+
+class Detective extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.inspector = null;
+    this.analyzer = new Analyzer(config);
+    this._running = false;
+    this._lagTimer = null;
+  }
+
+  /**
+   * Activate the inspector on the target process via SIGUSR1
+   */
+  _activateInspector() {
+    if (this.config.inspectorPort) return; // already specified
+
+    const pid = this.config.pid;
+    if (!pid) throw new Error('No PID provided');
+
+    try {
+      process.kill(pid, 0); // check process exists
+    } catch (err) {
+      throw new Error(`Process ${pid} not found or not accessible: ${err.message}`);
+    }
+
+    try {
+      process.kill(pid, 'SIGUSR1');
+    } catch (err) {
+      throw new Error(
+        `Failed to send SIGUSR1 to process ${pid}: ${err.message}\n` +
+        'Try running with elevated permissions, or start the target with --inspect'
+      );
+    }
+  }
+
+  /**
+   * Discover which port the inspector opened on
+   */
+  async _findInspectorPort() {
+    if (this.config.inspectorPort) return this.config.inspectorPort;
+
+    // After SIGUSR1, Node.js opens inspector on 9229 by default
+    // Give it a moment to start
+    await this._sleep(1000);
+    return 9229;
+  }
+
+  /**
+   * Start event loop lag detection via CDP Runtime.evaluate
+   * We inject a tiny lag-measuring snippet into the target process
+   */
+  async _startLagDetection() {
+    // Inject a lag detector into the target process
+    const script = `
+      (function() {
+        if (globalThis.__loopDetective) {
+          return { alreadyRunning: true };
+        }
+        const lags = [];
+        let lastTime = Date.now();
+        const threshold = ${this.config.threshold};
+
+        const timer = setInterval(() => {
+          const now = Date.now();
+          const delta = now - lastTime;
+          const lag = delta - ${this.config.interval};
+          if (lag > threshold) {
+            lags.push({ lag, timestamp: now });
+            if (lags.length > 100) lags.shift();
+          }
+          lastTime = now;
+        }, ${this.config.interval});
+
+        // Make sure our timer doesn't keep the process alive
+        if (timer.unref) timer.unref();
+
+        globalThis.__loopDetective = {
+          timer,
+          getLags: () => {
+            const result = lags.splice(0);
+            return result;
+          },
+          cleanup: () => {
+            clearInterval(timer);
+            delete globalThis.__loopDetective;
+          }
+        };
+        return { started: true };
+      })()
+    `;
+
+    await this.inspector.send('Runtime.enable');
+    const result = await this.inspector.send('Runtime.evaluate', {
+      expression: script,
+      returnByValue: true,
+    });
+
+    if (result.exceptionDetails) {
+      throw new Error(`Failed to inject lag detector: ${JSON.stringify(result.exceptionDetails)}`);
+    }
+
+    // Poll for lag events
+    this._lagTimer = setInterval(async () => {
+      if (!this._running) return;
+      try {
+        const pollResult = await this.inspector.send('Runtime.evaluate', {
+          expression: 'globalThis.__loopDetective ? globalThis.__loopDetective.getLags() : []',
+          returnByValue: true,
+        });
+        const lags = pollResult.result?.value || [];
+        for (const lag of lags) {
+          this.emit('lag', lag);
+        }
+      } catch {
+        // Inspector may have disconnected
+      }
+    }, 1000);
+  }
+
+  /**
+   * Take a CPU profile to identify blocking code
+   */
+  async _captureProfile(duration) {
+    await this.inspector.send('Profiler.enable');
+    await this.inspector.send('Profiler.setSamplingInterval', { interval: 100 });
+    await this.inspector.send('Profiler.start');
+
+    await this._sleep(duration);
+
+    const { profile } = await this.inspector.send('Profiler.stop');
+    await this.inspector.send('Profiler.disable');
+
+    return profile;
+  }
+
+  /**
+   * Clean up the injected lag detector
+   */
+  async _cleanupLagDetector() {
+    try {
+      await this.inspector.send('Runtime.evaluate', {
+        expression: 'globalThis.__loopDetective && globalThis.__loopDetective.cleanup()',
+        returnByValue: true,
+      });
+    } catch {
+      // Best effort cleanup
+    }
+  }
+
+  /**
+   * Start the detective
+   */
+  async start() {
+    this._running = true;
+
+    // Step 1: Activate inspector
+    this._activateInspector();
+    const port = await this._findInspectorPort();
+
+    // Step 2: Connect
+    this.inspector = new Inspector({ port });
+    await this.inspector.connect();
+    this.emit('connected');
+
+    if (this.config.watch) {
+      await this._watchMode();
+    } else {
+      await this._singleRun();
+    }
+  }
+
+  async _singleRun() {
+    try {
+      // Step 3: Start lag detection
+      await this._startLagDetection();
+
+      // Step 4: Capture CPU profile
+      const profile = await this._captureProfile(this.config.duration);
+
+      // Step 5: Analyze
+      const analysis = this.analyzer.analyzeProfile(profile);
+      this.emit('profile', analysis);
+    } finally {
+      await this.stop();
+    }
+  }
+
+  async _watchMode() {
+    await this._startLagDetection();
+
+    const runCycle = async () => {
+      if (!this._running) return;
+
+      const profile = await this._captureProfile(this.config.duration);
+      const analysis = this.analyzer.analyzeProfile(profile);
+      this.emit('profile', analysis);
+
+      if (this._running) {
+        setTimeout(runCycle, 1000);
+      }
+    };
+
+    runCycle();
+  }
+
+  /**
+   * Stop the detective and clean up
+   */
+  async stop() {
+    this._running = false;
+
+    if (this._lagTimer) {
+      clearInterval(this._lagTimer);
+      this._lagTimer = null;
+    }
+
+    if (this.inspector) {
+      await this._cleanupLagDetector();
+      await this.inspector.disconnect();
+      this.inspector = null;
+    }
+
+    this.emit('disconnected');
+  }
+
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = { Detective };

package/src/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { Detective } = require('./detective');
+const { Inspector } = require('./inspector');
+const { Analyzer } = require('./analyzer');
+const { Reporter } = require('./reporter');
+
+module.exports = { Detective, Inspector, Analyzer, Reporter };

package/src/inspector.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const http = require('node:http');
+const WebSocket = require('ws');
+const { EventEmitter } = require('node:events');
+
+class Inspector extends EventEmitter {
+  constructor({ host = '127.0.0.1', port = 9229 } = {}) {
+    super();
+    this.host = host;
+    this.port = port;
+    this.ws = null;
+    this._id = 0;
+    this._callbacks = new Map();
+  }
+
+  /**
+   * Discover the inspector WebSocket URL via /json/list
+   */
+  async getWebSocketUrl() {
+    return new Promise((resolve, reject) => {
+      const req = http.get(`http://${this.host}:${this.port}/json/list`, (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            const targets = JSON.parse(data);
+            if (targets.length === 0) {
+              return reject(new Error('No inspector targets found'));
+            }
+            resolve(targets[0].webSocketDebuggerUrl);
+          } catch (e) {
+            reject(new Error(`Failed to parse inspector response: ${e.message}`));
+          }
+        });
+      });
+      req.on('error', (err) => {
+        reject(new Error(
+          `Cannot connect to inspector at ${this.host}:${this.port}. ` +
+          `Is the Node.js inspector active? (${err.message})`
+        ));
+      });
+      req.setTimeout(5000, () => {
+        req.destroy();
+        reject(new Error('Timeout connecting to inspector'));
+      });
+    });
+  }
+
+  /**
+   * Connect to the inspector WebSocket
+   */
+  async connect() {
+    const wsUrl = await this.getWebSocketUrl();
+
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.on('open', () => {
+        this.emit('connected');
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.id !== undefined && this._callbacks.has(msg.id)) {
+          const { resolve, reject } = this._callbacks.get(msg.id);
+          this._callbacks.delete(msg.id);
+          if (msg.error) {
+            reject(new Error(msg.error.message));
+          } else {
+            resolve(msg.result);
+          }
+        } else if (msg.method) {
+          this.emit('event', msg);
+        }
+      });
+
+      this.ws.on('error', (err) => {
+        this.emit('error', err);
+        reject(err);
+      });
+
+      this.ws.on('close', () => {
+        this.emit('disconnected');
+      });
+    });
+  }
+
+  /**
+   * Send a CDP command and wait for the response
+   */
+  async send(method, params = {}) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error('Inspector not connected');
+    }
+
+    const id = ++this._id;
+
+    return new Promise((resolve, reject) => {
+      this._callbacks.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ id, method, params }));
+
+      // Timeout for individual commands
+      setTimeout(() => {
+        if (this._callbacks.has(id)) {
+          this._callbacks.delete(id);
+          reject(new Error(`CDP command timeout: ${method}`));
+        }
+      }, 30000);
+    });
+  }
+
+  /**
+   * Disconnect from the inspector
+   */
+  async disconnect() {
+    if (this.ws) {
+      this._callbacks.clear();
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+}
+
+module.exports = { Inspector };

package/src/reporter.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+  bgYellow: '\x1b[43m',
+  bgGreen: '\x1b[42m',
+};
+
+class Reporter {
+  constructor(config) {
+    this.config = config;
+    this.lagEvents = [];
+  }
+
+  onConnected() {
+    if (this.config.json) return;
+    this._print(`\n${COLORS.green}✔${COLORS.reset} Connected to Node.js process`);
+    this._print(`${COLORS.dim}  Profiling for ${this.config.duration / 1000}s with ${this.config.threshold}ms lag threshold...${COLORS.reset}\n`);
+  }
+
+  onLag(data) {
+    this.lagEvents.push(data);
+    if (this.config.json) return;
+    const severity = data.lag > 500 ? COLORS.red : data.lag > 200 ? COLORS.yellow : COLORS.cyan;
+    this._print(`${severity}⚠ Event loop lag: ${data.lag}ms${COLORS.reset} ${COLORS.dim}at ${new Date(data.timestamp).toISOString()}${COLORS.reset}`);
+  }
+
+  onProfile(analysis) {
+    if (this.config.json) {
+      this._print(JSON.stringify({ ...analysis, lagEvents: this.lagEvents }, null, 2));
+      this.lagEvents = [];
+      return;
+    }
+
+    this._printSummary(analysis.summary);
+    this._printPatterns(analysis.blockingPatterns);
+    this._printHeavyFunctions(analysis.heavyFunctions);
+    this._printCallStacks(analysis.callStacks);
+    this._printLagSummary();
+
+    this.lagEvents = [];
+  }
+
+  onError(err) {
+    if (this.config.json) {
+      this._print(JSON.stringify({ error: err.message }));
+    } else {
+      this._print(`\n${COLORS.red}✖ Error: ${err.message}${COLORS.reset}`);
+    }
+  }
+
+  onInfo(msg) {
+    if (!this.config.json) {
+      this._print(`${COLORS.dim}${msg}${COLORS.reset}`);
+    }
+  }
+
+  onDisconnected() {
+    if (!this.config.json) {
+      this._print(`\n${COLORS.green}✔${COLORS.reset} Disconnected cleanly\n`);
+    }
+  }
+
+  _printSummary(summary) {
+    this._print(`\n${'─'.repeat(60)}`);
+    this._print(`${COLORS.bold}  Event Loop Detective Report${COLORS.reset}`);
+    this._print(`${'─'.repeat(60)}`);
+    this._print(`  Duration:  ${summary.totalDurationMs}ms`);
+    this._print(`  Samples:   ${summary.samplesCount}`);
+    this._print(`  Hot funcs: ${summary.heavyFunctionCount}`);
+  }
+
+  _printPatterns(patterns) {
+    this._print(`\n${COLORS.bold}  Diagnosis${COLORS.reset}`);
+    this._print(`${'─'.repeat(60)}`);
+
+    for (const p of patterns) {
+      const icon = p.severity === 'high' ? `${COLORS.bgRed} HIGH ${COLORS.reset}`
+        : p.severity === 'medium' ? `${COLORS.bgYellow} MED  ${COLORS.reset}`
+        : `${COLORS.bgGreen} LOW  ${COLORS.reset}`;
+
+      this._print(`  ${icon} ${COLORS.bold}${p.type}${COLORS.reset}`);
+      this._print(`         ${p.message}`);
+      if (p.location) {
+        this._print(`         ${COLORS.dim}at ${p.location}${COLORS.reset}`);
+      }
+      this._print(`         ${COLORS.cyan}→ ${p.suggestion}${COLORS.reset}`);
+      this._print('');
+    }
+  }
+
+  _printHeavyFunctions(functions) {
+    if (functions.length === 0) return;
+
+    this._print(`${COLORS.bold}  Top CPU-Heavy Functions${COLORS.reset}`);
+    this._print(`${'─'.repeat(60)}`);
+
+    const top = functions.slice(0, 10);
+    for (let i = 0; i < top.length; i++) {
+      const f = top[i];
+      const bar = this._makeBar(f.percentage);
+      this._print(`  ${COLORS.bold}${(i + 1).toString().padStart(2)}.${COLORS.reset} ${f.functionName}`);
+      this._print(`      ${bar} ${f.selfTimeMs}ms (${f.percentage}%)`);
+      this._print(`      ${COLORS.dim}${f.url}:${f.lineNumber}:${f.columnNumber}${COLORS.reset}`);
+    }
+  }
+
+  _printCallStacks(stacks) {
+    if (stacks.length === 0) return;
+
+    this._print(`\n${COLORS.bold}  Call Stacks (top blockers)${COLORS.reset}`);
+    this._print(`${'─'.repeat(60)}`);
+
+    for (const s of stacks) {
+      this._print(`\n  ${COLORS.yellow}▸ ${s.target}${COLORS.reset} (${s.selfTimeMs}ms)`);
+      for (let i = 0; i < s.stack.length; i++) {
+        const frame = s.stack[i];
+        const indent = '    ' + '  '.repeat(Math.min(i, 5));
+        const isTarget = frame.functionName === s.target;
+        const color = isTarget ? COLORS.yellow : COLORS.dim;
+        this._print(`${indent}${color}${isTarget ? '→' : '│'} ${frame.functionName} ${frame.url}:${frame.lineNumber}${COLORS.reset}`);
+      }
+    }
+  }
+
+  _printLagSummary() {
+    if (this.lagEvents.length === 0) {
+      this._print(`\n  ${COLORS.green}✔ No event loop lag detected above threshold${COLORS.reset}`);
+    } else {
+      const maxLag = Math.max(...this.lagEvents.map((e) => e.lag));
+      const avgLag = Math.round(this.lagEvents.reduce((s, e) => s + e.lag, 0) / this.lagEvents.length);
+      this._print(`\n  ${COLORS.red}⚠ Event Loop Lag Summary${COLORS.reset}`);
+      this._print(`    Events: ${this.lagEvents.length}`);
+      this._print(`    Max:    ${maxLag}ms`);
+      this._print(`    Avg:    ${avgLag}ms`);
+    }
+
+    this._print(`\n${'─'.repeat(60)}\n`);
+  }
+
+  _makeBar(percentage) {
+    const width = 20;
+    const filled = Math.round((percentage / 100) * width);
+    const empty = width - filled;
+    const color = percentage > 50 ? COLORS.red : percentage > 20 ? COLORS.yellow : COLORS.green;
+    return `${color}${'█'.repeat(filled)}${'░'.repeat(empty)}${COLORS.reset}`;
+  }
+
+  _print(msg) {
+    console.log(msg);
+  }
+}
+
+module.exports = { Reporter };