portless 0.11.0 → 0.12.0

package/README.md

@@ -276,6 +276,34 @@ LAN mode depends on the system mDNS tools that portless already spawns: macOS sh
 
 - **Expo / React Native**: portless always injects `--port`. React Native also gets `--host 127.0.0.1`. Expo gets `--host localhost` outside LAN mode, but in LAN mode portless leaves Metro on its default LAN host behavior instead of forcing `--host` or `HOST`.
 
+## Tailscale sharing
+
+Share your dev server with teammates on your [Tailscale](https://tailscale.com) network:
+
+```bash
+portless myapp --tailscale next dev
+# -> https://myapp.localhost           (local)
+# -> https://devbox.yourteam.ts.net    (tailnet)
+```
+
+Each `--tailscale` app is root-mounted on its own Tailscale HTTPS port, so no framework `basePath` configuration is needed. The first app gets port 443, subsequent apps get 8443, 8444, etc.
+
+```bash
+portless myapp --tailscale next dev     # -> https://devbox.ts.net
+portless api --tailscale pnpm start     # -> https://devbox.ts.net:8443
+```
+
+Use `--funnel` to expose your dev server to the public internet via [Tailscale Funnel](https://tailscale.com/kb/1223/funnel/):
+
+```bash
+portless myapp --funnel next dev
+# -> https://devbox.yourteam.ts.net    (public)
+```
+
+Set `PORTLESS_TAILSCALE=1` in your shell profile or `.env` to share every app by default. `portless list` shows both local and tailnet URLs. Tailscale serve registrations are cleaned up automatically when the app exits.
+
+Requires the Tailscale CLI to be installed and connected (`tailscale up`).
+
 ## Commands
 
 ```bash
@@ -289,6 +317,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
 
@@ -320,6 +349,8 @@ portless proxy stop              # Stop the proxy
 --wildcard                       Allow unregistered subdomains to fall back to parent route
 --script <name>                  Run a specific package.json script (default: dev)
 --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
 --force                          Kill the existing process and take over its route
 --name <name>                    Use <name> as the app name
 ```
@@ -335,16 +366,19 @@ PORTLESS_LAN=1                   Enable LAN mode when set to 1 (auto-detects LAN
 PORTLESS_TLD=<tld>               Use a custom TLD (e.g. test; default: localhost)
 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)
+PORTLESS_FUNNEL=1                Share apps publicly via Tailscale Funnel (same as --funnel)
 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_TAILSCALE_URL           Tailscale URL of the app (when --tailscale is active)
 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
 
@@ -421,3 +455,4 @@ pnpm format           # Format all files with Prettier
 
 - Node.js 20+
 - macOS, Linux, or Windows
+- Tailscale CLI (optional, for `--tailscale` and `--funnel`)

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

@@ -846,13 +846,89 @@ var RouteStore = class _RouteStore {
         }
       }
       const filtered = routes.filter((r) => r.hostname !== hostname);
-      filtered.push({ hostname, port, pid });
+      const entry = { hostname, port, pid };
+      filtered.push(entry);
       this.saveRoutes(filtered);
     } finally {
       this.releaseLock();
     }
     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();
+    }
+  }
+  /**
+   * Update metadata on an existing route entry. Only provided fields are
+   * merged; the route must already exist (matched by hostname).
+   */
+  updateRoute(hostname, fields) {
+    this.ensureDir();
+    if (!this.acquireLock()) {
+      throw new Error("Failed to acquire route lock");
+    }
+    try {
+      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;
+      this.saveRoutes(routes);
+    } 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-3WLVQXFE.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -41,7 +41,7 @@ var colors_default = { bold, dim, red, green, yellow, blue, cyan, white, gray };
 // src/cli.ts
 import * as fs8 from "fs";
 import * as path8 from "path";
-import { spawn as spawn3, spawnSync as spawnSync2 } from "child_process";
+import { spawn as spawn3, spawnSync as spawnSync3 } from "child_process";
 import { StringDecoder } from "string_decoder";
 
 // src/certs.ts
@@ -754,6 +754,184 @@ function untrustCAWindows(caCertPath) {
   }
 }
 
+// src/tailscale.ts
+import { spawnSync } from "child_process";
+var TAILSCALE_BINARY = "tailscale";
+var PREFERRED_SERVE_PORTS = [443, 8443, 8444, 8445, 8446, 8447, 8448, 8449, 8450];
+var FUNNEL_PORTS = [443, 8443, 1e4];
+function defaultRunner(args) {
+  const result = spawnSync(TAILSCALE_BINARY, args, { encoding: "utf-8" });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    ...result.error ? { error: result.error } : {}
+  };
+}
+function trimDot(value) {
+  return value.endsWith(".") ? value.slice(0, -1) : value;
+}
+function normalizeSpace(value) {
+  return value.trim().replace(/\s+/g, " ");
+}
+function runOrThrow(args, action, runner) {
+  const result = runner(args);
+  if (result.error) {
+    const errno = result.error;
+    if (errno.code === "ENOENT") {
+      throw new Error(
+        "Tailscale CLI not found. Install Tailscale (https://tailscale.com/download) and ensure `tailscale` is on PATH."
+      );
+    }
+    throw new Error(`Failed to ${action}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const details = normalizeSpace(result.stderr || result.stdout);
+    throw new Error(`Failed to ${action}: ${details || "unknown tailscale error"}`);
+  }
+  return result;
+}
+function parseStatusJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error("Failed to parse `tailscale status --json` output.");
+  }
+}
+function statusToDnsName(status) {
+  const dnsName = status.Self?.DNSName;
+  if (typeof dnsName === "string" && dnsName.length > 0) {
+    return trimDot(dnsName);
+  }
+  const host = status.Self?.HostName;
+  const suffix = status.CurrentTailnet?.MagicDNSSuffix;
+  if (typeof host === "string" && host.length > 0 && typeof suffix === "string" && suffix.length > 0) {
+    return `${host}.${trimDot(suffix)}`;
+  }
+  throw new Error(
+    "Could not determine Tailscale node DNS name from `tailscale status --json`. Is Tailscale connected?"
+  );
+}
+function ensureTailscaleReady(runner = defaultRunner) {
+  runOrThrow(["version"], "check tailscale version", runner);
+  const statusResult = runOrThrow(["status", "--json"], "read tailscale status", runner);
+  const status = parseStatusJson(statusResult.stdout);
+  const dnsName = statusToDnsName(status);
+  return {
+    dnsName,
+    baseUrl: `https://${dnsName}`
+  };
+}
+function getUsedServePorts(runner = defaultRunner) {
+  const result = runner(["serve", "status", "--json"]);
+  if (result.error || result.status !== 0) {
+    return /* @__PURE__ */ new Set();
+  }
+  try {
+    const config = JSON.parse(result.stdout);
+    const ports = /* @__PURE__ */ new Set();
+    if (config.Web) {
+      for (const hostPort of Object.keys(config.Web)) {
+        const match = hostPort.match(/:(\d+)$/);
+        if (match) {
+          ports.add(parseInt(match[1], 10));
+        }
+      }
+    }
+    if (config.TCP) {
+      for (const portStr of Object.keys(config.TCP)) {
+        const p = parseInt(portStr, 10);
+        if (!isNaN(p)) ports.add(p);
+      }
+    }
+    return ports;
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function findAvailableServePort(usedPorts, mode = "serve") {
+  const pool = mode === "funnel" ? FUNNEL_PORTS : PREFERRED_SERVE_PORTS;
+  for (const port2 of pool) {
+    if (!usedPorts.has(port2)) return port2;
+  }
+  if (mode === "funnel") {
+    throw new Error(
+      "All Tailscale Funnel ports are in use (443, 8443, 10000). Stop an existing funnel to free a port."
+    );
+  }
+  let port = PREFERRED_SERVE_PORTS[PREFERRED_SERVE_PORTS.length - 1] + 1;
+  while (usedPorts.has(port)) port++;
+  return port;
+}
+function isConflictError(stderr, stdout) {
+  const text = `${stderr}
+${stdout}`.toLowerCase();
+  return text.includes("already in use") || text.includes("already exists") || text.includes("port conflict") || text.includes("address already");
+}
+var CONFLICT_MESSAGES = {
+  serve: "Stop the existing serve or let portless auto-assign a different port.",
+  funnel: "Tailscale Funnel supports ports 443, 8443, and 10000."
+};
+function register(mode, localPort, httpsPort, runner) {
+  const target = `http://127.0.0.1:${localPort}`;
+  const result = runner([mode, "--bg", "--yes", `--https=${httpsPort}`, target]);
+  if (result.error) {
+    const errno = result.error;
+    if (errno.code === "ENOENT") {
+      throw new Error(
+        "Tailscale CLI not found. Install Tailscale (https://tailscale.com/download) and ensure `tailscale` is on PATH."
+      );
+    }
+    throw new Error(`Failed to register tailscale ${mode}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    if (isConflictError(result.stderr, result.stdout)) {
+      throw new Error(
+        `Tailscale ${mode === "funnel" ? "Funnel " : ""}HTTPS port ${httpsPort} is already in use. ` + CONFLICT_MESSAGES[mode]
+      );
+    }
+    const details = normalizeSpace(result.stderr || result.stdout);
+    throw new Error(
+      `Failed to register tailscale ${mode} on port ${httpsPort}: ${details || "unknown tailscale error"}`
+    );
+  }
+}
+function unregister(mode, httpsPort, options) {
+  const runner = options?.runner ?? defaultRunner;
+  const result = runner([mode, "--yes", `--https=${httpsPort}`, "off"]);
+  if (result.error) {
+    const errno = result.error;
+    if (errno.code === "ENOENT") return;
+    throw new Error(`Failed to remove tailscale ${mode}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const text = `${result.stderr}
+${result.stdout}`.toLowerCase();
+    const looksLikeMissing = text.includes("not found") || text.includes("no serve config") || text.includes("nothing to remove") || text.includes("does not exist");
+    if (options?.ignoreMissing && looksLikeMissing) return;
+    const details = normalizeSpace(result.stderr || result.stdout);
+    throw new Error(
+      `Failed to remove tailscale ${mode} on port ${httpsPort}: ${details || "unknown tailscale error"}`
+    );
+  }
+}
+function registerServe(localPort, httpsPort, options) {
+  register("serve", localPort, httpsPort, options?.runner ?? defaultRunner);
+}
+function registerFunnel(localPort, httpsPort, options) {
+  register("funnel", localPort, httpsPort, options?.runner ?? defaultRunner);
+}
+function unregisterTailscale(route) {
+  if (!route.tailscaleHttpsPort) return;
+  const mode = route.tailscaleFunnel ? "funnel" : "serve";
+  unregister(mode, route.tailscaleHttpsPort, { ignoreMissing: true });
+}
+function formatTailscaleUrl(baseUrl, httpsPort) {
+  const trimmed = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  if (httpsPort === 443) return trimmed;
+  return `${trimmed}:${httpsPort}`;
+}
+
 // src/auto.ts
 import { createHash as createHash2 } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
@@ -1044,6 +1222,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 +1567,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 +1656,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 +1668,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));
   };
@@ -1585,7 +1800,7 @@ function removePortlessStateFiles(dir) {
 }
 
 // src/mdns.ts
-import { spawn as spawn2, spawnSync } from "child_process";
+import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 
 // src/lan-ip.ts
 import { createSocket } from "dgram";
@@ -1701,7 +1916,7 @@ function getMdnsPublisher() {
   return null;
 }
 function hasCommand(command, probeArgs) {
-  const result = spawnSync(command, probeArgs, {
+  const result = spawnSync2(command, probeArgs, {
     stdio: "ignore",
     timeout: 1e3,
     windowsHide: true
@@ -2482,7 +2697,7 @@ function collectPortlessEnvArgs() {
 function sudoStop(port) {
   const stopArgs = [process.execPath, getEntryScript(), "proxy", "stop", "-p", String(port)];
   console.log(colors_default.yellow("Proxy is running as root. Elevating with sudo to stop it..."));
-  const result = spawnSync2("sudo", ["env", ...collectPortlessEnvArgs(), ...stopArgs], {
+  const result = spawnSync3("sudo", ["env", ...collectPortlessEnvArgs(), ...stopArgs], {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
@@ -2822,6 +3037,10 @@ function listRoutes(store, proxyPort, tls2) {
     console.log(
       `  ${colors_default.cyan(url)}  ${colors_default.gray("->")}  ${colors_default.white(`localhost:${route.port}`)}  ${colors_default.gray(label)}`
     );
+    if (route.tailscaleUrl) {
+      const tsLabel = route.tailscaleFunnel ? "funnel" : "tailscale";
+      console.log(`    ${colors_default.gray(tsLabel + ":")} ${colors_default.green(route.tailscaleUrl)}`);
+    }
   }
   console.log();
 }
@@ -2905,7 +3124,7 @@ async function ensureProxyRunning(proxyPort, tls2, desired) {
     proxyPort: startPort
   });
   const startArgs = [getEntryScript(), "proxy", "start", ...proxyStartConfig.args];
-  const result = spawnSync2(process.execPath, startArgs, {
+  const result = spawnSync3(process.execPath, startArgs, {
     stdio: "inherit",
     timeout: SUDO_SPAWN_TIMEOUT_MS
   });
@@ -2939,6 +3158,25 @@ async function runApp(initialStore, proxyPort, stateDir, name, commandArgs, tls2
   console.log(chalk.blue.bold(`
 portless
 `));
+  const wantsFunnel = process.env.PORTLESS_FUNNEL === "1" || process.env.PORTLESS_FUNNEL === "true";
+  const wantsTailscale = wantsFunnel || process.env.PORTLESS_TAILSCALE === "1" || process.env.PORTLESS_TAILSCALE === "true";
+  let tsBaseUrl;
+  if (wantsTailscale) {
+    try {
+      const tsReady = ensureTailscaleReady();
+      tsBaseUrl = tsReady.baseUrl;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(colors_default.red(`Error: ${message}`));
+      if (message.includes("not found")) {
+        console.error(colors_default.blue("Install Tailscale: https://tailscale.com/download"));
+      } else {
+        console.error(colors_default.blue("Make sure Tailscale is connected:"));
+        console.error(colors_default.cyan("  tailscale up"));
+      }
+      process.exit(1);
+    }
+  }
   let desired;
   try {
     desired = resolveProxyDesiredState(lanMode);
@@ -3022,6 +3260,45 @@ portless
     console.log(chalk.green(`  LAN -> ${finalUrl}`));
     console.log(chalk.gray("  (accessible from other devices on the same WiFi network)\n"));
   }
+  let tailscaleHttpsPort;
+  let tailscaleUrl;
+  if (wantsTailscale && tsBaseUrl) {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const usedPorts = getUsedServePorts();
+      tailscaleHttpsPort = findAvailableServePort(usedPorts, wantsFunnel ? "funnel" : "serve");
+      try {
+        if (wantsFunnel) {
+          registerFunnel(port, tailscaleHttpsPort);
+        } else {
+          registerServe(port, tailscaleHttpsPort);
+        }
+        break;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isConflict = message.includes("already in use");
+        if (isConflict && attempt < maxAttempts) continue;
+        console.error(colors_default.red(`Error: ${message}`));
+        process.exit(1);
+      }
+    }
+    tailscaleUrl = formatTailscaleUrl(tsBaseUrl, tailscaleHttpsPort);
+    const label = wantsFunnel ? "Funnel (public)" : "Tailscale";
+    console.log(chalk.green(`  ${label} -> ${tailscaleUrl}`));
+    if (wantsFunnel) {
+      console.log(chalk.gray("  (accessible from the public internet via Tailscale Funnel)\n"));
+    } else {
+      console.log(chalk.gray("  (accessible from your tailnet)\n"));
+    }
+    try {
+      store.updateRoute(hostname, {
+        tailscaleUrl,
+        tailscaleHttpsPort,
+        tailscaleFunnel: wantsFunnel || void 0
+      });
+    } catch {
+    }
+  }
   const basename5 = path8.basename(commandArgs[0]);
   const isExpo = basename5 === "expo";
   const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
@@ -3055,9 +3332,17 @@ portless
       // baked-in pinging, making this env var ineffective. Expo handles its
       // own LAN discovery natively.
       ...lanMode ? { PORTLESS_LAN: "1" } : {},
+      ...tailscaleUrl ? { PORTLESS_TAILSCALE_URL: tailscaleUrl } : {},
       ...caEnv
     },
     onCleanup: () => {
+      try {
+        unregisterTailscale({
+          tailscaleHttpsPort,
+          tailscaleFunnel: wantsFunnel || void 0
+        });
+      } catch {
+      }
       try {
         store.removeRoute(hostname);
       } catch {
@@ -3087,6 +3372,18 @@ function appPortFromEnv() {
   }
   return port;
 }
+function applyTailscaleFlag(flag) {
+  if (flag === "--tailscale") {
+    process.env.PORTLESS_TAILSCALE = "1";
+    return true;
+  }
+  if (flag === "--funnel") {
+    process.env.PORTLESS_FUNNEL = "1";
+    process.env.PORTLESS_TAILSCALE = "1";
+    return true;
+  }
+  return false;
+}
 function parseRunArgs(args) {
   let force = false;
   let appPort;
@@ -3143,9 +3440,12 @@ ${colors_default.bold("Examples:")}
         process.exit(1);
       }
       name = args[i];
+    } else if (applyTailscaleFlag(args[i])) {
     } else {
       console.error(colors_default.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(colors_default.blue("Known flags: --name, --force, --app-port, --help"));
+      console.error(
+        colors_default.blue("Known flags: --name, --force, --app-port, --tailscale, --funnel, --help")
+      );
       process.exit(1);
     }
     i++;
@@ -3166,9 +3466,10 @@ function parseAppArgs(args) {
     } else if (args[i] === "--app-port") {
       i++;
       appPort = parseAppPort(args[i]);
+    } else if (applyTailscaleFlag(args[i])) {
     } else {
       console.error(colors_default.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(colors_default.blue("Known flags: --force, --app-port"));
+      console.error(colors_default.blue("Known flags: --force, --app-port, --tailscale, --funnel"));
       process.exit(1);
     }
     i++;
@@ -3184,9 +3485,10 @@ function parseAppArgs(args) {
     } else if (args[i] === "--app-port") {
       i++;
       appPort = parseAppPort(args[i]);
+    } else if (applyTailscaleFlag(args[i])) {
     } else {
       console.error(colors_default.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(colors_default.blue("Known flags: --force, --app-port"));
+      console.error(colors_default.blue("Known flags: --force, --app-port, --tailscale, --funnel"));
       process.exit(1);
     }
     i++;
@@ -3219,6 +3521,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}
 
@@ -3230,6 +3533,8 @@ ${colors_default.bold("Examples:")}
   portless run next dev               # -> https://<project>.localhost
   portless run next dev               # in worktree -> https://<worktree>.<project>.localhost
   portless get backend                # -> https://backend.localhost
+  portless myapp --tailscale next dev # -> also https://<node>.ts.net (tailnet)
+  portless myapp --funnel next dev    # -> also https://<node>.ts.net (public)
 
 ${colors_default.bold("Configuration (portless.json):")}
   Optional. Portless works out of the box by running the "dev" script
@@ -3280,6 +3585,15 @@ ${colors_default.bold("LAN mode:")}
   ${colors_default.cyan("portless proxy start --lan --https")}
   ${colors_default.cyan("portless proxy start --lan --ip 192.168.1.42")}
 
+${colors_default.bold("Tailscale sharing:")}
+  Use --tailscale to share your dev server with teammates on your tailnet.
+  Each app is root-mounted on its own Tailscale HTTPS port (443, then 8443,
+  8444, etc.) so no basePath configuration is needed.
+  Use --funnel to expose your dev server to the public internet via
+  Tailscale Funnel. Requires Tailscale CLI to be installed and connected.
+  ${colors_default.cyan("portless myapp --tailscale next dev")}
+  ${colors_default.cyan("portless myapp --funnel next dev")}
+
 ${colors_default.bold("Options:")}
   run [--name <name>] <cmd>      Infer project name (or override with --name)
                                 Adds worktree prefix in git worktrees
@@ -3296,6 +3610,8 @@ ${colors_default.bold("Options:")}
   --tld <tld>                   Use a custom TLD instead of .localhost (e.g. test, dev)
   --wildcard                    Allow unregistered subdomains to fall back to parent route
   --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
   --force                       Kill the existing process and take over its route
   --name <name>                 Use <name> as the app name (bypasses subcommand dispatch)
   --                            Stop flag parsing; everything after is passed to the child
@@ -3308,6 +3624,8 @@ ${colors_default.bold("Environment variables:")}
   PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
   PORTLESS_WILDCARD=1           Allow unregistered subdomains to fall back to parent route
   PORTLESS_SYNC_HOSTS=0         Disable auto-sync of ${HOSTS_DISPLAY} (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_STATE_DIR=<path>     Override the state directory
   PORTLESS=0                    Run command directly without proxy
 
@@ -3316,6 +3634,7 @@ ${colors_default.bold("Child process environment:")}
   HOST                          Usually 127.0.0.1 (omitted for Expo in LAN mode)
   PORTLESS_URL                  Public URL of the app (e.g. https://myapp.localhost)
   PORTLESS_LAN                  Set to 1 when proxy is in LAN mode
+  PORTLESS_TAILSCALE_URL        Tailscale URL of the app (when --tailscale is active)
   NODE_EXTRA_CA_CERTS           Path to the portless CA (set when HTTPS is active)
 
 ${colors_default.bold("Safari / DNS:")}
@@ -3331,14 +3650,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.12.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -3359,7 +3678,7 @@ async function handleTrust() {
   const isPermissionError = result.error?.includes("Permission denied") || result.error?.includes("EACCES");
   if (isPermissionError && !isWindows && process.getuid?.() !== 0) {
     console.log(colors_default.yellow("Trusting the CA requires elevated privileges. Requesting sudo..."));
-    const sudoResult = spawnSync2(
+    const sudoResult = spawnSync3(
       "sudo",
       [
         "env",
@@ -3415,6 +3734,16 @@ ${colors_default.bold("Options:")}
     onWarning: (msg) => console.warn(colors_default.yellow(msg))
   });
   await stopProxy(store, port, tls2);
+  const routesForClean = store.loadRoutesRaw();
+  for (const route of routesForClean) {
+    if (route.tailscaleHttpsPort) {
+      try {
+        unregisterTailscale(route);
+        console.log(colors_default.green(`Removed tailscale serve on port ${route.tailscaleHttpsPort}.`));
+      } catch {
+      }
+    }
+  }
   const stateDirs = collectStateDirsForCleanup();
   for (const stateDir of stateDirs) {
     const caPath = path8.join(stateDir, "ca.pem");
@@ -3443,7 +3772,7 @@ Try: sudo portless clean (Linux), or delete the certificate manually.`
     console.log(
       colors_default.yellow(`Updating ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
     );
-    const result = spawnSync2(
+    const result = spawnSync3(
       "sudo",
       ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "clean"],
       {
@@ -3464,6 +3793,74 @@ 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;
+  }
+  for (const route of stale) {
+    if (route.tailscaleHttpsPort) {
+      try {
+        unregisterTailscale(route);
+        console.log(
+          `  ${route.hostname} - removed tailscale serve on port ${route.tailscaleHttpsPort}`
+        );
+      } catch {
+      }
+    }
+  }
+  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, {
@@ -3614,7 +4011,7 @@ ${colors_default.bold("Auto-sync:")}
           `Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`
         )
       );
-      const result = spawnSync2(
+      const result = spawnSync3(
         "sudo",
         ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "clean"],
         {
@@ -3667,7 +4064,7 @@ ${colors_default.bold("Usage: portless hosts <command>")}
     console.log(
       colors_default.yellow(`Writing to ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
     );
-    const result = spawnSync2(
+    const result = spawnSync3(
       "sudo",
       ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "hosts", "sync"],
       {
@@ -3958,7 +4355,7 @@ ${colors_default.bold("LAN mode (--lan):")}
     if (!hasExplicitPort) {
       console.log(colors_default.gray(`(To skip sudo, use an unprivileged port: ${fallbackCommand})`));
     }
-    const result = spawnSync2("sudo", ["env", ...collectPortlessEnvArgs(), ...startArgs], {
+    const result = spawnSync3("sudo", ["env", ...collectPortlessEnvArgs(), ...startArgs], {
       stdio: "inherit",
       timeout: SUDO_SPAWN_TIMEOUT_MS
     });
@@ -4207,7 +4604,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 +4878,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 +4947,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();
@@ -4740,6 +5127,13 @@ async function main() {
     process.env[INTERNAL_LAN_IP_ENV] = autoIpResult;
     process.env.PORTLESS_LAN = "1";
   }
+  if (stripGlobalFlag("--tailscale", false)) {
+    process.env.PORTLESS_TAILSCALE = "1";
+  }
+  if (stripGlobalFlag("--funnel", false)) {
+    process.env.PORTLESS_FUNNEL = "1";
+    process.env.PORTLESS_TAILSCALE = "1";
+  }
   const scriptResult = stripGlobalFlag("--script", true);
   if (scriptResult === false) {
     console.error(colors_default.red("Error: --script requires a script name."));
@@ -4812,6 +5206,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

@@ -61,6 +61,9 @@ declare const FILE_MODE = 420;
 declare const DIR_MODE = 493;
 interface RouteMapping extends RouteInfo {
     pid: number;
+    tailscaleUrl?: string;
+    tailscaleHttpsPort?: number;
+    tailscaleFunnel?: boolean;
 }
 /**
  * Thrown when a route is already registered by a live process and --force was
@@ -108,6 +111,22 @@ 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[];
+    /**
+     * Update metadata on an existing route entry. Only provided fields are
+     * merged; the route must already exist (matched by hostname).
+     */
+    updateRoute(hostname: string, fields: Partial<Pick<RouteMapping, "tailscaleUrl" | "tailscaleHttpsPort" | "tailscaleFunnel">>): void;
     removeRoute(hostname: string): void;
 }
 

package/dist/index.js

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

package/package.json

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