portless 0.14.0 → 0.15.0

package/README.md

@@ -348,6 +348,7 @@ portless alias <name> <port>     # Register a static route (e.g. for Docker)
 portless alias <name> <port> --force  # Overwrite an existing route
 portless alias --remove <name>   # Remove a static route
 portless list                    # Show active routes
+portless doctor                  # Check proxy, routes, DNS, and CA trust
 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
@@ -423,7 +424,7 @@ PORTLESS_NGROK_URL               ngrok URL of the app (when --ngrok is active)
 NODE_EXTRA_CA_CERTS              Path to the portless CA (when HTTPS is active)
 ```
 
-> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, `prune`, `proxy`, and `service` 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`, `doctor`, `trust`, `clean`, `prune`, `proxy`, and `service` 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
 
@@ -448,6 +449,10 @@ portless hosts clean   # Clean up later
 
 Auto-syncs `/etc/hosts` for route hostnames by default (`.localhost`, custom TLDs, LAN `.local`). Set `PORTLESS_SYNC_HOSTS=0` to disable.
 
+## Troubleshooting
+
+Run `portless doctor` to inspect local health without changing state. It checks Node.js, the state directory, proxy liveness, route entries, HTTPS CA trust, hostname resolution, and LAN mode prerequisites, then prints suggested fixes.
+
 ## Proxying Between Portless Apps
 
 If your frontend dev server (e.g. Vite, webpack) proxies API requests to another portless app, make sure the proxy rewrites the `Host` header. Without this, portless routes the request back to the frontend in an infinite loop.

package/dist/{chunk-OZM4AEYL.js → chunk-PCBKLZK2.js}

@@ -17,6 +17,15 @@ function fixOwnership(...paths) {
 function isErrnoException(err) {
   return err instanceof Error && "code" in err && typeof err.code === "string";
 }
+function isProcessAlive(pid) {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return isErrnoException(err) && err.code === "EPERM";
+  }
+}
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -375,6 +384,9 @@ function createProxyServer(options) {
         delete proxyReqHeaders[key];
       }
     }
+    if (!proxyReqHeaders.host) {
+      proxyReqHeaders.host = getRequestHost(req);
+    }
     const proxyReq = http.request(
       {
         hostname: "127.0.0.1",
@@ -460,6 +472,9 @@ function createProxyServer(options) {
         delete proxyReqHeaders[key];
       }
     }
+    if (!proxyReqHeaders.host) {
+      proxyReqHeaders.host = getRequestHost(req);
+    }
     const proxyReq = http.request({
       hostname: "127.0.0.1",
       port: route.port,
@@ -869,13 +884,17 @@ var RouteStore = class _RouteStore {
       try {
         parsed = JSON.parse(raw);
       } catch {
+        this.onWarning?.(`Corrupted routes file (invalid JSON): ${this.routesPath}`);
         return [];
       }
       if (!Array.isArray(parsed)) {
+        this.onWarning?.(`Corrupted routes file (expected array): ${this.routesPath}`);
         return [];
       }
       return parsed.filter(isValidRoute);
-    } catch {
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.onWarning?.(`Could not read routes file: ${message}`);
       return [];
     }
   }
@@ -947,13 +966,21 @@ var RouteStore = class _RouteStore {
       this.releaseLock();
     }
   }
-  removeRoute(hostname) {
+  /**
+   * Remove a route by hostname. When `ownerPid` is provided, the entry is
+   * only removed while it is still owned by that pid. Exit cleanups must
+   * pass their own pid: after a `--force` takeover the killed process would
+   * otherwise deregister the route the new owner just registered.
+   */
+  removeRoute(hostname, ownerPid) {
     this.ensureDir();
     if (!this.acquireLock()) {
       throw new Error("Failed to acquire route lock");
     }
     try {
-      const routes = this.loadRoutes(true).filter((r) => r.hostname !== hostname);
+      const routes = this.loadRoutes(true).filter(
+        (r) => r.hostname !== hostname || ownerPid !== void 0 && r.pid !== ownerPid
+      );
       this.saveRoutes(routes);
     } finally {
       this.releaseLock();
@@ -964,6 +991,7 @@ var RouteStore = class _RouteStore {
 export {
   fixOwnership,
   isErrnoException,
+  isProcessAlive,
   escapeHtml,
   formatUrl,
   parseHostname,

package/dist/cli.js

@@ -4,16 +4,19 @@ import {
   PORTLESS_HEADER,
   RouteConflictError,
   RouteStore,
+  checkHostResolution,
   cleanHostsFile,
   createHttpRedirectServer,
   createProxyServer,
   fixOwnership,
   formatUrl,
+  getManagedHostnames,
   isErrnoException,
+  isProcessAlive,
   parseHostname,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-OZM4AEYL.js";
+} from "./chunk-PCBKLZK2.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -1503,6 +1506,7 @@ function readPortFromDir(dir) {
   }
 }
 var TLS_MARKER_FILE = "proxy.tls";
+var CUSTOM_CERT_MARKER_FILE = "proxy.custom-cert";
 function readTlsMarker(dir) {
   try {
     return fs3.existsSync(path3.join(dir, TLS_MARKER_FILE));
@@ -1521,6 +1525,24 @@ function writeTlsMarker(dir, enabled2) {
     }
   }
 }
+function readCustomCertMarker(dir) {
+  try {
+    return fs3.existsSync(path3.join(dir, CUSTOM_CERT_MARKER_FILE));
+  } catch {
+    return false;
+  }
+}
+function writeCustomCertMarker(dir, enabled2) {
+  const markerPath = path3.join(dir, CUSTOM_CERT_MARKER_FILE);
+  if (enabled2) {
+    fs3.writeFileSync(markerPath, "1", { mode: 420 });
+  } else {
+    try {
+      fs3.unlinkSync(markerPath);
+    } catch {
+    }
+  }
+}
 var LAN_MARKER_FILE = "proxy.lan";
 function readLanMarker(dir) {
   try {
@@ -2001,6 +2023,7 @@ var PORTLESS_STATE_FILES = [
   "proxy.port",
   "proxy.log",
   "proxy.tls",
+  "proxy.custom-cert",
   "proxy.tld",
   "proxy.lan",
   "ca-key.pem",
@@ -3880,7 +3903,7 @@ function formatProcessExitSuffix(code, signal) {
   if (code !== null) return ` (exit ${code})`;
   return "";
 }
-function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
+function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict, customCert = false) {
   store.ensureDir();
   const isTls = !!tlsOptions;
   const mdnsSupport = isMdnsSupported();
@@ -4009,6 +4032,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     fs9.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
     fs9.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
+    writeCustomCertMarker(store.dir, isTls && customCert);
     writeTldFile(store.dir, tld);
     writeLanMarker(store.dir, activeLanIp);
     fixOwnership(store.dir, store.pidPath, store.portFilePath);
@@ -4021,7 +4045,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     if (activeLanIp) {
       console.log(chalk.green(`LAN mode: ${activeLanIp}`));
       console.log(chalk.gray("Services are discoverable as <name>.local on your network"));
-      if (isTls) {
+      if (isTls && !customCert) {
         console.log(chalk.yellow("For HTTPS on devices, install the CA certificate:"));
         console.log(chalk.gray(`  ${path9.join(store.dir, "ca.pem")}`));
       }
@@ -4063,6 +4087,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    writeCustomCertMarker(store.dir, false);
     writeTldFile(store.dir, DEFAULT_TLD);
     writeLanMarker(store.dir, null);
     if (autoSyncHosts) cleanHostsFile();
@@ -4101,6 +4126,7 @@ async function stopProxy(store, proxyPort, _tls) {
           } catch {
           }
           writeTlsMarker(store.dir, false);
+          writeCustomCertMarker(store.dir, false);
           writeTldFile(store.dir, DEFAULT_TLD);
           writeLanMarker(store.dir, null);
           console.log(colors_default.green(`Killed process ${pid}. Proxy stopped.`));
@@ -4140,6 +4166,7 @@ async function stopProxy(store, proxyPort, _tls) {
       console.error(colors_default.red("Corrupted PID file. Removing it."));
       fs9.unlinkSync(pidPath);
       writeTlsMarker(store.dir, false);
+      writeCustomCertMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
@@ -4158,6 +4185,7 @@ async function stopProxy(store, proxyPort, _tls) {
       } catch {
       }
       writeTlsMarker(store.dir, false);
+      writeCustomCertMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
@@ -4171,6 +4199,7 @@ async function stopProxy(store, proxyPort, _tls) {
       console.log(colors_default.yellow("Removing stale PID file."));
       fs9.unlinkSync(pidPath);
       writeTlsMarker(store.dir, false);
+      writeCustomCertMarker(store.dir, false);
       writeTldFile(store.dir, DEFAULT_TLD);
       writeLanMarker(store.dir, null);
       return;
@@ -4182,6 +4211,7 @@ async function stopProxy(store, proxyPort, _tls) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    writeCustomCertMarker(store.dir, false);
     writeTldFile(store.dir, DEFAULT_TLD);
     writeLanMarker(store.dir, null);
     console.log(colors_default.green("Proxy stopped."));
@@ -4564,7 +4594,7 @@ portless
       } catch {
       }
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
       process.exit(1);
@@ -4618,7 +4648,7 @@ portless
       } catch {
       }
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
     }
@@ -4803,13 +4833,14 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless run")}                     Same as above
   ${colors_default.cyan("portless run <cmd>")}               Run a command through the proxy
   ${colors_default.cyan("portless <name> <cmd>")}            Run with an explicit app name
-  ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon)
+  ${colors_default.cyan("portless proxy start")}             Start the proxy (HTTPS on port 443, daemon); rarely needed since it auto-starts on first run
   ${colors_default.cyan("portless proxy stop")}              Stop the proxy
   ${colors_default.cyan("portless service install")}         Start proxy automatically when the OS starts
   ${colors_default.cyan("portless get <name>")}              Print URL for a service (for cross-service refs)
   ${colors_default.cyan("portless alias <name> <port>")}     Register a static route (e.g. for Docker)
   ${colors_default.cyan("portless alias --remove <name>")}   Remove a static route
   ${colors_default.cyan("portless list")}                    Show active routes
+  ${colors_default.cyan("portless doctor")}                  Check local portless health
   ${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
@@ -4827,6 +4858,7 @@ ${colors_default.bold("Examples:")}
   portless service install --lan      # Persist LAN mode in the startup service
   portless service install --wildcard # Persist wildcard routing in the startup service
   portless get backend                # -> https://backend.localhost
+  portless doctor                     # Check proxy, routes, DNS, and CA trust
   portless myapp --tailscale next dev # -> also https://<node>.ts.net (tailnet)
   portless myapp --funnel next dev    # -> also https://<node>.ts.net (public)
   portless myapp --ngrok next dev     # -> also https://<random>.ngrok.app (public)
@@ -4957,14 +4989,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, prune, proxy, service are subcommands and
+  run, get, alias, hosts, list, doctor, trust, clean, prune, proxy, service 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.14.0");
+  console.log("0.15.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -5401,6 +5433,355 @@ ${colors_default.bold("Usage: portless hosts <command>")}
   );
   process.exit(1);
 }
+function colorDoctorStatus(status) {
+  if (status === "fail") return colors_default.red;
+  if (status === "warn") return colors_default.yellow;
+  if (status === "ok") return colors_default.green;
+  return colors_default.gray;
+}
+function printDoctorFinding(finding) {
+  const status = finding.status.padEnd(5);
+  console.log(`${colorDoctorStatus(finding.status)(status)} ${finding.message}`);
+  if (finding.hint) {
+    console.log(colors_default.gray(`      ${finding.hint}`));
+  }
+}
+function isProcessAliveForDoctor(pid) {
+  if (pid <= 0) return true;
+  return isProcessAlive(pid);
+}
+function checkPathWritable(targetPath) {
+  try {
+    fs9.accessSync(targetPath, fs9.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findExistingAncestor(targetPath) {
+  let current = targetPath;
+  for (; ; ) {
+    if (fs9.existsSync(current)) return current;
+    const parent = path9.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function checkCommandAvailable(command, args) {
+  const result = spawnSync5(command, args, {
+    stdio: "ignore",
+    timeout: 3e3,
+    windowsHide: true
+  });
+  return !result.error && (result.status === 0 || result.status === null);
+}
+function pluralize(count, singular, plural = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+function isValidTcpPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+function doctorProxyStartHint(proxyPort, tls2) {
+  const defaultPort = getDefaultPort(tls2);
+  const portArgs = proxyPort === defaultPort ? "" : ` -p ${proxyPort}`;
+  const tlsArgs = tls2 ? "" : " --no-tls";
+  return `Run: portless proxy start${portArgs}${tlsArgs}`;
+}
+async function handleDoctor(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${colors_default.bold("portless doctor")} - Check local portless health and print suggested fixes.
+
+${colors_default.bold("Usage:")}
+  ${colors_default.cyan("portless doctor")}
+
+Checks Node.js, the state directory, proxy liveness, route entries, HTTPS CA
+trust, hostname resolution, and LAN mode prerequisites. It does not start,
+stop, clean, prune, trust, or modify portless state.
+
+${colors_default.bold("Options:")}
+  --help, -h             Show this help
+`);
+    process.exit(0);
+  }
+  if (args.length > 1) {
+    console.error(colors_default.red(`Error: Unknown argument "${args[1]}".`));
+    console.error(colors_default.cyan("  portless doctor --help"));
+    process.exit(1);
+  }
+  const findings = [];
+  const add = (status, message, hint) => {
+    findings.push({ status, message, hint });
+  };
+  let state;
+  try {
+    state = await discoverState();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    add("fail", `Could not discover portless state: ${message}`);
+    state = {
+      dir: resolveStateDir(),
+      port: getDefaultPort(!isHttpsEnvDisabled()),
+      tls: !isHttpsEnvDisabled(),
+      tld: DEFAULT_TLD,
+      lanMode: isLanEnvEnabled(),
+      lanIp: null
+    };
+  }
+  const store = new RouteStore(state.dir, {
+    onWarning: (msg) => add("warn", msg)
+  });
+  const hasPortFile = fs9.existsSync(store.portFilePath);
+  const configuredTls = hasPortFile ? state.tls : !isHttpsEnvDisabled();
+  const configuredPort = hasPortFile ? state.port : getDefaultPort(configuredTls);
+  const initialProxyRunning = await isProxyRunning(state.port, state.tls);
+  const probePort = initialProxyRunning || hasPortFile ? state.port : configuredPort;
+  const probeTls = initialProxyRunning || hasPortFile ? state.tls : configuredTls;
+  const proxyRunning = initialProxyRunning && probePort === state.port ? true : await isProxyRunning(probePort, probeTls);
+  const portListening = proxyRunning ? true : await isPortListening(probePort);
+  const proxyPort = proxyRunning || portListening || hasPortFile ? probePort : configuredPort;
+  const proxyTls = proxyRunning || portListening || hasPortFile ? probeTls : configuredTls;
+  const currentProxyStateIsHttp = (proxyRunning || portListening || hasPortFile) && !proxyTls;
+  const proxyUsesCustomCert = proxyTls && readCustomCertMarker(state.dir);
+  const stateExists = fs9.existsSync(state.dir);
+  console.log(colors_default.blue.bold("\nportless doctor\n"));
+  console.log(`Version: ${"0.15.0"}`);
+  console.log(`Node.js: ${process.versions.node}`);
+  console.log(`Platform: ${process.platform} ${process.arch}`);
+  console.log(`State dir: ${state.dir}`);
+  console.log(`Proxy target: ${formatUrl("127.0.0.1", proxyPort, proxyTls)}`);
+  console.log(`Mode: ${proxyTls ? "HTTPS" : "HTTP"}, .${state.tld}${state.lanMode ? ", LAN" : ""}`);
+  console.log("");
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  if (nodeMajor >= 24) {
+    add("ok", `Node.js ${process.versions.node} satisfies portless requirements.`);
+  } else {
+    add("fail", `Node.js ${process.versions.node} is unsupported.`, "Install Node.js 24 or newer.");
+  }
+  if (stateExists) {
+    try {
+      const stat = fs9.statSync(state.dir);
+      if (!stat.isDirectory()) {
+        add("fail", `State path exists but is not a directory: ${state.dir}`);
+      } else if (checkPathWritable(state.dir)) {
+        add("ok", `State directory is writable: ${state.dir}`);
+      } else {
+        add("fail", `State directory is not writable: ${state.dir}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      add("fail", `Could not inspect state directory: ${message}`);
+    }
+  } else {
+    const ancestor = findExistingAncestor(path9.dirname(state.dir));
+    if (!ancestor) {
+      add(
+        "fail",
+        `State directory does not exist and no writable ancestor was found: ${state.dir}`
+      );
+    } else {
+      const ancestorStat = fs9.statSync(ancestor);
+      if (!ancestorStat.isDirectory()) {
+        add("fail", `State directory does not exist and ancestor is not a directory: ${ancestor}`);
+      } else if (checkPathWritable(ancestor)) {
+        add("info", `State directory has not been created yet: ${state.dir}`);
+      } else {
+        add("fail", `State directory does not exist and ancestor is not writable: ${ancestor}`);
+      }
+    }
+  }
+  if (proxyRunning) {
+    add("ok", `Proxy is responding on port ${proxyPort}.`);
+  } else if (portListening) {
+    const pid = findPidOnPort(proxyPort);
+    add(
+      "fail",
+      `Port ${proxyPort} is in use, but it is not a portless proxy.`,
+      pid ? `Process on port: PID ${pid}` : "Could not identify the process holding the port."
+    );
+  } else {
+    add(
+      "warn",
+      `Proxy is not running on port ${proxyPort}.`,
+      doctorProxyStartHint(proxyPort, proxyTls)
+    );
+  }
+  if (fs9.existsSync(store.pidPath)) {
+    try {
+      const rawPid = fs9.readFileSync(store.pidPath, "utf-8").trim();
+      const pid = parseInt(rawPid, 10);
+      if (isNaN(pid) || pid <= 0) {
+        add("fail", `Proxy PID file is invalid: ${store.pidPath}`);
+      } else if (!isProcessAliveForDoctor(pid)) {
+        add("warn", `Proxy PID file is stale: ${pid}`, "Run: portless proxy stop");
+      } else if (!proxyRunning) {
+        add(
+          "warn",
+          `Proxy PID file points to PID ${pid}, but no portless proxy is responding on port ${proxyPort}.`,
+          "Run: portless proxy stop"
+        );
+      } else {
+        const portPid = findPidOnPort(proxyPort);
+        if (portPid !== null && portPid !== pid) {
+          add(
+            "warn",
+            `Proxy PID file points to PID ${pid}, but port ${proxyPort} is owned by PID ${portPid}.`,
+            "Run: portless proxy stop"
+          );
+        } else {
+          add("ok", `Proxy PID file points to the responding proxy process: ${pid}`);
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      add("fail", `Could not read proxy PID file: ${message}`);
+    }
+  } else if (proxyRunning) {
+    add("warn", `Proxy is running but the PID file is missing: ${store.pidPath}`);
+  }
+  if (proxyUsesCustomCert) {
+    add("ok", "Proxy is configured with a custom TLS certificate.");
+  } else if (proxyTls || !currentProxyStateIsHttp && !isHttpsEnvDisabled()) {
+    if (checkCommandAvailable("openssl", ["version"])) {
+      add("ok", "OpenSSL is available for certificate generation.");
+    } else {
+      add(
+        "fail",
+        "OpenSSL is not available on PATH.",
+        isWindows ? "Install OpenSSL or add Git for Windows OpenSSL to PATH." : "Install OpenSSL with your system package manager."
+      );
+    }
+  } else {
+    add("info", "HTTPS is disabled, so OpenSSL is not required for this run.");
+  }
+  if (proxyTls && proxyUsesCustomCert) {
+    add("info", "Generated local CA is not required for custom TLS certificates.");
+  } else if (proxyTls) {
+    const caPath = path9.join(state.dir, "ca.pem");
+    if (fs9.existsSync(caPath)) {
+      if (isCATrusted(state.dir)) {
+        add("ok", "Local CA is trusted by the OS trust store.");
+      } else {
+        add(
+          "warn",
+          "Local CA exists but is not trusted by the OS trust store.",
+          "Run: portless trust"
+        );
+      }
+    } else if (proxyRunning) {
+      add("warn", `Generated CA file is missing: ${caPath}`);
+    } else {
+      add("info", "Local CA has not been generated yet.");
+    }
+  } else {
+    add("info", "HTTPS is disabled for the current proxy state.");
+  }
+  let rawRoutes = [];
+  try {
+    rawRoutes = store.loadRoutesRaw();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    add("fail", `Could not read routes: ${message}`);
+  }
+  const liveRoutes = rawRoutes.filter(
+    (route) => route.pid === 0 || isProcessAliveForDoctor(route.pid)
+  );
+  const staleRoutes = rawRoutes.filter(
+    (route) => route.pid !== 0 && !isProcessAliveForDoctor(route.pid)
+  );
+  if (rawRoutes.length === 0) {
+    add("info", "No routes are registered.");
+  } else if (staleRoutes.length === 0) {
+    add("ok", `Routes: ${pluralize(liveRoutes.length, "active route")}.`);
+  } else {
+    add(
+      "warn",
+      `Routes: ${pluralize(liveRoutes.length, "active route")}, ${pluralize(staleRoutes.length, "stale route")}.`,
+      "Run: portless prune"
+    );
+  }
+  for (const route of staleRoutes.slice(0, 5)) {
+    add("warn", `Stale route ${route.hostname} is owned by exited PID ${route.pid}.`);
+  }
+  if (staleRoutes.length > 5) {
+    add("warn", `${staleRoutes.length - 5} additional stale routes hidden.`);
+  }
+  const routePortChecks = await Promise.all(
+    liveRoutes.map(async (route) => {
+      const validPort = isValidTcpPort(route.port);
+      return {
+        route,
+        invalidPort: !validPort,
+        listening: validPort ? await isPortListening(route.port) : false
+      };
+    })
+  );
+  for (const { route, invalidPort, listening } of routePortChecks) {
+    if (invalidPort) {
+      add(
+        "warn",
+        `Route ${route.hostname} has invalid port ${route.port}.`,
+        route.pid === 0 ? "Remove or recreate the alias." : "Run: portless prune"
+      );
+      continue;
+    }
+    if (listening) continue;
+    add(
+      "warn",
+      `Route ${route.hostname} points to port ${route.port}, but nothing is listening there.`,
+      route.pid === 0 ? "Remove the alias or start that service." : "The app may still be starting."
+    );
+  }
+  if (state.lanMode || isLanEnvEnabled()) {
+    const mdns = isMdnsSupported();
+    if (mdns.supported) {
+      add("ok", "mDNS publishing support is available for LAN mode.");
+    } else {
+      add("fail", `LAN mode is enabled but mDNS publishing is unavailable: ${mdns.reason}`);
+    }
+    if (state.lanIp) {
+      add("ok", `LAN IP is recorded: ${state.lanIp}`);
+    } else {
+      add("warn", "LAN mode is enabled but no LAN IP is recorded.");
+    }
+  } else if (liveRoutes.length > 0) {
+    const managedHosts = new Set(getManagedHostnames());
+    const resolutionChecks = await Promise.all(
+      liveRoutes.map(async (route) => ({
+        hostname: route.hostname,
+        resolves: await checkHostResolution(route.hostname),
+        managed: managedHosts.has(route.hostname)
+      }))
+    );
+    const unresolved = resolutionChecks.filter((result) => !result.resolves);
+    if (unresolved.length === 0) {
+      add("ok", "Registered hostnames resolve through the system resolver.");
+    } else {
+      add(
+        "warn",
+        `${pluralize(unresolved.length, "hostname")} did not resolve through the system resolver.`,
+        "Run: portless hosts sync"
+      );
+      for (const result of unresolved.slice(0, 5)) {
+        const hostState = result.managed ? "present in hosts block" : "missing from hosts block";
+        add("warn", `${result.hostname} is ${hostState}.`);
+      }
+    }
+  }
+  for (const finding of findings) {
+    printDoctorFinding(finding);
+  }
+  const failures = findings.filter((finding) => finding.status === "fail").length;
+  const warnings = findings.filter((finding) => finding.status === "warn").length;
+  console.log("");
+  if (failures > 0) {
+    console.log(
+      colors_default.red(`Summary: ${pluralize(failures, "failure")}, ${pluralize(warnings, "warning")}.`)
+    );
+    process.exit(1);
+  }
+  console.log(colors_default.green(`Summary: 0 failures, ${pluralize(warnings, "warning")}.`));
+}
 async function handleProxy(args) {
   if (args[1] === "stop") {
     let explicitPort;
@@ -5786,7 +6167,15 @@ ${colors_default.bold("LAN mode (--lan):")}
   }
   if (isForeground) {
     console.log(chalk.blue.bold("\nportless proxy\n"));
-    startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, desiredWildcard ? false : void 0);
+    startProxyServer(
+      store,
+      proxyPort,
+      tld,
+      tlsOptions,
+      lanIp,
+      desiredWildcard ? false : void 0,
+      !!(customCertPath && customKeyPath)
+    );
     return;
   }
   store.ensureDir();
@@ -6002,7 +6391,7 @@ async function spawnProxiedApp(app, stateDir, proxyPort, tls2, tld, exitCodes) {
     }
     if (capturedStore && capturedHostname) {
       try {
-        capturedStore.removeRoute(capturedHostname);
+        capturedStore.removeRoute(capturedHostname, process.pid);
       } catch {
       }
     }
@@ -6216,7 +6605,7 @@ async function runWithTurbo(wsRoot, stateDir, proxyPort, tls2, tld, scriptName,
     }, SIGKILL_TIMEOUT_MS).unref();
     for (const { hostname } of routes) {
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
     }
@@ -6280,7 +6669,7 @@ async function runWithDirectSpawn(stateDir, proxyPort, tls2, tld, proxiedApps, t
     }, SIGKILL_TIMEOUT_MS).unref();
     for (const { store, hostname } of routeEntries) {
       try {
-        store.removeRoute(hostname);
+        store.removeRoute(hostname, process.pid);
       } catch {
       }
     }
@@ -6492,7 +6881,7 @@ async function main() {
     args.shift();
   }
   const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
-  if (skipPortless && (isRunCommand || args.length === 0 || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean" && args[0] !== "service")) {
+  if (skipPortless && (isRunCommand || args.length === 0 || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean" && args[0] !== "doctor" && args[0] !== "service")) {
     const parsed = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     let commandArgs = parsed.commandArgs;
     if (commandArgs.length === 0 && (isRunCommand || args.length === 0)) {
@@ -6540,6 +6929,10 @@ async function main() {
       await handleList();
       return;
     }
+    if (args[0] === "doctor") {
+      await handleDoctor(args);
+      return;
+    }
     if (args[0] === "get") {
       await handleGet(args);
       return;

package/dist/index.d.ts

@@ -136,7 +136,13 @@ declare class RouteStore {
      * merged; the route must already exist (matched by hostname).
      */
     updateRoute(hostname: string, fields: RouteMetadataPatch): void;
-    removeRoute(hostname: string): void;
+    /**
+     * Remove a route by hostname. When `ownerPid` is provided, the entry is
+     * only removed while it is still owned by that pid. Exit cleanups must
+     * pass their own pid: after a `--force` takeover the killed process would
+     * otherwise deregister the route the new owner just registered.
+     */
+    removeRoute(hostname: string, ownerPid?: number): void;
 }
 
 /**
@@ -147,6 +153,8 @@ declare class RouteStore {
 declare function fixOwnership(...paths: string[]): void;
 /** Type guard for Node.js system errors with an error code. */
 declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
+/** Return whether a process exists, treating permission denial as alive. */
+declare function isProcessAlive(pid: number): boolean;
 /**
  * Escape HTML special characters to prevent XSS.
  */
@@ -204,4 +212,4 @@ declare function getManagedHostnames(): string[];
  */
 declare function checkHostResolution(hostname: string): Promise<boolean>;
 
-export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, shouldAutoSyncHosts, syncHostsFile };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, isProcessAlive, parseHostname, removeBlock, shouldAutoSyncHosts, syncHostsFile };

package/dist/index.js

@@ -15,11 +15,12 @@ import {
   formatUrl,
   getManagedHostnames,
   isErrnoException,
+  isProcessAlive,
   parseHostname,
   removeBlock,
   shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-OZM4AEYL.js";
+} from "./chunk-PCBKLZK2.js";
 export {
   DIR_MODE,
   FILE_MODE,
@@ -37,6 +38,7 @@ export {
   formatUrl,
   getManagedHostnames,
   isErrnoException,
+  isProcessAlive,
   parseHostname,
   removeBlock,
   shouldAutoSyncHosts,

package/package.json

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