pyre-cli 3.4.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyre-cli",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "CLI Mac monitoring tool: temps, system stats, live dashboard, packet monitor, battery predictor, export",
   "main": "dist/index.js",
   "type": "module",

package/src/formatters/formatters.md

@@ -0,0 +1,164 @@
+# src/formatters/ — Dashboard Formatting Module
+
+The formatters module is responsible for turning raw system-metric data (`StatsData`) into styled terminal output. It provides three categories of functionality:
+
+1. **Dashboard rendering** — `formatTable` draws the full terminal dashboard with panels, cards, tables, and tab navigation.
+2. **Data export** — `formatJson`, `formatCsv`, `formatTsv` serialise a `StatsData` snapshot to structured text formats.
+3. **Graph rendering** — `formatGraphs` draws sparkline/bar graphs of historical metrics.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel export — re-exports all public functions and types |
+| `types.ts` | Public-facing type definitions (`StatsData`, `VisibleItems`, `TableOptions`, `ThemeColors`, `ThemeName`) |
+| `themes.ts` | Six built-in colour themes (`THEMES` record) mapping UI roles to chalk colour functions |
+| `render.ts` | Core dashboard rendering: panels, cards, tables, tab bar, process tree, and the `formatTable` orchestrator |
+| `output.ts` | JSON/CSV/TSV serialisation and sparkline/bar graph rendering |
+
+## External Dependencies
+
+The formatters module imports from two sibling modules:
+
+- **`src/monitors/types.ts`** — defines `StatsData`, the aggregate data structure that every formatter consumes.
+- **`src/history.ts`** — defines the `History` class, a rolling window of metric samples used by `formatGraphs`.
+- **`src/sparkline.ts`** — exports the `sparkline()` function that renders Unicode block-character sparklines.
+
+## `index.ts` — Barrel Exports
+
+Re-exports everything public from the sub-modules:
+
+- From `render.ts`: `formatTable`, `clampWidth`, `gridColumns`, `thermalColor`, `capacityColor`, `getTabHitboxes`, `TAB_BAR_ROW`, `TAB_DEFS`, `panel`
+- From `output.ts`: `formatJson`, `formatCsv`, `formatTsv`, `formatGraphs`
+- From `types.ts`: `ThemeName`, `ThemeColors`, `VisibleItems`, `TableOptions` (types only)
+- From `themes.ts`: `THEMES`
+
+## `types.ts` — Public Type Definitions
+
+Defines the interfaces that control dashboard layout and visibility. All types are re-exported from `index.ts`.
+
+### `ThemeName`
+Union type re-exported from `themes.ts`: `'default' | 'dracula' | 'cyberpunk' | 'monochrome' | 'nord' | 'gruvbox'`.
+
+### `ThemeColors`
+Interface mapping 11 UI element roles to chalk colour functions: `border`, `cpu`, `mem`, `gpu`, `power`, `battery`, `thermal`, `network`, `disk`, `graphs`, `process`.
+
+### `VisibleItems`
+Optional boolean flags controlling which dashboard cards are shown. All default to visible when `undefined`:
+- `cpu`, `mem`, `gpu`, `power`, `battery`, `thermal`, `network`, `packets`, `tasks`, `disk`, `process`, `tree`
+
+### `TableOptions`
+Options object for `formatTable`:
+- `width?` — terminal width in columns (default 80, clamped to 60–240)
+- `sortBy?` — process sort key: `'cpu' | 'mem' | 'pid' | 'user' | 'command' | 'state' | 'threads' | 'runtime'`
+- `filter?` — case-insensitive substring filter on process command
+- `processLimit?` — max process rows to display
+- `theme?` — visual theme name
+- `visible?` — `VisibleItems` override
+- `treeView?` — show process tree instead of flat table
+- `activePanel?` — detail panel to show: `'grid' | 'cpu' | 'mem' | 'gpu' | 'power' | 'battery' | 'thermal' | 'network' | 'packets' | 'tasks' | 'disk' | 'process'`
+
+### `StatsData` (re-exported from `monitors/types.ts`)
+The aggregate data structure consumed by all formatters. Contains: `header`, `cpu`, `gpu`, `memory`, `disk`, `battery`, `thermal`, `network`, `processes`, `power`, `timestamp`, `packets`, `tasks`.
+
+## `themes.ts` — Colour Themes
+
+Exports `THEMES`, a `Record<ThemeName, ThemeColors>` containing six built-in themes. Each theme maps the 11 UI roles to a chalk colour function.
+
+### Built-in Themes
+
+| Theme | Description |
+|-------|-------------|
+| `default` | Muted greys and cyan accents; safe for any terminal |
+| `dracula` | Popular Dracula dark palette |
+| `cyberpunk` | High-contrast neon on black |
+| `monochrome` | White-only; useful for colour-blind users or terminals without 256-colour support |
+| `nord` | Nord colour palette |
+| `gruvbox` | Gruvbox retro colour palette |
+
+Each theme's `ThemeColors` object has keys: `border`, `cpu`, `mem`, `gpu`, `power`, `battery`, `thermal`, `network`, `disk`, `graphs`, `process`.
+
+## `render.ts` — Dashboard Rendering
+
+The largest file in the module (660 lines). Contains every function that turns a `StatsData` snapshot into styled terminal output.
+
+### Low-Level Utilities
+
+- `visLen(s: string): number` — computes the visible length of a string by stripping ANSI escape codes.
+- `padVisible(s: string, width: number): string` — pads a string with spaces to a target visible width.
+- `truncatePlain(s: string, width: number): string` — truncates a plain string with `…` if it exceeds `width`.
+
+### Panel & Layout
+
+- `panel(title, lines, width, accent, borderAccent, height?): string[]` — draws a rounded panel box of exactly `width` columns. Returns an array of strings (one per line).
+- `hstack(blocks, gap?): string[]` — joins equal-or-uneven-height panel blocks side by side with a gap.
+- `statRow(label, value, width?): string` — renders a label/value pair with dim label.
+- `gaugeRow(label, percent, contentWidth): string` — renders a horizontal bar gauge.
+- `bar(percent, width?): string` — renders a filled/empty block bar coloured by threshold.
+
+### Colour Helpers
+
+- `thermalColor(pressureLevel: number): Chalk` — maps 0–3 pressure level to green/yellow/yellowBright/red.
+- `capacityColor(percent: number): Chalk` — maps battery capacity to red (<80%)/yellow (<90%)/green.
+- `formatBytes(bytes: number): string` — converts bytes to human-readable `B`/`KB`/`MB`/`GB`.
+- `celsiusToFahrenheit(c: number): number` — converts °C to °F.
+- `formatTemp(c: number): string` — renders `"62.0°C / 143.6°F"`.
+
+### Card Renderers (each returns `string[] | null`)
+
+- `cpuCard(data, contentWidth)` — brand, cores, frequency, usage gauge, load avg, optional temp.
+- `memCard(data, contentWidth)` — total, used, cached, free, usage gauge, swap.
+- `gpuCard(data, contentWidth)` — model, memory, utilization, optional temp, process count. Returns `null` if no GPU data.
+- `powerCard(data)` — CPU/GPU/combined watts, battery watts if discharging. Returns `null` if no power data.
+- `batteryCard(data, contentWidth)` — level/state, time remaining, cycles, condition, capacity, source, estimated empty, discharge rate. Returns `null` if no battery data.
+- `thermalCard(data, contentWidth)` — state (coloured by pressure), per-sensor temps, optional error.
+- `networkCard(data, contentWidth)` — interface name/IP, RX/TX bytes and packets.
+- `packetCard(data, contentWidth)` — total/rx/tx packets, connections, top process, interface count. Returns `null` if no packet data.
+- `tasksCard(data, contentWidth)` — up to 6 tasks with pid, user, cpu%, mem%, state, command. Returns `null` if no tasks.
+
+### Table Renderers
+
+- `processTableLines(processes, contentWidth, borderAccent?): string[]` — renders a fixed-column process table with PID, PPID, USER, CPU%, MEM%, STATE, THREADS, RUNTIME, COMMAND columns. Colour-codes CPU% and MEM% by threshold.
+- `diskTableLines(disks, contentWidth, borderAccent?): string[]` — renders a filesystem table with FILESYSTEM, SIZE, USED, AVAIL, CAP, MOUNT columns. Colour-codes capacity by threshold.
+- `buildProcessTree(processes): string[]` — renders a tree view of processes using Unicode box-drawing characters, sorted by CPU usage within each subtree.
+
+### Tab Bar
+
+- `TAB_DEFS` — canonical array of 12 tab definitions: `{ id, label, key }` mapping panel IDs to display labels and keyboard shortcuts (1–9, 0, P, R).
+- `TAB_BAR_ROW` — constant `4` (1-indexed terminal row where the tab bar renders).
+- `getTabHitboxes(): { id, start, end }[]` — computes column ranges for each tab so mouse clicks can be mapped back to panel IDs.
+- `tabBar(activePanel, width, theme): string` — renders the tab bar line with active tab bold and inactive tabs dim.
+
+### Header
+
+- `header(data, width, badges?, borderAccent?): string[]` — renders the top header line with PYRE branding, hostname, OS, uptime, current time, and optional badges.
+
+### Main Orchestrator
+
+- `formatTable(data, opts?): string` — the primary entry point for dashboard rendering.
+  1. Clamps width via `clampWidth`.
+  2. If `activePanel !== 'grid'`, renders a single detail panel for that tab.
+  3. If `activePanel === 'grid'`, lays out visible cards in a grid (1–3 columns depending on width via `gridColumns`), then optionally appends Disk and Process panels.
+  4. Process panel supports `filter`, `sortBy`, `processLimit`, and `treeView` options.
+
+### Exported Helpers
+
+- `clampWidth(width?): number` — clamps terminal width to 60–240, defaulting to 80.
+- `gridColumns(width: number): number` — returns 1/2/3 cards per row based on width thresholds (≥150→3, ≥96→2, else 1).
+
+## `output.ts` — Data Export & Graphs
+
+### Export Functions
+
+- `formatJson(data: StatsData): string` — serialises `StatsData` to pretty-printed JSON (2-space indent).
+- `formatCsv(data: StatsData): string` — serialises `StatsData` to CSV with a `property,key,value` header row. Includes all fields from cpu, memory, thermal, network, battery, power, system, packets (if present), gpu (if present), and every process (pid, ppid, user, cpu, mem, state, threads, runtime, command). String values are double-quote-escaped.
+- `formatTsv(data: StatsData): string` — converts CSV output to TSV by replacing commas with tabs.
+
+### Graph Rendering
+
+- `formatGraphs(history, width?, themeName?, graphMode?): string` — renders a panel of sparkline/bar graphs for CPU, memory, temperature, network RX/TX, power, and packet rates. Uses `panel()` for the border and `graphRow()` for each metric line.
+
+### Internal Helpers
+
+- `graphRow(label, values, bounds, fmt, sparkWidth?, emptyMessage?, mode?): string` — renders a single graph line with label, sparkline/bar, and current value. Colour-codes by percentage of the bounds range.
+- `barGraph(values, bounds, width): string` — renders a bar-graph using Unicode block characters (`█` `▇` `▆` `▄` ` `).

package/src/formatters/output.ts

@@ -104,21 +104,21 @@ export function formatGraphs(history: History, width = 80, themeName: ThemeName
   const sparkWidth = Math.max(10, contentWidth - 28);
 
   const lines: string[] = [];
-  lines.push(graphRow('CPU %', history.cpuUsage, { min: 0, max: 100 }, v => `${v.toFixed(0)}%`, sparkWidth, graphMode));
-  lines.push(graphRow('Mem %', history.memUsage, { min: 0, max: 100 }, v => `${v.toFixed(0)}%`, sparkWidth, graphMode));
+  lines.push(graphRow('CPU %', history.cpuUsage, { min: 0, max: 100 }, v => `${v.toFixed(0)}%`, sparkWidth, 'collecting data...', graphMode));
+  lines.push(graphRow('Mem %', history.memUsage, { min: 0, max: 100 }, v => `${v.toFixed(0)}%`, sparkWidth, 'collecting data...', graphMode));
   lines.push(
     graphRow('Temp', history.temp, {}, formatTemp, sparkWidth, 'no sensor access (needs sudo powermetrics)', graphMode)
   );
-  lines.push(graphRow('Net RX/s', history.netRxRate, {}, v => `${formatBytes(v)}/s`, sparkWidth, graphMode));
-  lines.push(graphRow('Net TX/s', history.netTxRate, {}, v => `${formatBytes(v)}/s`, sparkWidth, graphMode));
+  lines.push(graphRow('Net RX/s', history.netRxRate, {}, v => `${formatBytes(v)}/s`, sparkWidth, 'collecting data...', graphMode));
+  lines.push(graphRow('Net TX/s', history.netTxRate, {}, v => `${formatBytes(v)}/s`, sparkWidth, 'collecting data...', graphMode));
   if (history.powerWatts.length) {
-    lines.push(graphRow('Power W', history.powerWatts, {}, v => `${v.toFixed(1)} W`, sparkWidth, graphMode));
+    lines.push(graphRow('Power W', history.powerWatts, {}, v => `${v.toFixed(1)} W`, sparkWidth, 'collecting data...', graphMode));
   }
   if (history.rxPacketRate.length) {
-    lines.push(graphRow('RX pkt/s', history.rxPacketRate, {}, v => `${v.toFixed(0)} pkt/s`, sparkWidth, graphMode));
+    lines.push(graphRow('RX pkt/s', history.rxPacketRate, {}, v => `${v.toFixed(0)} pkt/s`, sparkWidth, 'collecting data...', graphMode));
   }
   if (history.txPacketRate.length) {
-    lines.push(graphRow('TX pkt/s', history.txPacketRate, {}, v => `${v.toFixed(0)} pkt/s`, sparkWidth, graphMode));
+    lines.push(graphRow('TX pkt/s', history.txPacketRate, {}, v => `${v.toFixed(0)} pkt/s`, sparkWidth, 'collecting data...', graphMode));
   }
 
   const title = `Graphs · mode:${graphMode} · last ${sampleCount} sample${sampleCount === 1 ? '' : 's'}`;
@@ -151,8 +151,14 @@ function graphRow(
 }
 
 function barGraph(values: number[], bounds: { min?: number; max?: number }, width: number): string {
-  const min = bounds.min ?? Math.min(...values);
-  const max = bounds.max ?? Math.max(...values);
+  let min = bounds.min ?? Infinity;
+  let max = bounds.max ?? -Infinity;
+  if (bounds.min === undefined || bounds.max === undefined) {
+    for (const v of values) {
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
   const range = max - min || 1;
   return values.map(v => {
     const pct = (v - min) / range;

package/src/formatters/render.ts

@@ -56,7 +56,7 @@ export function panel(
 }
 
 /** Join equal-or-uneven-height panel blocks side by side with a gap. */
-function hstack(blocks: string[][], gap = 2): string[] {
+function hstack(blocks: string[][], gap = 2, targetWidth?: number): string[] {
   if (!blocks.length) return [];
   const height = Math.max(...blocks.map(b => b.length));
   const widths = blocks.map(b => visLen(b[0] ?? ''));
@@ -68,7 +68,12 @@ function hstack(blocks: string[][], gap = 2): string[] {
   });
   const out: string[] = [];
   for (let row = 0; row < height; row++) {
-    out.push(padded.map(a => a[row]).join(' '.repeat(gap)));
+    let line = padded.map(a => a[row]).join(' '.repeat(gap));
+    if (targetWidth !== undefined) {
+      const pad = Math.max(0, targetWidth - visLen(line));
+      line += ' '.repeat(pad);
+    }
+    out.push(line);
   }
   return out;
 }
@@ -393,36 +398,54 @@ function processTableLines(
    return `${hrs}h ${mins % 60}m`;
  }
 
- function buildProcessTree(
+function buildProcessTree(
    processes: { pid: number; ppid: number; user: string; cpu: number; mem: number; command: string; state: string; threads: number; runtime: number }[]
- ): string[] {
+  ): string[] {
    const map = new Map<number, typeof processes[0]>();
    const roots: typeof processes[0][] = [];
    for (const p of processes) map.set(p.pid, p);
    for (const p of processes) {
      if (p.ppid === 0 || !map.has(p.ppid)) roots.push(p);
    }
-   const lines: string[] = [];
-   const visited = new Set<number>();
-   function renderNode(proc: typeof processes[0], prefix: string, isLast: boolean) {
-     if (visited.has(proc.pid)) return;
-     visited.add(proc.pid);
-     const connector = isLast ? '└── ' : '├── ';
-    const pidStr = String(proc.pid).padEnd(8);
-      const cpuStr = pctColor(proc.cpu)(`${proc.cpu.toFixed(1)}%`.padEnd(8));
-      const memStr = pctColor(proc.mem)(`${proc.mem.toFixed(1)}%`.padEnd(8));
-      const stateStr = chalk.dim(proc.state.padEnd(8));
-      const thrStr = String(proc.threads).padEnd(6);
-
-     const cmd = truncatePlain(proc.command, Math.max(10, 100 - pidStr.length - cpuStr.length - memStr.length - stateStr.length - thrStr.length - 10));
-     lines.push(`${prefix}${connector}${pidStr}${cpuStr}${memStr}${stateStr}${thrStr} ${cmd}`);
-     const children = processes.filter(p => p.ppid === proc.pid && !visited.has(p.pid));
-     children.sort((a, b) => b.cpu - a.cpu);
-     children.forEach((child, i) => {
-       const nextPrefix = prefix + (isLast ? '    ' : '│   ');
-       renderNode(child, nextPrefix, i === children.length - 1);
-     });
+
+   const childrenMap = new Map<number, typeof processes[0][]>();
+   for (const p of processes) {
+     const list = childrenMap.get(p.ppid) || [];
+     list.push(p);
+     childrenMap.set(p.ppid, list);
    }
+   for (const list of childrenMap.values()) {
+     list.sort((a, b) => b.cpu - a.cpu);
+   }
+
+    const lines: string[] = [];
+    const visited = new Set<number>();
+    function renderNode(proc: typeof processes[0], prefix: string, isLast: boolean) {
+      if (visited.has(proc.pid)) return;
+      visited.add(proc.pid);
+      const connector = isLast ? '└── ' : '├── ';
+     const pidStr = String(proc.pid).padEnd(8);
+       const cpuStr = pctColor(proc.cpu)(`${proc.cpu.toFixed(1)}%`.padEnd(8));
+       const memStr = pctColor(proc.mem)(`${proc.mem.toFixed(1)}%`.padEnd(8));
+       const stateStr = chalk.dim(proc.state.padEnd(8));
+       const thrStr = String(proc.threads).padEnd(6);
+
+      const cmd = truncatePlain(proc.command, Math.max(10, 100 - pidStr.length - cpuStr.length - memStr.length - stateStr.length - thrStr.length - 10));
+      lines.push(`${prefix}${connector}${pidStr}${cpuStr}${memStr}${stateStr}${thrStr} ${cmd}`);
+      const children = childrenMap.get(proc.pid);
+      if (children) {
+        let idx = 0;
+        let total = 0;
+        for (const c of children) {
+          if (!visited.has(c.pid)) total++;
+        }
+        for (const child of children) {
+          if (visited.has(child.pid)) continue;
+          const nextPrefix = prefix + (isLast ? '    ' : '│   ');
+          renderNode(child, nextPrefix, ++idx === total);
+        }
+      }
+    }
    roots.sort((a, b) => b.cpu - a.cpu);
    roots.forEach((root, i) => renderNode(root, '', i === roots.length - 1));
    return lines;
@@ -478,8 +501,10 @@ function detailPanelTitle(panel: string): string {
   return map[panel] || panel;
 }
 
-function activeDetailLines(data: StatsData, activePanel: string, width: number): string[] | null {
+function activeDetailLines(data: StatsData, activePanel: string, width: number, opts: TableOptions = {}): string[] | null {
   const contentWidth = width - 4;
+  const themeName = opts.theme || 'default';
+  const theme = THEMES[themeName] || THEMES.default;
   switch (activePanel) {
     case 'cpu':
       return cpuCard(data, contentWidth);
@@ -529,10 +554,17 @@ function activeDetailLines(data: StatsData, activePanel: string, width: number):
     case 'tasks':
       return data.tasks?.length ? tasksCard(data, contentWidth) : ['No task data available'];
     case 'disk':
-      return data.disk.length ? diskTableLines(data.disk, width - 4, THEMES.default.border) : ['No disk data available'];
+      return data.disk.length ? diskTableLines(data.disk, width - 4, theme.border) : ['No disk data available'];
     case 'process': {
-      const sorted = sortProcesses([...data.processes], 'cpu');
-      return processTableLines(sorted.slice(0, 50), width - 4, THEMES.default.border);
+      const filtered = opts.filter
+        ? data.processes.filter(p => p.command.toLowerCase().includes(opts.filter!.toLowerCase()))
+        : data.processes;
+      const sorted = sortProcesses(filtered, opts.sortBy ?? 'cpu');
+      const limited = opts.processLimit ? sorted.slice(0, opts.processLimit) : sorted;
+      if (opts.treeView) {
+        return buildProcessTree(limited);
+      }
+      return processTableLines(limited, width - 4, theme.border);
     }
     default:
       return null;
@@ -558,7 +590,7 @@ export function formatTable(data: StatsData, opts: TableOptions = {}): string {
   out.push('');
 
   if (activePanel !== 'grid') {
-    const lines = activeDetailLines(data, activePanel, width);
+    const lines = activeDetailLines(data, activePanel, width, opts);
     if (lines) {
       out.push(...panel(detailPanelTitle(activePanel), lines, width, theme[activePanel as keyof ThemeColors] ?? theme.cpu, theme.border));
     }
@@ -601,13 +633,13 @@ export function formatTable(data: StatsData, opts: TableOptions = {}): string {
     if (tasks) cards.push({ title: 'Tasks', accent: theme.process, lines: tasks });
   }
 
-  for (let i = 0; i < cards.length; i += columns) {
-    const row = cards.slice(i, i + columns);
-    const rowHeight = Math.max(...row.map(c => c.lines.length));
-    const blocks = row.map(c => panel(c.title, c.lines, cardWidth, c.accent, theme.border, rowHeight));
-    out.push(...hstack(blocks, gap));
-    out.push('');
-  }
+   for (let i = 0; i < cards.length; i += columns) {
+     const row = cards.slice(i, i + columns);
+     const rowHeight = Math.max(...row.map(c => c.lines.length));
+     const blocks = row.map(c => panel(c.title, c.lines, cardWidth, c.accent, theme.border, rowHeight));
+     out.push(...hstack(blocks, gap, width));
+     out.push('');
+   }
 
   if (vis.disk !== false && data.disk.length) {
     const dw = width - 4;

package/src/history.ts

@@ -16,6 +16,9 @@ export class History {
   /** Maximum number of samples retained in the rolling window. */
   maxLen: number;
 
+  /** Monotonically increasing version, bumped on every push. */
+  version = 0;
+
   /** Rolling window of CPU usage percentages (0–100). */
   cpuUsage: number[] = [];
 
@@ -113,6 +116,8 @@ export class History {
       if (sample.rxPackets !== undefined) this.pushBounded(this.rxPacketRate, rxPktRate);
       if (sample.txPackets !== undefined) this.pushBounded(this.txPacketRate, txPktRate);
       if (sample.connections !== undefined) this.pushBounded(this.connections, sample.connections);
+
+      this.version++;
     }
 
     /** Clear all rolling windows and reset cumulative byte counters. */
@@ -132,6 +137,7 @@ export class History {
       this.lastRxPackets = 0;
       this.lastTxPackets = 0;
       this.lastTs = 0;
+      this.version = 0;
     }
 
    /**