metwatch 0.1.0

package/src/core/runtime-manager.ts

@@ -0,0 +1,299 @@
+// ---------------------------------------------------------------------------
+// Runtime Manager
+//
+// Collects Node/Bun runtime metrics from managed processes via the Chrome
+// DevTools Protocol (inspector).
+//
+// How it works:
+//   1. The launcher passes --inspect=0 to each Node/Bun child process,
+//      which picks a random available port and prints:
+//        "Debugger listening on ws://127.0.0.1:<port>/..."
+//   2. RuntimeManager reads that port (supplied via managedPorts map),
+//      opens a WebSocket to the inspector endpoint, and polls CDP APIs.
+//   3. Metrics are emitted as 'metrics:runtime:updated' events on the bus.
+//
+// CDP methods used:
+//   Runtime.getHeapUsage()        → heapUsed, heapTotal
+//   Runtime.evaluate(expression)  → RSS, external, uptime, handles etc.
+//     (Uses process.memoryUsage() and process._getActiveHandles() evaluated
+//      inside the target process via the inspector)
+//
+// Event loop lag measurement:
+//   A lightweight probe is evaluated in the target via inspector:
+//     const start = Date.now(); setImmediate(() => resolve(Date.now() - start));
+//   Lag = actual delay - expected 0ms.
+//
+// GC metrics are not available via stable CDP; they require the
+// --expose-gc flag and custom instrumentation. We track cumulative
+// estimate via heap growth heuristic (Phase 2). Native GC events
+// will be added in Phase 3 via v8.GCProfiler or perf_hooks.
+// ---------------------------------------------------------------------------
+
+import { bus }                  from './event-bus.ts';
+import { updateRuntimeMetrics } from './state-manager.ts';
+import type { RuntimeMetrics, GcMetrics } from '../types/metrics.types.ts';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+interface WsLike {
+  send: (data: string) => void;
+  close: () => void;
+  on: (event: string, handler: (...args: unknown[]) => void) => void;
+}
+
+interface InspectorSession {
+  ws:      WsLike;
+  id:      number;
+  pending: Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>;
+}
+
+export interface RuntimeManagerHandle {
+  /** Register a managed process inspector port. Called by the launcher after spawn. */
+  register:   (id: string, pid: number, wsUrl: string) => void;
+  /** Unregister a managed process. Called when the process exits. */
+  unregister: (id: string) => void;
+  /** Stop all inspector sessions and timers. */
+  stop:       () => void;
+}
+
+// ── Internal session state ────────────────────────────────────────────────────
+
+interface ProcessSession {
+  id:      string;
+  pid:     number;
+  wsUrl:   string;
+  session: InspectorSession | null;
+  gcState: { lastHeap: number; count: number; totalMs: number; lastPauseMs: number | null };
+}
+
+// ── WebSocket helper ──────────────────────────────────────────────────────────
+// Use the global WebSocket available in Bun 1+ and Node 22+.
+// Falls back gracefully if the runtime doesn't support it.
+
+async function openSession(wsUrl: string): Promise<InspectorSession> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const WS = (globalThis as Record<string, unknown>)['WebSocket'] as (new (url: string) => WsLike) | undefined;
+  if (!WS) throw new Error('WebSocket not available in this runtime (need Bun 1+ or Node 22+)');
+
+  const ws = new WS(wsUrl);
+
+  return new Promise((resolve, reject) => {
+    const session: InspectorSession = {
+      ws,
+      id: 1,
+      pending: new Map(),
+    };
+
+    ws.on('open', () => resolve(session));
+    ws.on('error', (err: unknown) => reject(err instanceof Error ? err : new Error(String(err))));
+    ws.on('message', (raw: unknown) => {
+      try {
+        const str = typeof raw === 'string' ? raw : String(raw);
+        const msg = JSON.parse(str) as {
+          id?: number;
+          result?: unknown;
+          error?: { message: string };
+        };
+        if (msg.id !== undefined) {
+          const cb = session.pending.get(msg.id);
+          if (cb) {
+            session.pending.delete(msg.id);
+            if (msg.error) {
+              cb.reject(new Error(msg.error.message));
+            } else {
+              cb.resolve(msg.result);
+            }
+          }
+        }
+      } catch {
+        // ignore malformed messages
+      }
+    });
+  });
+}
+
+function cdpCall<T>(
+  session: InspectorSession,
+  method: string,
+  params: Record<string, unknown> = {}
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const id = session.id++;
+    session.pending.set(id, {
+      resolve: resolve as (v: unknown) => void,
+      reject,
+    });
+    session.ws.send(JSON.stringify({ id, method, params }));
+    // Timeout individual calls to avoid hanging
+    setTimeout(() => {
+      if (session.pending.has(id)) {
+        session.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method}`));
+      }
+    }, 3000);
+  });
+}
+
+// JS expression evaluated inside the target process
+const METRICS_EXPR = `(function() {
+  const m = process.memoryUsage();
+  const handles  = (process._getActiveHandles  ? process._getActiveHandles().length  : 0);
+  const requests = (process._getActiveRequests ? process._getActiveRequests().length : 0);
+  const uptime   = process.uptime();
+  return JSON.stringify({ rss: m.rss, external: m.external, arrayBuffers: m.arrayBuffers, handles, requests, uptime });
+})()`;
+
+const LAG_EXPR = `(function() {
+  return new Promise(resolve => {
+    const start = Date.now();
+    setImmediate(() => resolve(Date.now() - start));
+  });
+})()`;
+
+// ── Poll a single process ──────────────────────────────────────────────────────
+
+async function pollProcess(
+  ps: ProcessSession,
+  intervalMs: number
+): Promise<RuntimeMetrics | null> {
+  if (!ps.session) return null;
+
+  try {
+    const [heapResult, evalResult, lagResult] = await Promise.allSettled([
+      cdpCall<{ usedSize: number; totalSize: number }>(
+        ps.session, 'Runtime.getHeapUsage'
+      ),
+      cdpCall<{ result: { value: string } }>(
+        ps.session, 'Runtime.evaluate',
+        { expression: METRICS_EXPR, returnByValue: true, awaitPromise: false }
+      ),
+      cdpCall<{ result: { value: number } }>(
+        ps.session, 'Runtime.evaluate',
+        { expression: LAG_EXPR, returnByValue: true, awaitPromise: true,
+          timeout: Math.min(intervalMs, 2000) }
+      ),
+    ]);
+
+    const heap = heapResult.status === 'fulfilled' ? heapResult.value : null;
+    const evalData = evalResult.status === 'fulfilled'
+      ? JSON.parse(evalResult.value.result.value) as {
+          rss: number; external: number; arrayBuffers: number;
+          handles: number; requests: number; uptime: number;
+        }
+      : null;
+    const lag = lagResult.status === 'fulfilled'
+      ? lagResult.value.result.value
+      : 0;
+
+    // GC heuristic: if heap used dropped significantly, a GC likely ran
+    const heapUsed  = heap?.usedSize ?? 0;
+    const heapTotal = heap?.totalSize ?? 0;
+    const prevHeap  = ps.gcState.lastHeap;
+    if (prevHeap > 0 && heapUsed < prevHeap * 0.85) {
+      const freedMs = Math.round((prevHeap - heapUsed) / (1024 * 1024)); // crude proxy
+      ps.gcState.count++;
+      ps.gcState.totalMs   += freedMs;
+      ps.gcState.lastPauseMs = freedMs;
+    }
+    ps.gcState.lastHeap = heapUsed;
+
+    const gc: GcMetrics = {
+      count:        ps.gcState.count,
+      totalPauseMs: ps.gcState.totalMs,
+      lastPauseMs:  ps.gcState.lastPauseMs,
+    };
+
+    return {
+      managedId:      ps.id,
+      pid:            ps.pid,
+      heapUsed,
+      heapTotal,
+      rss:            evalData?.rss         ?? 0,
+      external:       evalData?.external    ?? 0,
+      arrayBuffers:   evalData?.arrayBuffers ?? 0,
+      eventLoopLag:   typeof lag === 'number' ? lag : 0,
+      activeHandles:  evalData?.handles     ?? 0,
+      activeRequests: evalData?.requests    ?? 0,
+      gc,
+      uptime:         evalData?.uptime      ?? 0,
+      timestamp:      Date.now(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+export function createRuntimeManager(intervalMs: number): RuntimeManagerHandle {
+  const sessions = new Map<string, ProcessSession>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  async function tick(): Promise<void> {
+    for (const ps of sessions.values()) {
+      if (!ps.session) continue;
+      const metrics = await pollProcess(ps, intervalMs);
+      if (metrics) {
+        updateRuntimeMetrics(metrics);
+        bus.emit('metrics:runtime:updated', metrics);
+      }
+    }
+  }
+
+  function startTimer(): void {
+    if (timer !== null) return;
+    // Slight delay on first poll to give the inspector time to warm up
+    setTimeout(() => {
+      void tick();
+      timer = setInterval(() => void tick(), intervalMs);
+    }, 1500);
+  }
+
+  async function register(id: string, pid: number, wsUrl: string): Promise<void> {
+    const ps: ProcessSession = {
+      id, pid, wsUrl,
+      session: null,
+      gcState: { lastHeap: 0, count: 0, totalMs: 0, lastPauseMs: null },
+    };
+    sessions.set(id, ps);
+
+    try {
+      ps.session = await openSession(wsUrl);
+      // Enable Runtime domain
+      await cdpCall(ps.session, 'Runtime.enable');
+    } catch (err) {
+      bus.emit('app:error', {
+        source: `runtime-manager:${id}`,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+      ps.session = null;
+    }
+
+    startTimer();
+  }
+
+  function unregister(id: string): void {
+    const ps = sessions.get(id);
+    if (ps?.session) {
+      try { ps.session.ws.close(); } catch { /* ignore */ }
+    }
+    sessions.delete(id);
+  }
+
+  function stop(): void {
+    if (timer !== null) { clearInterval(timer); timer = null; }
+    for (const ps of sessions.values()) {
+      try { ps.session?.ws.close(); } catch { /* ignore */ }
+    }
+    sessions.clear();
+  }
+
+  // Expose register as async but return the synchronous-compatible handle
+  const handle: RuntimeManagerHandle = {
+    register: (id, pid, wsUrl) => { void register(id, pid, wsUrl); },
+    unregister,
+    stop,
+  };
+
+  return handle;
+}

package/src/core/state-manager.ts

@@ -0,0 +1,88 @@
+// ---------------------------------------------------------------------------
+// State Manager
+//
+// Single source of truth for the latest system snapshot.
+// Widgets NEVER fetch data — they read from state and react to bus events.
+//
+// This is intentionally NOT a reactive store (no proxies, no signals).
+// The event bus handles reactivity. State is just a plain in-memory cache
+// so widgets can read the last known value synchronously on first render
+// without waiting for the next poll cycle.
+// ---------------------------------------------------------------------------
+
+import type {
+  CpuMetrics,
+  MemoryMetrics,
+  SystemMetrics,
+  DiskMetrics,
+  NetworkMetrics,
+  RuntimeMetrics,
+} from '../types/metrics.types.ts';
+import type { ProcessList } from '../types/process.types.ts';
+
+// ── Internal state (module-scoped, not exported) ──────────────────────────────
+
+let _cpu:        CpuMetrics     | null = null;
+let _memory:     MemoryMetrics  | null = null;
+let _disk:       DiskMetrics    | null = null;
+let _network:    NetworkMetrics | null = null;
+let _processes:  ProcessList          = [];
+// Runtime metrics keyed by managed process id
+const _runtime   = new Map<string, RuntimeMetrics>();
+
+// ── CPU ───────────────────────────────────────────────────────────────────────
+
+export function getCpuMetrics(): CpuMetrics | null    { return _cpu; }
+export function updateCpuMetrics(m: CpuMetrics): void { _cpu = m; }
+
+// ── Memory ────────────────────────────────────────────────────────────────────
+
+export function getMemoryMetrics(): MemoryMetrics | null    { return _memory; }
+export function updateMemoryMetrics(m: MemoryMetrics): void { _memory = m; }
+
+// ── System (convenience) ──────────────────────────────────────────────────────
+
+export function getSystemMetrics(): SystemMetrics | null {
+  if (!_cpu || !_memory) return null;
+  return { cpu: _cpu, memory: _memory };
+}
+
+// ── Disk ──────────────────────────────────────────────────────────────────────
+
+export function getDiskMetrics(): DiskMetrics | null    { return _disk; }
+export function updateDiskMetrics(m: DiskMetrics): void { _disk = m; }
+
+// ── Network ───────────────────────────────────────────────────────────────────
+
+export function getNetworkMetrics(): NetworkMetrics | null    { return _network; }
+export function updateNetworkMetrics(m: NetworkMetrics): void { _network = m; }
+
+// ── Processes ─────────────────────────────────────────────────────────────────
+
+export function getProcesses(): ProcessList             { return _processes; }
+export function updateProcesses(list: ProcessList): void { _processes = list; }
+
+// ── Runtime (per managed process) ─────────────────────────────────────────────
+
+export function getRuntimeMetrics(id: string): RuntimeMetrics | null {
+  return _runtime.get(id) ?? null;
+}
+
+export function getAllRuntimeMetrics(): RuntimeMetrics[] {
+  return [..._runtime.values()];
+}
+
+export function updateRuntimeMetrics(m: RuntimeMetrics): void {
+  _runtime.set(m.managedId, m);
+}
+
+// ── Reset ─────────────────────────────────────────────────────────────────────
+
+export function resetState(): void {
+  _cpu       = null;
+  _memory    = null;
+  _disk      = null;
+  _network   = null;
+  _processes = [];
+  _runtime.clear();
+}

package/src/services/disk.service.ts

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Disk Service
+//
+// Wraps systeminformation filesystem APIs to produce normalized DiskMetrics.
+//
+// Two si calls per tick:
+//   si.fsSize()   → per-mount space usage (total/used/free/%)
+//   si.fsStats()  → aggregate read/write bytes since last call (delta-based)
+//
+// IO rates are calculated as deltas between successive calls. The first call
+// returns zero rates (no baseline yet). Subsequent calls divide the byte delta
+// by the elapsed seconds to get bytes/sec.
+// ---------------------------------------------------------------------------
+
+import si from 'systeminformation';
+import type { DiskMetrics, DiskMount, DiskIO } from '../types/metrics.types.ts';
+
+// ── Fetch ─────────────────────────────────────────────────────────────────────
+
+export async function fetchDiskMetrics(): Promise<DiskMetrics> {
+  const now = Date.now();
+
+  const [fsSizes, disksIO] = await Promise.all([
+    si.fsSize(),
+    si.disksIO().catch(() => null),
+  ]);
+
+  // ── IO delta calculation ────────────────────────────────────────────────────
+  // disksIO may return null on some platforms (e.g. Windows without admin).
+
+  let diskIo: DiskIO | null = null;
+
+  // disksIO returns an object with rIO/wIO/tIO/rIO_sec/wIO_sec/tIO_sec/rIO_ms/wIO_ms...
+  // The *_sec fields are already rates calculated by systeminformation.
+  if (disksIO !== null && typeof disksIO === 'object') {
+    const d = disksIO as unknown as Record<string, number>;
+    const readBPS   = (d['rIO_sec']  ?? 0) * 512;  // sectors → bytes (approx)
+    const writeBPS  = (d['wIO_sec']  ?? 0) * 512;
+    const readIops  = d['rIO_sec']   ?? 0;
+    const writeIops = d['wIO_sec']   ?? 0;
+    const totalBPS  = readBPS + writeBPS;
+    const utilization = Math.min(100, (totalBPS / (500 * 1024 * 1024)) * 100);
+
+    diskIo = {
+      readBytesPerSec:  Math.round(readBPS),
+      writeBytesPerSec: Math.round(writeBPS),
+      readIOPS:         Math.round(readIops),
+      writeIOPS:        Math.round(writeIops),
+      utilization:      Math.round(utilization * 10) / 10,
+    };
+  }
+
+  void 0; // placeholder
+  // ── Mount entries ──────────────────────────────────────────────────────────
+  // Filter out pseudo-filesystems (tmpfs, devfs, etc.) that have 0 total size.
+
+  const mounts: DiskMount[] = fsSizes
+    .filter(fs => fs.size > 0)
+    .map(fs => ({
+      fs:      fs.fs     ?? 'unknown',
+      mount:   fs.mount  ?? '/',
+      type:    fs.type   ?? 'unknown',
+      total:   fs.size   ?? 0,
+      used:    fs.used   ?? 0,
+      free:    (fs.size ?? 0) - (fs.used ?? 0),
+      percent: fs.use    ?? 0,
+      io:      diskIo,   // same IO object for all mounts (aggregate only for now)
+    }));
+
+  return {
+    mounts,
+    totalReadBytesPerSec:  diskIo?.readBytesPerSec  ?? 0,
+    totalWriteBytesPerSec: diskIo?.writeBytesPerSec ?? 0,
+    timestamp: now,
+  };
+}

package/src/services/network.service.ts

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// Network Service
+//
+// Wraps systeminformation network APIs to produce normalized NetworkMetrics.
+//
+// Two si calls per tick:
+//   si.networkInterfaces()  → static info (IP addresses, operstate)
+//   si.networkStats()       → cumulative byte/packet counters (delta-based)
+//
+// Rates are calculated as deltas between successive calls — same approach as
+// disk.service.ts. First call returns zero rates.
+// ---------------------------------------------------------------------------
+
+import si from 'systeminformation';
+import type { NetworkMetrics, NetworkInterface } from '../types/metrics.types.ts';
+
+// ── Delta tracking ────────────────────────────────────────────────────────────
+
+interface IfaceSnapshot {
+  rx_bytes:   number;
+  tx_bytes:   number;
+  rx_sec:     number;   // packets
+  tx_sec:     number;
+  rx_errors:  number;
+  tx_errors:  number;
+  rx_dropped: number;
+  tx_dropped: number;
+  ts:         number;
+}
+
+const _prev = new Map<string, IfaceSnapshot>();
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function operstate(s: string | undefined): 'up' | 'down' | 'unknown' {
+  if (s === 'up')   return 'up';
+  if (s === 'down') return 'down';
+  return 'unknown';
+}
+
+// ── Fetch ─────────────────────────────────────────────────────────────────────
+
+export async function fetchNetworkMetrics(): Promise<NetworkMetrics> {
+  const now = Date.now();
+
+  const [ifaces, stats] = await Promise.all([
+    si.networkInterfaces(),
+    si.networkStats('*'),
+  ]);
+
+  // Build a map of static info keyed by iface name
+  const ifaceArray = Array.isArray(ifaces) ? ifaces : [ifaces];
+  const staticInfo = new Map(ifaceArray.map(i => [i.iface, i]));
+
+  const statsArray = Array.isArray(stats) ? stats : [stats];
+
+  const interfaces: NetworkInterface[] = [];
+  let totalRx = 0;
+  let totalTx = 0;
+
+  for (const s of statsArray) {
+    const iface = s.iface ?? '';
+    if (!iface) continue;
+
+    const prev = _prev.get(iface);
+    const dtSec = prev ? Math.max(0.001, (now - prev.ts) / 1000) : 1;
+
+    const rxBPS = prev
+      ? Math.max(0, ((s.rx_bytes ?? 0) - prev.rx_bytes) / dtSec)
+      : 0;
+    const txBPS = prev
+      ? Math.max(0, ((s.tx_bytes ?? 0) - prev.tx_bytes) / dtSec)
+      : 0;
+    const rxPPS = prev
+      ? Math.max(0, ((s.rx_sec   ?? 0) - prev.rx_sec)   / dtSec)
+      : 0;
+    const txPPS = prev
+      ? Math.max(0, ((s.tx_sec   ?? 0) - prev.tx_sec)   / dtSec)
+      : 0;
+
+    _prev.set(iface, {
+      rx_bytes:   s.rx_bytes   ?? 0,
+      tx_bytes:   s.tx_bytes   ?? 0,
+      rx_sec:     s.rx_sec     ?? 0,
+      tx_sec:     s.tx_sec     ?? 0,
+      rx_errors:  s.rx_errors  ?? 0,
+      tx_errors:  s.tx_errors  ?? 0,
+      rx_dropped: s.rx_dropped ?? 0,
+      tx_dropped: s.tx_dropped ?? 0,
+      ts:         now,
+    });
+
+    const info = staticInfo.get(iface);
+
+    totalRx += rxBPS;
+    totalTx += txBPS;
+
+    // Skip loopback in displayed interfaces but keep it in totals
+    if (iface === 'lo' || iface === 'loopback') continue;
+
+    interfaces.push({
+      iface,
+      ip4:             info?.ip4  ?? '',
+      ip6:             info?.ip6  ?? '',
+      operstate:       operstate(info?.operstate),
+      rxBytesPerSec:   Math.round(rxBPS),
+      txBytesPerSec:   Math.round(txBPS),
+      rxPacketsPerSec: Math.round(rxPPS),
+      txPacketsPerSec: Math.round(txPPS),
+      rxErrors:        s.rx_errors  ?? 0,
+      txErrors:        s.tx_errors  ?? 0,
+      rxDrops:         s.rx_dropped ?? 0,
+      txDrops:         s.tx_dropped ?? 0,
+    });
+  }
+
+  // Sort: up interfaces first, then by name
+  interfaces.sort((a, b) => {
+    if (a.operstate !== b.operstate) {
+      return a.operstate === 'up' ? -1 : 1;
+    }
+    return a.iface.localeCompare(b.iface);
+  });
+
+  return {
+    interfaces,
+    totalRxBytesPerSec: Math.round(totalRx),
+    totalTxBytesPerSec: Math.round(totalTx),
+    timestamp: now,
+  };
+}

package/src/services/process.service.ts

@@ -0,0 +1,49 @@
+// ---------------------------------------------------------------------------
+// Process Service
+//
+// Fetches and normalizes the process list using systeminformation.
+// Maps raw si data to the canonical ProcessInfo shape — including the
+// Phase 2 extended fields: user, threads, handles.
+// ---------------------------------------------------------------------------
+
+import si from 'systeminformation';
+import type { ProcessInfo, ProcessList, ProcessStatus } from '../types/process.types.ts';
+
+function mapStatus(raw: string): ProcessStatus {
+  switch (raw.toLowerCase()) {
+    case 'running': return 'running';
+    case 'sleeping':
+    case 'sleep': return 'sleeping';
+    case 'stopped': return 'stopped';
+    case 'zombie': return 'zombie';
+    default: return 'unknown';
+  }
+}
+
+export async function fetchProcessList(limit = 100): Promise<ProcessList> {
+  const { list } = await si.processes();
+
+  // Sort by CPU descending before slicing so we surface the most active
+  const sorted = [...list].sort((a, b) => b.cpu - a.cpu);
+  const top = sorted.slice(0, limit);
+
+  const totalMem = (await si.mem()).total;
+
+  return top.map((p): ProcessInfo => ({
+    pid:           p.pid,
+    name:          p.name    || 'unknown',
+    command:       p.command || p.name || '',
+    cpu:           Math.round((p.cpu    ?? 0) * 10) / 10,
+    memory:        p.memRss  ?? 0,
+    memoryPercent: totalMem > 0
+      ? Math.round(((p.memRss ?? 0) / totalMem) * 1000) / 10
+      : 0,
+    status:    mapStatus(p.state      ?? ''),
+    startedAt: p.started ? new Date(p.started).getTime() : null,
+    ppid:      p.parentPid   ?? null,
+    // ── Extended (Phase 2) ──────────────────────────────────────────────────
+    user:      (p as unknown as { user?: string }).user      ?? '',
+    threads:   (p as unknown as { threads?: number }).threads ?? 1,
+    handles:   (p as unknown as { fd?: number }).fd          ?? 0,
+  }));
+}