bgrun 3.12.2 → 3.12.4

package/dist/index.js

@@ -25,6 +25,7 @@ __export(exports_platform, {
   reconcileProcessPids: () => reconcileProcessPids,
   readFileTail: () => readFileTail,
   psExec: () => psExec,
+  parseUnixListeningPorts: () => parseUnixListeningPorts,
   killProcessOnPort: () => killProcessOnPort,
   isWindows: () => isWindows,
   isProcessRunning: () => isProcessRunning,
@@ -457,6 +458,17 @@ async function getProcessBatchResources(pids) {
     return resourceMap;
   }) ?? new Map;
 }
+function parseUnixListeningPorts(output) {
+  const ports = new Set;
+  for (const line of output.split(`
+`)) {
+    const portMatch = line.match(/:(\d+)\s+\(LISTEN\)/);
+    if (portMatch) {
+      ports.add(parseInt(portMatch[1]));
+    }
+  }
+  return Array.from(ports);
+}
 async function getProcessPorts(pid) {
   try {
     if (isWindows()) {
@@ -473,29 +485,21 @@ async function getProcessPorts(pid) {
     } else {
       try {
         const result2 = await $`ss -tlnp`.nothrow().quiet().text();
-        const ports2 = new Set;
+        const ports = new Set;
         for (const line of result2.split(`
 `)) {
           if (line.includes(`pid=${pid}`)) {
             const portMatch = line.match(/:(\d+)\s/);
             if (portMatch) {
-              ports2.add(parseInt(portMatch[1]));
+              ports.add(parseInt(portMatch[1]));
             }
           }
         }
-        if (ports2.size > 0)
-          return Array.from(ports2);
+        if (ports.size > 0)
+          return Array.from(ports);
       } catch {}
       const result = await $`lsof -Pan -p ${pid} -iTCP -sTCP:LISTEN`.nothrow().quiet().text();
-      const ports = new Set;
-      for (const line of result.split(`
-`)) {
-        const portMatch = line.match(/:(\d+)\s+\(LISTEN\)/);
-        if (portMatch) {
-          ports.add(parseInt(portMatch[1]));
-        }
-      }
-      return Array.from(ports);
+      return parseUnixListeningPorts(result);
     }
   } catch {
     return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bgrun",
-  "version": "3.12.2",
+  "version": "3.12.4",
   "description": "bgrun — A lightweight process manager for Bun",
   "type": "module",
   "main": "./src/api.ts",
@@ -8,7 +8,7 @@
     ".": "./src/api.ts"
   },
   "bin": {
-    "bgrun": "./dist/index.js"
+    "bgrun": "dist/index.js"
   },
   "scripts": {
     "build": "bun run ./src/build.ts",
@@ -17,7 +17,22 @@
   },
   "files": [
     "dist",
-    "src",
+    "src/api.ts",
+    "src/build.ts",
+    "src/config.ts",
+    "src/db.ts",
+    "src/deploy.ts",
+    "src/deps.ts",
+    "src/guard.ts",
+    "src/index.ts",
+    "src/log-rotation.ts",
+    "src/logger.ts",
+    "src/platform.ts",
+    "src/server.ts",
+    "src/table.ts",
+    "src/types.ts",
+    "src/utils.ts",
+    "src/commands",
     "dashboard/app",
     "scripts",
     "README.md",
@@ -37,7 +52,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/7flash/bgrun.git"
+    "url": "git+https://github.com/7flash/bgrun.git"
   },
   "devDependencies": {
     "@types/bun": "^1.3.10",

package/src/platform.ts

@@ -608,6 +608,20 @@ export async function getProcessBatchResources(pids: number[]): Promise<Map<numb
   }) ?? new Map();
 }
 
+/**
+ * Parse Unix lsof LISTEN output and return only true listening TCP ports.
+ */
+export function parseUnixListeningPorts(output: string): number[] {
+  const ports = new Set<number>();
+  for (const line of output.split('\n')) {
+    const portMatch = line.match(/:(\d+)\s+\(LISTEN\)/);
+    if (portMatch) {
+      ports.add(parseInt(portMatch[1]));
+    }
+  }
+  return Array.from(ports);
+}
+
 /**
  * Get the TCP ports a process is currently listening on by querying the OS.
  * Returns an array of port numbers (empty if none or process not found).
@@ -643,14 +657,7 @@ export async function getProcessPorts(pid: number): Promise<number[]> {
       } catch { /* ss not available, try lsof */ }
 
       const result = await $`lsof -Pan -p ${pid} -iTCP -sTCP:LISTEN`.nothrow().quiet().text();
-      const ports = new Set<number>();
-      for (const line of result.split('\n')) {
-        const portMatch = line.match(/:(\d+)\s+\(LISTEN\)/);
-        if (portMatch) {
-          ports.add(parseInt(portMatch[1]));
-        }
-      }
-      return Array.from(ports);
+      return parseUnixListeningPorts(result);
     }
   } catch {
     return [];

package/src/bgrun.test.ts

@@ -1,280 +0,0 @@
-/**
- * bgrun core utility tests
- *
- * Tests pure logic functions: env parsing, config flattening,
- * string truncation, and runtime calculation.
- *
- * Run: bun test src/bgrun.test.ts
- */
-import { describe, expect, test } from 'bun:test'
-import { parseEnvString, calculateRuntime } from './utils'
-import { stripAnsi, truncateString, truncatePath } from './table'
-import { detectPackageManager, formatDeployToolError } from './deploy'
-import { isProcessRunning } from './platform'
-import { mkdirSync, rmSync } from 'fs'
-
-// Use a test-specific database to avoid polluting real data
-process.env.BGRUN_DB = `bgrun-test-${Date.now()}.sqlite`
-import { addDependency, removeDependency, getDependencyGraph, getDependencies, getDependents, getStartOrder, removeAllDependencies } from './db'
-
-// ─── parseEnvString ─────────────────────────────────────
-
-describe('parseEnvString', () => {
-    test('parses comma-separated key=value pairs', () => {
-        const result = parseEnvString('PORT=3000,HOST=localhost,DEBUG=true')
-        expect(result).toEqual({
-            PORT: '3000',
-            HOST: 'localhost',
-            DEBUG: 'true',
-        })
-    })
-
-    test('handles single pair', () => {
-        expect(parseEnvString('KEY=value')).toEqual({ KEY: 'value' })
-    })
-
-    test('handles empty string', () => {
-        expect(parseEnvString('')).toEqual({})
-    })
-
-    test('ignores malformed pairs (no =)', () => {
-        const result = parseEnvString('GOOD=yes,BAD,ALSO_GOOD=ok')
-        expect(result.GOOD).toBe('yes')
-        expect(result.ALSO_GOOD).toBe('ok')
-        expect(result.BAD).toBeUndefined()
-    })
-})
-
-// ─── calculateRuntime ───────────────────────────────────
-
-describe('calculateRuntime', () => {
-    test('returns 0 minutes for recent start', () => {
-        const now = new Date().toISOString()
-        expect(calculateRuntime(now)).toBe('0 minutes')
-    })
-
-    test('returns correct minutes', () => {
-        const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString()
-        expect(calculateRuntime(fiveMinAgo)).toBe('5 minutes')
-    })
-
-    test('returns correct for 1 hour', () => {
-        const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString()
-        expect(calculateRuntime(oneHourAgo)).toBe('60 minutes')
-    })
-})
-
-// ─── stripAnsi ──────────────────────────────────────────
-
-describe('stripAnsi', () => {
-    test('strips color codes', () => {
-        const colored = '\u001b[31mred text\u001b[0m'
-        expect(stripAnsi(colored)).toBe('red text')
-    })
-
-    test('passes through plain text', () => {
-        expect(stripAnsi('hello world')).toBe('hello world')
-    })
-
-    test('handles empty string', () => {
-        expect(stripAnsi('')).toBe('')
-    })
-})
-
-// ─── truncateString ─────────────────────────────────────
-
-describe('truncateString', () => {
-    test('returns string unchanged if within limit', () => {
-        expect(truncateString('hello', 10)).toBe('hello')
-    })
-
-    test('truncates with ellipsis', () => {
-        const result = truncateString('a very long string that exceeds limit', 15)
-        expect(result.length).toBeLessThanOrEqual(15)
-        expect(result).toContain('…')
-    })
-
-    test('handles maxLength smaller than ellipsis', () => {
-        const result = truncateString('hello world', 2)
-        expect(result.length).toBeLessThanOrEqual(2)
-    })
-})
-
-// ─── truncatePath ───────────────────────────────────────
-
-describe('truncatePath', () => {
-    test('returns path unchanged if within limit', () => {
-        expect(truncatePath('/home/user', 50)).toBe('/home/user')
-    })
-
-    test('truncates middle of long path', () => {
-        const longPath = '/home/user/projects/very/deeply/nested/directory/structure'
-        const result = truncatePath(longPath, 30)
-        expect(result.length).toBeLessThanOrEqual(30)
-        expect(result).toContain('…')
-    })
-})
-
-// ─── detectPackageManager ───────────────────────────────
-
-// ─── isProcessRunning (Windows liveness fallback) ───────
-
-describe('isProcessRunning', () => {
-    test('returns true for the current process PID', async () => {
-        const alive = await isProcessRunning(process.pid)
-        expect(alive).toBe(true)
-    })
-
-    test('returns false for PID 0 (intentionally stopped)', async () => {
-        const alive = await isProcessRunning(0)
-        expect(alive).toBe(false)
-    })
-
-    test('returns false for a very high unlikely PID', async () => {
-        const alive = await isProcessRunning(999999)
-        expect(alive).toBe(false)
-    })
-
-    test('returns false for negative PID', async () => {
-        const alive = await isProcessRunning(-1)
-        expect(alive).toBe(false)
-    })
-})
-
-// ─── detectPackageManager ───────────────────────────────
-
-describe('formatDeployToolError', () => {
-    test('returns actionable message for missing binary', () => {
-        const msg = formatDeployToolError('pnpm', new Error('command not found: pnpm'))
-        expect(msg).toContain("requires 'pnpm'")
-        expect(msg).toContain('PATH')
-    })
-
-    test('preserves non-missing-binary failures', () => {
-        const msg = formatDeployToolError('npm', new Error('npm ci failed with exit code 1'))
-        expect(msg).toContain('Dependency install failed with npm')
-        expect(msg).toContain('exit code 1')
-    })
-})
-
-describe('detectPackageManager', () => {
-    test('returns null when no package.json exists', async () => {
-        const dir = `${process.cwd()}/tmp-no-package-${Date.now()}`
-        mkdirSync(dir, { recursive: true })
-        try {
-            expect(await detectPackageManager(dir)).toBeNull()
-        } finally {
-            rmSync(dir, { recursive: true, force: true })
-        }
-    })
-
-    test('prefers bun lockfiles', async () => {
-        const dir = `${process.cwd()}/tmp-bun-${Date.now()}`
-        mkdirSync(dir, { recursive: true })
-        try {
-            await Bun.write(`${dir}/package.json`, '{}')
-            await Bun.write(`${dir}/bun.lock`, '')
-            expect(await detectPackageManager(dir)).toBe('bun')
-        } finally {
-            rmSync(dir, { recursive: true, force: true })
-        }
-    })
-
-    test('detects pnpm, yarn, and npm lockfiles', async () => {
-        const base = `${process.cwd()}/tmp-pm-${Date.now()}`
-
-        const pnpmDir = `${base}-pnpm`
-        mkdirSync(pnpmDir, { recursive: true })
-        await Bun.write(`${pnpmDir}/package.json`, '{}')
-        await Bun.write(`${pnpmDir}/pnpm-lock.yaml`, '')
-        expect(await detectPackageManager(pnpmDir)).toBe('pnpm')
-
-        const yarnDir = `${base}-yarn`
-        mkdirSync(yarnDir, { recursive: true })
-        await Bun.write(`${yarnDir}/package.json`, '{}')
-        await Bun.write(`${yarnDir}/yarn.lock`, '')
-        expect(await detectPackageManager(yarnDir)).toBe('yarn')
-
-        const npmDir = `${base}-npm`
-        mkdirSync(npmDir, { recursive: true })
-        await Bun.write(`${npmDir}/package.json`, '{}')
-        await Bun.write(`${npmDir}/package-lock.json`, '{}')
-        expect(await detectPackageManager(npmDir)).toBe('npm')
-
-        rmSync(pnpmDir, { recursive: true, force: true })
-        rmSync(yarnDir, { recursive: true, force: true })
-        rmSync(npmDir, { recursive: true, force: true })
-    })
-
-    test('defaults to bun for package.json projects without a lockfile', async () => {
-        const dir = `${process.cwd()}/tmp-default-bun-${Date.now()}`
-        mkdirSync(dir, { recursive: true })
-        try {
-            await Bun.write(`${dir}/package.json`, '{}')
-            expect(await detectPackageManager(dir)).toBe('bun')
-        } finally {
-            rmSync(dir, { recursive: true, force: true })
-        }
-    })
-})
-
-// ─── Dependencies ───────────────────────────────────────
-
-describe('addDependency', () => {
-    test('adds a valid dependency', () => {
-        removeAllDependencies('web-server');
-        removeAllDependencies('database');
-        const ok = addDependency('web-server', 'database');
-        expect(ok).toBe(true);
-        expect(getDependencies('web-server')).toContain('database');
-    })
-
-    test('prevents self-dependency', () => {
-        expect(addDependency('api', 'api')).toBe(false);
-    })
-
-    test('prevents duplicate dependency', () => {
-        removeAllDependencies('app');
-        addDependency('app', 'db');
-        expect(addDependency('app', 'db')).toBe(false);
-    })
-
-    test('prevents circular dependency', () => {
-        removeAllDependencies('a');
-        removeAllDependencies('b');
-        removeAllDependencies('c');
-        addDependency('a', 'b');
-        addDependency('b', 'c');
-        // c -> a would create a cycle
-        expect(addDependency('c', 'a')).toBe(false);
-    })
-})
-
-describe('getDependencyGraph', () => {
-    test('returns full graph', () => {
-        removeAllDependencies('svc-a');
-        removeAllDependencies('svc-b');
-        addDependency('svc-a', 'svc-b');
-        const graph = getDependencyGraph();
-        expect(graph['svc-a']).toContain('svc-b');
-    })
-})
-
-describe('getDependents', () => {
-    test('finds processes that depend on a target', () => {
-        removeAllDependencies('frontend');
-        removeAllDependencies('backend');
-        addDependency('frontend', 'backend');
-        expect(getDependents('backend')).toContain('frontend');
-    })
-})
-
-describe('removeDependency', () => {
-    test('removes an existing dependency', () => {
-        removeAllDependencies('x');
-        addDependency('x', 'y');
-        expect(getDependencies('x')).toContain('y');
-        removeDependency('x', 'y');
-        expect(getDependencies('x')).not.toContain('y');
-    })
-})

package/src/index_copy.ts

@@ -1,614 +0,0 @@
-#!/usr/bin/env bun
-
-import { parseArgs } from "util";
-import { getVersion } from "./utils";
-import { handleRun } from "./commands/run";
-import { showAll } from "./commands/list";
-import { handleDelete, handleClean, handleDeleteAll, handleStop } from "./commands/cleanup";
-import { handleWatch } from "./commands/watch";
-import { showLogs } from "./commands/logs";
-import { showDetails } from "./commands/details";
-import type { CommandOptions } from "./types";
-import { error, announce } from "./logger";
-// startServer is dynamically imported only when --_serve is used
-// to avoid loading melina (which has side-effects) on every bgrun command
-import { getHomeDir, getShellCommand, findChildPid, isProcessRunning, terminateProcess, getProcessPorts, killProcessOnPort, waitForPortFree, isPortFree, findPidByPort } from "./platform";
-import { insertProcess, removeProcessByName, getProcess, retryDatabaseOperation, getDbInfo } from "./db";
-import dedent from "dedent";
-import chalk from "chalk";
-import { join } from "path";
-import { sleep } from "bun";
-import { configure } from "measure-fn";
-
-if (!Bun.argv.includes("--_serve")) {
-  if (!Bun.env.MEASURE_SILENT) {
-    configure({ silent: true });
-  }
-}
-
-/**
- * Redirect console.log/warn/error to log files when running detached.
- * The parent spawner passes file paths via BGR_STDOUT/BGR_STDERR env vars.
- * Appends timestamped lines so `bgrun <name> --logs` shows real output.
- */
-function redirectConsoleToFiles() {
-  const stdoutPath = Bun.env.BGR_STDOUT;
-  const stderrPath = Bun.env.BGR_STDERR;
-  if (!stdoutPath && !stderrPath) return; // Not detached, keep normal console
-
-  const { appendFileSync } = require('fs');
-
-  // Strip ANSI escape codes for clean log files
-  const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, '');
-
-  const timestamp = () => new Date().toISOString().replace('T', ' ').substring(0, 19);
-
-  if (stdoutPath) {
-    const origLog = console.log;
-    const origWarn = console.warn;
-    console.log = (...args: any[]) => {
-      const line = `[${timestamp()}] ${stripAnsi(args.map(String).join(' '))}\n`;
-      try { appendFileSync(stdoutPath, line); } catch { }
-      origLog.apply(console, args); // Also keep original (goes to /dev/null when detached, but useful if attached)
-    };
-    console.warn = (...args: any[]) => {
-      const line = `[${timestamp()}] WARN: ${stripAnsi(args.map(String).join(' '))}\n`;
-      try { appendFileSync(stdoutPath, line); } catch { }
-      origWarn.apply(console, args);
-    };
-  }
-
-  if (stderrPath) {
-    const origError = console.error;
-    console.error = (...args: any[]) => {
-      const line = `[${timestamp()}] ERROR: ${stripAnsi(args.map(String).join(' '))}\n`;
-      try { appendFileSync(stderrPath, line); } catch { }
-      origError.apply(console, args);
-    };
-  }
-}
-
-async function showHelp() {
-  const usage = dedent`
-    ${chalk.bold('bgrun — Bun Background Runner')}
-    ${chalk.gray('═'.repeat(50))}
-
-    ${chalk.yellow('Usage:')}
-      bgrun [name] [options]
-
-    ${chalk.yellow('Commands:')}
-      bgrun                     List all processes
-      bgrun [name]             Show details for a process
-      bgrun --dashboard        Launch web dashboard (managed by bgrun)
-      bgrun --guard            Launch standalone process guard
-      bgrun --restart [name]   Restart a process
-      bgrun --restart-all      Restart ALL registered processes
-      bgrun --stop [name]      Stop a process (keep in registry)
-      bgrun --stop-all         Stop ALL running processes
-      bgrun --delete [name]    Delete a process
-      bgrun --clean            Remove all stopped processes
-      bgrun --nuke             Delete ALL processes
-
-    ${chalk.yellow('Options:')}
-      --name <string>        Process name (required for new)
-      --command <string>     Process command (required for new)
-      --directory <path>     Working directory (required for new)
-      --config <path>        Config file (default: .config.toml)
-      --watch                Watch for file changes and auto-restart
-      --force                Force restart existing process
-      --fetch                Fetch latest git changes before running
-      --json                 Output in JSON format
-      --filter <group>       Filter list by BGR_GROUP
-      --logs                 Show logs
-      --log-stdout           Show only stdout logs
-      --log-stderr           Show only stderr logs
-      --lines <n>            Number of log lines to show (default: all)
-      --version              Show version
-      --debug                Show debug info (DB path, BGR home, etc.)
-      --dashboard            Launch web dashboard as bgrun-managed process
-      --port <number>        Port for dashboard (default: 3000)
-      --help                 Show this help message
-
-    ${chalk.yellow('Examples:')}
-      bgrun --dashboard
-      bgrun --name myapp --command "bun run dev" --directory . --watch
-      bgrun myapp --logs --lines 50
-  `;
-  console.log(usage);
-}
-
-// Re-running parseArgs logic properly
-async function run() {
-  const { values, positionals } = parseArgs({
-    args: Bun.argv.slice(2),
-    options: {
-      name: { type: 'string' },
-      command: { type: 'string' },
-      directory: { type: 'string' },
-      config: { type: 'string' },
-      watch: { type: 'boolean' },
-      force: { type: 'boolean' },
-      fetch: { type: 'boolean' },
-      delete: { type: 'boolean' },
-      nuke: { type: 'boolean' },
-      restart: { type: 'boolean' },
-      "restart-all": { type: 'boolean' },
-      stop: { type: 'boolean' },
-      "stop-all": { type: 'boolean' },
-      clean: { type: 'boolean' },
-      json: { type: 'boolean' },
-      logs: { type: 'boolean' },
-      "log-stdout": { type: 'boolean' },
-      "log-stderr": { type: 'boolean' },
-      lines: { type: 'string' },
-      filter: { type: 'string' },
-      version: { type: 'boolean' },
-      help: { type: 'boolean' },
-      db: { type: 'string' },
-      stdout: { type: 'string' },
-      stderr: { type: 'string' },
-      dashboard: { type: 'boolean' },
-      guard: { type: 'boolean' },
-      debug: { type: 'boolean' },
-      "_serve": { type: 'boolean' },
-      "_guard-loop": { type: 'boolean' },
-      port: { type: 'string' },
-    },
-    strict: false,
-    allowPositionals: true,
-  });
-
-  // Internal: actually run the HTTP server (spawned by --dashboard)
-  // Port is NOT passed explicitly — Melina auto-detects from BUN_PORT env
-  // or defaults to 3000 with fallback to next available port.
-  if (values['_serve']) {
-    // Redirect console output to log files when running detached
-    // The spawner passes paths via BGR_STDOUT/BGR_STDERR env vars
-    redirectConsoleToFiles();
-    const { startServer } = await import("./server");
-    await startServer();
-    return;
-  }
-
-  // Internal: actually run the guard loop (spawned by --guard)
-  if (values['_guard-loop']) {
-    // Redirect console output to log files when running detached
-    redirectConsoleToFiles();
-    const { startGuardLoop } = await import("./guard");
-    const intervalStr = positionals[0];
-    const intervalMs = intervalStr ? parseInt(intervalStr) * 1000 : undefined;
-    await startGuardLoop(intervalMs);
-    return;
-  }
-
-  // Dashboard: spawn the dashboard server as a bgr-managed process
-  if (values.dashboard) {
-    const dashboardName = 'bgr-dashboard';
-    const homePath = getHomeDir();
-    const bgrDir = join(homePath, '.bgr');
-    // User can request a specific port via BUN_PORT=XXXX bgrun --dashboard
-    // Otherwise Melina picks automatically (3000 → fallback)
-    const requestedPort = values.port as string | undefined;
-
-    // Check if dashboard is already running
-    const existing = getProcess(dashboardName);
-    if (existing && await isProcessRunning(existing.pid)) {
-      // The stored PID may be the shell wrapper (cmd.exe), not the actual bun process
-      // Try the stored PID first, then traverse the process tree to find the real one
-      let existingPorts = await getProcessPorts(existing.pid);
-      if (existingPorts.length === 0) {
-        const childPid = await findChildPid(existing.pid);
-        if (childPid !== existing.pid) {
-          existingPorts = await getProcessPorts(childPid);
-        }
-      }
-      const portStr = existingPorts.length > 0 ? `:${existingPorts[0]}` : '(detecting...)';
-      announce(
-        `Dashboard is already running (PID ${existing.pid})\n\n` +
-        `  🌐  ${chalk.cyan(`http://localhost${portStr}`)}\n\n` +
-        `  Use ${chalk.yellow(`bgrun --stop ${dashboardName}`)} to stop it\n` +
-        `  Use ${chalk.yellow(`bgrun --dashboard --force`)} to restart`,
-        'BGR Dashboard'
-      );
-      return;
-    }
-
-    // Kill existing if force
-    if (existing) {
-      if (await isProcessRunning(existing.pid)) {
-        const detectedPorts = await getProcessPorts(existing.pid);
-        await terminateProcess(existing.pid);
-        for (const p of detectedPorts) {
-          await killProcessOnPort(p);
-          await waitForPortFree(p, 5000);
-        }
-      }
-      await retryDatabaseOperation(() => removeProcessByName(dashboardName));
-    }
-
-    // Spawn the dashboard server as a managed process
-    // Port is NOT passed as CLI arg — Melina will auto-detect.
-    // If user wants a specific port, we pass it via BUN_PORT env var.
-    const { resolve } = require('path');
-    const scriptPath = resolve(process.argv[1]);
-    const spawnCommand = `bun run ${scriptPath} --_serve`;
-    const command = `bgrun --_serve`;
-    const stdoutPath = join(bgrDir, `${dashboardName}-out.txt`);
-    const stderrPath = join(bgrDir, `${dashboardName}-err.txt`);
-
-    await Bun.write(stdoutPath, '');
-    await Bun.write(stderrPath, '');
-
-    // Pass BUN_PORT env var only if user explicitly requested a port
-    const spawnEnv: Record<string, string> = { ...Bun.env } as any;
-    if (requestedPort) {
-      spawnEnv.BUN_PORT = requestedPort;
-    }
-    // Pass log paths so the detached process can redirect its own console output
-    spawnEnv.BGR_STDOUT = stdoutPath;
-    spawnEnv.BGR_STDERR = stderrPath;
-
-    // Resolve the target port: --port flag > BUN_PORT env > default 3000
-    const targetPort = parseInt(requestedPort || Bun.env.BUN_PORT || '3000');
-    if (!isNaN(targetPort) && targetPort > 0) {
-      // Auto-kill whatever occupies the target port so dashboard always reclaims it
-      const portFree = await isPortFree(targetPort);
-      if (!portFree) {
-        console.log(chalk.yellow(`  ⚡ Port ${targetPort} is occupied — reclaiming...`));
-        await killProcessOnPort(targetPort);
-        const freed = await waitForPortFree(targetPort, 5000);
-        if (!freed) {
-          console.log(chalk.red(`  ⚠ Could not free port ${targetPort} — dashboard may pick a fallback port`));
-        }
-      }
-    }
-
-    const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
-      env: spawnEnv,
-      cwd: bgrDir,
-      stdout: "ignore",
-      stderr: "ignore",
-      detached: true, // Windows: new process group outside parent's Job Object — survives terminal close
-    } as any);
-
-    newProcess.unref();
-
-    // With detached: cmd.exe wrapper exits immediately, so findChildPid won't work.
-    // Instead, wait for the server to bind a port and find the PID from there.
-    await sleep(2000); // Give the server time to start and bind a port
-    const resolvedPort = parseInt(requestedPort || Bun.env.BUN_PORT || '3000');
-    const actualPid = await findPidByPort(resolvedPort, 10000) ?? await findChildPid(newProcess.pid);
-
-    // Detect the port the server actually bound to
-    let actualPort: number | null = null;
-    for (let attempt = 0; attempt < 10; attempt++) {
-      const ports = await getProcessPorts(actualPid);
-      if (ports.length > 0) {
-        actualPort = ports[0];
-        break;
-      }
-      await sleep(1000);
-    }
-
-    await retryDatabaseOperation(() =>
-      insertProcess({
-        pid: actualPid,
-        workdir: bgrDir,
-        command,
-        name: dashboardName,
-        env: '',
-        configPath: '',
-        stdout_path: stdoutPath,
-        stderr_path: stderrPath,
-      })
-    );
-
-    const portDisplay = actualPort ? String(actualPort) : '(detecting...)';
-    const urlDisplay = actualPort ? `http://localhost:${actualPort}` : 'http://localhost (port auto-assigned)';
-
-    const msg = dedent`
-      ${chalk.bold('⚡ BGR Dashboard launched')}
-      ${chalk.gray('─'.repeat(40))}
-
-        🌐  Open in browser: ${chalk.cyan.underline(urlDisplay)}
-        📊  Manage all your processes from the web UI
-        🔄  Auto-refreshes every 3 seconds
-
-      ${chalk.gray('─'.repeat(40))}
-        Process: ${chalk.white(dashboardName)}  |  PID: ${chalk.white(String(actualPid))}  |  Port: ${chalk.white(portDisplay)}
-
-        ${chalk.yellow('bgrun bgr-dashboard --logs')}    View dashboard logs
-        ${chalk.yellow('bgrun --stop bgr-dashboard')}    Stop the dashboard
-        ${chalk.yellow('bgrun --restart bgr-dashboard')} Restart the dashboard
-    `;
-    announce(msg, 'BGR Dashboard');
-    return;
-  }
-
-  // Guard: spawn the standalone guard as a bgr-managed process
-  if (values.guard) {
-    const guardName = 'bgr-guard';
-    const homePath = getHomeDir();
-    const bgrDir = join(homePath, '.bgr');
-
-    // Check if guard is already running
-    const existing = getProcess(guardName);
-    if (existing && await isProcessRunning(existing.pid)) {
-      announce(
-        `Guard is already running (PID ${existing.pid})\n\n` +
-        `  Use ${chalk.yellow(`bgrun --stop ${guardName}`)} to stop it\n` +
-        `  Use ${chalk.yellow(`bgrun --guard --force`)} to restart`,
-        'BGR Guard'
-      );
-      return;
-    }
-
-    // Kill existing if force
-    if (existing) {
-      if (await isProcessRunning(existing.pid)) {
-        await terminateProcess(existing.pid);
-      }
-      await retryDatabaseOperation(() => removeProcessByName(guardName));
-    }
-
-    const { resolve } = require('path');
-    const scriptPath = resolve(process.argv[1]);
-    const spawnCommand = `bun run ${scriptPath} --_guard-loop`;
-    const command = `bgrun --_guard-loop`;
-    const stdoutPath = join(bgrDir, `${guardName}-out.txt`);
-    const stderrPath = join(bgrDir, `${guardName}-err.txt`);
-
-    await Bun.write(stdoutPath, '');
-    await Bun.write(stderrPath, '');
-
-    const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
-      env: { ...Bun.env, BGR_STDOUT: stdoutPath, BGR_STDERR: stderrPath },
-      cwd: bgrDir,
-      stdout: "ignore",
-      stderr: "ignore",
-      detached: true, // Windows: new process group outside parent's Job Object — survives terminal close
-    } as any);
-
-    newProcess.unref();
-    await sleep(1000);
-    // With detached: cmd.exe exits immediately. Search for the guard by command line.
-    let actualPid = await findChildPid(newProcess.pid);
-    if (!(await isProcessRunning(actualPid))) {
-      // cmd.exe already died — search for the bun process running --_guard-loop
-      const { psExec: ps } = await import('./platform');
-      const result = ps(
-        `Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | Where-Object { $_.CommandLine -match '_guard-loop' } | Sort-Object -Property CreationDate -Descending | Select-Object -First 1 -ExpandProperty ProcessId`,
-        3000
-      );
-      const foundPid = parseInt(result.trim());
-      if (!isNaN(foundPid) && foundPid > 0) actualPid = foundPid;
-    }
-
-    await retryDatabaseOperation(() =>
-      insertProcess({
-        pid: actualPid,
-        workdir: bgrDir,
-        command,
-        name: guardName,
-        env: 'BGR_KEEP_ALIVE=false', // Guard doesn't guard itself
-        configPath: '',
-        stdout_path: stdoutPath,
-        stderr_path: stderrPath,
-      })
-    );
-
-    const msg = dedent`
-      ${chalk.bold('🛡️  BGR Standalone Guard launched')}
-      ${chalk.gray('─'.repeat(40))}
-
-        Monitors: All processes with BGR_KEEP_ALIVE=true
-        Also watches: bgr-dashboard (auto-restart if it dies)
-        Check interval: 30 seconds
-        Backoff: Exponential after 5 rapid crashes
-
-      ${chalk.gray('─'.repeat(40))}
-        Process: ${chalk.white(guardName)}  |  PID: ${chalk.white(String(actualPid))}
-
-        ${chalk.yellow(`bgrun ${guardName} --logs`)}    View guard logs
-        ${chalk.yellow(`bgrun --stop ${guardName}`)}    Stop the guard
-    `;
-    announce(msg, 'BGR Guard');
-    return;
-  }
-
-  if (values.version) {
-    console.log(`bgrun version: ${await getVersion()}`);
-    return;
-  }
-
-  if (values.help) {
-    await showHelp();
-    return;
-  }
-
-  if (values.debug) {
-    const info = getDbInfo();
-    const version = await getVersion();
-    console.log(dedent`
-      ${chalk.bold('bgrun debug info')}
-      ${chalk.gray('─'.repeat(40))}
-      Version:   ${chalk.cyan(version)}
-      BGR Home:  ${chalk.yellow(info.bgrHome)}
-      DB Path:   ${chalk.yellow(info.dbPath)}
-      DB File:   ${info.dbFilename}
-      DB Exists: ${info.exists ? chalk.green('✓') : chalk.red('✗')}
-      Platform:  ${process.platform}
-      Bun:       ${Bun.version}
-    `);
-    return;
-  }
-
-  // Commands flow
-  if (values.nuke) {
-    await handleDeleteAll();
-    return;
-  }
-
-  if (values.clean) {
-    await handleClean();
-    return;
-  }
-
-  // Restart all registered processes
-  if (values['restart-all']) {
-    const { getAllProcesses } = await import('./db');
-    const all = getAllProcesses();
-    if (all.length === 0) {
-      error('No processes registered.');
-      return;
-    }
-    console.log(chalk.bold(`\n  Restarting ${all.length} processes...\n`));
-    for (const proc of all) {
-      try {
-        console.log(chalk.yellow(`  ↻ Restarting ${proc.name}...`));
-        await handleRun({
-          action: 'run',
-          name: proc.name,
-          force: true,
-          remoteName: '',
-        });
-      } catch (err: any) {
-        console.error(chalk.red(`  ✗ Failed to restart ${proc.name}: ${err.message}`));
-      }
-    }
-    console.log(chalk.green(`\n  ✓ All processes restarted.\n`));
-    return;
-  }
-
-  // Stop all running processes
-  if (values['stop-all']) {
-    const { getAllProcesses } = await import('./db');
-    const all = getAllProcesses();
-    if (all.length === 0) {
-      error('No processes registered.');
-      return;
-    }
-    console.log(chalk.bold(`\n  Stopping ${all.length} processes...\n`));
-    for (const proc of all) {
-      try {
-        if (await isProcessRunning(proc.pid)) {
-          console.log(chalk.yellow(`  ■ Stopping ${proc.name} (PID ${proc.pid})...`));
-          await handleStop(proc.name);
-        } else {
-          console.log(chalk.gray(`  ○ ${proc.name} already stopped`));
-        }
-      } catch (err: any) {
-        console.error(chalk.red(`  ✗ Failed to stop ${proc.name}: ${err.message}`));
-      }
-    }
-    console.log(chalk.green(`\n  ✓ All processes stopped.\n`));
-    return;
-  }
-
-  const name = (values.name as string) || positionals[0];
-
-  // Delete
-  if (values.delete) {
-    // bgr --delete (bool)
-    if (name) {
-      await handleDelete(name);
-    } else {
-      error("Please specify a process name to delete.");
-    }
-    return;
-  }
-
-  // Restart
-  if (values.restart) {
-    if (!name) {
-      error("Please specify a process name to restart.");
-    }
-    await handleRun({
-      action: 'run',
-      name: name,
-      force: true,
-      // other options undefined, handleRun will look up process
-      remoteName: '',
-    });
-    return;
-  }
-
-  // Stop
-  if (values.stop) {
-    if (!name) {
-      error("Please specify a process name to stop.");
-    }
-    await handleStop(name);
-    return;
-  }
-
-  // Logs
-  if (values.logs || values["log-stdout"] || values["log-stderr"]) {
-    if (!name) {
-      error("Please specify a process name to show logs for.");
-    }
-    const logType = values["log-stdout"] ? 'stdout' : (values["log-stderr"] ? 'stderr' : 'both');
-    const lines = values.lines ? parseInt(values.lines as string) : undefined;
-    await showLogs(name, logType, lines);
-    return;
-  }
-
-  // Watch
-  if (values.watch) {
-    await handleWatch({
-      action: 'watch',
-      name: name,
-      command: values.command as string | undefined,
-      directory: values.directory as string | undefined,
-      configPath: values.config as string | undefined,
-      force: values.force as boolean | undefined,
-      remoteName: '',
-      dbPath: values.db as string | undefined,
-      stdout: values.stdout as string | undefined,
-      stderr: values.stderr as string | undefined
-    }, {
-      showLogs: (values.logs as boolean) || false,
-      logType: 'both',
-      lines: values.lines ? parseInt(values.lines as string) : undefined
-    });
-    return;
-  }
-
-  // List or Run or Details
-  if (name) {
-    if (!values.command && !values.directory) {
-      await showDetails(name);
-    } else {
-      await handleRun({
-        action: 'run',
-        name: name,
-        command: values.command as string | undefined,
-        directory: values.directory as string | undefined,
-        configPath: values.config as string | undefined,
-        force: values.force as boolean | undefined,
-        fetch: values.fetch as boolean | undefined,
-        remoteName: '',
-        dbPath: values.db as string | undefined,
-        stdout: values.stdout as string | undefined,
-        stderr: values.stderr as string | undefined
-      });
-    }
-  } else {
-    if (values.command) {
-      error("Process name is required.");
-    }
-    await showAll({
-      json: values.json as boolean | undefined,
-      filter: values.filter as string | undefined
-    });
-  }
-}
-
-run().catch(err => {
-  // BgrunError was already printed by error() — just exit
-  // For unexpected errors, print and exit
-  if (err.name !== 'BgrunError') {
-    console.error(err);
-  }
-  process.exit(1);
-});