pyre-cli 9.5.2 → 10.1.0

package/src/netUsageCmd.ts

@@ -0,0 +1,121 @@
+/**
+ * pyre netusage — Per-application network usage tracker.
+ *
+ * Uses macOS socket accounting and nettop parsing from collectPackets
+ * to produce detailed real-time and cumulative network metrics per process.
+ */
+import chalk from 'chalk';
+import { collectPackets } from './monitors/collectors.js';
+import { formatBytes } from './formatters/render.js';
+
+export interface NetUsageOptions {
+  top?: number;
+  sort?: 'rx' | 'tx' | 'total';
+  json?: boolean;
+  interval?: number;
+}
+
+export async function runNetUsageCommand(opts: NetUsageOptions = {}): Promise<void> {
+  const topCount = opts.top || 15;
+  const sortKey = opts.sort || 'total';
+
+  const packetData = await collectPackets();
+  if (!packetData || !packetData.allProcesses || packetData.allProcesses.length === 0) {
+    if (opts.json) {
+      console.log(JSON.stringify({ processes: [], totalRx: 0, totalTx: 0 }));
+      return;
+    }
+    console.log(chalk.yellow('\n  ⚠ No active per-application network sockets detected.'));
+    console.log(chalk.dim('  Ensure network activity is present or run with elevated permissions if required.\n'));
+    return;
+  }
+
+  // Aggregate by process command / name
+  interface AggregatedProc {
+    pid: number;
+    command: string;
+    rxBytes: number;
+    txBytes: number;
+    totalBytes: number;
+    connections: number;
+  }
+
+  const appMap = new Map<string, AggregatedProc>();
+
+  for (const proc of packetData.allProcesses) {
+    const key = proc.command || `pid-${proc.pid}`;
+    const rx = proc.rxBytes || 0;
+    const tx = proc.txBytes || 0;
+    const conns = proc.connections ? proc.connections.length : 0;
+
+    const existing = appMap.get(key);
+    if (existing) {
+      existing.rxBytes += rx;
+      existing.txBytes += tx;
+      existing.totalBytes += (rx + tx);
+      existing.connections += conns;
+    } else {
+      appMap.set(key, {
+        pid: proc.pid,
+        command: key,
+        rxBytes: rx,
+        txBytes: tx,
+        totalBytes: rx + tx,
+        connections: conns,
+      });
+    }
+  }
+
+  const sorted = Array.from(appMap.values()).sort((a, b) => {
+    if (sortKey === 'rx') return b.rxBytes - a.rxBytes;
+    if (sortKey === 'tx') return b.txBytes - a.txBytes;
+    return b.totalBytes - a.totalBytes;
+  });
+
+  const displayList = sorted.slice(0, topCount);
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      totalRx: packetData.rxPackets,
+      totalTx: packetData.txPackets,
+      activeConnections: packetData.connections,
+      processes: displayList,
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('\n  🔥 pyre netusage — Per-Application Network Traffic\n'));
+
+  const pidW = 8;
+  const appW = 28;
+  const rxW = 14;
+  const txW = 14;
+  const totalW = 14;
+  const connsW = 8;
+
+  const header =
+    chalk.bold.hex('#f8f8f2').bgHex('#44475a')(' PID    ') +
+    chalk.bold.hex('#f8f8f2').bgHex('#44475a')(' APPLICATION                ') +
+    chalk.bold.hex('#f8f8f2').bgHex('#44475a')(' DOWN (RX)    ') +
+    chalk.bold.hex('#f8f8f2').bgHex('#44475a')(' UP (TX)      ') +
+    chalk.bold.hex('#f8f8f2').bgHex('#44475a')(' TOTAL        ') +
+    chalk.bold.hex('#f8f8f2').bgHex('#44475a')(' CONNS  ');
+
+  console.log('  ' + header);
+  console.log('  ' + chalk.dim('─'.repeat(pidW + appW + rxW + txW + totalW + connsW)));
+
+  for (const p of displayList) {
+    const pidStr = String(p.pid).padEnd(pidW);
+    const appStr = (p.command.length > appW - 2 ? p.command.slice(0, appW - 3) + '…' : p.command).padEnd(appW);
+    const rxStr = chalk.green(formatBytes(p.rxBytes).padStart(rxW - 2)) + '  ';
+    const txStr = chalk.cyan(formatBytes(p.txBytes).padStart(txW - 2)) + '  ';
+    const totStr = chalk.bold(formatBytes(p.totalBytes).padStart(totalW - 2)) + '  ';
+    const connsStr = String(p.connections).padStart(connsW - 2);
+
+    console.log(`  ${pidStr}${appStr}${rxStr}${txStr}${totStr}${connsStr}`);
+  }
+
+  console.log();
+  console.log(chalk.dim(`  Total active socket connections: ${chalk.bold(String(packetData.connections))}  |  Showing top ${displayList.length} apps`));
+  console.log();
+}

package/src/platform.test.ts

@@ -0,0 +1,99 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('Linux Telemetry Parsers', () => {
+  it('should parse Linux memory info structure correctly', async () => {
+    const { collectLinuxMemory } = await import('./monitors/platform/linux.js');
+    const mem = await collectLinuxMemory();
+    assert.ok(typeof mem.total === 'number');
+    assert.ok(typeof mem.used === 'number');
+    assert.ok(typeof mem.free === 'number');
+    assert.ok(typeof mem.usagePercent === 'number');
+    assert.ok(mem.pageSize === 4096);
+  });
+
+  it('should collect Linux system info', async () => {
+    const { collectLinuxSystem } = await import('./monitors/platform/linux.js');
+    const sys = await collectLinuxSystem();
+    assert.ok(typeof sys.hostname === 'string');
+    assert.ok(typeof sys.os === 'string');
+    assert.ok(typeof sys.uptime === 'string');
+  });
+
+  it('should collect Linux disk structure', async () => {
+    const { collectLinuxDisk } = await import('./monitors/platform/linux.js');
+    const disks = await collectLinuxDisk();
+    assert.ok(Array.isArray(disks));
+    assert.ok(disks.length > 0);
+    assert.ok(typeof disks[0].filesystem === 'string');
+    assert.ok(typeof disks[0].mountpoint === 'string');
+  });
+
+  it('should collect Linux thermal structure gracefully', async () => {
+    const { collectLinuxThermal } = await import('./monitors/platform/linux.js');
+    const thermal = await collectLinuxThermal();
+    assert.ok(typeof thermal.state === 'string');
+    assert.ok(typeof thermal.pressureLevel === 'number');
+  });
+});
+
+describe('Windows Telemetry Parsers', () => {
+  it('should collect Windows system info with Windows OS mapping', async () => {
+    const { collectWindowsSystem } = await import('./monitors/platform/windows.js');
+    const sys = await collectWindowsSystem();
+    assert.ok(typeof sys.hostname === 'string');
+    assert.ok(sys.os.startsWith('Windows'));
+    assert.ok(typeof sys.uptime === 'string');
+  });
+
+  it('should collect Windows memory structure', async () => {
+    const { collectWindowsMemory } = await import('./monitors/platform/windows.js');
+    const mem = await collectWindowsMemory();
+    assert.ok(typeof mem.total === 'number');
+    assert.ok(typeof mem.used === 'number');
+    assert.ok(typeof mem.free === 'number');
+    assert.ok(typeof mem.usagePercent === 'number');
+    assert.ok(mem.pageSize === 4096);
+  });
+
+  it('should collect Windows CPU structure with simulated load average', async () => {
+    const { collectWindowsCpu } = await import('./monitors/platform/windows.js');
+    const cpuRef = { current: null };
+    const cpu = await collectWindowsCpu(cpuRef);
+    assert.ok(typeof cpu.brand === 'string');
+    assert.ok(cpu.cores >= 1);
+    assert.ok(Array.isArray(cpu.loadAvg));
+    assert.strictEqual(cpu.loadAvg.length, 3);
+  });
+
+  it('should return Windows disk fallback structure', async () => {
+    const { collectWindowsDisk } = await import('./monitors/platform/windows.js');
+    const disks = await collectWindowsDisk();
+    assert.ok(Array.isArray(disks));
+    assert.ok(disks.length > 0);
+    assert.ok(disks[0].mountpoint.includes(':'));
+  });
+
+  it('should collect Windows thermal structure with pressure level', async () => {
+    const { collectWindowsThermal } = await import('./monitors/platform/windows.js');
+    const thermal = await collectWindowsThermal();
+    assert.ok(typeof thermal.state === 'string');
+    assert.ok([0, 1, 2, 3].includes(thermal.pressureLevel));
+  });
+});
+
+describe('Cross-Platform Service & Package Management', () => {
+  it('should report package manager health without crashing', async () => {
+    const { getBrewHealth } = await import('./brewHealth.js');
+    const health = await getBrewHealth();
+    assert.ok(typeof health.managerName === 'string');
+    assert.ok(typeof health.brewAvailable === 'boolean');
+    assert.ok(typeof health.installedCount === 'number');
+  });
+
+  it('should query system extensions / drivers without crashing', async () => {
+    const { getSystemExtensions } = await import('./extensions.js');
+    const extensions = await getSystemExtensions();
+    assert.ok(Array.isArray(extensions));
+  });
+});

package/src/plugins/index.ts

@@ -0,0 +1,143 @@
+/**
+ * pyre Plugin System.
+ *
+ * Discovers and executes custom user-authored metric collectors from
+ * ~/.config/pyre/plugins/*.js (or .mjs).
+ *
+ * Plugin contract:
+ * export default {
+ *   name: 'my-metric',
+ *   title: 'My Custom Metric',
+ *   intervalSec: 5, // optional refresh interval
+ *   collect: async () => {
+ *     return {
+ *       title: 'Custom Title', // optional override
+ *       lines: ['Metric 1: 42', 'Status: OK']
+ *     };
+ *   }
+ * };
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getConfigDir } from '../state/config.js';
+
+export interface PyrePluginOutput {
+  title?: string;
+  lines: string[];
+}
+
+export interface PyrePlugin {
+  name: string;
+  title?: string;
+  intervalSec?: number;
+  collect: () => Promise<PyrePluginOutput | string[] | Record<string, any>>;
+}
+
+export interface LoadedPlugin {
+  plugin: PyrePlugin;
+  lastRun: number;
+  lastOutput: PyrePluginOutput;
+  error?: string;
+}
+
+const loadedPlugins: Map<string, LoadedPlugin> = new Map();
+
+export function getPluginsDir(): string {
+  return path.join(getConfigDir(), 'plugins');
+}
+
+export async function loadPlugins(): Promise<Map<string, LoadedPlugin>> {
+  const pluginsDir = getPluginsDir();
+  if (!fs.existsSync(pluginsDir)) {
+    try {
+      fs.mkdirSync(pluginsDir, { recursive: true });
+    } catch {
+      return loadedPlugins;
+    }
+  }
+
+  let files: string[] = [];
+  try {
+    files = fs.readdirSync(pluginsDir).filter(f => f.endsWith('.js') || f.endsWith('.mjs'));
+  } catch {
+    return loadedPlugins;
+  }
+
+  for (const file of files) {
+    const filePath = path.join(pluginsDir, file);
+    try {
+      const fileUrl = pathToFileURL(filePath).href;
+      const mod = await import(`${fileUrl}?t=${Date.now()}`);
+      const plugin: PyrePlugin = mod.default || mod;
+      if (plugin && typeof plugin.collect === 'function') {
+        const name = plugin.name || path.basename(file, path.extname(file));
+        if (!loadedPlugins.has(name)) {
+          loadedPlugins.set(name, {
+            plugin: { ...plugin, name },
+            lastRun: 0,
+            lastOutput: { title: plugin.title || name, lines: ['Collecting...'] },
+          });
+        }
+      }
+    } catch (err: any) {
+      const name = path.basename(file, path.extname(file));
+      loadedPlugins.set(name, {
+        plugin: { name, collect: async () => ({ lines: [`Error loading plugin: ${err.message}`] }) },
+        lastRun: Date.now(),
+        lastOutput: { title: name, lines: [`Failed to load: ${err.message}`] },
+        error: err.message,
+      });
+    }
+  }
+
+  return loadedPlugins;
+}
+
+export async function executePlugins(): Promise<LoadedPlugin[]> {
+  const now = Date.now();
+  const results: LoadedPlugin[] = [];
+
+  for (const [, item] of loadedPlugins.entries()) {
+    const intervalMs = (item.plugin.intervalSec || 5) * 1000;
+    if (now - item.lastRun >= intervalMs) {
+      try {
+        const raw = await Promise.race([
+          item.plugin.collect(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout (5s)')), 5000)),
+        ]);
+
+        let output: PyrePluginOutput;
+        if (Array.isArray(raw)) {
+          output = { title: item.plugin.title || item.plugin.name, lines: raw.map(String) };
+        } else if (raw && typeof raw === 'object' && Array.isArray((raw as any).lines)) {
+          output = {
+            title: (raw as any).title || item.plugin.title || item.plugin.name,
+            lines: (raw as any).lines.map(String),
+          };
+        } else if (raw && typeof raw === 'object') {
+          output = {
+            title: item.plugin.title || item.plugin.name,
+            lines: Object.entries(raw).map(([k, v]) => `${k}: ${v}`),
+          };
+        } else {
+          output = { title: item.plugin.title || item.plugin.name, lines: [String(raw)] };
+        }
+
+        item.lastOutput = output;
+        item.lastRun = now;
+        item.error = undefined;
+      } catch (err: any) {
+        item.lastOutput = {
+          title: item.plugin.title || item.plugin.name,
+          lines: [`Execution error: ${err.message}`],
+        };
+        item.error = err.message;
+        item.lastRun = now;
+      }
+    }
+    results.push(item);
+  }
+
+  return results;
+}

package/src/profileProcCmd.ts

@@ -0,0 +1,133 @@
+/**
+ * pyre profile-proc — Process CPU Profiler.
+ *
+ * Samples a process for a given duration (default 5 seconds) using macOS `sample`
+ * or fallback thread analysis, then presents an annotated call-tree and
+ * hot frames summary.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import chalk from 'chalk';
+
+const execFileAsync = promisify(execFile);
+
+export interface ProfileProcOptions {
+  pid: number;
+  durationSec?: number;
+  raw?: boolean;
+}
+
+export async function runProfileProcCommand(opts: ProfileProcOptions): Promise<void> {
+  const { pid, durationSec = 5, raw } = opts;
+
+  if (isNaN(pid) || pid <= 0) {
+    console.error(chalk.red('\n  ✖ Error: Valid PID is required. Usage: pyre profile-proc <pid> [--duration <sec>]\n'));
+    process.exit(1);
+  }
+
+  // 1. Verify process exists
+  try {
+    process.kill(pid, 0);
+  } catch {
+    console.error(chalk.red(`\n  ✖ Error: Process with PID ${pid} is not running or accessible.\n`));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold(`\n  🔥 pyre profile-proc — Profiling PID ${pid} for ${durationSec}s...\n`));
+
+  let sampleOutput = '';
+  let usedFallback = false;
+
+  // Try macOS native `sample` command (available on macOS)
+  if (process.platform === 'darwin') {
+    try {
+      const { stdout } = await execFileAsync('sample', [String(pid), String(durationSec), '-file', '/dev/stdout'], {
+        timeout: (durationSec + 5) * 1000,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+      sampleOutput = stdout;
+    } catch (err: any) {
+      // Sample might fail if SIP restricts it on system processes or timeout
+      sampleOutput = err.stdout || '';
+    }
+  }
+
+  // Fallback: If sample produced no usable output or running on Linux, sample via thread / proc stats
+  if (!sampleOutput || sampleOutput.length < 100) {
+    usedFallback = true;
+    try {
+      const { stdout } = await execFileAsync('ps', ['-M', '-p', String(pid), '-o', 'pid,thread,pcpu,pmem,state,time,command']);
+      sampleOutput = stdout;
+    } catch {
+      sampleOutput = `Process PID ${pid} active. Deep stack sampling requires elevated permissions or user-owned process.`;
+    }
+  }
+
+  if (raw) {
+    console.log(sampleOutput);
+    return;
+  }
+
+  // Parse and display clean call-tree analysis
+  if (!usedFallback) {
+    // Extract Call graph section
+    const lines = sampleOutput.split('\n');
+    const headerLines: string[] = [];
+    const stackLines: string[] = [];
+    let inCallGraph = false;
+
+    for (const line of lines) {
+      if (line.includes('Analysis of sampling') || line.includes('Process:') || line.includes('Path:') || line.includes('Identifier:')) {
+        headerLines.push(line.trim());
+      }
+      if (line.includes('Call graph:') || line.includes('+ Line Coverage')) {
+        inCallGraph = true;
+        continue;
+      }
+      if (inCallGraph) {
+        if (line.includes('Total number in stack') || line.includes('Binary Images:')) {
+          inCallGraph = false;
+        } else if (line.trim().length > 0 && stackLines.length < 35) {
+          stackLines.push(line);
+        }
+      }
+    }
+
+    if (headerLines.length > 0) {
+      console.log(chalk.dim('  Process Info:'));
+      for (const h of headerLines.slice(0, 4)) {
+        console.log(`    ${chalk.cyan(h)}`);
+      }
+      console.log();
+    }
+
+    console.log(chalk.bold('  Top Call Stacks & Hot Functions:'));
+    console.log(chalk.dim('  ' + '─'.repeat(70)));
+
+    if (stackLines.length === 0) {
+      for (const l of lines.slice(0, 20)) {
+        if (l.trim()) console.log(`  ${l}`);
+      }
+    } else {
+      for (const l of stackLines) {
+        if (l.includes('???')) {
+          console.log(chalk.dim(`  ${l}`));
+        } else if (l.includes('+')) {
+          console.log(chalk.yellow(`  ${l}`));
+        } else {
+          console.log(`  ${l}`);
+        }
+      }
+    }
+  } else {
+    console.log(chalk.yellow('  Note: Kernel/SIP restriction prevented deep call-graph unwind.'));
+    console.log(chalk.dim('  Showing process thread snapshot:\n'));
+    for (const l of sampleOutput.split('\n')) {
+      if (l.trim()) console.log(`    ${l}`);
+    }
+  }
+
+  console.log();
+  console.log(chalk.green(`  ✔ Sampling complete for PID ${pid} (${durationSec}s profile duration).`));
+  console.log();
+}

package/src/prometheusCmd.ts

@@ -0,0 +1,107 @@
+/**
+ * pyre prometheus — Prometheus metrics exporter.
+ *
+ * Starts an HTTP server that exposes system metrics in the
+ * Prometheus text exposition format at GET /metrics.
+ * Uses the existing formatPrometheusMetrics() from prometheus.ts
+ * and collectAll() from monitors/index.ts.
+ *
+ * No new dependencies — uses Node.js built-in http module.
+ */
+import http from 'node:http';
+import os from 'node:os';
+import { collectAll } from './monitors/index.js';
+import { formatPrometheusMetrics } from './prometheus.js';
+import chalk from 'chalk';
+
+export interface PrometheusOptions {
+  port: number;
+  interval: number;
+  detailed?: boolean;
+}
+
+export async function runPrometheusServer(opts: PrometheusOptions): Promise<void> {
+  const { port, interval, detailed } = opts;
+
+  // Pre-warm with an initial collection so /metrics is never empty on first scrape
+  let latestData = await collectAll({ detailed });
+  let lastCollect = Date.now();
+
+  // Background refresh loop — collects fresh data every `interval` seconds
+  const refreshTimer = setInterval(async () => {
+    try {
+      latestData = await collectAll({ detailed });
+      lastCollect = Date.now();
+    } catch {
+      // Keep serving last good data on collection failure
+    }
+  }, interval * 1000);
+
+  const server = http.createServer(async (req, res) => {
+    const url = req.url?.split('?')[0] ?? '/';
+
+    if (url === '/metrics') {
+      try {
+        // If data is stale (> 2x interval), re-collect synchronously
+        if (Date.now() - lastCollect > interval * 2000) {
+          latestData = await collectAll({ detailed });
+          lastCollect = Date.now();
+        }
+        const body = formatPrometheusMetrics(latestData);
+        res.writeHead(200, {
+          'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+          'Content-Length': Buffer.byteLength(body),
+        });
+        res.end(body);
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end(`# collection error: ${err instanceof Error ? err.message : String(err)}\n`);
+      }
+      return;
+    }
+
+    if (url === '/health' || url === '/api/health') {
+      const body = JSON.stringify({ status: 'ok', uptime: os.uptime(), timestamp: new Date().toISOString() });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(body);
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not found. Available endpoints: /metrics  /health\n');
+  });
+
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(chalk.red(`  ✖ Port ${port} is already in use. Try --prometheus-port <other-port>`));
+    } else {
+      console.error(chalk.red(`  ✖ Server error: ${err.message}`));
+    }
+    clearInterval(refreshTimer);
+    process.exit(1);
+  });
+
+  await new Promise<void>((resolve) => server.listen(port, '0.0.0.0', resolve));
+
+  console.log(chalk.bold('\n  🔥 pyre — Prometheus Exporter\n'));
+  console.log(`  ${chalk.green('✔')} Metrics endpoint: ${chalk.cyan(`http://0.0.0.0:${port}/metrics`)}`);
+  console.log(`  ${chalk.green('✔')} Health endpoint:  ${chalk.cyan(`http://0.0.0.0:${port}/health`)}`);
+  console.log(`  ${chalk.dim(`Refresh interval: ${interval}s  |  Detailed mode: ${detailed ? 'on' : 'off'}`)}`);
+  console.log(`\n  ${chalk.dim('Add to prometheus.yml:')}`);
+  console.log(chalk.dim(`    - job_name: 'pyre'`));
+  console.log(chalk.dim(`      static_configs:`));
+  console.log(chalk.dim(`        - targets: ['localhost:${port}']`));
+  console.log(`\n  ${chalk.dim('Press Ctrl+C to stop.')}\n`);
+
+  const shutdown = () => {
+    clearInterval(refreshTimer);
+    server.close(() => {
+      console.log(chalk.dim('\n  Prometheus server stopped.'));
+      process.exit(0);
+    });
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  await new Promise<void>(() => { /* runs until signal */ });
+}