portless 0.13.1 → 0.15.0

package/README.md

@@ -323,6 +323,20 @@ Set `PORTLESS_TAILSCALE=1` in your shell profile or `.env` to share every app by
 
 Requires the Tailscale CLI to be installed and connected (`tailscale up`), with Tailscale HTTPS certificates enabled.
 
+## ngrok sharing
+
+Expose your dev server to the public internet with [ngrok](https://ngrok.com):
+
+```bash
+portless myapp --ngrok next dev
+# -> https://myapp.localhost           (local)
+# -> https://abc123.ngrok.app          (public)
+```
+
+Set `PORTLESS_NGROK=1` in your shell profile or `.env` to enable ngrok by default when portless runs an app. `portless list` shows both local and ngrok URLs. The ngrok tunnel is cleaned up automatically when the app exits.
+
+Requires the ngrok CLI to be installed and authenticated. If ngrok reports an authentication error, run `ngrok config add-authtoken <token>` and try again.
+
 ## Commands
 
 ```bash
@@ -334,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
@@ -378,6 +393,7 @@ portless service uninstall       # Remove the startup service
 --app-port <number>              Use a fixed port for the app (skip auto-assignment)
 --tailscale                      Share the app on your Tailscale network (tailnet)
 --funnel                         Share the app publicly via Tailscale Funnel
+--ngrok                          Share the app publicly via ngrok
 --force                          Kill the existing process and take over its route
 --name <name>                    Use <name> as the app name
 ```
@@ -396,6 +412,7 @@ PORTLESS_WILDCARD=1              Allow unregistered subdomains to fall back to p
 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)
 PORTLESS_FUNNEL=1                Share apps publicly via Tailscale Funnel (same as --funnel)
+PORTLESS_NGROK=1                 Share apps publicly via ngrok (same as --ngrok)
 PORTLESS_STATE_DIR=<path>        Override the state directory
 
 # Injected into child processes
@@ -403,10 +420,11 @@ 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_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
 
@@ -431,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.
@@ -486,3 +508,4 @@ pnpm format           # Format all files with Prettier
 - Node.js 24+
 - macOS, Linux, or Windows
 - Tailscale CLI (optional, for `--tailscale` and `--funnel`)
+- ngrok CLI (optional, for `--ngrok`)

package/dist/{chunk-3WLVQXFE.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 [];
     }
   }
@@ -920,22 +939,48 @@ var RouteStore = class _RouteStore {
       const routes = this.loadRoutes(true);
       const route = routes.find((r) => r.hostname === hostname);
       if (!route) return;
-      if (fields.tailscaleUrl !== void 0) route.tailscaleUrl = fields.tailscaleUrl;
-      if (fields.tailscaleHttpsPort !== void 0)
-        route.tailscaleHttpsPort = fields.tailscaleHttpsPort;
-      if (fields.tailscaleFunnel !== void 0) route.tailscaleFunnel = fields.tailscaleFunnel;
+      if ("tailscaleUrl" in fields) {
+        if (fields.tailscaleUrl === null) delete route.tailscaleUrl;
+        else if (fields.tailscaleUrl !== void 0) route.tailscaleUrl = fields.tailscaleUrl;
+      }
+      if ("tailscaleHttpsPort" in fields) {
+        if (fields.tailscaleHttpsPort === null) delete route.tailscaleHttpsPort;
+        else if (fields.tailscaleHttpsPort !== void 0)
+          route.tailscaleHttpsPort = fields.tailscaleHttpsPort;
+      }
+      if ("tailscaleFunnel" in fields) {
+        if (fields.tailscaleFunnel === null) delete route.tailscaleFunnel;
+        else if (fields.tailscaleFunnel !== void 0)
+          route.tailscaleFunnel = fields.tailscaleFunnel;
+      }
+      if ("ngrokUrl" in fields) {
+        if (fields.ngrokUrl === null) delete route.ngrokUrl;
+        else if (fields.ngrokUrl !== void 0) route.ngrokUrl = fields.ngrokUrl;
+      }
+      if ("ngrokPid" in fields) {
+        if (fields.ngrokPid === null) delete route.ngrokPid;
+        else if (fields.ngrokPid !== void 0) route.ngrokPid = fields.ngrokPid;
+      }
       this.saveRoutes(routes);
     } finally {
       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();
@@ -946,6 +991,7 @@ var RouteStore = class _RouteStore {
 export {
   fixOwnership,
   isErrnoException,
+  isProcessAlive,
   escapeHtml,
   formatUrl,
   parseHostname,