portless 0.11.0 → 0.11.1

package/README.md

@@ -289,6 +289,7 @@ portless alias --remove <name>   # Remove a static route
 portless list                    # Show active routes
 portless trust                   # Add local CA to system trust store
 portless clean                   # Remove state, CA trust entry, and hosts block
+portless prune                   # Kill orphaned dev servers from crashed sessions
 portless hosts sync              # Add routes to /etc/hosts (fixes Safari)
 portless hosts clean             # Remove portless entries from /etc/hosts
 
@@ -344,7 +345,7 @@ PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
 NODE_EXTRA_CA_CERTS              Path to the portless CA (when HTTPS is active)
 ```
 
-> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, `prune`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
 
 ## Uninstall / reset
 

package/dist/{chunk-6PDLZVDS.js → chunk-RRH2JUIU.js}

@@ -853,6 +853,59 @@ var RouteStore = class _RouteStore {
     }
     return killedPid;
   }
+  /**
+   * Load all routes from disk without filtering out dead PIDs. Used by
+   * `portless prune` to discover stale entries whose owning CLI is gone
+   * but whose dev server may still be holding a port.
+   */
+  loadRoutesRaw() {
+    if (!fs3.existsSync(this.routesPath)) {
+      return [];
+    }
+    try {
+      const raw = fs3.readFileSync(this.routesPath, "utf-8");
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        return [];
+      }
+      if (!Array.isArray(parsed)) {
+        return [];
+      }
+      return parsed.filter(isValidRoute);
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Remove all route entries whose owning process is dead and persist the
+   * result. Returns the removed stale entries so the caller can act on them.
+   */
+  pruneStaleRoutes() {
+    this.ensureDir();
+    if (!this.acquireLock()) {
+      throw new Error("Failed to acquire route lock");
+    }
+    try {
+      const all = this.loadRoutesRaw();
+      const alive = [];
+      const stale = [];
+      for (const r of all) {
+        if (r.pid === 0 || this.isProcessAlive(r.pid)) {
+          alive.push(r);
+        } else {
+          stale.push(r);
+        }
+      }
+      if (stale.length > 0) {
+        this.saveRoutes(alive);
+      }
+      return stale;
+    } finally {
+      this.releaseLock();
+    }
+  }
   removeRoute(hostname) {
     this.ensureDir();
     if (!this.acquireLock()) {

package/dist/cli.js

@@ -13,7 +13,7 @@ import {
   parseHostname,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-6PDLZVDS.js";
+} from "./chunk-RRH2JUIU.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -1044,6 +1044,23 @@ var SIGNAL_CODES = {
   SIGKILL: 9,
   SIGTERM: 15
 };
+function killTree(child, signal = "SIGTERM") {
+  if (!child.pid) {
+    child.kill(signal);
+    return;
+  }
+  if (!isWindows) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
 function getProtocolPort(tls2) {
   return tls2 ? 443 : 80;
 }
@@ -1372,6 +1389,25 @@ function parsePidFromNetstat(output, port) {
   }
   return null;
 }
+function findPidsOnPort(port) {
+  try {
+    if (isWindows) {
+      const output2 = execSync("netstat -ano -p tcp", {
+        encoding: "utf-8",
+        timeout: PID_LOOKUP_TIMEOUT_MS
+      });
+      const pid = parsePidFromNetstat(output2, port);
+      return pid === null ? [] : [pid];
+    }
+    const output = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
+      encoding: "utf-8",
+      timeout: PID_LOOKUP_TIMEOUT_MS
+    });
+    return output.trim().split("\n").map((s) => parseInt(s, 10)).filter((n) => !isNaN(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
 function findPidOnPort(port) {
   try {
     if (isWindows) {
@@ -1442,7 +1478,8 @@ function spawnCommand(commandArgs, options) {
     env
   }) : spawn("/bin/sh", ["-c", commandArgs.map(shellEscape).join(" ")], {
     stdio: "inherit",
-    env
+    env,
+    detached: true
   });
   let exiting = false;
   const cleanup = () => {
@@ -1453,7 +1490,7 @@ function spawnCommand(commandArgs, options) {
   const handleSignal = (signal) => {
     if (exiting) return;
     exiting = true;
-    child.kill(signal);
+    killTree(child, signal);
     cleanup();
     process.exit(128 + (SIGNAL_CODES[signal] || 15));
   };
@@ -3219,6 +3256,7 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless list")}                    Show active routes
   ${colors_default.cyan("portless trust")}                   Add local CA to system trust store
   ${colors_default.cyan("portless clean")}                   Remove portless state, trust entry, and hosts block
+  ${colors_default.cyan("portless prune")}                   Kill orphaned dev servers from crashed sessions
   ${colors_default.cyan("portless hosts sync")}              Add routes to ${HOSTS_DISPLAY} (fixes Safari)
   ${colors_default.cyan("portless hosts clean")}             Remove portless entries from ${HOSTS_DISPLAY}
 
@@ -3331,14 +3369,14 @@ ${colors_default.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
 
 ${colors_default.bold("Reserved names:")}
-  run, get, alias, hosts, list, trust, clean, proxy are subcommands and cannot
-  be used as app names directly. Use "portless run" to infer the name,
+  run, get, alias, hosts, list, trust, clean, prune, proxy are subcommands and
+  cannot be used as app names directly. Use "portless run" to infer the name,
   or "portless --name <name>" to force any name including reserved ones.
 `);
   process.exit(0);
 }
 function printVersion() {
-  console.log("0.11.0");
+  console.log("0.11.1");
   process.exit(0);
 }
 async function handleTrust() {
@@ -3464,6 +3502,63 @@ Try: sudo portless clean (Linux), or delete the certificate manually.`
   }
   console.log(colors_default.green("Clean finished."));
 }
+async function handlePrune(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${colors_default.bold("portless prune")} - Kill orphaned dev servers left behind by crashed portless sessions.
+
+When portless is killed with SIGKILL (kill -9) or crashes, child dev servers
+may survive and continue holding their ports. This command finds those orphans
+by checking routes whose owning CLI process is dead but whose port is still in
+use, then terminates them and cleans up the stale route entries.
+
+${colors_default.bold("Usage:")}
+  ${colors_default.cyan("portless prune")}
+  ${colors_default.cyan("portless prune --force")}     Send SIGKILL instead of SIGTERM
+
+${colors_default.bold("Options:")}
+  --force                Send SIGKILL instead of SIGTERM
+  --help, -h             Show this help
+`);
+    process.exit(0);
+  }
+  const forceKill = args.includes("--force");
+  const { dir } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(colors_default.yellow(msg))
+  });
+  const stale = store.pruneStaleRoutes();
+  if (stale.length === 0) {
+    console.log("No orphaned routes found.");
+    return;
+  }
+  let killed = 0;
+  for (const route of stale) {
+    const pids = findPidsOnPort(route.port);
+    if (pids.length === 0) {
+      console.log(`  ${route.hostname} :${route.port} - route removed (port already free)`);
+      continue;
+    }
+    const signal = forceKill ? "SIGKILL" : "SIGTERM";
+    for (const pid of pids) {
+      try {
+        process.kill(pid, signal);
+        killed++;
+        console.log(`  ${route.hostname} :${route.port} - killed PID ${pid} (${signal})`);
+      } catch {
+        console.log(`  ${route.hostname} :${route.port} - PID ${pid} already exited`);
+      }
+    }
+  }
+  const routeWord = stale.length === 1 ? "route" : "routes";
+  const procWord = killed === 1 ? "process" : "processes";
+  console.log(
+    colors_default.green(
+      `
+Pruned ${stale.length} stale ${routeWord}, killed ${killed} orphaned ${procWord}.`
+    )
+  );
+}
 async function handleList() {
   const { dir, port, tls: tls2 } = await discoverState();
   const store = new RouteStore(dir, {
@@ -4207,7 +4302,8 @@ function spawnChildProcess(commandArgs, env, cwd) {
   return spawn3(commandArgs[0], commandArgs.slice(1), {
     stdio: ["ignore", "pipe", "pipe"],
     env,
-    cwd
+    cwd,
+    ...isWindows ? {} : { detached: true }
   });
 }
 function prefixStream(stream, output, prefix) {
@@ -4480,23 +4576,18 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
     env: {
       ...process.env,
       NODE_OPTIONS: buildNodeOptions()
-    }
+    },
+    ...isWindows ? {} : { detached: true }
   });
   const SIGKILL_TIMEOUT_MS = 5e3;
   let cleanedUp = false;
   const cleanup = () => {
     if (cleanedUp) return;
     cleanedUp = true;
-    try {
-      turboChild.kill("SIGTERM");
-    } catch {
-    }
+    killTree(turboChild, "SIGTERM");
     setTimeout(() => {
       if (turboChild.exitCode === null && !turboChild.killed) {
-        try {
-          turboChild.kill("SIGKILL");
-        } catch {
-        }
+        killTree(turboChild, "SIGKILL");
       }
     }, SIGKILL_TIMEOUT_MS).unref();
     for (const { hostname } of routes) {
@@ -4554,18 +4645,12 @@ async function runWithDirectSpawn(stateDir, proxyPort, tls2, tld, proxiedApps, t
     if (cleanedUp) return;
     cleanedUp = true;
     for (const child of children) {
-      try {
-        child.kill("SIGTERM");
-      } catch {
-      }
+      killTree(child, "SIGTERM");
     }
     setTimeout(() => {
       for (const child of children) {
         if (child.exitCode === null && !child.killed) {
-          try {
-            child.kill("SIGKILL");
-          } catch {
-          }
+          killTree(child, "SIGKILL");
         }
       }
     }, SIGKILL_TIMEOUT_MS).unref();
@@ -4812,6 +4897,10 @@ async function main() {
       await handleClean(args);
       return;
     }
+    if (args[0] === "prune") {
+      await handlePrune(args);
+      return;
+    }
     if (args[0] === "list") {
       await handleList();
       return;

package/dist/index.d.ts

@@ -108,6 +108,17 @@ declare class RouteStore {
      * log it.
      */
     addRoute(hostname: string, port: number, pid: number, force?: boolean): number | undefined;
+    /**
+     * Load all routes from disk without filtering out dead PIDs. Used by
+     * `portless prune` to discover stale entries whose owning CLI is gone
+     * but whose dev server may still be holding a port.
+     */
+    loadRoutesRaw(): RouteMapping[];
+    /**
+     * Remove all route entries whose owning process is dead and persist the
+     * result. Returns the removed stale entries so the caller can act on them.
+     */
+    pruneStaleRoutes(): RouteMapping[];
     removeRoute(hostname: string): void;
 }
 

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   removeBlock,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-6PDLZVDS.js";
+} from "./chunk-RRH2JUIU.js";
 export {
   DIR_MODE,
   FILE_MODE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",