bgrun 3.11.0 → 3.12.1

package/src/platform.ts

@@ -11,6 +11,28 @@ import { measure, createMeasure } from "measure-fn";
 
 const plat = createMeasure('platform');
 
+/**
+ * Execute a PowerShell command with -NoProfile synchronously.
+ * Returns stdout as string, or empty string on error.
+ * 
+ * Uses Bun.spawnSync to avoid async stream hanging issues on Windows
+ * where Bun's pipe reader hangs indefinitely when reading killed processes.
+ */
+export function psExec(command: string, _timeoutMs: number = 3000): string {
+  const tmpFile = join(os.tmpdir(), `bgr-ps-${Date.now()}.ps1`);
+  try {
+    fs.writeFileSync(tmpFile, command);
+    const result = Bun.spawnSync(
+      ['powershell', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', tmpFile]
+    );
+    try { fs.unlinkSync(tmpFile); } catch { }
+    return result.stdout?.toString() || '';
+  } catch {
+    try { fs.unlinkSync(tmpFile); } catch { }
+    return '';
+  }
+}
+
 /** Detect if running on Windows - use function to prevent bundler tree-shaking */
 export function isWindows(): boolean {
   return process.platform === "win32";
@@ -39,8 +61,9 @@ export async function isProcessRunning(pid: number, command?: string): Promise<b
       }
 
       if (isWindows()) {
-        const result = await $`tasklist /FI "PID eq ${pid}" /NH`.nothrow().text();
-        return result.includes(`${pid}`);
+        // process.kill(pid, 0) — signal 0 checks existence without killing
+        // 100x faster than tasklist which hangs on some Windows systems
+        try { process.kill(pid, 0); return true; } catch { return false; }
       } else {
         const result = await $`ps -p ${pid}`.nothrow().text();
         return result.includes(`${pid}`);
@@ -86,8 +109,10 @@ async function isDockerContainerRunning(command: string): Promise<boolean> {
 async function getChildPids(pid: number): Promise<number[]> {
   try {
     if (isWindows()) {
-      // On Windows, use PowerShell to get child processes
-      const result = await $`powershell -Command "Get-CimInstance Win32_Process -Filter 'ParentProcessId=${pid}' | Select-Object -ExpandProperty ProcessId"`.nothrow().text();
+      const result = await psExec(
+        `Get-CimInstance Win32_Process -Filter 'ParentProcessId=${pid}' | Select-Object -ExpandProperty ProcessId`,
+        3000
+      );
       return result
         .split('\n')
         .map(line => parseInt(line.trim()))
@@ -176,6 +201,39 @@ export async function isPortFree(port: number): Promise<boolean> {
   }
 }
 
+/**
+ * Get info about what's using a port.
+ * Returns { inUse: boolean, pid?: number, processName?: string }
+ */
+export async function getPortInfo(port: number): Promise<{ inUse: boolean; pid?: number; processName?: string }> {
+    try {
+        if (isWindows()) {
+            const result = await $`netstat -ano | findstr :${port}`.nothrow().quiet().text();
+            for (const line of result.split('\n')) {
+                const match = line.match(new RegExp(`:(${port})\\s+.*LISTENING\\s+(\\d+)`));
+                if (match) {
+                    const pid = parseInt(match[2]);
+                    if (pid > 0 && await isProcessRunning(pid)) {
+                        // Get process name
+                        const nameResult = await $`powershell -NoProfile -Command "(Get-Process -Id ${pid} -ErrorAction SilentlyContinue).ProcessName"`.nothrow().quiet().text();
+                        return { inUse: true, pid, processName: nameResult.trim() || 'unknown' };
+                    }
+                }
+            }
+            return { inUse: false };
+        } else {
+            const result = await $`ss -tln sport = :${port}`.nothrow().quiet().text();
+            const lines = result.trim().split('\n').filter((l: string) => l.trim());
+            if (lines.length > 1) {
+                return { inUse: true };
+            }
+            return { inUse: false };
+        }
+    } catch {
+        return { inUse: false };
+    }
+}
+
 /**
  * Wait for a port to become free, polling with timeout.
  * Returns true if port is free, false if timeout reached.
@@ -265,23 +323,26 @@ export function getShellCommand(command: string): string[] {
     return ["sh", "-c", command];
   }
 }
-
 /**
  * Find the actual child process PID spawned by a shell wrapper.
- * Traverses the process tree recursively to find the deepest (leaf) child.
- * On Windows, bgr spawn creates: cmd.exe → bgr.exe → bun.exe
- * We need the bun.exe PID, not the intermediate bgr.exe.
+ * Traverses the process tree to find the deepest (leaf) child.
+ * On Windows, bgr spawn creates: cmd.exe → bun.exe (typically 1-2 levels)
+ * 
+ * Uses PowerShell with -NoProfile and a hard timeout to prevent hangs.
  */
 export async function findChildPid(parentPid: number): Promise<number> {
   let currentPid = parentPid;
-  const maxDepth = 5; // Safety limit to avoid infinite loops
+  const maxDepth = 2; // cmd.exe → bun.exe is the typical chain
 
   for (let depth = 0; depth < maxDepth; depth++) {
     try {
       let childPids: number[] = [];
 
       if (isWindows()) {
-        const result = await $`powershell -Command "Get-CimInstance Win32_Process -Filter 'ParentProcessId=${currentPid}' | Select-Object -ExpandProperty ProcessId"`.nothrow().text();
+        const result = await psExec(
+          `Get-CimInstance Win32_Process -Filter 'ParentProcessId=${currentPid}' | Select-Object -ExpandProperty ProcessId`,
+          3000
+        );
         childPids = result
           .split('\n')
           .map((line: string) => parseInt(line.trim()))
@@ -295,12 +356,7 @@ export async function findChildPid(parentPid: number): Promise<number> {
           .filter(n => !isNaN(n) && n > 0);
       }
 
-      if (childPids.length === 0) {
-        // No children — currentPid is the leaf process
-        break;
-      }
-
-      // Follow the first child deeper
+      if (childPids.length === 0) break;
       currentPid = childPids[0];
     } catch {
       break;
@@ -335,14 +391,10 @@ export async function reconcileProcessPids(
       let runningProcs: Array<{ pid: number; cmdLine: string }> = [];
 
       if (isWindows()) {
-        // Write a temp PS1 script to avoid quoting issues with $() in Bun's shell
-        const tmpScript = join(os.tmpdir(), 'bgr-reconcile.ps1');
-        const psCode = `Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'bun.exe' } | ForEach-Object { Write-Output "$($_.ProcessId)|$($_.CommandLine)" }`;
-        await Bun.write(tmpScript, psCode);
-
-        const ps = Bun.spawnSync(['powershell', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', tmpScript]);
-        const output = ps.stdout.toString();
-
+        const output = await psExec(
+          `Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | ForEach-Object { Write-Output "$($_.ProcessId)|$($_.CommandLine)" }`,
+          5000
+        );
         for (const line of output.split('\n')) {
           const sepIdx = line.indexOf('|');
           if (sepIdx === -1) continue;
@@ -508,32 +560,17 @@ export async function getProcessBatchResources(pids: number[]): Promise<Map<numb
 
     try {
       if (isWindows()) {
-        const result = await $`powershell -Command "Get-Process | Select-Object Id, CPU, WorkingSet"`.nothrow().quiet().text();
-        const lines = result.trim().split('\n');
-
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed || trimmed.startsWith('Id') || trimmed.startsWith('--')) continue;
-
-          // Replace multiple spaces with a single space to parse correctly
-          const parts = trimmed.split(/\s+/);
-          if (parts.length >= 3) {
-            const pid = parseInt(parts[0]);
-            // CPU can sometimes be blank if process is just starting, handle that
-            let cpuStr = parts[1];
-            let memStr = parts[2];
-            if (parts.length === 2) {
-              // If CPU is missing, powershell might omit it and give just ID and WorkingSet
-              cpuStr = "0";
-              memStr = parts[1];
-            }
-
-            const cpu = parseFloat(cpuStr) || 0;
-            const memory = parseInt(memStr) || 0;
-
-            if (!isNaN(pid) && !isNaN(memory)) {
-              if (pidSet.has(pid)) resourceMap.set(pid, { memory, cpu });
-            }
+        // psExec(Get-Process) is fast (~2ms) vs tasklist which hangs
+        const output = psExec(
+          `Get-Process -Id ${pids.join(',')} -ErrorAction SilentlyContinue | Select-Object Id, WorkingSet64 | ForEach-Object { Write-Output "$($_.Id)|$($_.WorkingSet64)" }`
+        );
+        for (const line of output.split('\n')) {
+          const sepIdx = line.indexOf('|');
+          if (sepIdx === -1) continue;
+          const pid = parseInt(line.substring(0, sepIdx).trim());
+          const memory = parseInt(line.substring(sepIdx + 1).trim()) || 0;
+          if (!isNaN(pid) && pidSet.has(pid)) {
+            resourceMap.set(pid, { memory, cpu: 0 });
           }
         }
       } else {

package/src/server.ts

@@ -14,7 +14,7 @@
  *   - Otherwise → defaults to 3000, falls back to next available if busy
  */
 import path from 'path';
-import { getAllProcesses, getProcess } from './db';
+import { getAllProcesses, getProcess, addHistoryEntry } from './db';
 import { isProcessRunning } from './platform';
 import { handleRun } from './commands/run';
 import { parseEnvString } from './utils';
@@ -26,8 +26,44 @@ const GUARD_SKIP_NAMES = new Set(['bgr-dashboard', 'bgr-guard']); // Don't try t
 const _g = globalThis as any;
 if (!_g.__bgrGuardRestartCounts) _g.__bgrGuardRestartCounts = new Map<string, number>();
 if (!_g.__bgrGuardNextRestartTime) _g.__bgrGuardNextRestartTime = new Map<string, number>();
+if (!_g.__bgrGuardEvents) _g.__bgrGuardEvents = [] as { time: number; name: string; action: string; success: boolean }[];
 export const guardRestartCounts: Map<string, number> = _g.__bgrGuardRestartCounts;
 const guardNextRestartTime: Map<string, number> = _g.__bgrGuardNextRestartTime;
+export const guardEvents: { time: number; name: string; action: string; success: boolean }[] = _g.__bgrGuardEvents;
+
+/** Try to free a port from zombie processes (dead PIDs holding sockets) */
+async function cleanupPort(port: number): Promise<number> {
+    if (process.platform !== 'win32') return port;
+    try {
+        const proc = Bun.spawn(['powershell', '-NoProfile', '-Command',
+            `Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess`
+        ], { stdout: 'pipe', stderr: 'pipe' });
+        const text = await new Response(proc.stdout).text();
+        const pid = parseInt(text.trim(), 10);
+        if (!pid || pid === process.pid) return port;
+
+        // Check if the owning process is actually dead
+        const checkProc = Bun.spawn(['powershell', '-NoProfile', '-Command',
+            `Get-Process -Id ${pid} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Id`
+        ], { stdout: 'pipe', stderr: 'pipe' });
+        const checkText = await new Response(checkProc.stdout).text();
+        if (checkText.trim()) {
+            // Process is alive — kill it to reclaim the port
+            console.log(`[server] Killing PID ${pid} holding port ${port}`);
+            Bun.spawn(['taskkill', '/F', '/PID', String(pid)], { stdout: 'pipe', stderr: 'pipe' });
+            await Bun.sleep(1000);
+            return port;
+        } else {
+            // Process is dead but socket is zombie — use fallback port
+            const fallback = port + 1;
+            console.log(`[server] ⚠ Port ${port} held by zombie PID ${pid} — falling back to port ${fallback}`);
+            return fallback;
+        }
+    } catch { return port; /* best-effort cleanup */ }
+}
+
+let _originalPort = 3000;
+let _currentPort = 3000;
 
 export async function startServer() {
     // Dynamic import to avoid melina's side-effect console.log at bundle load time
@@ -36,12 +72,20 @@ export async function startServer() {
 
     // Only pass port when BUN_PORT is explicitly set.
     // When omitted, Melina defaults to 3000 with auto-fallback to next available port.
-    const explicitPort = process.env.BUN_PORT ? parseInt(process.env.BUN_PORT, 10) : undefined;
+    const requestedPort = process.env.BUN_PORT ? parseInt(process.env.BUN_PORT, 10) : 3000;
+    _originalPort = requestedPort;
+
+    // Clean up zombie port bindings before starting — may return a different fallback port
+    const resolvedPort = await cleanupPort(requestedPort);
+    _currentPort = resolvedPort;
+
+    // Pass port explicitly if user requested one OR if we had to fallback
+    const needsExplicitPort = process.env.BUN_PORT || resolvedPort !== requestedPort;
     await start({
         appDir,
         defaultTitle: 'bgrun Dashboard - Process Manager',
         globalCss: path.join(appDir, 'globals.css'),
-        ...(explicitPort !== undefined && { port: explicitPort }),
+        ...(needsExplicitPort && { port: resolvedPort }),
     });
 
     // Start the built-in process guard
@@ -50,6 +94,33 @@ export async function startServer() {
     // Start log rotation (prevents unbounded log file growth)
     const { startLogRotation } = await import('./log-rotation');
     startLogRotation(() => getAllProcesses());
+
+    // Start sticky port checker - periodically try original port if we're on a fallback
+    if (resolvedPort !== requestedPort) {
+        startStickyPortChecker();
+    }
+}
+
+function startStickyPortChecker() {
+    const CHECK_INTERVAL_MS = 60_000; // Check every 60 seconds
+    console.log(`[server] Starting sticky port checker (original: ${_originalPort}, current: ${_currentPort})`);
+
+    setInterval(async () => {
+        if (_currentPort === _originalPort) return; // Already on original port
+
+        try {
+            const proc = Bun.spawn(['powershell', '-NoProfile', '-Command',
+                `Get-NetTCPConnection -LocalPort ${_originalPort} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess`
+            ], { stdout: 'pipe', stderr: 'pipe' });
+            const text = await new Response(proc.stdout).text();
+            const pid = parseInt(text.trim(), 10);
+
+            if (!pid) {
+                console.log(`[server] ✓ Original port ${_originalPort} is now available! Consider restarting to reclaim it.`);
+                _currentPort = _originalPort;
+            }
+        } catch { /* best-effort */ }
+    }, CHECK_INTERVAL_MS);
 }
 
 /**
@@ -89,6 +160,7 @@ function startGuard() {
                     if (now < nextRestart) continue; // Still in backoff period
 
                     console.log(`[guard] ⚠ Guarded process "${proc.name}" (PID ${proc.pid}) is dead, restarting...`);
+                    let success = false;
                     try {
                         await handleRun({
                             action: 'run',
@@ -96,12 +168,22 @@ function startGuard() {
                             force: true,
                             remoteName: '',
                         });
+                        success = true;
 
                         // Track restart count
                         const prevCount = guardRestartCounts.get(proc.name) || 0;
                         const newCount = prevCount + 1;
                         guardRestartCounts.set(proc.name, newCount);
 
+                        // Record in history database
+                        try {
+                            addHistoryEntry(proc.name, 'restart', undefined, { by: 'guard', count: newCount });
+                        } catch { /* ignore history errors */ }
+
+                        // Record event for dashboard
+                        guardEvents.unshift({ time: now, name: proc.name, action: 'restart', success: true });
+                        if (guardEvents.length > 100) guardEvents.pop();
+
                         // Exponential backoff if it crashes repeatedly (more than 5 times)
                         if (newCount > 5) {
                             const backoffSeconds = Math.min(30 * Math.pow(2, newCount - 6), 300); // 30s, 60s, 120s, up to 5 mins
@@ -112,6 +194,8 @@ function startGuard() {
                         }
                     } catch (err: any) {
                         console.error(`[guard] ✗ Failed to restart "${proc.name}": ${err.message}`);
+                        guardEvents.unshift({ time: now, name: proc.name, action: 'restart', success: false });
+                        if (guardEvents.length > 100) guardEvents.pop();
                     }
                 } else {
                     // Reset counter if process has been stable (alive at least once during check)

package/src/table.ts

@@ -34,12 +34,12 @@ export function getTerminalWidth(): number {
 }
 
 // Strip ANSI color codes for accurate length calculation
-function stripAnsi(str: string): string {
+export function stripAnsi(str: string): string {
   return str.replace(/\u001b\[[0-9;]*m/g, "");
 }
 
 // Default truncator: trims the end of a string
-function truncateString(str: string, maxLength: number): string {
+export function truncateString(str: string, maxLength: number): string {
   const stripped = stripAnsi(str);
   if (stripped.length <= maxLength) return str;
   const ellipsis = "…";
@@ -52,7 +52,7 @@ function truncateString(str: string, maxLength: number): string {
 }
 
 // Path truncator: trims the middle of a string
-function truncatePath(str: string, maxLength: number): string {
+export function truncatePath(str: string, maxLength: number): string {
   const stripped = stripAnsi(str);
   if (stripped.length <= maxLength) return str;
   const ellipsis = "…";

package/src/utils.ts

@@ -37,8 +37,8 @@ export async function getVersion(): Promise<string> {
 
 export function validateDirectory(directory: string) {
     if (!directory || !fs.existsSync(directory)) {
-        console.log(chalk.red("❌ Error: 'directory' must be a valid path."));
-        process.exit(1);
+        // Throw instead of process.exit() — lets dashboard API handlers catch gracefully
+        throw new Error(`Directory not found or invalid: '${directory}'`);
     }
 }