portless 0.14.0 → 0.15.1

package/README.md

@@ -34,7 +34,7 @@ HTTPS with HTTP/2 is enabled by default. On first run, portless generates a loca
 
 The proxy auto-starts when you run an app. A random port (4000-4999) is assigned via the `PORT` environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore `PORT` (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the right `--port` flag and, when needed, a matching `--host` flag.
 
-When auto-starting, portless reuses the configuration (port, TLS, TLD) from the most recent proxy run, so a restart or reboot does not silently revert to defaults. Explicit env vars (`PORTLESS_PORT`, `PORTLESS_HTTPS`, etc.) always take priority.
+When auto-starting, portless reuses the configuration (port, TLS, TLDs) from the most recent proxy run, so a restart or reboot does not silently revert to defaults. Explicit env vars (`PORTLESS_PORT`, `PORTLESS_HTTPS`, etc.) always take priority.
 
 In non-interactive environments (no TTY, or `CI=1`), portless exits with a descriptive error instead of prompting, so task runners like turborepo and CI scripts fail early with a clear message.
 
@@ -210,6 +210,17 @@ portless myapp next dev
 
 The proxy auto-syncs `/etc/hosts` for route hostnames (including `.test`), so those domains resolve on your machine.
 
+Repeat `--tld` to serve the same app names under multiple TLDs from one proxy:
+
+```bash
+portless proxy start --tld localhost --tld test
+portless myapp next dev
+# -> https://myapp.localhost
+# -> https://myapp.test
+```
+
+When multiple TLDs are configured, `PORTLESS_URL` uses the first TLD. `PORTLESS_TLD` also accepts a comma separated list, e.g. `PORTLESS_TLD=localhost,test`.
+
 Recommended: `.test` (IANA-reserved, no collision risk). Avoid `.local` (conflicts with mDNS/Bonjour) and `.dev` (Google-owned, forces HTTPS via HSTS).
 
 ## How it works
@@ -264,7 +275,7 @@ portless service uninstall
 
 The service uses portless defaults unless install options or `PORTLESS_*` environment variables are provided: HTTPS on port 443 with `.localhost` names. `service install` accepts the proxy options you would use with `proxy start`, including `--port`, `--no-tls`, `--lan`, `--ip`, `--tld`, `--wildcard`, `--cert`, and `--key`. Use `--state-dir <path>` or `PORTLESS_STATE_DIR=<path>` to choose where service state and logs are written.
 
-The chosen service configuration is written into launchd, systemd, or Task Scheduler and reused after reboot. `portless service status` reports the installed port, HTTPS mode, TLD, LAN mode, wildcard mode, and state directory. macOS and Linux install a root-owned service so port 443 can bind at boot. Windows installs a Task Scheduler startup task that runs as SYSTEM. Installation and removal may require administrator privileges. `portless clean` automatically removes the service.
+The chosen service configuration is written into launchd, systemd, or Task Scheduler and reused after reboot. `portless service status` reports the installed port, HTTPS mode, TLDs, LAN mode, wildcard mode, and state directory. macOS and Linux install a root-owned service so port 443 can bind at boot. Windows installs a Task Scheduler startup task that runs as SYSTEM. Installation and removal may require administrator privileges. `portless clean` automatically removes the service.
 
 ## LAN mode
 
@@ -276,7 +287,7 @@ portless proxy start --lan --ip 192.168.1.42
 
 `--lan` switches the proxy to mDNS discovery: services are advertised as `<name>.local` and reachable from any device on the same network. Portless auto-detects your LAN IP and follows Wi-Fi/IP changes automatically, but you can pin another address with `--ip <address>` or by exporting `PORTLESS_LAN_IP`. Set `PORTLESS_LAN=1` in your shell (0/1 boolean) to make LAN mode the default whenever the proxy starts.
 
-Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start it again, it stays in LAN mode. All proxy settings (port, TLS, TLD, LAN) are persisted and reused on auto-start unless overridden by explicit flags or env vars. Use `PORTLESS_LAN=0` for one start to switch back to `.localhost` mode. If a proxy is already running with different explicit LAN/TLS/TLD settings, portless warns and asks you to stop it first.
+Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start it again, it stays in LAN mode. All proxy settings (port, TLS, TLDs, LAN) are persisted and reused on auto-start unless overridden by explicit flags or env vars. Use `PORTLESS_LAN=0` for one start to switch back to `.localhost` mode. If a proxy is already running with different explicit LAN/TLS/TLD settings, portless warns and asks you to stop it first.
 
 LAN mode depends on the system mDNS tools that portless already spawns: macOS ships with `dns-sd`, while Linux uses `avahi-publish-address` from `avahi-utils` (install via `sudo apt install avahi-utils` or your distro’s equivalent). If the command is missing or your network isn’t reachable, `portless proxy start --lan` prints the relevant error and exits.
 
@@ -348,6 +359,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
@@ -385,7 +397,7 @@ portless service uninstall       # Remove the startup service
 --cert <path>                    Use a custom TLS certificate
 --key <path>                     Use a custom TLS private key
 --foreground                     Run proxy in foreground instead of daemon
---tld <tld>                      Use a custom TLD instead of .localhost (e.g. test)
+--tld <tld>                      Use a custom TLD instead of .localhost; repeat for more
 --wildcard                       Allow unregistered subdomains to fall back to parent route
 --state-dir <path>               Use a custom state directory with service install
 --script <name>                  Run a specific package.json script (default: dev)
@@ -406,7 +418,7 @@ PORTLESS_APP_PORT=<number>       Use a fixed port for the app (same as --app-por
 PORTLESS_HTTPS=0                 Disable HTTPS (same as --no-tls)
 PORTLESS_LAN=1                   Enable LAN mode when set to 1 (auto-detects LAN IP)
 PORTLESS_LAN_IP=<address>        Pin a specific LAN IP for LAN mode
-PORTLESS_TLD=<tld>               Use a custom TLD (e.g. test; default: localhost)
+PORTLESS_TLD=<tld>[,<tld>]       Use one or more TLDs (e.g. localhost,test)
 PORTLESS_WILDCARD=1              Allow unregistered subdomains to fall back to parent route
 PORTLESS_SYNC_HOSTS=0            Disable auto-sync of /etc/hosts (on by default)
 PORTLESS_TAILSCALE=1             Share apps on your Tailscale network (same as --tailscale)
@@ -417,13 +429,13 @@ PORTLESS_STATE_DIR=<path>        Override the state directory
 # Injected into child processes
 PORT                             Ephemeral port the child should listen on
 HOST                             Usually 127.0.0.1 (omitted for Expo in LAN mode)
-PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
+PORTLESS_URL                     Primary public URL (e.g. https://myapp.localhost)
 PORTLESS_TAILSCALE_URL           Tailscale URL of the app (when --tailscale is active)
 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 +460,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-SD2PIWJU.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;");
 }
@@ -56,6 +65,18 @@ function parseHostname(input, tld = "localhost") {
   }
   return hostname;
 }
+function parseHostnames(input, tlds = ["localhost"]) {
+  const uniqueTlds = [...new Set(tlds)];
+  let baseInput = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
+  for (const tld of uniqueTlds) {
+    const suffix = `.${tld}`;
+    if (baseInput.endsWith(suffix)) {
+      baseInput = baseInput.slice(0, -suffix.length);
+      break;
+    }
+  }
+  return uniqueTlds.map((tld) => parseHostname(baseInput, tld));
+}
 
 // src/proxy.ts
 import * as http from "http";
@@ -313,11 +334,13 @@ function createProxyServer(options) {
     getRoutes,
     proxyPort,
     tld = "localhost",
+    tlds = [tld],
     strict = true,
     onError = (msg) => console.error(msg),
     tls
   } = options;
-  const tldSuffix = `.${tld}`;
+  const tldSuffixes = [...new Set(tlds.length > 0 ? tlds : [tld])].map((value) => `.${value}`);
+  const primaryTldSuffix = tldSuffixes[0] ?? ".localhost";
   const handleRequest = (req, res) => {
     const reqTls = isEncrypted(req);
     res.setHeader(PORTLESS_HEADER, "1");
@@ -340,7 +363,7 @@ function createProxyServer(options) {
           "Loop Detected",
           `<div class="content"><p class="desc">This request has passed through portless ${hops} times. This usually means a dev server (Vite, webpack, etc.) is proxying requests back through portless without rewriting the Host header.</p><div class="section"><p class="label">Fix: add changeOrigin to your proxy config</p><pre class="terminal">proxy: {
   "/api": {
-    target: "${reqTls ? "https" : "http"}://&lt;backend&gt;${escapeHtml(tldSuffix)}${reqTls ? "" : ":&lt;port&gt;"}",
+    target: "${reqTls ? "https" : "http"}://&lt;backend&gt;${escapeHtml(primaryTldSuffix)}${reqTls ? "" : ":&lt;port&gt;"}",
     changeOrigin: true,
   },
 }</pre></div></div>`
@@ -351,7 +374,8 @@ function createProxyServer(options) {
     const route = findRoute(routes, host, strict);
     if (!route) {
       const safeHost = escapeHtml(host);
-      const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host;
+      const matchedSuffix = tldSuffixes.find((suffix) => host.endsWith(suffix));
+      const strippedHost = matchedSuffix ? host.slice(0, -matchedSuffix.length) : host;
       const safeSuggestion = escapeHtml(strippedHost);
       const routesList = routes.length > 0 ? `<div class="section"><p class="label">Active apps</p><ul class="card">${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort, reqTls))}" class="card-link"><span class="name">${escapeHtml(r.hostname)}</span><span class="meta"><code class="port">127.0.0.1:${escapeHtml(String(r.port))}</code><span class="arrow">${ARROW_SVG}</span></span></a></li>`).join("")}</ul></div>` : '<p class="empty">No apps running.</p>';
       res.writeHead(404, { "Content-Type": "text/html" });
@@ -375,6 +399,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 +487,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,
@@ -679,9 +709,9 @@ function checkHostResolution(hostname) {
 import * as fs3 from "fs";
 import * as path2 from "path";
 var STALE_LOCK_THRESHOLD_MS = 1e4;
-var LOCK_TIMEOUT_MS = 5e3;
+var LOCK_TIMEOUT_MS = 15e3;
 var LOCK_RETRY_BASE_MS = 10;
-var LOCK_RETRY_CAP_MS = 500;
+var LOCK_RETRY_CAP_MS = 100;
 var FILE_MODE = 420;
 var DIR_MODE = 493;
 function isValidRoute(value) {
@@ -869,13 +899,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 +981,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,9 +1006,11 @@ var RouteStore = class _RouteStore {
 export {
   fixOwnership,
   isErrnoException,
+  isProcessAlive,
   escapeHtml,
   formatUrl,
   parseHostname,
+  parseHostnames,
   PORTLESS_HEADER,
   createProxyServer,
   createHttpRedirectServer,