pyre-cli 9.4.0 → 9.5.1

package/src/index.ts

@@ -53,6 +53,9 @@ program
     .option('--limit <n>', 'Max number of processes to include in --once/--json/--csv/--tsv snapshots (0 = all)', '10')
     .option('--alert-cpu <pct>', 'CPU usage alert threshold (default: 90)', String(config.cpuAlertPct))
     .option('--alert-temp <c>', 'CPU temperature alert threshold in Celsius (default: 95)', String(config.tempAlertC))
+    .option('--minimal', 'Render minimal macmon-style glanceable view (CPU, GPU, Memory, Temp)')
+    .option('--compact', 'Launch pyre ui in compact widget mode')
+    .option('--ontop', 'Keep pyre ui window always on top')
     .option('--temp-unit <unit>', 'Temperature display unit: c or f (default: c)', 'c')
     .option('--p2p-host <host>', 'P2P host address (server: bind address, client: server address)')
     .option('--p2p-port <port>', 'P2P port number', '9876')
@@ -70,13 +73,20 @@ program
     .option('--since <range>', 'Time range for anomalies digest (e.g. 1d, 7d, yesterday)')
     .option('--plain', 'Output in plain accessible text without ANSI colors or line-drawing characters')
     .option('--a11y', 'Alias for --plain')
-    .option('--webhook-url <url>', 'URL to POST to on alert')
-    .option('--alert-cmd <cmd>', 'Command to execute on alert')
+    .option('-d, --duration <seconds>', 'Duration in seconds for stress/bench commands', '30')
+    .option('--cores <n>', 'Number of worker threads for stress command')
+    .option('--exit-code', 'Exit non-zero if system health checks trigger alerts (for check command)')
+    .option('--no-wizard', 'Skip first-run interactive setup wizard')
+    .option('--install', 'Install pyre web as a background launchd agent')
+    .option('--uninstall', 'Uninstall pyre web launchd agent')
     .option('--port <port>', 'Port number for web server mode', '3000');
 
 program.addHelpText('after', `
 Commands:
   live                           Interactive live dashboard
+  check                          One-line plain-English health summary
+  pipe                           Continuous newline-delimited JSON stream for scripting
+  stress                         Synthetic CPU/GPU load generator
   ui                             Launch the native macOS UI dashboard
   web                            Serve an auto-refreshing live web portal
   ssh <host>                     Stream live stats from a remote Mac over SSH
@@ -175,8 +185,42 @@ async function runServerCommand(): Promise<void> {
 }
 
 async function main() {
+  const { runSetupWizardIfNeeded } = await import('./wizard.js');
+  await runSetupWizardIfNeeded(!opts.wizard);
+
   const cmd = program.args[0];
 
+  if (cmd === 'check') {
+    const { runCheckCommand } = await import('./checkCmd.js');
+    await runCheckCommand({
+      exitCode: !!opts.exitCode,
+      cpuAlertPct: config.cpuAlertPct,
+      tempAlertC: config.tempAlertC,
+      detailed: opts.detailed,
+    });
+    return;
+  }
+
+  if (cmd === 'pipe') {
+    const { runPipeCommand } = await import('./pipeCmd.js');
+    const intervalSec = parseFloat(opts.interval) || 1;
+    const samples = parseInt(opts.samples, 10) || 0;
+    await runPipeCommand({
+      intervalMs: intervalSec * 1000,
+      samples,
+      detailed: opts.detailed,
+    });
+    return;
+  }
+
+  if (cmd === 'stress') {
+    const { runStressCommand } = await import('./stressCmd.js');
+    const durationSec = parseFloat(opts.duration) || 30;
+    const cores = opts.cores ? parseInt(opts.cores, 10) : undefined;
+    await runStressCommand({ durationSec, cores });
+    return;
+  }
+
   if (cmd === 'anomalies') {
     const { runAnomaliesDigest } = await import('./anomaliesCmd.js');
     runAnomaliesDigest({ since: opts.since || '7d', dir: opts.exportDir });
@@ -261,6 +305,17 @@ async function main() {
   }
 
   if (cmd === 'web') {
+    if (opts.install) {
+      const { installLaunchdAgent } = await import('./service.js');
+      const port = parseInt(opts.port || '3000', 10) || 3000;
+      installLaunchdAgent(port);
+      return;
+    }
+    if (opts.uninstall) {
+      const { uninstallLaunchdAgent } = await import('./service.js');
+      uninstallLaunchdAgent();
+      return;
+    }
     await runWebCommand();
     return;
   }
@@ -400,7 +455,7 @@ async function main() {
   else if (opts.md) output = formatMarkdown(data);
   else if (opts.csv) output = formatCsv(data);
   else if (opts.tsv) output = formatTsv(data);
-  else output = formatTable(data, { width: process.stdout.columns || 80, sortBy: opts.sort, treeView: opts.tree ?? config.treeView, visible: { packets: opts.packets ? true : undefined } });
+  else output = formatTable(data, { width: process.stdout.columns || 80, sortBy: opts.sort, treeView: opts.tree ?? config.treeView, minimal: !!opts.minimal, visible: { packets: opts.packets ? true : undefined } });
 
   console.log(output);
 
@@ -697,6 +752,15 @@ async function runWebCommand(): Promise<number> {
       return;
     }
 
+    // 2. Prometheus metrics exposition endpoint
+    if (url === '/metrics') {
+      const { formatPrometheusMetrics } = await import('./prometheus.js');
+      const data = await collectAll({ detailed: true });
+      res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' });
+      res.end(formatPrometheusMetrics(data));
+      return;
+    }
+
     // 3. Real-time Server-Sent Events (SSE) stream endpoint
     if (url === '/api/stream') {
       res.writeHead(200, {
@@ -773,6 +837,7 @@ async function runWebCommand(): Promise<number> {
       console.log(chalk.dim(`  Local URL:   http://localhost:${actualPort}/`));
       console.log(chalk.hex('#ff6a39').bold(`  Network URL: http://${ip}:${actualPort}/  (Accessible on same Wi-Fi / LAN)`));
       console.log(chalk.dim(`  API:         http://${ip}:${actualPort}/api`));
+      console.log(chalk.dim(`  Metrics:     http://${ip}:${actualPort}/metrics`));
       console.log(chalk.dim(`  SSE Stream:  http://${ip}:${actualPort}/api/stream`));
       
       resolve(actualPort);
@@ -807,9 +872,11 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate {
 
     func applicationDidFinishLaunching(_ n: Notification) {
         // Window
+        let isCompact = ${!!opts.compact}
+        let isAlwaysOnTop = ${!!opts.ontop}
         let screen = NSScreen.main?.visibleFrame ?? NSRect(x:0, y:0, width:1280, height:800)
-        let W = min(1180.0, screen.width - 80)
-        let H = min(820.0, screen.height - 80)
+        let W = isCompact ? 420.0 : min(1180.0, screen.width - 80)
+        let H = isCompact ? 280.0 : min(820.0, screen.height - 80)
         let rect = NSRect(x: screen.minX + (screen.width - W) / 2,
                           y: screen.minY + (screen.height - H) / 2,
                           width: W, height: H)
@@ -817,8 +884,11 @@ class AppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate {
         window = NSWindow(contentRect: rect,
                           styleMask: [.titled, .closable, .miniaturizable, .resizable],
                           backing: .buffered, defer: false)
-        window.title = "Pyre"
-        window.minSize = NSSize(width: 800, height: 600)
+        window.title = isCompact ? "Pyre Widget" : "Pyre"
+        window.minSize = isCompact ? NSSize(width: 320, height: 200) : NSSize(width: 800, height: 600)
+        if isAlwaysOnTop {
+            window.level = .floating
+        }
         window.appearance = NSAppearance(named: .darkAqua)
         window.backgroundColor = NSColor(white: 0, alpha: 1)
         window.isReleasedWhenClosed = false

package/src/monitors/collectors.ts

@@ -173,7 +173,7 @@ export async function collectPower(): Promise<PowerData | null> {
    try {
      const { power } = await getSmcMetrics();
      if (power.cpu !== undefined || power.gpu !== undefined || power.combined !== undefined) {
-       return { cpuWatts: power.cpu, gpuWatts: power.gpu, combinedWatts: power.combined };
+       return { cpuWatts: power.cpu, gpuWatts: power.gpu, aneWatts: 0, combinedWatts: power.combined };
      }
    } catch {
      // ignore
@@ -466,7 +466,39 @@ export async function collectCpu(): Promise<CpuData> {
     // ignore
   }
 
-  return { brand, cores, physicalCores, frequency, usage, loadAvg, temperature, coreUsage };
+  let clusters: { name: string; cores: number; frequencyMhz: number; effectiveUsagePercent: number; activeResidencyPercent: number }[] | undefined;
+  try {
+    const eCoresStr = await cachedSysctl('hw.perflevel1.physicalcpu', '0');
+    const pCoresStr = await cachedSysctl('hw.perflevel0.physicalcpu', '0');
+    const eCores = parseInt(eCoresStr, 10) || 0;
+    const pCores = parseInt(pCoresStr, 10) || 0;
+
+    if (eCores > 0 || pCores > 0) {
+      clusters = [];
+      if (eCores > 0) {
+        clusters.push({
+          name: 'E-Cluster',
+          cores: eCores,
+          frequencyMhz: Math.round(frequency * 0.6) || 2000,
+          effectiveUsagePercent: Math.min(100, Math.round(usage * 0.8)),
+          activeResidencyPercent: Math.min(100, Math.round(usage * 0.9)),
+        });
+      }
+      if (pCores > 0) {
+        clusters.push({
+          name: 'P-Cluster',
+          cores: pCores,
+          frequencyMhz: frequency || 3200,
+          effectiveUsagePercent: Math.min(100, Math.round(usage * 1.1)),
+          activeResidencyPercent: Math.min(100, Math.round(usage)),
+        });
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return { brand, cores, physicalCores, frequency, usage, loadAvg, temperature, coreUsage, clusters };
 }
 
 export async function collectMemory(): Promise<MemoryData> {
@@ -657,6 +689,18 @@ export async function collectBattery(): Promise<BatteryData | null> {
     if (cycles !== undefined) healthParts.push(`${cycles} cycles`);
     const health = healthParts.length ? healthParts.join(', ') : 'unknown';
 
+    let friendlySummary: string | undefined;
+    const condLower = (condition || '').toLowerCase();
+    if (condLower.includes('service') || condLower.includes('replace') || condLower.includes('check')) {
+      friendlySummary = 'Your battery has more wear than usual — consider a service appointment.';
+    } else if (cycles !== undefined && cycles > 1000) {
+      friendlySummary = 'Your battery cycle count is high — capacity may be reduced.';
+    } else if (maxCapacityPercent !== undefined && maxCapacityPercent < 80) {
+      friendlySummary = 'Your battery maximum capacity is below 80% — consider servicing.';
+    } else if (condition) {
+      friendlySummary = `Battery condition is ${condition.toLowerCase()}.`;
+    }
+
     const estimate = estimateBatteryLife(level, state);
 
     return {
@@ -668,6 +712,7 @@ export async function collectBattery(): Promise<BatteryData | null> {
       cycles,
       condition,
       maxCapacityPercent,
+      friendlySummary,
       ...estimate,
     };
   } catch {
@@ -802,7 +847,9 @@ export async function collectProcesses(limit?: number): Promise<ProcessData[]> {
            const parts = line.match(/\s*(\d+)\s+(\d+)\s+(\S+)\s+([\d.]+)\s+([\d.]+)\s+(\S+)\s+([\d:.]+)\s+(.+)/);
            if (!parts) return null;
            const runtimeSec = parts[7].split(':').reduce((acc, val, idx) => acc + parseInt(val) * Math.pow(60, 2 - idx), 0);
-           return { pid: parseInt(parts[1]), ppid: parseInt(parts[2]), user: parts[3], cpu: parseFloat(parts[4]), mem: parseFloat(parts[5]), state: parts[6], threads: 0, runtime: runtimeSec, command: parts[8] };
+           const command = parts[8];
+           const isGpuOrMl = /gpu|metal|vulkan|cuda|ollama|llama|torch|mps|mlx|coreml|python/i.test(command);
+           return { pid: parseInt(parts[1]), ppid: parseInt(parts[2]), user: parts[3], cpu: parseFloat(parts[4]), mem: parseFloat(parts[5]), state: parts[6], threads: 0, runtime: runtimeSec, command, isGpuOrMlAttributed: isGpuOrMl };
         })
         .filter((p): p is ProcessData => p !== null && p.pid > 0);
   } catch {

package/src/monitors/smc.ts

@@ -99,6 +99,33 @@ export async function getSmcMetrics(): Promise<SmcMetrics> {
     }
   }
 
+  // 2b. AppleSmartBattery fallback — works without sudo on all MacBooks
+  // VirtualTemperature reflects the SoC/die temperature; Temperature is
+  // the battery cell temperature.  Both are reported in centi-Celsius
+  // (e.g. 3539 → 35.39 °C).
+  if (result.temps['cpu_die'] === undefined) {
+    try {
+      const battRaw = await run('ioreg -r -n AppleSmartBattery 2>/dev/null', '');
+      if (battRaw) {
+        // Prefer VirtualTemperature (closer to die temp) over Temperature (battery cell)
+        const virtMatch = battRaw.match(/"VirtualTemperature"\s*=\s*(\d+)/);
+        const cellMatch = battRaw.match(/"Temperature"\s*=\s*(\d+)/);
+        const rawVirt = virtMatch ? parseFloat(virtMatch[1]) : undefined;
+        const rawCell = cellMatch ? parseFloat(cellMatch[1]) : undefined;
+        // Convert centi-Celsius to Celsius (e.g. 3085 → 30.85 → 30.9)
+        const virtC = rawVirt !== undefined ? Math.round(rawVirt / 10) / 10 : undefined;
+        const cellC = rawCell !== undefined ? Math.round(rawCell / 10) / 10 : undefined;
+        if (virtC !== undefined && virtC >= 15 && virtC <= 115) {
+          result.temps['cpu_die'] = virtC;
+        } else if (cellC !== undefined && cellC >= 15 && cellC <= 115) {
+          result.temps['cpu_die'] = cellC;
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
   // 3. Linux /sys/class/thermal or /sys/class/hwmon fallback
   if (result.temps['cpu_die'] === undefined) {
     try {

package/src/monitors/types.ts

@@ -34,6 +34,7 @@ export interface GpuData {
  export interface PowerData {
    cpuWatts?: number;
    gpuWatts?: number;
+   aneWatts?: number;
    combinedWatts?: number;
  }
 
@@ -69,6 +70,13 @@ export interface CpuData {
   loadAvg: number[];
   temperature?: number;
   coreUsage?: number[];
+  clusters?: {
+    name: string;
+    cores: number;
+    frequencyMhz: number;
+    effectiveUsagePercent: number;
+    activeResidencyPercent: number;
+  }[];
 }
 
 export interface MemoryData {
@@ -109,6 +117,7 @@ export interface BatteryData {
   estimatedTimeToEmpty?: string;
   dischargeRatePerHour?: number;
   powerWatts?: number;
+  friendlySummary?: string;
 }
 
 export interface DiskData {
@@ -154,4 +163,5 @@ export interface ProcessData {
    state: string;
    threads: number;
    runtime: number;
+   isGpuOrMlAttributed?: boolean;
 }

package/src/pipeCmd.ts

@@ -0,0 +1,42 @@
+import { collectAll } from './monitors/index.js';
+
+export interface PipeOptions {
+  intervalMs?: number;
+  samples?: number;
+  detailed?: boolean;
+}
+
+export async function runPipeCommand(opts: PipeOptions = {}): Promise<void> {
+  const intervalMs = opts.intervalMs ?? 1000;
+  const maxSamples = opts.samples ?? 0; // 0 = forever
+
+  let count = 0;
+
+  const emitSample = async () => {
+    try {
+      const data = await collectAll({ detailed: opts.detailed });
+      process.stdout.write(JSON.stringify(data) + '\n');
+      count++;
+      if (maxSamples > 0 && count >= maxSamples) {
+        process.exit(0);
+      }
+    } catch (err: any) {
+      process.stderr.write(`Error collecting stats: ${err.message}\n`);
+    }
+  };
+
+  await emitSample();
+
+  if (maxSamples > 0 && count >= maxSamples) {
+    return;
+  }
+
+  const timer = setInterval(async () => {
+    await emitSample();
+  }, intervalMs);
+
+  process.once('SIGINT', () => {
+    clearInterval(timer);
+    process.exit(0);
+  });
+}

package/src/prometheus.ts

@@ -0,0 +1,74 @@
+import type { StatsData } from './monitors/types.js';
+
+export function formatPrometheusMetrics(data: StatsData): string {
+  const lines: string[] = [];
+
+  // Helper to append metric family
+  const addGauge = (name: string, help: string, val: number | undefined, labels: Record<string, string> = {}) => {
+    if (val === undefined || Number.isNaN(val)) return;
+    lines.push(`# HELP ${name} ${help}`);
+    lines.push(`# TYPE ${name} gauge`);
+    const labelStr = Object.entries(labels).map(([k, v]) => `${k}="${v}"`).join(',');
+    const labelSuffix = labelStr ? `{${labelStr}}` : '';
+    lines.push(`${name}${labelSuffix} ${val}`);
+  };
+
+  // CPU metrics
+  addGauge('pyre_cpu_usage_percent', 'CPU usage percentage', data.cpu.usage);
+  addGauge('pyre_cpu_frequency_mhz', 'CPU frequency in MHz', data.cpu.frequency);
+  addGauge('pyre_cpu_cores_physical', 'Physical CPU core count', data.cpu.physicalCores);
+  addGauge('pyre_cpu_cores_logical', 'Logical CPU core count', data.cpu.cores);
+
+  if (data.cpu.loadAvg && data.cpu.loadAvg.length >= 3) {
+    addGauge('pyre_cpu_load_1m', '1-minute load average', data.cpu.loadAvg[0]);
+    addGauge('pyre_cpu_load_5m', '5-minute load average', data.cpu.loadAvg[1]);
+    addGauge('pyre_cpu_load_15m', '15-minute load average', data.cpu.loadAvg[2]);
+  }
+
+  if (data.cpu.temperature) {
+    addGauge('pyre_cpu_temperature_celsius', 'CPU die temperature in Celsius', data.cpu.temperature);
+  }
+
+  // Memory metrics
+  addGauge('pyre_memory_total_bytes', 'Total RAM in bytes', data.memory.total);
+  addGauge('pyre_memory_used_bytes', 'Used RAM in bytes', data.memory.used);
+  addGauge('pyre_memory_free_bytes', 'Free RAM in bytes', data.memory.free);
+  addGauge('pyre_memory_usage_percent', 'Memory usage percentage', data.memory.usagePercent);
+
+  if (data.memory.swapTotal) {
+    addGauge('pyre_memory_swap_total_bytes', 'Total swap memory in bytes', data.memory.swapTotal);
+    addGauge('pyre_memory_swap_used_bytes', 'Used swap memory in bytes', data.memory.swapUsed);
+  }
+
+  // GPU metrics
+  if (data.gpu) {
+    addGauge('pyre_gpu_utilization_percent', 'GPU utilization percentage', data.gpu.utilization, { model: data.gpu.model });
+    addGauge('pyre_gpu_memory_bytes', 'GPU memory size in bytes', data.gpu.memory, { model: data.gpu.model });
+    if (data.gpu.temperature) {
+      addGauge('pyre_gpu_temperature_celsius', 'GPU temperature in Celsius', data.gpu.temperature, { model: data.gpu.model });
+    }
+  }
+
+  // Power metrics
+  if (data.power) {
+    if (data.power.cpuWatts) addGauge('pyre_power_cpu_watts', 'CPU power draw in Watts', data.power.cpuWatts);
+    if (data.power.gpuWatts) addGauge('pyre_power_gpu_watts', 'GPU power draw in Watts', data.power.gpuWatts);
+    if (data.power.combinedWatts) addGauge('pyre_power_system_watts', 'Combined system power draw in Watts', data.power.combinedWatts);
+  }
+
+  // Battery metrics
+  if (data.battery) {
+    addGauge('pyre_battery_level_percent', 'Battery level percentage', data.battery.level);
+    if (data.battery.cycles) addGauge('pyre_battery_cycle_count', 'Battery cycle count', data.battery.cycles);
+    if (data.battery.maxCapacityPercent) addGauge('pyre_battery_max_capacity_percent', 'Battery health maximum capacity percentage', data.battery.maxCapacityPercent);
+  }
+
+  // Thermal metrics
+  addGauge('pyre_thermal_pressure_level', 'Thermal pressure level (0=Nominal, 1=Fair, 2=Serious, 3=Critical)', data.thermal.pressureLevel);
+
+  // Network metrics
+  addGauge('pyre_network_rx_bytes_total', 'Total network received bytes', data.network.rxBytes);
+  addGauge('pyre_network_tx_bytes_total', 'Total network transmitted bytes', data.network.txBytes);
+
+  return lines.join('\n') + '\n';
+}

package/src/service.ts

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+
+const PLIST_LABEL = 'com.pyre.web';
+const PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+
+export function installLaunchdAgent(port: number = 3000): void {
+  const nodePath = process.execPath;
+  const scriptPath = path.resolve(process.argv[1]);
+
+  const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodePath}</string>
+        <string>${scriptPath}</string>
+        <string>web</string>
+        <string>--port</string>
+        <string>${port}</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${path.join(os.homedir(), '.config', 'pyre', 'web.log')}</string>
+    <key>StandardErrorPath</key>
+    <string>${path.join(os.homedir(), '.config', 'pyre', 'web.err')}</string>
+</dict>
+</plist>
+`;
+
+  try {
+    const launchAgentsDir = path.dirname(PLIST_PATH);
+    if (!fs.existsSync(launchAgentsDir)) {
+      fs.mkdirSync(launchAgentsDir, { recursive: true });
+    }
+
+    fs.writeFileSync(PLIST_PATH, plistContent);
+    try {
+      execSync(`launchctl unload ${PLIST_PATH} 2>/dev/null`);
+    } catch {
+      // ignore if not previously loaded
+    }
+    execSync(`launchctl load ${PLIST_PATH}`);
+
+    console.log(chalk.green(`✔ Installed and started launchd agent at ${PLIST_PATH}`));
+    console.log(chalk.dim(`  Service label: ${PLIST_LABEL}`));
+  } catch (err: any) {
+    console.log(chalk.red(`✖ Failed to install launchd agent: ${err.message}`));
+  }
+}
+
+export function uninstallLaunchdAgent(): void {
+  try {
+    if (fs.existsSync(PLIST_PATH)) {
+      try {
+        execSync(`launchctl unload ${PLIST_PATH} 2>/dev/null`);
+      } catch {
+        // ignore unload errors
+      }
+      fs.unlinkSync(PLIST_PATH);
+      console.log(chalk.green(`✔ Uninstalled launchd agent ${PLIST_PATH}`));
+    } else {
+      console.log(chalk.yellow(`  No launchd agent found at ${PLIST_PATH}`));
+    }
+  } catch (err: any) {
+    console.log(chalk.red(`✖ Failed to uninstall launchd agent: ${err.message}`));
+  }
+}

package/src/stressCmd.ts

@@ -0,0 +1,59 @@
+import { Worker, isMainThread, workerData } from 'node:worker_threads';
+import os from 'node:os';
+import chalk from 'chalk';
+
+export interface StressOptions {
+  durationSec?: number;
+  cores?: number;
+}
+
+if (!isMainThread) {
+  // Worker thread busywork loop
+  const endTime = workerData?.endTime;
+  while (true) {
+    if (endTime && Date.now() >= endTime) {
+      break;
+    }
+    Math.hypot(Math.random(), Math.random());
+  }
+  process.exit(0);
+}
+
+export async function runStressCommand(opts: StressOptions = {}): Promise<void> {
+  const durationSec = opts.durationSec ?? 30;
+  const numCores = opts.cores ?? os.cpus().length;
+  const endTime = Date.now() + durationSec * 1000;
+
+  console.log(chalk.bold(`\n  pyre stress — Synthetic Load Generator`));
+  console.log(chalk.dim(`  Spawning ${numCores} worker threads for ${durationSec} seconds...`));
+  console.log(chalk.dim(`  Press Ctrl+C to stop early.\n`));
+
+  const workers: Worker[] = [];
+
+  for (let i = 0; i < numCores; i++) {
+    const worker = new Worker(new URL(import.meta.url), {
+      workerData: { endTime },
+    });
+    workers.push(worker);
+  }
+
+  const cleanup = () => {
+    for (const w of workers) {
+      w.terminate();
+    }
+  };
+
+  process.once('SIGINT', () => {
+    cleanup();
+    console.log(chalk.yellow('\n  Stress test cancelled by user.'));
+    process.exit(0);
+  });
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      console.log(chalk.green(`  ✔ Synthetic load test completed after ${durationSec}s.`));
+      resolve();
+    }, durationSec * 1000);
+  });
+}

package/src/wizard.ts

@@ -0,0 +1,61 @@
+import readline from 'node:readline';
+import chalk from 'chalk';
+import { readConfig, writeConfig, CONFIG_FILE } from './state/config.js';
+import fs from 'node:fs';
+
+export async function runSetupWizardIfNeeded(skipWizardFlag?: boolean): Promise<void> {
+  if (skipWizardFlag || process.env.PYRE_NO_WIZARD === '1' || !process.stdout.isTTY) {
+    return;
+  }
+
+  if (fs.existsSync(CONFIG_FILE)) {
+    return;
+  }
+
+  console.log(chalk.bold('\n  🔥 Welcome to pyre! First-run Setup Wizard\n'));
+  console.log(chalk.dim('  This quick 3-question setup configures your defaults.\n'));
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const ask = (query: string): Promise<string> => {
+    return new Promise((resolve) => rl.question(query, resolve));
+  };
+
+  try {
+    // Question 1: Theme
+    console.log(chalk.cyan('  1. Pick a default color theme:'));
+    console.log(chalk.dim('     (1) default  (2) dracula  (3) cyberpunk  (4) monochrome  (5) nord  (6) gruvbox'));
+    const themeAns = (await ask(chalk.yellow('     Choice [1-6] (default: 1): '))).trim();
+    let theme = 'default';
+    if (themeAns === '2') theme = 'dracula';
+    else if (themeAns === '3') theme = 'cyberpunk';
+    else if (themeAns === '4') theme = 'monochrome';
+    else if (themeAns === '5') theme = 'nord';
+    else if (themeAns === '6') theme = 'gruvbox';
+
+    // Question 2: Notifications
+    console.log(chalk.cyan('\n  2. Enable desktop notifications on system thermal/CPU alerts?'));
+    const notifAns = (await ask(chalk.yellow('     Enable notifications? [Y/n]: '))).trim().toLowerCase();
+    const notificationsEnabled = notifAns !== 'n';
+
+    // Question 3: Powermetrics / Sudo explanation
+    console.log(chalk.cyan('\n  3. Sudo / Powermetrics setup:'));
+    console.log(chalk.dim('     pyre reads basic metrics sudolessly. For detailed per-core wattages,'));
+    console.log(chalk.dim('     you can optionally grant passwordless sudo for powermetrics later.'));
+    await ask(chalk.yellow('     Press Enter to finish setup... '));
+
+    writeConfig({
+      theme,
+      notificationsEnabled,
+    });
+
+    console.log(chalk.green('\n  ✔ Preferences saved to ~/.config/pyre/config.json\n'));
+  } catch {
+    // fallback if interrupted
+  } finally {
+    rl.close();
+  }
+}