pyre-cli 9.5.2 → 10.0.0

package/src/smartCmd.ts

@@ -0,0 +1,205 @@
+/**
+ * pyre smart — S.M.A.R.T. disk health inspector.
+ *
+ * Uses smartctl (from smartmontools, via brew install smartmontools)
+ * for detailed SMART data. Falls back to diskutil info when
+ * smartctl is not installed.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import chalk from 'chalk';
+
+const execFileAsync = promisify(execFile);
+
+interface DiskInfo {
+  device: string;
+  model: string;
+  serialNumber: string;
+  health: 'PASSED' | 'FAILED' | 'Unknown';
+  tempC?: number;
+  powerOnHours?: number;
+  reallocatedSectors?: number;
+  percentUsed?: number;
+  bytesRead?: number;
+  bytesWritten?: number;
+  protocol?: string;
+  capacity?: string;
+}
+
+async function runCmd(cmd: string, args: string[], timeoutMs = 5000): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(cmd, args, { timeout: timeoutMs });
+    return stdout.trim();
+  } catch {
+    return '';
+  }
+}
+
+async function getPhysicalDisks(): Promise<string[]> {
+  // 1. First try smartctl --scan --json on all platforms
+  const scanRaw = await runCmd('smartctl', ['--scan', '--json']);
+  if (scanRaw) {
+    try {
+      const parsed = JSON.parse(scanRaw);
+      if (Array.isArray(parsed.devices) && parsed.devices.length > 0) {
+        return parsed.devices.map((d: any) => d.name).filter(Boolean);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // 2. Linux fallback: lsblk
+  if (process.platform === 'linux') {
+    const lsblk = await runCmd('lsblk', ['-dpno', 'NAME']);
+    if (lsblk) {
+      const disks = lsblk.split('\n').map(s => s.trim()).filter(d => /^\/dev\/(sd[a-z]|nvme\d+n\d+|vd[a-z])/.test(d));
+      if (disks.length > 0) return disks;
+    }
+    return ['/dev/sda'];
+  }
+
+  // 3. Windows fallback
+  if (process.platform === 'win32') {
+    return ['/dev/sda', '/dev/csmi0,0'];
+  }
+
+  // 4. macOS fallback: diskutil
+  const raw = await runCmd('diskutil', ['list', '-plist']);
+  if (!raw) return ['/dev/disk0'];
+  const matches = raw.match(/\/dev\/disk\d+(?!s)/g) ?? [];
+  return [...new Set(matches)].filter(d => /^\/dev\/disk\d+$/.test(d));
+}
+
+async function collectSmartctlDisk(device: string): Promise<DiskInfo | null> {
+  const raw = await runCmd('smartctl', ['-a', '--json', device], 6000);
+  if (!raw) return null;
+  try {
+    const j = JSON.parse(raw);
+    const model = j.model_name ?? j.device?.name ?? 'Unknown';
+    const serial = j.serial_number ?? '';
+    const protocol = j.device?.protocol ?? '';
+    const passed = j.smart_status?.passed;
+    const health: DiskInfo['health'] = passed === true ? 'PASSED' : passed === false ? 'FAILED' : 'Unknown';
+
+    let tempC: number | undefined;
+    if (j.temperature?.current !== undefined) tempC = j.temperature.current;
+
+    const poh = j.power_on_time?.hours;
+
+    let reallocated: number | undefined;
+    if (Array.isArray(j.ata_smart_attributes?.table)) {
+      const attr = j.ata_smart_attributes.table.find((a: any) => a.id === 5);
+      if (attr) reallocated = attr.raw?.value ?? 0;
+    }
+
+    let percentUsed: number | undefined;
+    if (j.nvme_smart_health_information_log?.percentage_used !== undefined) {
+      percentUsed = j.nvme_smart_health_information_log.percentage_used;
+    }
+
+    let bytesRead: number | undefined;
+    let bytesWritten: number | undefined;
+    if (j.nvme_smart_health_information_log) {
+      const unitsRead = j.nvme_smart_health_information_log.data_units_read;
+      const unitsWritten = j.nvme_smart_health_information_log.data_units_written;
+      if (unitsRead !== undefined) bytesRead = unitsRead * 512000;
+      if (unitsWritten !== undefined) bytesWritten = unitsWritten * 512000;
+    }
+
+    const userCap = j.user_capacity?.bytes;
+    const capacity = userCap !== undefined
+      ? userCap >= 1e12 ? `${(userCap / 1e12).toFixed(1)} TB`
+        : userCap >= 1e9 ? `${(userCap / 1e9).toFixed(0)} GB`
+        : `${(userCap / 1e6).toFixed(0)} MB`
+      : undefined;
+
+    return { device, model, serialNumber: serial, health, tempC, powerOnHours: poh,
+             reallocatedSectors: reallocated, percentUsed, bytesRead, bytesWritten, protocol, capacity };
+  } catch {
+    return null;
+  }
+}
+
+async function collectDiskutilFallback(device: string): Promise<DiskInfo | null> {
+  const raw = await runCmd('diskutil', ['info', device]);
+  if (!raw) return null;
+  const nameMatch = raw.match(/(?:Device \/ Media Name|Volume Name|Media Name):\s*(.+)/i);
+  const sizeMatch = raw.match(/Disk Size:\s*(.+?\([^)]+\))/i);
+  return {
+    device,
+    model: nameMatch?.[1]?.trim() || 'Unknown',
+    serialNumber: '',
+    health: 'Unknown',
+    capacity: sizeMatch?.[1]?.trim(),
+  };
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes >= 1e15) return `${(bytes / 1e15).toFixed(1)} PB`;
+  if (bytes >= 1e12) return `${(bytes / 1e12).toFixed(1)} TB`;
+  if (bytes >= 1e9) return `${(bytes / 1e9).toFixed(1)} GB`;
+  if (bytes >= 1e6) return `${(bytes / 1e6).toFixed(0)} MB`;
+  return `${bytes} B`;
+}
+
+function healthColor(h: DiskInfo['health']): string {
+  if (h === 'PASSED') return chalk.green(h);
+  if (h === 'FAILED') return chalk.red.bold(h);
+  return chalk.dim(h);
+}
+
+export async function runSmartCommand(): Promise<void> {
+  console.log(chalk.bold('\n  🔥 pyre — S.M.A.R.T. Disk Health\n'));
+
+  const smartctlVersion = await runCmd('smartctl', ['--version'], 2000);
+  const hasSmartctl = smartctlVersion.includes('smartmontools');
+
+  if (!hasSmartctl) {
+    console.log(chalk.yellow('  ⚠ smartctl not found. Showing basic disk info.'));
+    console.log(chalk.dim('  For full SMART data: ') + chalk.cyan('brew install smartmontools') + '\n');
+  }
+
+  const devices = await getPhysicalDisks();
+  if (devices.length === 0) {
+    console.log(chalk.yellow('  No physical disks found.\n'));
+    return;
+  }
+
+  for (const device of devices) {
+    let info: DiskInfo | null = null;
+    if (hasSmartctl) info = await collectSmartctlDisk(device);
+    if (!info) info = await collectDiskutilFallback(device);
+    if (!info) continue;
+
+    console.log(chalk.bold(`  ${info.device}`));
+    console.log(`    Model:            ${info.model}`);
+    if (info.serialNumber) console.log(`    Serial:           ${chalk.dim(info.serialNumber)}`);
+    if (info.protocol) console.log(`    Protocol:         ${info.protocol}`);
+    if (info.capacity) console.log(`    Capacity:         ${info.capacity}`);
+    console.log(`    Health:           ${healthColor(info.health)}`);
+    if (info.tempC !== undefined) {
+      const tc = info.tempC >= 60 ? chalk.red : info.tempC >= 45 ? chalk.yellow : chalk.green;
+      console.log(`    Temperature:      ${tc(`${info.tempC}°C`)}`);
+    }
+    if (info.powerOnHours !== undefined) {
+      const days = Math.floor(info.powerOnHours / 24);
+      console.log(`    Power-On Hours:   ${info.powerOnHours.toLocaleString()} h (${days} days)`);
+    }
+    if (info.reallocatedSectors !== undefined) {
+      const sc = info.reallocatedSectors > 0 ? chalk.yellow : chalk.green;
+      console.log(`    Reallocated Secs: ${sc(info.reallocatedSectors.toString())}`);
+    }
+    if (info.percentUsed !== undefined) {
+      const wc = info.percentUsed >= 90 ? chalk.red : info.percentUsed >= 50 ? chalk.yellow : chalk.green;
+      console.log(`    Wear Level:       ${wc(`${info.percentUsed}% used`)}`);
+    }
+    if (info.bytesRead !== undefined) console.log(`    Data Read:        ${formatBytes(info.bytesRead)}`);
+    if (info.bytesWritten !== undefined) console.log(`    Data Written:     ${formatBytes(info.bytesWritten)}`);
+    console.log();
+  }
+
+  if (!hasSmartctl) {
+    console.log(chalk.dim('  Install smartmontools for full SMART attributes.\n'));
+  }
+}

package/src/state/config.ts

@@ -13,8 +13,6 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-const CONFIG_DIR = path.join(os.homedir(), '.config', 'pyre');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
 export interface PyreConfig {
   theme?: string;
@@ -41,6 +39,22 @@ export interface PyreConfig {
   watchdogMem?: number;
   webhookUrl?: string;
   alertCmd?: string;
+  /** Slack incoming webhook URL for alert notifications */
+  slackAlertUrl?: string;
+  /** Discord webhook URL for alert notifications */
+  discordAlertUrl?: string;
+  /** Pushover application token for alert notifications */
+  pushoverToken?: string;
+  /** Pushover user key for alert notifications */
+  pushoverUser?: string;
+  /** ntfy.sh topic URL (e.g. https://ntfy.sh/my-pyre-alerts) for alert notifications */
+  ntfyUrl?: string;
+  /** AI backend: 'builtin' (heuristic / rule-based), 'ollama', or 'openai' */
+  aiBackend?: string;
+  /** Selected AI model identifier */
+  aiModel?: string;
+  /** Optional API key for external cloud providers */
+  aiApiKey?: string;
   dockerModeConfirmed?: boolean;
   visiblePanels?: {
     cpu?: boolean;
@@ -86,6 +100,14 @@ export const DEFAULT_CONFIG: Required<PyreConfig> = {
   splashAnimation: 'classic',
   webhookUrl: '',
   alertCmd: '',
+  slackAlertUrl: '',
+  discordAlertUrl: '',
+  pushoverToken: '',
+  pushoverUser: '',
+  ntfyUrl: '',
+  aiBackend: 'builtin',
+  aiModel: 'expert-rules-v1',
+  aiApiKey: '',
   dockerModeConfirmed: false,
   visiblePanels: {
     cpu: true,
@@ -106,10 +128,27 @@ export const DEFAULT_CONFIG: Required<PyreConfig> = {
   panelLayout: ['mem', 'disk', 'net'],
 };
 
+export function getConfigDir(): string {
+  return process.env.PYRE_CONFIG_DIR || path.join(os.homedir(), '.config', 'pyre');
+}
+
+export function getConfigFile(): string {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+export function getProfilesDir(): string {
+  return path.join(getConfigDir(), 'profiles');
+}
+
+export const CONFIG_DIR = getConfigDir();
+export const CONFIG_FILE = getConfigFile();
+export const PROFILES_DIR = getProfilesDir();
+
 export function readConfig(): Required<PyreConfig> {
   try {
-    if (!fs.existsSync(CONFIG_FILE)) return { ...DEFAULT_CONFIG };
-    const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+    const file = getConfigFile();
+    if (!fs.existsSync(file)) return { ...DEFAULT_CONFIG };
+    const raw = fs.readFileSync(file, 'utf-8');
     const parsed = JSON.parse(raw) as Partial<PyreConfig>;
     return deepMerge(DEFAULT_CONFIG, parsed);
   } catch {
@@ -119,32 +158,34 @@ export function readConfig(): Required<PyreConfig> {
 
 export function writeConfig(config: Partial<PyreConfig>): void {
   try {
-    if (!fs.existsSync(CONFIG_DIR)) {
-      fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const dir = getConfigDir();
+    const file = getConfigFile();
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
     }
     const merged = deepMerge(readConfig(), config);
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + '\n');
+    fs.writeFileSync(file, JSON.stringify(merged, null, 2) + '\n');
   } catch {
     // ignore write errors
   }
 }
 
-const PROFILES_DIR = path.join(CONFIG_DIR, 'profiles');
-
 export function saveProfile(name: string): void {
   if (!name || name.includes('/') || name.includes('\\')) {
     throw new Error('Invalid profile name.');
   }
-  if (!fs.existsSync(PROFILES_DIR)) {
-    fs.mkdirSync(PROFILES_DIR, { recursive: true });
+  const profilesDir = getProfilesDir();
+  if (!fs.existsSync(profilesDir)) {
+    fs.mkdirSync(profilesDir, { recursive: true });
   }
   const currentConfig = readConfig();
-  const profileFile = path.join(PROFILES_DIR, `${name}.json`);
+  const profileFile = path.join(profilesDir, `${name}.json`);
   fs.writeFileSync(profileFile, JSON.stringify(currentConfig, null, 2) + '\n');
 }
 
 export function loadProfile(name: string): void {
-  const profileFile = path.join(PROFILES_DIR, `${name}.json`);
+  const profilesDir = getProfilesDir();
+  const profileFile = path.join(profilesDir, `${name}.json`);
   if (!fs.existsSync(profileFile)) {
     throw new Error(`Profile '${name}' does not exist.`);
   }
@@ -155,8 +196,9 @@ export function loadProfile(name: string): void {
 }
 
 export function listProfiles(): string[] {
-  if (!fs.existsSync(PROFILES_DIR)) return [];
-  const files = fs.readdirSync(PROFILES_DIR);
+  const profilesDir = getProfilesDir();
+  if (!fs.existsSync(profilesDir)) return [];
+  const files = fs.readdirSync(profilesDir);
   return files.filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''));
 }
 
@@ -175,7 +217,6 @@ function deepMerge(target: any, source: any): any {
 }
 
 export function getConfigPath(): string {
-  return CONFIG_FILE;
+  return getConfigFile();
 }
 
-export { CONFIG_FILE, PROFILES_DIR };

package/src/syncCmd.ts

@@ -0,0 +1,166 @@
+/**
+ * pyre sync — Cloud Configuration & Anomaly History Sync.
+ *
+ * Synchronizes configuration profiles (~/.config/pyre/profiles/),
+ * alert rules, thresholds, and anomaly history across multiple Macs
+ * via iCloud Drive or any user-defined sync folder.
+ *
+ * Commands:
+ *   pyre sync status
+ *   pyre sync push
+ *   pyre sync pull
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import chalk from 'chalk';
+import { getConfigDir, getConfigFile, getProfilesDir, readConfig, writeConfig } from './state/config.js';
+
+export interface SyncOptions {
+  syncDir?: string;
+  force?: boolean;
+}
+
+interface SyncManifest {
+  version: number;
+  lastUpdated: string;
+  sourceHost: string;
+  checksum: string;
+  profilesCount: number;
+}
+
+function getDefaultSyncDir(): string {
+  if (process.env.PYRE_SYNC_DIR) return process.env.PYRE_SYNC_DIR;
+
+  // macOS native iCloud Drive path
+  const icloudPath = path.join(os.homedir(), 'Library', 'Mobile Documents', 'com~apple~CloudDocs', 'PyreSync');
+  if (fs.existsSync(path.dirname(icloudPath))) {
+    return icloudPath;
+  }
+
+  // Fallback to cross-platform standard shared folder
+  return path.join(os.homedir(), '.pyre-sync');
+}
+
+function computeDirChecksum(dirPath: string): string {
+  const hash = crypto.createHash('sha256');
+  if (!fs.existsSync(dirPath)) return '';
+
+  const files = fs.readdirSync(dirPath).sort();
+  for (const file of files) {
+    const full = path.join(dirPath, file);
+    if (fs.statSync(full).isFile()) {
+      hash.update(file);
+      hash.update(fs.readFileSync(full));
+    }
+  }
+  return hash.digest('hex').slice(0, 16);
+}
+
+export async function runSyncCommand(subcommand: string = 'status', opts: SyncOptions = {}): Promise<void> {
+  const syncDir = opts.syncDir || getDefaultSyncDir();
+  const manifestPath = path.join(syncDir, 'sync-manifest.json');
+  const remoteProfilesDir = path.join(syncDir, 'profiles');
+  const remoteConfigFile = path.join(syncDir, 'config.json');
+
+  const localProfilesDir = getProfilesDir();
+  const localConfigFile = getConfigFile();
+
+  console.log(chalk.bold('\n  🔥 pyre sync — Configuration & Profile Cloud Sync\n'));
+  console.log(`  Sync Target Directory: ${chalk.cyan(syncDir)}`);
+
+  if (subcommand === 'status' || !subcommand) {
+    const hasSyncDir = fs.existsSync(syncDir);
+    const hasManifest = fs.existsSync(manifestPath);
+
+    console.log(`  Local Profiles:        ${chalk.bold(String(fs.existsSync(localProfilesDir) ? fs.readdirSync(localProfilesDir).filter(f => f.endsWith('.json')).length : 0))}`);
+    console.log(`  Sync Target Available: ${hasSyncDir ? chalk.green('YES') : chalk.yellow('NO (will be created on push)')}`);
+
+    if (hasManifest) {
+      try {
+        const manifest: SyncManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        console.log(`  Remote Last Updated:   ${chalk.green(manifest.lastUpdated)} (from ${chalk.bold(manifest.sourceHost)})`);
+        console.log(`  Remote Profiles Count: ${chalk.bold(String(manifest.profilesCount))}`);
+        console.log(`  Remote Checksum:       ${chalk.dim(manifest.checksum)}`);
+      } catch {
+        console.log(chalk.yellow('  Remote manifest corrupted.'));
+      }
+    } else {
+      console.log(chalk.dim('  No remote sync bundle detected yet. Run "pyre sync push" to initialize.'));
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'push') {
+    if (!fs.existsSync(syncDir)) {
+      fs.mkdirSync(syncDir, { recursive: true });
+    }
+    if (!fs.existsSync(remoteProfilesDir)) {
+      fs.mkdirSync(remoteProfilesDir, { recursive: true });
+    }
+
+    // 1. Sync config.json
+    if (fs.existsSync(localConfigFile)) {
+      fs.copyFileSync(localConfigFile, remoteConfigFile);
+    }
+
+    // 2. Sync profiles/
+    let profileCount = 0;
+    if (fs.existsSync(localProfilesDir)) {
+      const files = fs.readdirSync(localProfilesDir).filter(f => f.endsWith('.json'));
+      profileCount = files.length;
+      for (const f of files) {
+        fs.copyFileSync(path.join(localProfilesDir, f), path.join(remoteProfilesDir, f));
+      }
+    }
+
+    // 3. Write manifest
+    const checksum = computeDirChecksum(remoteProfilesDir);
+    const manifest: SyncManifest = {
+      version: 1,
+      lastUpdated: new Date().toISOString(),
+      sourceHost: os.hostname(),
+      checksum,
+      profilesCount: profileCount,
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    console.log(chalk.green(`  ✔ Successfully pushed config and ${profileCount} profile(s) to sync target.`));
+    console.log(`  Checksum: ${chalk.dim(checksum)}  |  Timestamp: ${chalk.dim(manifest.lastUpdated)}\n`);
+    return;
+  }
+
+  if (subcommand === 'pull') {
+    if (!fs.existsSync(manifestPath) || !fs.existsSync(remoteConfigFile)) {
+      console.error(chalk.red(`  ✖ Error: No sync manifest found at ${syncDir}. Run "pyre sync push" first from another machine.\n`));
+      process.exit(1);
+    }
+
+    // 1. Pull config.json
+    if (fs.existsSync(remoteConfigFile)) {
+      const remoteConfig = JSON.parse(fs.readFileSync(remoteConfigFile, 'utf-8'));
+      writeConfig(remoteConfig);
+    }
+
+    // 2. Pull profiles
+    let pulledCount = 0;
+    if (fs.existsSync(remoteProfilesDir)) {
+      if (!fs.existsSync(localProfilesDir)) {
+        fs.mkdirSync(localProfilesDir, { recursive: true });
+      }
+      const files = fs.readdirSync(remoteProfilesDir).filter(f => f.endsWith('.json'));
+      pulledCount = files.length;
+      for (const f of files) {
+        fs.copyFileSync(path.join(remoteProfilesDir, f), path.join(localProfilesDir, f));
+      }
+    }
+
+    console.log(chalk.green(`  ✔ Successfully pulled latest configuration and ${pulledCount} profile(s).`));
+    console.log(chalk.dim(`  Applied to ${localConfigFile}\n`));
+    return;
+  }
+
+  console.log(chalk.yellow(`  Unknown subcommand: "${subcommand}". Available: status, push, pull\n`));
+}

package/src/topoCmd.ts

@@ -0,0 +1,176 @@
+/**
+ * pyre topo — Network Topology Mapper.
+ *
+ * Visualizes the local network topology, including default gateways,
+ * active routing paths, LAN neighbors (via ARP cache), and active remote sockets.
+ * Also scans LAN neighbors for running pyre instances (P2P port 9876, REST port 8080/3000).
+ */
+import net from 'node:net';
+import os from 'node:os';
+import chalk from 'chalk';
+import { run } from './monitors/run.js';
+import { collectNetwork } from './monitors/collectors.js';
+
+export interface TopoOptions {
+  scan?: boolean;
+  json?: boolean;
+}
+
+interface LanPeer {
+  ip: string;
+  mac: string;
+  interface: string;
+  isGateway: boolean;
+  pyreP2P?: boolean;
+  pyreRest?: boolean;
+  hostname?: string;
+}
+
+async function probePort(ip: string, port: number, timeoutMs = 400): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once('timeout', () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once('error', () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.connect(port, ip);
+  });
+}
+
+async function getDefaultGateway(): Promise<string> {
+  try {
+    const raw = await run("route -n get default 2>/dev/null | grep gateway | awk '{print $2}'", '');
+    if (raw.trim()) return raw.trim();
+  } catch {}
+  try {
+    const raw = await run("netstat -nr | grep default | awk '{print $2}' | head -n1", '');
+    if (raw.trim()) return raw.trim();
+  } catch {}
+  return '192.168.1.1';
+}
+
+async function getArpNeighbors(gatewayIp: string): Promise<LanPeer[]> {
+  const peers: LanPeer[] = [];
+  try {
+    const raw = await run('arp -a -n 2>/dev/null', '');
+    const lines = raw.split('\n');
+    for (const line of lines) {
+      // macOS format: "? (192.168.1.1) at 0:11:22:33:44:55 on en0 ifscope [ethernet]"
+      const match = line.match(/\(([\d.]+)\)\s+at\s+([0-9a-fA-F:]+)\s+on\s+(\S+)/);
+      if (match) {
+        const ip = match[1];
+        const mac = match[2];
+        const iface = match[3];
+        if (ip === '255.255.255.255' || ip.startsWith('224.') || mac.includes('incomplete')) continue;
+        peers.push({
+          ip,
+          mac,
+          interface: iface,
+          isGateway: ip === gatewayIp,
+        });
+      }
+    }
+  } catch {}
+  return peers;
+}
+
+export async function runTopoCommand(opts: TopoOptions = {}): Promise<void> {
+  const localNet = await collectNetwork();
+  const gatewayIp = await getDefaultGateway();
+  const lanPeers = await getArpNeighbors(gatewayIp);
+  const hostname = os.hostname();
+
+  // If scan is requested or small peer count, probe common pyre ports
+  if (opts.scan || lanPeers.length <= 15) {
+    await Promise.all(
+      lanPeers.map(async (peer) => {
+        const [hasP2P, hasRest] = await Promise.all([
+          probePort(peer.ip, 9876, 250),
+          probePort(peer.ip, 8080, 250),
+        ]);
+        peer.pyreP2P = hasP2P;
+        peer.pyreRest = hasRest;
+      })
+    );
+  }
+
+  const establishedConns = (localNet.topRemoteHosts || []).slice(0, 6);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          localNode: {
+            hostname,
+            ip: localNet.ip,
+            interface: localNet.interface,
+          },
+          gateway: gatewayIp,
+          lanPeers,
+          activeRemoteConnections: establishedConns,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  console.log(chalk.bold('\n  🔥 pyre topo — Network Topology Map\n'));
+
+  // Local Host Header Box
+  console.log(`  ${chalk.bgCyan.black.bold(' LOCAL HOST ')} ${chalk.bold(hostname)}`);
+  console.log(`    ├── IP Address:       ${chalk.green.bold(localNet.ip || '127.0.0.1')} (${localNet.interface})`);
+  console.log(`    ├── Active RX / TX:   ↓ ${chalk.cyan(localNet.rxBytes ? `${(localNet.rxBytes / 1e6).toFixed(1)} MB` : '0 MB')}  ↑ ${chalk.blue(localNet.txBytes ? `${(localNet.txBytes / 1e6).toFixed(1)} MB` : '0 MB')}`);
+  console.log('    │');
+
+  // Gateway Node
+  console.log(`    ├── ${chalk.yellow.bold('DEFAULT GATEWAY / ROUTER')}`);
+  console.log(`    │    └── IP: ${chalk.yellow(gatewayIp)}  [Route → WAN / Internet]`);
+  console.log('    │');
+
+  // LAN Neighborhood
+  console.log(`    ├── ${chalk.magenta.bold('LAN NEIGHBORS & PEERS')} (${lanPeers.length} discovered via ARP)`);
+  if (lanPeers.length === 0) {
+    console.log(`    │    └── ${chalk.dim('No neighboring ARP entries currently cached.')}`);
+  } else {
+    for (let i = 0; i < lanPeers.length; i++) {
+      const peer = lanPeers[i];
+      const isLast = i === lanPeers.length - 1;
+      const prefix = isLast ? '    │    └──' : '    │    ├──';
+      const gwBadge = peer.isGateway ? chalk.yellow(' [Gateway]') : '';
+      let pyreBadge = '';
+      if (peer.pyreP2P) pyreBadge += chalk.hex('#ff5500').bold(' [🔥 pyre P2P :9876]');
+      if (peer.pyreRest) pyreBadge += chalk.hex('#00ffcc').bold(' [🔥 pyre REST :8080]');
+
+      console.log(`${prefix} ${peer.ip.padEnd(16)} ${chalk.dim(peer.mac)}${gwBadge}${pyreBadge}`);
+    }
+  }
+  console.log('    │');
+
+  // Active External Remote Sockets
+  console.log(`    └── ${chalk.cyan.bold('TOP ACTIVE REMOTE CONNECTIONS')}`);
+  if (establishedConns.length === 0) {
+    console.log(`         └── ${chalk.dim('No active established sockets detected.')}`);
+  } else {
+    for (let i = 0; i < establishedConns.length; i++) {
+      const conn = establishedConns[i];
+      const isLast = i === establishedConns.length - 1;
+      const prefix = isLast ? '         └──' : '         ├──';
+      const connsBadge = chalk.dim(`(${conn.connectionCount} socket${conn.connectionCount > 1 ? 's' : ''})`);
+      console.log(`${prefix} ${chalk.white(conn.host.padEnd(24))} ${chalk.green('ESTABLISHED')} ${connsBadge}`);
+    }
+  }
+
+  console.log();
+  console.log(chalk.dim('  Tip: Run "pyre p2p server" on any node to allow automatic live cluster streaming.\n'));
+}