metwatch 0.1.0

package/src/types/metrics.types.ts

@@ -0,0 +1,182 @@
+// ---------------------------------------------------------------------------
+// Metrics Types
+//
+// Domain types for all system metrics flowing through the event bus and state
+// manager. Never expose raw systeminformation objects outside the services layer.
+// ---------------------------------------------------------------------------
+
+// ── CPU ───────────────────────────────────────────────────────────────────────
+
+export interface CpuCore {
+  /** Core index (0-based) */
+  index: number;
+  /** Usage percentage 0–100 */
+  usage: number;
+}
+
+export interface CpuMetrics {
+  /** Overall CPU usage percentage (0–100) */
+  usage: number;
+  /** Per-core usage */
+  cores: CpuCore[];
+  /** Human-readable model string e.g. "Intel Core i7-1185G7" */
+  model: string;
+  /** Number of logical cores */
+  coreCount: number;
+  /** Timestamp of this snapshot (unix ms) */
+  timestamp: number;
+}
+
+// ── Memory ────────────────────────────────────────────────────────────────────
+
+export interface MemoryMetrics {
+  /** Total physical memory in bytes */
+  total: number;
+  /** Used memory in bytes */
+  used: number;
+  /** Free memory in bytes */
+  free: number;
+  /** Used percentage 0–100 */
+  percent: number;
+  /** Active memory in bytes */
+  active: number;
+  /** Cached/buffered memory in bytes */
+  cached: number;
+  /** Timestamp of this snapshot (unix ms) */
+  timestamp: number;
+}
+
+// ── System (convenience composite) ───────────────────────────────────────────
+
+export interface SystemMetrics {
+  cpu: CpuMetrics;
+  memory: MemoryMetrics;
+}
+
+// ── Disk ──────────────────────────────────────────────────────────────────────
+
+export interface DiskIO {
+  /** Read throughput in bytes/sec */
+  readBytesPerSec: number;
+  /** Write throughput in bytes/sec */
+  writeBytesPerSec: number;
+  /** Read operations per second */
+  readIOPS: number;
+  /** Write operations per second */
+  writeIOPS: number;
+  /** Disk utilization 0–100% */
+  utilization: number;
+}
+
+export interface DiskMount {
+  /** Block device path e.g. "/dev/sda1" */
+  fs: string;
+  /** Mount point e.g. "/" or "/home" */
+  mount: string;
+  /** Filesystem type e.g. "ext4", "NTFS" */
+  type: string;
+  /** Total capacity in bytes */
+  total: number;
+  /** Used bytes */
+  used: number;
+  /** Free bytes */
+  free: number;
+  /** Used percentage 0–100 */
+  percent: number;
+  /** IO stats — null if unavailable on this platform */
+  io: DiskIO | null;
+}
+
+export interface DiskMetrics {
+  /** One entry per mounted filesystem */
+  mounts: DiskMount[];
+  /** Aggregate read across all disks (bytes/sec) */
+  totalReadBytesPerSec: number;
+  /** Aggregate write across all disks (bytes/sec) */
+  totalWriteBytesPerSec: number;
+  /** Timestamp of this snapshot (unix ms) */
+  timestamp: number;
+}
+
+// ── Network ───────────────────────────────────────────────────────────────────
+
+export interface NetworkInterface {
+  /** Interface name e.g. "eth0", "en0", "Wi-Fi" */
+  iface: string;
+  /** IPv4 address (empty string if none) */
+  ip4: string;
+  /** IPv6 address (empty string if none) */
+  ip6: string;
+  /** Whether the interface is up */
+  operstate: 'up' | 'down' | 'unknown';
+  /** Received bytes per second */
+  rxBytesPerSec: number;
+  /** Transmitted bytes per second */
+  txBytesPerSec: number;
+  /** Received packets per second */
+  rxPacketsPerSec: number;
+  /** Transmitted packets per second */
+  txPacketsPerSec: number;
+  /** Cumulative RX errors */
+  rxErrors: number;
+  /** Cumulative TX errors */
+  txErrors: number;
+  /** Cumulative RX drops */
+  rxDrops: number;
+  /** Cumulative TX drops */
+  txDrops: number;
+}
+
+export interface NetworkMetrics {
+  /** One entry per active network interface */
+  interfaces: NetworkInterface[];
+  /** Total download across all interfaces (bytes/sec) */
+  totalRxBytesPerSec: number;
+  /** Total upload across all interfaces (bytes/sec) */
+  totalTxBytesPerSec: number;
+  /** Timestamp of this snapshot (unix ms) */
+  timestamp: number;
+}
+
+// ── Runtime (Node / Bun specific) ─────────────────────────────────────────────
+
+export interface GcMetrics {
+  /** Most recent GC pause duration in ms (null if no GC has occurred) */
+  lastPauseMs: number | null;
+  /** Total GC pause time in ms since process start */
+  totalPauseMs: number;
+  /** Number of GC events since process start */
+  count: number;
+}
+
+export interface RuntimeMetrics {
+  /** Managed process ID (name from ManagedProcessDef) */
+  managedId: string;
+  /** OS PID of the process */
+  pid: number;
+  /** V8 heap used in bytes */
+  heapUsed: number;
+  /** V8 heap total allocated in bytes */
+  heapTotal: number;
+  /** RSS (Resident Set Size) in bytes */
+  rss: number;
+  /** External memory held by C++ objects in bytes */
+  external: number;
+  /** ArrayBuffer memory in bytes */
+  arrayBuffers: number;
+  /**
+   * Event loop lag in milliseconds — how long the event loop is blocked
+   * beyond the expected tick interval. > 100ms = problematic.
+   */
+  eventLoopLag: number;
+  /** Number of active libuv handles (timers, sockets, etc.) */
+  activeHandles: number;
+  /** Number of active libuv requests */
+  activeRequests: number;
+  /** Garbage collector metrics */
+  gc: GcMetrics;
+  /** Process uptime in seconds */
+  uptime: number;
+  /** Timestamp of this snapshot (unix ms) */
+  timestamp: number;
+}

package/src/types/process.types.ts

@@ -0,0 +1,49 @@
+// ---------------------------------------------------------------------------
+// Process Types
+// Domain types for process data. ProcessInfo is the normalized shape used
+// throughout MetWatch regardless of whether data comes from systeminformation
+// or pidusage. Never expose raw library types outside the services layer.
+// ---------------------------------------------------------------------------
+
+export type ProcessStatus = 'running' | 'sleeping' | 'stopped' | 'zombie' | 'unknown';
+
+export interface ProcessInfo {
+  pid: number;
+  /** Human-readable process name */
+  name: string;
+  /** Full command line with arguments */
+  command: string;
+  /** CPU usage percentage (0–100, can exceed 100 on multi-core) */
+  cpu: number;
+  /** Memory usage in bytes (RSS) */
+  memory: number;
+  /** Memory as a percentage of total RAM (0–100) */
+  memoryPercent: number;
+  status: ProcessStatus;
+  /** Process start time as unix ms, if available */
+  startedAt: number | null;
+  /** Parent PID */
+  ppid: number | null;
+  // ── Extended fields (Phase 2) ──────────────────────────────────────────
+  /** Username that owns the process (empty string if unavailable) */
+  user: string;
+  /** Number of threads */
+  threads: number;
+  /** Open file descriptors / handles */
+  handles: number;
+}
+
+export type ProcessList = ProcessInfo[];
+
+/** View mode for the process table widget */
+export type ProcessViewMode = 'all' | 'watched';
+
+/** Column to sort the process table by */
+export type ProcessSortKey = 'cpu' | 'memory' | 'name' | 'pid';
+
+export interface ProcessTableState {
+  viewMode: ProcessViewMode;
+  sortKey: ProcessSortKey;
+  sortDesc: boolean;
+  selectedIndex: number;
+}

package/src/ui/layout.ts

@@ -0,0 +1,318 @@
+// ---------------------------------------------------------------------------
+// Layout — Dynamic Collapsible Grid
+//
+// btop-inspired layout: all panels live on one screen, user can toggle each
+// panel on/off with a key. Hidden panels collapse; remaining panels expand.
+//
+// Default grid (all panels visible, ~50 row terminal assumed):
+//
+//   ┌────────────┬────────────┬────────────┐  ← row A  height ~20%
+//   │   CPU      │  Memory    │   Disk     │
+//   ├────────────┴────────────┴────────────┤  ← row B  height ~18%
+//   │   Network            │  Runtime      │
+//   ├─────────────────────────────────────┤  ← row C  height ~32%
+//   │          Processes                  │
+//   ├─────────────────────────────────────┤  ← row D  height ~30%
+//   │          Logs                       │
+//   └─────────────────────────────────────┘
+//
+// Panel toggle keys:
+//   d  → Disk        n  → Network
+//   R  → Runtime     p  → Processes
+//   l  → Logs (focus/toggle)
+//   (CPU and Memory are always visible)
+//
+// Heights are recalculated every time a panel is toggled. The layout
+// re-builds widget positions using blessed's hide()/show() — no widget
+// teardown needed (positions are updated via .top/.height attributes).
+// ---------------------------------------------------------------------------
+
+import blessed from 'blessed';
+import type { BlessedScreen, BlessedElement } from 'blessed';
+import type { ResolvedConfig } from '../types/config.types.ts';
+import type { LauncherHandle }   from '../core/launcher.ts';
+import type { LogManagerHandle } from '../core/log-manager.ts';
+import { createCpuWidget }          from './widgets/cpu.widget.ts';
+import { createMemoryWidget }       from './widgets/memory.widget.ts';
+import { createDiskWidget }         from './widgets/disk.widget.ts';
+import { createNetworkWidget }      from './widgets/network.widget.ts';
+import { createRuntimeWidget }      from './widgets/runtime.widget.ts';
+import { createProcessTableWidget } from './widgets/process-table.widget.ts';
+import { createLogsWidget }         from './widgets/logs.widget.ts';
+
+interface LayoutOptions {
+  screen:     BlessedScreen;
+  config:     ResolvedConfig;
+  launcher:   LauncherHandle | null;
+  logManager: LogManagerHandle | null;
+}
+
+interface LayoutHandles {
+  destroy: () => void;
+}
+
+// ── Height constants (percentages, must sum to 100 when all panels visible) ──
+
+const H = {
+  ROW_A:    20,   // CPU + Memory + Disk
+  ROW_B:    24,   // Network + Runtime (extra height for line graph)
+  ROW_C:    30,   // Processes
+  ROW_D:    26,   // Logs
+} as const;
+
+// ── Utility ───────────────────────────────────────────────────────────────────
+
+type Pct = `${number}%`;
+function pct(n: number): Pct { return `${n}%`; }
+
+/** Given a set of visible row heights (% units), compute their cumulative tops. */
+function tops(heights: number[]): number[] {
+  const result: number[] = [];
+  let acc = 0;
+  for (const h of heights) {
+    result.push(acc);
+    acc += h;
+  }
+  return result;
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+export function buildLayout(opts: LayoutOptions): LayoutHandles {
+  const { screen, config, launcher, logManager } = opts;
+
+  const panels = config.panels;
+  const managedNames = new Set<string>(
+    launcher ? launcher.getAll().map(p => p.name) : []
+  );
+
+  // Track which optional panels are currently visible
+  const visible = {
+    disk:      panels.disk      !== false,
+    network:   panels.network   !== false,
+    runtime:   panels.runtime   !== false,
+    processes: panels.processes !== false,
+    logs:      panels.logs      !== false,
+  };
+
+  // ── Create all widgets ─────────────────────────────────────────────────────
+  // Initial positions are placeholders; recalc() sets real values.
+
+  const cpu = createCpuWidget({
+    screen, top: 0, left: 0, width: '34%', height: pct(H.ROW_A),
+  });
+
+  const memory = createMemoryWidget({
+    screen, top: 0, left: '34%', width: '33%', height: pct(H.ROW_A),
+  });
+
+  const disk = createDiskWidget({
+    screen, top: 0, left: '67%', width: '33%', height: pct(H.ROW_A),
+  });
+
+  const network = createNetworkWidget({
+    screen, top: pct(H.ROW_A), left: 0, width: '55%', height: pct(H.ROW_B),
+  });
+
+  const runtime = createRuntimeWidget({
+    screen, top: pct(H.ROW_A), left: '55%', width: '45%', height: pct(H.ROW_B),
+  });
+
+  const processes = createProcessTableWidget({
+    screen,
+    config,
+    getManagedById: (id) => launcher?.get(id),
+    managedNames,
+    top: pct(H.ROW_A + H.ROW_B),
+    left: 0,
+    width: '100%',
+    height: pct(H.ROW_C),
+  });
+
+  const logs = createLogsWidget({
+    screen,
+    logManager: logManager ?? {
+      getLines:   () => [],
+      getAllLines: () => [],
+      clearLines: () => undefined,
+      destroy:    () => undefined,
+    },
+    processCount: managedNames.size,
+    top: pct(H.ROW_A + H.ROW_B + H.ROW_C),
+    left: 0,
+    width: '100%',
+    height: pct(H.ROW_D),
+  });
+
+  // ── Apply initial visibility from config ───────────────────────────────────
+
+  function applyVisibility(): void {
+    // Row A: CPU + Memory always shown; Disk optional.
+    // When Disk is hidden, CPU and Memory each take 50%.
+    const cpuBox     = cpu.box     as unknown as { top: string; left: string; width: string; height: string };
+    const memBox     = memory.box  as unknown as { top: string; left: string; width: string; height: string };
+    const diskBox    = disk.box    as unknown as { top: string; left: string; width: string; height: string; hide: () => void; show: () => void };
+    const netBox     = network.box as unknown as { top: string; left: string; width: string; height: string; hide: () => void; show: () => void };
+    const runtimeBox = runtime.box as unknown as { top: string; left: string; width: string; height: string; hide: () => void; show: () => void };
+    const procBox    = processes.box as unknown as { top: string; height: string; hide: () => void; show: () => void };
+    const logsBox    = logs.box    as unknown as { top: string; height: string; hide: () => void; show: () => void };
+
+    // Row A widths
+    if (visible.disk) {
+      cpuBox.width = '34%'; cpuBox.left = '0%';
+      memBox.width = '33%'; memBox.left = '34%';
+      diskBox.width = '33%'; diskBox.left = '67%';
+      diskBox.show();
+    } else {
+      cpuBox.width = '50%'; cpuBox.left = '0%';
+      memBox.width = '50%'; memBox.left = '50%';
+      diskBox.hide();
+    }
+
+    // Row A height
+    const rowAH = H.ROW_A;
+    cpuBox.height = pct(rowAH); memBox.height = pct(rowAH);
+
+    // Row B: Network + Runtime. If both hidden, row B has height 0.
+    let rowBTop = rowAH;
+    let rowBH   = 0;
+
+    if (visible.network || visible.runtime) {
+      rowBH = H.ROW_B;
+      if (visible.network && visible.runtime) {
+        netBox.width  = '55%'; netBox.left  = '0%';
+        runtimeBox.width = '45%'; runtimeBox.left = '55%';
+      } else if (visible.network) {
+        netBox.width  = '100%'; netBox.left = '0%';
+      } else {
+        runtimeBox.width = '100%'; runtimeBox.left = '0%';
+      }
+      if (visible.network) { netBox.top = pct(rowBTop); netBox.height = pct(rowBH); netBox.show(); }
+      else netBox.hide();
+      if (visible.runtime) { runtimeBox.top = pct(rowBTop); runtimeBox.height = pct(rowBH); runtimeBox.show(); }
+      else runtimeBox.hide();
+    } else {
+      netBox.hide();
+      runtimeBox.hide();
+    }
+
+    // Remaining height after rows A and B
+    const remaining = 100 - rowAH - rowBH;
+
+    // Split remaining between Processes and Logs
+    const showProc = visible.processes;
+    const showLogs = visible.logs;
+
+    let procH = 0;
+    let logsH = 0;
+
+    if (showProc && showLogs) {
+      procH = Math.round(remaining * 0.55);
+      logsH = remaining - procH;
+    } else if (showProc) {
+      procH = remaining;
+    } else if (showLogs) {
+      logsH = remaining;
+    }
+
+    const rowCTop = rowAH + rowBH;
+    const rowDTop = rowCTop + procH;
+
+    if (showProc) {
+      procBox.top = pct(rowCTop); procBox.height = pct(procH); procBox.show();
+    } else {
+      procBox.hide();
+    }
+
+    if (showLogs) {
+      logsBox.top = pct(rowDTop); logsBox.height = pct(logsH); logsBox.show();
+    } else {
+      logsBox.hide();
+    }
+
+    screen.render();
+  }
+
+  applyVisibility();
+
+  // ── Toggle keybindings ─────────────────────────────────────────────────────
+
+  screen.key(['d'], () => {
+    visible.disk = !visible.disk;
+    applyVisibility();
+  });
+
+  screen.key(['n'], () => {
+    visible.network = !visible.network;
+    applyVisibility();
+  });
+
+  screen.key(['R'], () => {
+    visible.runtime = !visible.runtime;
+    applyVisibility();
+  });
+
+  screen.key(['p'], () => {
+    visible.processes = !visible.processes;
+    applyVisibility();
+  });
+
+  // ── Help overlay ───────────────────────────────────────────────────────────
+  // Press ? to show keybindings overlay
+
+  const helpBox = blessed.box({
+    parent: screen as unknown as BlessedElement,
+    top: 'center', left: 'center',
+    width: 52, height: 18,
+    tags: true,
+    border: { type: 'line' },
+    hidden: true,
+    style: { border: { fg: 'white' }, bg: 'black' },
+    label: ' MetWatch — Keybindings ',
+    content: [
+      '',
+      '  {bold}Navigation{/bold}',
+      '  ↑ / k       Move process selection up',
+      '  ↓ / j       Move process selection down',
+      '',
+      '  {bold}View{/bold}',
+      '  a           Process table: All mode',
+      '  f           Process table: Watched mode',
+      '  c / m       Sort by CPU / Memory',
+      '',
+      '  {bold}Panel Toggles{/bold}',
+      '  d           Toggle Disk panel',
+      '  n           Toggle Network panel',
+      '  R           Toggle Runtime panel',
+      '  p           Toggle Process panel',
+      '',
+      '  {bold}Actions{/bold}',
+      '  K           Kill selected process',
+      '  r           Restart managed process',
+      '  s           Stop managed process',
+      '  q / Ctrl+C  Quit',
+      '  ?           Close this help',
+    ].join('\n'),
+  });
+
+  screen.key(['?'], () => {
+    const box = helpBox as unknown as { hidden: boolean; show: () => void; hide: () => void };
+    if (box.hidden) { box.show(); } else { box.hide(); }
+    screen.render();
+  });
+
+  // ── Destroy ────────────────────────────────────────────────────────────────
+
+  function destroy(): void {
+    cpu.destroy();
+    memory.destroy();
+    disk.destroy();
+    network.destroy();
+    runtime.destroy();
+    processes.destroy();
+    logs.destroy();
+    helpBox.destroy();
+  }
+
+  return { destroy };
+}

package/src/ui/screen.ts

@@ -0,0 +1,45 @@
+// ---------------------------------------------------------------------------
+// Screen
+//
+// Creates and exports the blessed screen singleton. This is the only place
+// in the codebase where `blessed.screen()` is called. All other modules
+// receive the screen via parameter or import this module.
+//
+// Configuration choices:
+//   smartCSR  — only redraw damaged regions (significant perf boost)
+//   fullUnicode — required for block chars (█) used in bars/gauges
+//   dockBorders — adjacent panels share border chars cleanly (┬ ┤ etc.)
+//   autoPadding — children auto-respect parent border+padding
+// ---------------------------------------------------------------------------
+
+import blessed from 'blessed';
+import type { BlessedScreen } from 'blessed';
+
+let _screen: BlessedScreen | null = null;
+
+export function createScreen(): BlessedScreen {
+  if (_screen) return _screen;
+
+  _screen = blessed.screen({
+    smartCSR: true,
+    fullUnicode: true,
+    dockBorders: true,
+    autoPadding: true,
+    title: 'MetWatch',
+    ignoreLocked: ['C-c'],
+  });
+
+  return _screen;
+}
+
+export function getScreen(): BlessedScreen {
+  if (!_screen) throw new Error('Screen not initialized. Call createScreen() first.');
+  return _screen;
+}
+
+export function destroyScreen(): void {
+  if (_screen) {
+    _screen.destroy();
+    _screen = null;
+  }
+}

package/src/ui/widgets/cpu.widget.ts

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// CPU Widget
+//
+// Renders per-core CPU usage as stacked horizontal gauges plus an overall
+// usage bar. Subscribes to 'metrics:cpu:updated' events and re-renders.
+//
+// Layout:
+//   ┌─ CPU ──────────────────────────────────┐
+//   │ Overall  ████████░░░░░░░░  45.3%        │
+//   │ Core 0   ██████░░░░░░░░░░  38.1%        │
+//   │ Core 1   █████████░░░░░░░  52.4%        │
+//   │ ...                                      │
+//   └─────────────────────────────────────────┘
+// ---------------------------------------------------------------------------
+
+import blessed from 'blessed';
+import type { BlessedScreen, Box } from 'blessed';
+import { bus } from '../../core/event-bus.ts';
+import { getCpuMetrics } from '../../core/state-manager.ts';
+import type { CpuMetrics } from '../../types/metrics.types.ts';
+import { formatPercent, colorPercent } from '../../utils/formatters.ts';
+
+interface CpuWidgetOptions {
+  screen: BlessedScreen;
+  top: number | string;
+  left: number | string;
+  width: number | string;
+  height: number | string;
+}
+
+interface CpuWidgetHandle {
+  box: Box;
+  destroy: () => void;
+}
+
+export function createCpuWidget(options: CpuWidgetOptions): CpuWidgetHandle {
+  const { screen, top, left, width, height } = options;
+
+  const box = blessed.box({
+    top,
+    left,
+    width,
+    height,
+    label: ' CPU ',
+    tags: true,
+    border: { type: 'line' },
+    style: {
+      border: { fg: 'cyan' },
+      label: { fg: 'cyan', bold: true },
+    },
+    padding: { top: 0, left: 1, right: 1, bottom: 0 },
+  });
+
+  screen.append(box as unknown as import('blessed').BlessedElement);
+
+  function renderMetrics(metrics: CpuMetrics): void {
+    const innerWidth = (typeof width === 'string' ? box.width : width as number) - 4;
+    const barWidth = Math.max(10, innerWidth - 14); // reserve space for label + percent
+
+    function makeLine(label: string, usage: number): string {
+      const filled = Math.round((Math.min(100, usage) / 100) * barWidth);
+      const empty = barWidth - filled;
+      const barColor = usage >= 85 ? '{red-fg}' : usage >= 60 ? '{yellow-fg}' : '{green-fg}';
+      const bar = `${barColor}${'█'.repeat(filled)}{/}${'░'.repeat(empty)}`;
+      const pct = colorPercent(usage);
+      return ` ${label.padEnd(8)} ${bar} ${pct}`;
+    }
+
+    const lines: string[] = [
+      makeLine('Overall', metrics.usage),
+      '',
+      ...metrics.cores.slice(0, 8).map(c => makeLine(`Core ${c.index}`, c.usage)),
+    ];
+
+    if (metrics.cores.length > 8) {
+      lines.push(` {gray-fg}  ... +${metrics.cores.length - 8} cores{/gray-fg}`);
+    }
+
+    lines.push('');
+    lines.push(` {gray-fg}Model: ${metrics.model}{/gray-fg}`);
+
+    box.setContent(lines.join('\n'));
+    screen.render();
+  }
+
+  // Paint immediately if state is already populated (re-mount case)
+  const initial = getCpuMetrics();
+  if (initial) renderMetrics(initial);
+
+  const unsub = bus.on('metrics:cpu:updated', renderMetrics);
+
+  function destroy(): void {
+    unsub();
+    box.destroy();
+  }
+
+  return { box: box as unknown as Box, destroy };
+}