metwatch 0.1.0

package/src/services/system.service.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// System Service
+//
+// Pure async functions that fetch raw data from systeminformation and
+// normalize it into MetWatch domain types. This is the ONLY place in the
+// codebase that imports systeminformation. Swap the data source here without
+// touching anything else.
+//
+// All functions are stateless and have no side-effects beyond network/OS I/O.
+// ---------------------------------------------------------------------------
+
+import si from 'systeminformation';
+import type { CpuMetrics, MemoryMetrics } from '../types/metrics.types.ts';
+
+// Cache CPU model to avoid redundant si.cpu() calls on every tick
+let _cpuModelCache: string | null = null;
+
+async function resolveCpuModel(): Promise<string> {
+  if (_cpuModelCache) return _cpuModelCache;
+  try {
+    const info = await si.cpu();
+    _cpuModelCache = `${info.manufacturer} ${info.brand}`.trim() || 'Unknown CPU';
+  } catch {
+    _cpuModelCache = 'Unknown CPU';
+  }
+  return _cpuModelCache;
+}
+
+// ── CPU ───────────────────────────────────────────────────────────────────────
+
+export async function fetchCpuMetrics(): Promise<CpuMetrics> {
+  const [load, model] = await Promise.all([si.currentLoad(), resolveCpuModel()]);
+
+  return {
+    usage: Math.round(load.currentLoad * 10) / 10,
+    cores: load.cpus.map((core, index) => ({
+      index,
+      usage: Math.round(core.load * 10) / 10,
+    })),
+    model,
+    coreCount: load.cpus.length,
+    timestamp: Date.now(),
+  };
+}
+
+// ── Memory ────────────────────────────────────────────────────────────────────
+
+export async function fetchMemoryMetrics(): Promise<MemoryMetrics> {
+  const mem = await si.mem();
+
+  const used = mem.active; // active is more accurate than total - free
+  const percent = mem.total > 0 ? Math.round((used / mem.total) * 1000) / 10 : 0;
+
+  return {
+    total: mem.total,
+    used,
+    free: mem.available,
+    percent,
+    active: mem.active,
+    cached: mem.cached,
+    timestamp: Date.now(),
+  };
+}

package/src/types/blessed.d.ts

@@ -0,0 +1,332 @@
+// ---------------------------------------------------------------------------
+// Ambient declarations for blessed and blessed-contrib
+//
+// We use a local declaration file instead of @types/blessed because:
+//   1. @types/blessed (0.1.20, 2019) predates many blessed APIs and conflicts
+//      with Bun's bundler module resolution.
+//   2. We only need the subset of the API that MetWatch actually uses.
+//   3. This file is authoritative and won't drift when npm packages change.
+//
+// Add declarations here as new blessed features are consumed.
+// ---------------------------------------------------------------------------
+
+declare module 'blessed' {
+  import { EventEmitter } from 'events';
+
+  // ── Style objects ─────────────────────────────────────────────────────────
+
+  interface BorderStyle {
+    type?: 'line' | 'bg';
+    fg?: string;
+    bg?: string;
+  }
+
+  interface ScrollbarStyle {
+    ch?: string;
+    fg?: string;
+    bg?: string;
+    track?: { bg?: string; fg?: string };
+  }
+
+  interface ElementStyle {
+    fg?: string;
+    bg?: string;
+    bold?: boolean;
+    underline?: boolean;
+    border?: BorderStyle;
+    scrollbar?: ScrollbarStyle;
+    label?: Partial<ElementStyle>;
+    focus?: Partial<ElementStyle>;
+    hover?: Partial<ElementStyle>;
+    selected?: Partial<ElementStyle>;
+    item?: Partial<ElementStyle>;
+    header?: Partial<ElementStyle>;
+    cell?: Partial<ElementStyle>;
+    bar?: Partial<ElementStyle>;
+  }
+
+  // ── Options ───────────────────────────────────────────────────────────────
+
+  interface ScreenOptions {
+    smartCSR?: boolean;
+    fastCSR?: boolean;
+    fullUnicode?: boolean;
+    dockBorders?: boolean;
+    title?: string;
+    debug?: boolean;
+    ignoreLocked?: string[];
+    autoPadding?: boolean;
+  }
+
+  interface ElementOptions {
+    parent?: BlessedElement | BlessedScreen;
+    top?: number | string;
+    left?: number | string;
+    width?: number | string;
+    height?: number | string;
+    right?: number | string;
+    bottom?: number | string;
+    content?: string;
+    label?: string;
+    tags?: boolean;
+    border?: BorderStyle | { type: string };
+    style?: ElementStyle;
+    scrollable?: boolean;
+    alwaysScroll?: boolean;
+    scrollbar?: ScrollbarStyle | boolean;
+    keys?: boolean;
+    vi?: boolean;
+    mouse?: boolean;
+    hidden?: boolean;
+    padding?: number | { top?: number; right?: number; bottom?: number; left?: number };
+    shrink?: boolean;
+    focusable?: boolean;
+    input?: boolean;
+    clickable?: boolean;
+    interactive?: boolean;
+  }
+
+  interface BoxOptions extends ElementOptions {}
+
+  interface ListOptions extends ElementOptions {
+    items?: string[];
+    invertSelected?: boolean;
+  }
+
+  interface ListTableOptions extends ElementOptions {
+    data?: string[][];
+    rows?: string[][];
+    pad?: number;
+    noCellBorders?: boolean;
+    fillCellBorders?: boolean;
+  }
+
+  interface LogOptions extends ElementOptions {
+    scrollback?: number;
+    scrollOnInput?: boolean;
+  }
+
+  interface ProgressBarOptions extends ElementOptions {
+    orientation?: 'horizontal' | 'vertical';
+    pch?: string;
+    filled?: number;
+    value?: number;
+  }
+
+  interface QuestionOptions extends ElementOptions {}
+  interface MessageOptions extends ElementOptions {}
+
+  // ── Elements ──────────────────────────────────────────────────────────────
+
+  class BlessedElement extends EventEmitter {
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    content: string;
+    hidden: boolean;
+
+    setContent(text: string): void;
+    getContent(): string;
+    setText(text: string): void;
+    setLabel(text: string): void;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    focus(): void;
+    render(): void;
+    destroy(): void;
+    key(keys: string | string[], handler: (ch: string, key: KeyEvent) => void): void;
+    onceKey(keys: string | string[], handler: (ch: string, key: KeyEvent) => void): void;
+    unkey(keys: string | string[], handler: (ch: string, key: KeyEvent) => void): void;
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    append(child: BlessedElement): void;
+    remove(child: BlessedElement): void;
+  }
+
+  class BlessedScreen extends BlessedElement {
+    cols: number;
+    rows: number;
+    focused: BlessedElement;
+
+    render(): void;
+    destroy(): void;
+    key(keys: string | string[], handler: (ch: string, key: KeyEvent) => void): void;
+    append(child: BlessedElement): void;
+    remove(child: BlessedElement): void;
+  }
+
+  class Box extends BlessedElement {
+    constructor(options?: BoxOptions);
+  }
+
+  class Log extends BlessedElement {
+    constructor(options?: LogOptions);
+    log(text: string): void;
+    add(text: string): void;
+  }
+
+  class ListTable extends BlessedElement {
+    constructor(options?: ListTableOptions);
+    setData(data: string[][]): void;
+    setRows(rows: string[][]): void;
+  }
+
+  class ProgressBar extends BlessedElement {
+    constructor(options?: ProgressBarOptions);
+    setProgress(amount: number): void;
+    progress(amount: number): void;
+    reset(): void;
+  }
+
+  class Question extends BlessedElement {
+    constructor(options?: QuestionOptions);
+    ask(question: string, callback: (err: Error | null, value: boolean) => void): void;
+  }
+
+  class Message extends BlessedElement {
+    constructor(options?: MessageOptions);
+    display(text: string, time: number, callback?: () => void): void;
+    error(text: string, time: number, callback?: () => void): void;
+  }
+
+  // ── Keyboard event ────────────────────────────────────────────────────────
+
+  interface KeyEvent {
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    sequence: string;
+    full: string;
+  }
+
+  // ── Factory functions ─────────────────────────────────────────────────────
+
+  function screen(options?: ScreenOptions): BlessedScreen;
+  function box(options?: BoxOptions): Box;
+  function log(options?: LogOptions): Log;
+  function listtable(options?: ListTableOptions): ListTable;
+  function progressbar(options?: ProgressBarOptions): ProgressBar;
+  function question(options?: QuestionOptions): Question;
+  function message(options?: MessageOptions): Message;
+}
+
+declare module 'blessed-contrib' {
+  import type { BlessedElement, BlessedScreen, ElementOptions } from 'blessed';
+
+  // ── Grid ──────────────────────────────────────────────────────────────────
+
+  interface GridOptions {
+    rows: number;
+    cols: number;
+    screen: BlessedScreen;
+    hideBorder?: boolean;
+    color?: string;
+  }
+
+  type WidgetConstructor<T> = new (options: ElementOptions) => T;
+
+  class grid {
+    constructor(options: GridOptions);
+    set<T extends BlessedElement>(
+      row: number,
+      col: number,
+      rowSpan: number,
+      colSpan: number,
+      widget: WidgetConstructor<T> | ((options: ElementOptions) => T),
+      options: Record<string, unknown>
+    ): T;
+  }
+
+  // ── Gauge ─────────────────────────────────────────────────────────────────
+
+  interface GaugeOptions extends ElementOptions {
+    label?: string;
+    stroke?: string;
+    fill?: string;
+    percent?: number;
+    showLabel?: boolean;
+  }
+
+  class gauge extends BlessedElement {
+    constructor(options?: GaugeOptions);
+    setPercent(percent: number): void;
+    setData(data: { percent: number; label?: string }): void;
+  }
+
+  // ── GaugeList (stacked gauges) ────────────────────────────────────────────
+
+  interface GaugeListOptions extends ElementOptions {
+    label?: string;
+    gauges?: Array<{ percent: number; stroke?: string; label?: string }>;
+  }
+
+  class gaugeList extends BlessedElement {
+    constructor(options?: GaugeListOptions);
+    setGauges(gauges: Array<{ percent: number; stroke?: string; label?: string }>): void;
+  }
+
+  // ── Table ─────────────────────────────────────────────────────────────────
+
+  interface TableOptions extends ElementOptions {
+    keys?: boolean;
+    vi?: boolean;
+    mouse?: boolean;
+    interactive?: boolean;
+    label?: string;
+    columnSpacing?: number;
+    columnWidth?: number[];
+  }
+
+  class table extends BlessedElement {
+    constructor(options?: TableOptions);
+    setData(data: { headers: string[]; data: string[][] }): void;
+  }
+
+  // ── Log ───────────────────────────────────────────────────────────────────
+
+  interface ContribLogOptions extends ElementOptions {
+    label?: string;
+    bufferLength?: number;
+    scrollbar?: { ch?: string };
+  }
+
+  class log extends BlessedElement {
+    constructor(options?: ContribLogOptions);
+    log(text: string): void;
+    add(text: string): void;
+  }
+
+  // ── Line chart ────────────────────────────────────────────────────────────
+
+  interface LineSeries {
+    title?: string;
+    x: string[];
+    y: number[];
+    style?: { line?: string };
+  }
+
+  interface LineOptions extends ElementOptions {
+    label?:          string;
+    showLegend?:     boolean;
+    legend?:         { width?: number };
+    xLabelPadding?:  number;
+    xPadding?:       number;
+    numYLabels?:     number;
+    showNthLabel?:   number;
+    wholeNumbersOnly?: boolean;
+    minY?:           number;
+    maxY?:           number;
+    style?: {
+      line?:     string | string[];
+      text?:     string;
+      baseline?: string;
+    };
+  }
+
+  class line extends BlessedElement {
+    constructor(options?: LineOptions);
+    setData(data: LineSeries | LineSeries[]): void;
+  }
+}

package/src/types/config.types.ts

@@ -0,0 +1,77 @@
+// ---------------------------------------------------------------------------
+// Config Types
+// Shape of metwatch.config.json. Loaded once at startup; changes require
+// restart. The config is intentionally flat and simple — no nested schemas.
+// ---------------------------------------------------------------------------
+
+import type { ManagedProcessDef } from './managed-process.types.ts';
+import type { PanelName }         from '../core/event-bus.ts';
+
+export interface WatchedProcess {
+  /** Process name to match (substring match against ProcessInfo.name) */
+  name: string;
+  /** Optional display label override shown in the Watched view */
+  label?: string;
+}
+
+/**
+ * Controls which panels are visible by default.
+ * Missing keys default to true (all panels shown on first launch).
+ * User can toggle panels with keyboard shortcuts at runtime.
+ */
+export type PanelVisibility = Partial<Record<PanelName, boolean>>;
+
+export interface MetWatchConfig {
+  /**
+   * Processes to highlight in the "Watched" view (f key).
+   * If empty, the watched view will show nothing until the user adds entries.
+   */
+  watchedProcesses: WatchedProcess[];
+  /**
+   * Polling interval in milliseconds.
+   * Minimum: 250ms. Default: 1000ms.
+   */
+  refreshInterval: number;
+  /**
+   * Maximum number of processes to display in the "All" view.
+   * Sorted by CPU descending before truncation. Default: 50.
+   */
+  maxProcesses: number;
+  /**
+   * Processes that MetWatch should launch and manage (like PM2).
+   * These are started automatically on TUI boot.
+   * CLI flags (--run) are merged in at runtime and take precedence.
+   */
+  managedProcesses: ManagedProcessDef[];
+  /**
+   * Number of log lines to keep in the circular buffer per managed process.
+   * Default: 500.
+   */
+  logScrollback: number;
+  /**
+   * Which panels are visible on startup.
+   * All panels default to visible if this key is omitted.
+   * Example: { "disk": false, "runtime": false }
+   */
+  panels: PanelVisibility;
+}
+
+/** Resolved config — all fields guaranteed (defaults merged in) */
+export type ResolvedConfig = Required<MetWatchConfig>;
+
+export const DEFAULT_CONFIG: ResolvedConfig = {
+  watchedProcesses: [],
+  refreshInterval:  1000,
+  maxProcesses:     50,
+  managedProcesses: [],
+  logScrollback:    500,
+  panels: {
+    cpu:       true,
+    memory:    true,
+    disk:      true,
+    network:   true,
+    runtime:   true,
+    processes: true,
+    logs:      true,
+  },
+};

package/src/types/managed-process.types.ts

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// Managed Process Types
+//
+// A "managed process" is a child process that MetWatch launched and owns —
+// distinct from the passive observation of system processes (ProcessInfo).
+//
+// Lifecycle:
+//   ManagedProcessDef  →  created at config / CLI parse time (static intent)
+//   ManagedProcess     →  runtime state wrapping the def (mutable, in launcher)
+// ---------------------------------------------------------------------------
+
+export type ManagedProcessStatus =
+  | 'running'
+  | 'stopped'
+  | 'crashed'
+  | 'restarting';
+
+/**
+ * Static definition of a process MetWatch should launch and manage.
+ * Comes from metwatch.config.json `managedProcesses[]` or CLI flags.
+ */
+export interface ManagedProcessDef {
+  /** Display label shown in the TUI. Defaults to command basename. */
+  name: string;
+  /** Executable to run: "bun", "node", "python", etc. */
+  command: string;
+  /** Arguments passed to the executable. */
+  args: string[];
+  /**
+   * Restart the process automatically on crash.
+   * Uses exponential back-off: 1s → 2s → 4s → 8s → 16s → 30s (cap).
+   * Counter resets if the process lives > 10s consecutively.
+   * Default: true
+   */
+  autoRestart: boolean;
+  /** Working directory for the child process. Defaults to process.cwd(). */
+  cwd?: string;
+  /** Additional environment variables merged into process.env. */
+  env?: Record<string, string>;
+}
+
+/**
+ * Runtime state for a managed process. Extends the static def with live data.
+ * Mutated by the launcher; never mutated by widgets or managers.
+ */
+export interface ManagedProcess extends ManagedProcessDef {
+  pid: number | null;
+  status: ManagedProcessStatus;
+  /** Total number of times this process has been restarted (crash or manual). */
+  restarts: number;
+  /** Unix ms when the current (or most recent) run started. */
+  startedAt: number | null;
+  /** Exit code of the most recent run. null if still running. */
+  exitCode: number | null;
+}