pyre-cli 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyre-cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI Mac monitoring tool: temps, system stats, live dashboard, and export",
   "main": "dist/index.js",
   "type": "module",
@@ -9,9 +9,12 @@
   },
   "files": [
     "dist",
+    "src",
+    "tsconfig.json",
     "install.sh",
     "Formula/pyre.rb",
-    "README.md"
+    "README.md",
+    "parity.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --clean",

package/parity.md

@@ -0,0 +1,542 @@
+btop is a **resource monitor and process manager** designed as a modern, interactive replacement for tools like `top` and `htop`. It combines a rich terminal UI with system telemetry, process control, graphs, and customization.
+
+Below is a comprehensive feature list.
+
+# btop Feature List
+
+## 1. User Interface (TUI) Features
+
+### Modern Terminal Dashboard
+
+* Full-screen terminal interface
+* Multi-panel dashboard layout
+* Real-time animated graphs
+* Color-coded status indicators
+* Smooth transitions and updates
+* Mouse interaction support
+* Keyboard-driven navigation
+* Responsive layout scaling
+* Unicode/ASCII rendering support
+* True-color terminal support
+
+### Main Dashboard Panels
+
+#### CPU Panel
+
+Displays:
+
+* Total CPU utilization
+* Per-core utilization
+* Core frequency
+* CPU temperature (when available)
+* CPU load averages
+* Process activity
+* CPU graph history
+
+Visualizations:
+
+* Per-core bar graphs
+* Historical usage graphs
+* Frequency indicators
+
+---
+
+#### Memory Panel
+
+Shows:
+
+* Total RAM
+* Used RAM
+* Available RAM
+* Cached memory
+* Buffers
+* Memory percentage
+* Swap usage
+
+Visualizations:
+
+* RAM usage bars
+* Swap graphs
+* Memory history
+
+---
+
+#### Disk Panel
+
+Displays:
+
+* Disk usage
+* Mounted drives
+* Used/free space
+* Read/write activity
+* I/O speed
+* Storage utilization
+
+Metrics:
+
+* Read throughput
+* Write throughput
+* Disk activity graphs
+
+---
+
+#### Network Panel
+
+Shows:
+
+* Upload speed
+* Download speed
+* Total transferred data
+* Network interface activity
+
+Metrics:
+
+* RX bandwidth
+* TX bandwidth
+* Packet activity
+* Network history graphs
+
+---
+
+#### Process Panel
+
+Displays:
+
+* Running processes
+* Process IDs
+* CPU usage
+* Memory usage
+* User
+* Command name
+* Process state
+* Threads
+
+---
+
+# 2. Process Management Features
+
+## Process Viewer
+
+Supports:
+
+* Real-time process list
+* Sorting processes
+* Searching processes
+* Filtering processes
+* Process tree view
+* Parent/child relationships
+* Process details
+
+---
+
+## Process Sorting
+
+Sort by:
+
+* CPU usage
+* Memory usage
+* PID
+* User
+* Command
+* Process state
+* Threads
+* Runtime
+
+---
+
+## Process Actions
+
+Can:
+
+* Kill processes
+* Send signals
+* Terminate applications
+* Force kill stuck processes
+
+Supported signals include:
+
+* SIGTERM
+* SIGKILL
+* SIGINT
+* SIGHUP
+* SIGSTOP
+* SIGCONT
+
+---
+
+# 3. Real-Time Monitoring
+
+## Live Updates
+
+Configurable:
+
+* Update interval
+* Graph refresh speed
+* Process refresh rate
+* Animation speed
+
+Default behavior:
+
+* Continuous monitoring
+* Low latency updates
+* Minimal CPU overhead
+
+---
+
+## Historical Graphs
+
+Provides:
+
+* CPU history
+* RAM history
+* Network history
+* Disk I/O history
+* Temperature history
+
+Graph features:
+
+* Scrolling history
+* Adjustable time window
+* Smooth rendering
+
+---
+
+# 4. Hardware Monitoring
+
+## CPU Monitoring
+
+Tracks:
+
+* CPU load
+* Per-thread activity
+* Core utilization
+* Frequency scaling
+* Load averages
+* CPU temperature (hardware dependent)
+
+---
+
+## Temperature Monitoring
+
+Supports:
+
+* CPU temperatures
+* Sensor readings
+* Thermal states
+
+Availability depends on:
+
+* OS
+* Hardware sensors
+* Permissions
+
+---
+
+## Battery Monitoring (Laptop)
+
+Displays:
+
+* Battery percentage
+* Charging state
+* Battery time remaining
+* Power consumption
+
+---
+
+# 5. macOS-Specific Features
+
+On macOS, btop can display:
+
+* Apple Silicon CPU information
+* Intel CPU information
+* Memory pressure data
+* Battery state
+* Disk statistics
+* Network statistics
+* Process information
+
+Supports:
+
+* Intel Macs
+* Apple Silicon Macs (M1/M2/M3/M4)
+
+---
+
+# 6. GPU Monitoring
+
+GPU support:
+
+Displays (when available):
+
+* GPU utilization
+* GPU memory usage
+* GPU temperature
+* GPU processes
+
+Support depends on:
+
+* Operating system APIs
+* GPU vendor
+* Drivers
+
+---
+
+# 7. Configuration Features
+
+## Fully Configurable UI
+
+Customize:
+
+* Colors
+* Themes
+* Layout
+* Display order
+* Graph styles
+* Update speed
+* Background style
+
+Configuration file:
+
+```
+~/.config/btop/btop.conf
+```
+
+---
+
+## Theme System
+
+Supports:
+
+* Built-in themes
+* Custom themes
+* User-created color schemes
+
+Theme file:
+
+```
+~/.config/btop/themes/
+```
+
+Examples:
+
+* Dracula style
+* Nord style
+* Monokai style
+* Solarized style
+
+---
+
+## Layout Customization
+
+Adjust:
+
+* Panel sizes
+* Visible modules
+* Graph types
+* Information density
+
+---
+
+# 8. Keyboard Controls
+
+Common shortcuts:
+
+| Key   | Action           |
+| ----- | ---------------- |
+| `Esc` | Close menu       |
+| `m`   | Main menu        |
+| `p`   | Process menu     |
+| `f`   | Filter processes |
+| `k`   | Kill process     |
+| `r`   | Reverse sorting  |
+| `c`   | Sort by CPU      |
+| `m`   | Sort by memory   |
+| `q`   | Quit             |
+
+Navigation:
+
+* Arrow keys
+* Page Up/Down
+* Mouse clicks
+
+---
+
+# 9. Technical Features
+
+## Cross Platform
+
+Supported:
+
+* macOS
+* Linux
+* FreeBSD
+
+---
+
+## Implementation
+
+Written in:
+
+* C++
+
+Uses:
+
+* Native OS APIs
+* Terminal rendering
+* Low-level system calls
+
+---
+
+## Performance
+
+Designed for:
+
+* Low CPU usage
+* Low memory usage
+* Fast startup
+* Efficient polling
+
+Typical resource usage:
+
+* Small RAM footprint
+* Minimal background overhead
+
+---
+
+# 10. Terminal Compatibility
+
+Works with:
+
+* Terminal.app
+* iTerm2
+* Ghostty
+* Alacritty
+* Kitty
+* WezTerm
+* tmux
+* SSH sessions
+
+Supports:
+
+* ANSI colors
+* Unicode
+* True color
+* 256-color terminals
+
+---
+
+# 11. Accessibility Features
+
+Includes:
+
+* High contrast themes
+* Adjustable colors
+* Keyboard-only operation
+* Configurable information density
+
+---
+
+# 12. Advanced Features
+
+## Mouse Support
+
+Allows:
+
+* Clicking panels
+* Selecting processes
+* Opening menus
+* Changing sorting
+
+---
+
+## Vim-Like Navigation
+
+Supports:
+
+* Keyboard navigation
+* Fast movement
+* Terminal workflow
+
+---
+
+## Process Tree
+
+Shows:
+
+```
+launchd
+ ├── Terminal
+ │    └── btop
+ └── Chrome
+      ├── Renderer
+      └── GPU Process
+```
+
+---
+
+## Secure Operation
+
+Features:
+
+* Does not require root for normal usage
+* Uses read-only system metrics by default
+* Only requires elevated privileges for certain actions
+
+---
+
+# 13. Developer / Sysadmin Features
+
+Useful for:
+
+### Debugging
+
+* CPU spikes
+* Memory leaks
+* Zombie processes
+* Runaway applications
+
+### Servers
+
+* SSH monitoring
+* Lightweight dashboards
+* Resource tracking
+
+### Development
+
+* Compiler monitoring
+* Docker workload observation
+* Build performance tracking
+
+---
+
+# 14. What btop Does NOT Do
+
+Compared to macOS Activity Monitor, btop does **not** provide:
+
+* App energy impact scoring
+* Detailed GPU history graphs on all Macs
+* Network connection inspector
+* Application sandbox details
+* Launch agent management
+* System extension management
+* Full disk/file activity tracing
+
+---
+
+# Feature Summary
+
+| Category      | Features                            |
+| ------------- | ----------------------------------- |
+| UI            | Animated TUI, graphs, colors, mouse |
+| CPU           | Cores, load, frequency, temperature |
+| Memory        | RAM, cache, swap                    |
+| Disk          | Usage, I/O, throughput              |
+| Network       | RX/TX monitoring                    |
+| Processes     | Search, sort, kill, tree            |
+| Hardware      | Sensors, battery, temperature       |
+| Customization | Themes, layouts, configs            |
+| Platforms     | macOS/Linux/FreeBSD                 |
+| Performance   | Lightweight, real-time              |
+| Terminal      | Ghostty/iTerm/Kitty compatible      |
+
+**In short:** btop is essentially a **terminal-native Activity Monitor** with a dashboard-first design, closer to a "cyberpunk system HUD" than the classic `top` experience.

package/src/formatters/index.ts

@@ -0,0 +1,17 @@
+/**
+ * pyre formatters module.
+ *
+ * Provides dashboard rendering (`formatTable`), data export
+ * (`formatJson`, `formatCsv`, `formatTsv`), and graph
+ * rendering (`formatGraphs`) for the live dashboard.
+ *
+ * The module is organised into four sub-files:
+ * - `types.ts`  — public-facing type definitions
+ * - `themes.ts` — colour theme definitions
+ * - `render.ts` — dashboard layout, cards, tables, and the main `formatTable`
+ * - `output.ts` — JSON/CSV/TSV export and sparkline graph rendering
+ */
+export { formatTable, clampWidth, gridColumns, thermalColor, capacityColor } from './render.js';
+export { formatJson, formatCsv, formatTsv, formatGraphs } from './output.js';
+export type { ThemeName, ThemeColors, VisibleItems, TableOptions } from './types.js';
+export { THEMES } from './themes.js';

package/src/formatters/output.ts

@@ -0,0 +1,137 @@
+/**
+ * Data-export and graph-rendering helpers.
+ *
+ * Provides JSON, CSV, and TSV serialisation of a
+ * {@link StatsData} snapshot, as well as sparkline-graph
+ * rendering for the live dashboard.
+ */
+import chalk from 'chalk';
+import { sparkline } from '../sparkline.js';
+import type { History } from '../history.js';
+import type { StatsData } from './types.js';
+import { THEMES, type ThemeName } from './themes.js';
+import { formatBytes, celsiusToFahrenheit, formatTemp } from './render.js';
+import { panel } from './render.js';
+
+export function formatJson(data: StatsData): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export function formatCsv(data: StatsData): string {
+  const rows: string[][] = [
+    ['property', 'key', 'value'],
+    ['cpu', 'brand', data.cpu.brand],
+    ['cpu', 'usage', String(data.cpu.usage)],
+    ['cpu', 'loadAvg_1m', String(data.cpu.loadAvg[0])],
+    ['cpu', 'loadAvg_5m', String(data.cpu.loadAvg[1])],
+    ['cpu', 'loadAvg_15m', String(data.cpu.loadAvg[2])],
+    ['memory', 'total', String(data.memory.total)],
+    ['memory', 'used', String(data.memory.used)],
+    ['memory', 'usagePercent', String(data.memory.usagePercent)],
+    ['memory', 'swapUsed', String(data.memory.swapUsed)],
+    ['memory', 'swapTotal', String(data.memory.swapTotal)],
+    ['thermal', 'state', data.thermal.state],
+    ['thermal', 'cpuTempC', data.thermal.temperatures?.cpu_die ? String(data.thermal.temperatures.cpu_die) : ''],
+    [
+      'thermal',
+      'cpuTempF',
+      data.thermal.temperatures?.cpu_die != null ? String(celsiusToFahrenheit(data.thermal.temperatures.cpu_die)) : '',
+    ],
+    ['network', 'rxBytes', String(data.network.rxBytes)],
+    ['network', 'txBytes', String(data.network.txBytes)],
+    ['battery', 'level', data.battery ? String(data.battery.level) : ''],
+    ['battery', 'powerSource', data.battery ? data.battery.powerSource : ''],
+    ['battery', 'condition', data.battery?.condition ?? ''],
+    ['battery', 'maxCapacityPercent', data.battery?.maxCapacityPercent !== undefined ? String(data.battery.maxCapacityPercent) : ''],
+    ['battery', 'cycles', data.battery?.cycles !== undefined ? String(data.battery.cycles) : ''],
+    ['power', 'cpuWatts', data.power?.cpuWatts !== undefined ? String(data.power.cpuWatts) : ''],
+    ['power', 'gpuWatts', data.power?.gpuWatts !== undefined ? String(data.power.gpuWatts) : ''],
+    ['power', 'combinedWatts', data.power?.combinedWatts !== undefined ? String(data.power.combinedWatts) : ''],
+['system', 'hostname', data.header.hostname],
+     ['system', 'uptime', data.header.uptime],
+     ['system', 'timestamp', data.timestamp],
+   ];
+
+   if (data.gpu) {
+     rows.push(['gpu', 'model', data.gpu.model]);
+     rows.push(['gpu', 'memory', String(data.gpu.memory)]);
+     rows.push(['gpu', 'utilization', String(data.gpu.utilization)]);
+     if (data.gpu.temperature) rows.push(['gpu', 'tempC', String(data.gpu.temperature)]);
+     rows.push(['gpu', 'processes', String(data.gpu.processes)]);
+   }
+
+   for (const p of data.processes) {
+    rows.push(['process', `pid=${p.pid}`, `${p.pid}`]);
+    rows.push(['process', `ppid=${p.pid}`, String(p.ppid)]);
+    rows.push(['process', `user=${p.pid}`, p.user]);
+    rows.push(['process', `cpu=${p.pid}`, String(p.cpu)]);
+    rows.push(['process', `mem=${p.pid}`, String(p.mem)]);
+    rows.push(['process', `state=${p.pid}`, p.state]);
+    rows.push(['process', `threads=${p.pid}`, String(p.threads)]);
+    rows.push(['process', `runtime=${p.pid}`, String(p.runtime)]);
+    rows.push(['process', `command=${p.pid}`, p.command]);
+  }
+  return rows.map(r => r.map(item => `"${String(item).replace(/"/g, '""')}"`).join(',')).join('\n');
+}
+
+export function formatTsv(data: StatsData): string {
+  return formatCsv(data).split('\n').map(r => r.split(',').join('\t')).join('\n');
+}
+
+export function formatGraphs(history: History, width = 80, themeName: ThemeName = 'default', graphMode: 'spark' | 'bar' = 'spark'): string {
+  const theme = THEMES[themeName] || THEMES.default;
+  const contentWidth = width - 4;
+  const sampleCount = history.cpuUsage.length;
+  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('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));
+
+  const title = `Graphs · mode:${graphMode} · last ${sampleCount} sample${sampleCount === 1 ? '' : 's'}`;
+  return panel(title, lines, width, theme.graphs, theme.border).join('\n');
+}
+
+function graphRow(
+  label: string,
+  values: number[],
+  bounds: { min?: number; max?: number },
+  fmt: (v: number) => string,
+  sparkWidth = 40,
+  emptyMessage = 'collecting data...',
+  mode: 'spark' | 'bar' = 'spark'
+): string {
+  if (!values.length) {
+    return `${chalk.dim(label.padEnd(10))} ${chalk.dim(emptyMessage)}`;
+  }
+  const visible = values.slice(-sparkWidth);
+  const spark = mode === 'spark' ? sparkline(visible, bounds) : barGraph(visible, bounds, sparkWidth);
+  const current = values[values.length - 1];
+
+  let color = chalk.cyan;
+  if (bounds.min !== undefined && bounds.max !== undefined) {
+    const pct = ((current - bounds.min) / (bounds.max - bounds.min || 1)) * 100;
+    color = pct > 90 ? chalk.red : pct > 70 ? chalk.yellow : chalk.green;
+  }
+
+  return `${chalk.dim(label.padEnd(10))}${color(spark)}  ${chalk.bold(fmt(current))}`;
+}
+
+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);
+  const range = max - min || 1;
+  return values.map(v => {
+    const pct = (v - min) / range;
+    if (pct > 0.8) return '█';
+    if (pct > 0.6) return '▇';
+    if (pct > 0.4) return '▆';
+    if (pct > 0.2) return '▄';
+    return ' ';
+  }).join('');
+}