bgrun 3.12.24 → 3.12.25

package/dist/api.js

@@ -240,7 +240,7 @@ function ensureDir(dirPath) {
 }
 function getShellCommand(command) {
   if (isWindows()) {
-    return ["cmd", "/c", command];
+    return [process.env.ComSpec || "cmd.exe", "/c", command];
   } else {
     return ["sh", "-c", command];
   }
@@ -1427,6 +1427,78 @@ function getRecentGuardEvents(limit = 100) {
 var homePath2 = getHomeDir();
 var run = createMeasure2("run");
 var INTERNAL_BUNX_PREFIX = "bunx bgrun";
+async function resolveSpawnedProcessPid(parentPid, command, workdir) {
+  if (parentPid <= 0)
+    return 0;
+  let candidatePid = parentPid;
+  const spawnedAt = Date.now();
+  for (let attempt = 0;attempt < 6; attempt++) {
+    const descendantPid = await findChildPid(parentPid);
+    if (descendantPid > 0) {
+      candidatePid = descendantPid;
+    }
+    if (candidatePid > 0 && await isProcessRunning(candidatePid, command)) {
+      return candidatePid;
+    }
+    await sleep2(250);
+  }
+  const reconciled = await reconcileProcessPids([{ name: "__spawn__", pid: parentPid, command, workdir }], new Set([parentPid]));
+  const matchedPid = reconciled.get("__spawn__") ?? 0;
+  if (matchedPid > 0 && await isProcessRunning(matchedPid, command)) {
+    return matchedPid;
+  }
+  if (process.platform === "win32") {
+    try {
+      const commandParts = command.toLowerCase().split(/\s+/).map((part) => part.trim()).filter((part) => part.length > 2);
+      const output = await psExec(`Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | ` + `ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)|$($_.CreationDate)|$($_.CommandLine)" }`, 5000);
+      let bestPid = 0;
+      let bestScore = -1;
+      for (const line of output.split(`
+`)) {
+        const parts = line.split("|");
+        if (parts.length < 4)
+          continue;
+        const pid = parseInt(parts[0]?.trim(), 10);
+        const candidateParentPid = parseInt(parts[1]?.trim(), 10);
+        const creationDateRaw = parts[2]?.trim() || "";
+        const candidateCommand = parts.slice(3).join("|").trim().toLowerCase();
+        if (isNaN(pid) || pid <= 0 || pid === process.pid)
+          continue;
+        if (!candidateCommand)
+          continue;
+        let score = 0;
+        if (candidateParentPid === parentPid)
+          score += 10;
+        for (const part of commandParts) {
+          if (candidateCommand.includes(part))
+            score += 2;
+        }
+        if (candidateCommand.includes("run server.ts"))
+          score += 2;
+        if (candidateCommand.includes(workdir.toLowerCase().replace(/\\/g, "/")))
+          score += 4;
+        if (candidateCommand.includes(workdir.toLowerCase()))
+          score += 4;
+        const createdAt = creationDateRaw ? Date.parse(creationDateRaw) : NaN;
+        if (!isNaN(createdAt)) {
+          const ageMs = Math.abs(createdAt - spawnedAt);
+          if (ageMs <= 15000)
+            score += 6;
+          else if (ageMs <= 60000)
+            score += 2;
+        }
+        if (score > bestScore && await isProcessRunning(pid, command)) {
+          bestScore = score;
+          bestPid = pid;
+        }
+      }
+      if (bestScore >= 4) {
+        return bestPid;
+      }
+    } catch {}
+  }
+  return 0;
+}
 function resolveInternalBgrunCommand(command) {
   const trimmed = command.trim();
   if (!trimmed.startsWith("bgrun --_") && !trimmed.startsWith(`${INTERNAL_BUNX_PREFIX} --_`)) {
@@ -1637,11 +1709,13 @@ async function handleRun(options) {
         stderr: Bun.file(stderrPath)
       });
       newProcess.unref();
-      await sleep2(100);
-      const pid = await findChildPid(newProcess.pid);
-      await sleep2(400);
-      return pid;
+      return await resolveSpawnedProcessPid(newProcess.pid, finalCommand, finalDirectory);
     }) ?? 0;
+    if (actualPid <= 0) {
+      throw new Error(`Failed to resolve a live PID for "${name}" after launch. The child process likely exited immediately. Check logs:
+stdout: ${stdoutPath}
+stderr: ${stderrPath}`);
+    }
     await retryDatabaseOperation(() => insertProcess({
       pid: actualPid,
       workdir: finalDirectory,

package/dist/deploy.js

@@ -240,7 +240,7 @@ function ensureDir(dirPath) {
 }
 function getShellCommand(command) {
   if (isWindows()) {
-    return ["cmd", "/c", command];
+    return [process.env.ComSpec || "cmd.exe", "/c", command];
   } else {
     return ["sh", "-c", command];
   }
@@ -1426,6 +1426,78 @@ function getRecentGuardEvents(limit = 100) {
 var homePath2 = getHomeDir();
 var run = createMeasure2("run");
 var INTERNAL_BUNX_PREFIX = "bunx bgrun";
+async function resolveSpawnedProcessPid(parentPid, command, workdir) {
+  if (parentPid <= 0)
+    return 0;
+  let candidatePid = parentPid;
+  const spawnedAt = Date.now();
+  for (let attempt = 0;attempt < 6; attempt++) {
+    const descendantPid = await findChildPid(parentPid);
+    if (descendantPid > 0) {
+      candidatePid = descendantPid;
+    }
+    if (candidatePid > 0 && await isProcessRunning(candidatePid, command)) {
+      return candidatePid;
+    }
+    await sleep2(250);
+  }
+  const reconciled = await reconcileProcessPids([{ name: "__spawn__", pid: parentPid, command, workdir }], new Set([parentPid]));
+  const matchedPid = reconciled.get("__spawn__") ?? 0;
+  if (matchedPid > 0 && await isProcessRunning(matchedPid, command)) {
+    return matchedPid;
+  }
+  if (process.platform === "win32") {
+    try {
+      const commandParts = command.toLowerCase().split(/\s+/).map((part) => part.trim()).filter((part) => part.length > 2);
+      const output = await psExec(`Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | ` + `ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)|$($_.CreationDate)|$($_.CommandLine)" }`, 5000);
+      let bestPid = 0;
+      let bestScore = -1;
+      for (const line of output.split(`
+`)) {
+        const parts = line.split("|");
+        if (parts.length < 4)
+          continue;
+        const pid = parseInt(parts[0]?.trim(), 10);
+        const candidateParentPid = parseInt(parts[1]?.trim(), 10);
+        const creationDateRaw = parts[2]?.trim() || "";
+        const candidateCommand = parts.slice(3).join("|").trim().toLowerCase();
+        if (isNaN(pid) || pid <= 0 || pid === process.pid)
+          continue;
+        if (!candidateCommand)
+          continue;
+        let score = 0;
+        if (candidateParentPid === parentPid)
+          score += 10;
+        for (const part of commandParts) {
+          if (candidateCommand.includes(part))
+            score += 2;
+        }
+        if (candidateCommand.includes("run server.ts"))
+          score += 2;
+        if (candidateCommand.includes(workdir.toLowerCase().replace(/\\/g, "/")))
+          score += 4;
+        if (candidateCommand.includes(workdir.toLowerCase()))
+          score += 4;
+        const createdAt = creationDateRaw ? Date.parse(creationDateRaw) : NaN;
+        if (!isNaN(createdAt)) {
+          const ageMs = Math.abs(createdAt - spawnedAt);
+          if (ageMs <= 15000)
+            score += 6;
+          else if (ageMs <= 60000)
+            score += 2;
+        }
+        if (score > bestScore && await isProcessRunning(pid, command)) {
+          bestScore = score;
+          bestPid = pid;
+        }
+      }
+      if (bestScore >= 4) {
+        return bestPid;
+      }
+    } catch {}
+  }
+  return 0;
+}
 function resolveInternalBgrunCommand(command) {
   const trimmed = command.trim();
   if (!trimmed.startsWith("bgrun --_") && !trimmed.startsWith(`${INTERNAL_BUNX_PREFIX} --_`)) {
@@ -1636,11 +1708,13 @@ async function handleRun(options) {
         stderr: Bun.file(stderrPath)
       });
       newProcess.unref();
-      await sleep2(100);
-      const pid = await findChildPid(newProcess.pid);
-      await sleep2(400);
-      return pid;
+      return await resolveSpawnedProcessPid(newProcess.pid, finalCommand, finalDirectory);
     }) ?? 0;
+    if (actualPid <= 0) {
+      throw new Error(`Failed to resolve a live PID for "${name}" after launch. The child process likely exited immediately. Check logs:
+stdout: ${stdoutPath}
+stderr: ${stderrPath}`);
+    }
     await retryDatabaseOperation(() => insertProcess({
       pid: actualPid,
       workdir: finalDirectory,

package/dist/deps.js

@@ -240,7 +240,7 @@ function ensureDir(dirPath) {
 }
 function getShellCommand(command) {
   if (isWindows()) {
-    return ["cmd", "/c", command];
+    return [process.env.ComSpec || "cmd.exe", "/c", command];
   } else {
     return ["sh", "-c", command];
   }

package/dist/index.js

@@ -241,7 +241,7 @@ function ensureDir(dirPath) {
 }
 function getShellCommand(command) {
   if (isWindows()) {
-    return ["cmd", "/c", command];
+    return [process.env.ComSpec || "cmd.exe", "/c", command];
   } else {
     return ["sh", "-c", command];
   }
@@ -1587,6 +1587,78 @@ function getRecentGuardEvents(limit = 100) {
 var homePath2 = getHomeDir();
 var run = createMeasure2("run");
 var INTERNAL_BUNX_PREFIX = "bunx bgrun";
+async function resolveSpawnedProcessPid(parentPid, command, workdir) {
+  if (parentPid <= 0)
+    return 0;
+  let candidatePid = parentPid;
+  const spawnedAt = Date.now();
+  for (let attempt = 0;attempt < 6; attempt++) {
+    const descendantPid = await findChildPid(parentPid);
+    if (descendantPid > 0) {
+      candidatePid = descendantPid;
+    }
+    if (candidatePid > 0 && await isProcessRunning(candidatePid, command)) {
+      return candidatePid;
+    }
+    await sleep2(250);
+  }
+  const reconciled = await reconcileProcessPids([{ name: "__spawn__", pid: parentPid, command, workdir }], new Set([parentPid]));
+  const matchedPid = reconciled.get("__spawn__") ?? 0;
+  if (matchedPid > 0 && await isProcessRunning(matchedPid, command)) {
+    return matchedPid;
+  }
+  if (process.platform === "win32") {
+    try {
+      const commandParts = command.toLowerCase().split(/\s+/).map((part) => part.trim()).filter((part) => part.length > 2);
+      const output = await psExec(`Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | ` + `ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)|$($_.CreationDate)|$($_.CommandLine)" }`, 5000);
+      let bestPid = 0;
+      let bestScore = -1;
+      for (const line of output.split(`
+`)) {
+        const parts = line.split("|");
+        if (parts.length < 4)
+          continue;
+        const pid = parseInt(parts[0]?.trim(), 10);
+        const candidateParentPid = parseInt(parts[1]?.trim(), 10);
+        const creationDateRaw = parts[2]?.trim() || "";
+        const candidateCommand = parts.slice(3).join("|").trim().toLowerCase();
+        if (isNaN(pid) || pid <= 0 || pid === process.pid)
+          continue;
+        if (!candidateCommand)
+          continue;
+        let score = 0;
+        if (candidateParentPid === parentPid)
+          score += 10;
+        for (const part of commandParts) {
+          if (candidateCommand.includes(part))
+            score += 2;
+        }
+        if (candidateCommand.includes("run server.ts"))
+          score += 2;
+        if (candidateCommand.includes(workdir.toLowerCase().replace(/\\/g, "/")))
+          score += 4;
+        if (candidateCommand.includes(workdir.toLowerCase()))
+          score += 4;
+        const createdAt = creationDateRaw ? Date.parse(creationDateRaw) : NaN;
+        if (!isNaN(createdAt)) {
+          const ageMs = Math.abs(createdAt - spawnedAt);
+          if (ageMs <= 15000)
+            score += 6;
+          else if (ageMs <= 60000)
+            score += 2;
+        }
+        if (score > bestScore && await isProcessRunning(pid, command)) {
+          bestScore = score;
+          bestPid = pid;
+        }
+      }
+      if (bestScore >= 4) {
+        return bestPid;
+      }
+    } catch {}
+  }
+  return 0;
+}
 function resolveInternalBgrunCommand(command) {
   const trimmed = command.trim();
   if (!trimmed.startsWith("bgrun --_") && !trimmed.startsWith(`${INTERNAL_BUNX_PREFIX} --_`)) {
@@ -1797,11 +1869,13 @@ async function handleRun(options) {
         stderr: Bun.file(stderrPath)
       });
       newProcess.unref();
-      await sleep2(100);
-      const pid = await findChildPid(newProcess.pid);
-      await sleep2(400);
-      return pid;
+      return await resolveSpawnedProcessPid(newProcess.pid, finalCommand, finalDirectory);
     }) ?? 0;
+    if (actualPid <= 0) {
+      throw new Error(`Failed to resolve a live PID for "${name}" after launch. The child process likely exited immediately. Check logs:
+stdout: ${stdoutPath}
+stderr: ${stderrPath}`);
+    }
     await retryDatabaseOperation(() => insertProcess({
       pid: actualPid,
       workdir: finalDirectory,
@@ -2870,6 +2944,7 @@ async function showHelp() {
       bunx bgrun --delete [name]    Delete a process
       bunx bgrun --clean            Remove all stopped processes
       bunx bgrun --nuke             Delete ALL processes
+      bunx bgrun --kill-port <n>    Kill whatever is currently listening on a port
 
     ${chalk7.yellow("Options:")}
       --name <string>        Process name (required for new)
@@ -2894,18 +2969,21 @@ async function showHelp() {
       --dashboard            Launch web dashboard as bgrun-managed process
       --guard                Enable per-process crash watcher
       --guard-off            Disable per-process crash watcher
+      --kill-port <number>   Kill the process currently using a port
       --port <number>        Port for dashboard (default: 3000)
       --help                 Show this help message
 
     ${chalk7.yellow("Examples:")}
       bunx bgrun -- bun run dev
       bunx bgrun --hot -- bun run index.ts
+      bunx bgrun -hl -- bun run server.ts
       bunx bgrun --no-config -- bun run script.ts
       bunx bgrun --force -- bun run server.ts
       bunx bgrun inline -- bun run dev
       Invoke-Expression (bunx bgrun --env)
       eval "$(bunx bgrun --env --shell sh)"
       bunx bgrun --dashboard
+      bunx bgrun --kill-port 3000
       bunx bgrun myapp --guard
       bunx bgrun myapp --guard-off
       bunx bgrun --name myapp --command "bun run dev" --directory . --watch
@@ -2914,16 +2992,16 @@ async function showHelp() {
   console.log(usage);
 }
 var cliArgOptions = {
-  name: { type: "string" },
-  command: { type: "string" },
-  directory: { type: "string" },
+  name: { type: "string", short: "n" },
+  command: { type: "string", short: "c" },
+  directory: { type: "string", short: "d" },
   config: { type: "string" },
   "no-config": { type: "boolean" },
   env: { type: "boolean" },
   shell: { type: "string" },
-  watch: { type: "boolean" },
-  hot: { type: "boolean" },
-  force: { type: "boolean" },
+  watch: { type: "boolean", short: "w" },
+  hot: { type: "boolean", short: "h" },
+  force: { type: "boolean", short: "f" },
   fetch: { type: "boolean" },
   delete: { type: "boolean" },
   nuke: { type: "boolean" },
@@ -2932,13 +3010,13 @@ var cliArgOptions = {
   stop: { type: "boolean" },
   "stop-all": { type: "boolean" },
   clean: { type: "boolean" },
-  json: { type: "boolean" },
-  logs: { type: "boolean" },
+  json: { type: "boolean", short: "j" },
+  logs: { type: "boolean", short: "l" },
   "log-stdout": { type: "boolean" },
   "log-stderr": { type: "boolean" },
   lines: { type: "string" },
   filter: { type: "string" },
-  version: { type: "boolean" },
+  version: { type: "boolean", short: "v" },
   help: { type: "boolean" },
   db: { type: "string" },
   stdout: { type: "string" },
@@ -2947,6 +3025,7 @@ var cliArgOptions = {
   guard: { type: "boolean" },
   "guard-off": { type: "boolean" },
   debug: { type: "boolean" },
+  "kill-port": { type: "string" },
   _serve: { type: "boolean" },
   "_watch-process": { type: "string" },
   port: { type: "string" }
@@ -2954,7 +3033,7 @@ var cliArgOptions = {
 async function run2() {
   const rawArgs = Bun.argv.slice(2);
   const isActionInvocation = (values2) => {
-    return Boolean(values2.dashboard || values2.guard || values2["guard-off"] || values2.version || values2.help || values2.debug || values2.nuke || values2.clean || values2["restart-all"] || values2["stop-all"] || values2.delete || values2.restart || values2.stop || values2.logs || values2["log-stdout"] || values2["log-stderr"] || values2.watch || values2.hot || values2.json || values2.filter);
+    return Boolean(values2.dashboard || values2.guard || values2["guard-off"] || values2.version || values2.help || values2.debug || values2["kill-port"] || values2.nuke || values2.clean || values2["restart-all"] || values2["stop-all"] || values2.delete || values2.restart || values2.stop || values2.logs || values2["log-stdout"] || values2["log-stderr"] || values2.watch || values2.hot || values2.json || values2.filter);
   };
   if (rawArgs[0] === "inline") {
     const parsed = parseInlineArgs(rawArgs.slice(1));
@@ -3227,6 +3306,24 @@ async function run2() {
     `);
     return;
   }
+  if (values["kill-port"]) {
+    const port = parseInt(String(values["kill-port"]), 10);
+    if (isNaN(port) || port <= 0) {
+      error("Please provide a valid port number for --kill-port.");
+    }
+    const wasFree = await isPortFree(port);
+    if (wasFree) {
+      announce(`Port ${port} is already free.`, "Port Free");
+      return;
+    }
+    await killProcessOnPort(port);
+    const freed = await waitForPortFree(port, 5000);
+    if (!freed) {
+      error(`Port ${port} is still busy after attempted cleanup.`);
+    }
+    announce(`Freed port ${port}.`, "Port Cleanup");
+    return;
+  }
   if (values.nuke) {
     await handleDeleteAll();
     return;

package/dist/server.js

@@ -311,7 +311,7 @@ function ensureDir(dirPath) {
 }
 function getShellCommand(command) {
   if (isWindows()) {
-    return ["cmd", "/c", command];
+    return [process.env.ComSpec || "cmd.exe", "/c", command];
   } else {
     return ["sh", "-c", command];
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bgrun",
-  "version": "3.12.24",
+  "version": "3.12.25",
   "description": "bgrun — A lightweight process manager for Bun",
   "type": "module",
   "main": "./dist/api.js",