portless 0.8.0 → 0.9.1

package/README.md

@@ -9,26 +9,29 @@ Replace port numbers with stable, named .localhost URLs for local development. F
 
 ## Install
 
+**Global (recommended):**
+
 ```bash
 npm install -g portless
 ```
 
-> Install globally. Do not add as a project dependency or run via npx.
+**Or as a project dev dependency:**
+
+```bash
+npm install -D portless
+```
+
+> portless is pre-1.0. When installed per-project, different contributors may run different versions. The state directory format may change between releases, which can require re-running `portless trust`.
 
 ## Run your app
 
 ```bash
-# Enable HTTPS (one-time setup, auto-generates certs)
-portless proxy start --https
-
 portless myapp next dev
 # -> https://myapp.localhost
-
-# Without --https, runs on port 1355
-portless myapp next dev
-# -> http://myapp.localhost:1355
 ```
 
+HTTPS with HTTP/2 is enabled by default. On first run, portless generates a local CA, trusts it, and binds port 443 (auto-elevates with sudo on macOS/Linux). Use `--no-tls` for plain HTTP.
+
 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, Astro, React Router, Angular, Expo, React Native), portless auto-injects `--port` and `--host` flags.
 
 ## Use in package.json
@@ -47,45 +50,45 @@ Organize services with subdomains:
 
 ```bash
 portless api.myapp pnpm start
-# -> http://api.myapp.localhost:1355
+# -> https://api.myapp.localhost
 
 portless docs.myapp next dev
-# -> http://docs.myapp.localhost:1355
+# -> https://docs.myapp.localhost
 ```
 
-By default, only explicitly registered subdomains are routed (strict mode). Use `--wildcard` when starting the proxy to allow any subdomain of a registered route to fall back to that app (e.g. `tenant1.myapp.localhost:1355` routes to the `myapp` app without extra registration).
+By default, only explicitly registered subdomains are routed (strict mode). Use `--wildcard` when starting the proxy to allow any subdomain of a registered route to fall back to that app (e.g. `tenant1.myapp.localhost` routes to the `myapp` app without extra registration).
 
 ## Git Worktrees
 
 `portless run` automatically detects git worktrees. In a linked worktree, the branch name is prepended as a subdomain so each worktree gets its own URL without any config changes:
 
 ```bash
-# Main worktree -- no prefix
-portless run next dev   # -> http://myapp.localhost:1355
+# Main worktree (no prefix)
+portless run next dev   # -> https://myapp.localhost
 
 # Linked worktree on branch "fix-ui"
-portless run next dev   # -> http://fix-ui.myapp.localhost:1355
+portless run next dev   # -> https://fix-ui.myapp.localhost
 ```
 
 Use `--name` to override the inferred base name while keeping the worktree prefix:
 
 ```bash
-portless run --name myapp next dev   # -> http://fix-ui.myapp.localhost:1355
+portless run --name myapp next dev   # -> https://fix-ui.myapp.localhost
 ```
 
-Put `portless run` in your `package.json` once and it works everywhere -- the main checkout uses the plain name, each worktree gets a unique subdomain. No collisions, no `--force`.
+Put `portless run` in your `package.json` once and it works everywhere. The main checkout uses the plain name, each worktree gets a unique subdomain. No collisions, no `--force`.
 
 ## Custom TLD
 
 By default, portless uses `.localhost` which auto-resolves to `127.0.0.1` in most browsers. If you prefer a different TLD (e.g. `.test`), use `--tld`:
 
 ```bash
-sudo portless proxy start --https --tld test
+portless proxy start --tld test
 portless myapp next dev
 # -> https://myapp.test
 ```
 
-The proxy auto-syncs `/etc/hosts` for custom TLDs when started with sudo, so `.test` domains resolve correctly.
+The proxy auto-syncs `/etc/hosts` for custom TLDs, so `.test` domains resolve correctly.
 
 Recommended: `.test` (IANA-reserved, no collision risk). Avoid `.local` (conflicts with mDNS/Bonjour) and `.dev` (Google-owned, forces HTTPS via HSTS).
 
@@ -93,40 +96,35 @@ Recommended: `.test` (IANA-reserved, no collision risk). Avoid `.local` (conflic
 
 ```mermaid
 flowchart TD
-    Browser["Browser<br>myapp.localhost:1355"]
-    Proxy["portless proxy<br>(port 1355)"]
+    Browser["Browser<br>myapp.localhost"]
+    Proxy["portless proxy<br>(port 80 or 443)"]
     App1[":4123<br>myapp"]
     App2[":4567<br>api"]
 
-    Browser -->|port 1355| Proxy
+    Browser --> Proxy
     Proxy --> App1
     Proxy --> App2
 ```
 
-1. **Start the proxy** -- auto-starts when you run an app, or start explicitly with `portless proxy start`
-2. **Run apps** -- `portless <name> <command>` assigns a free port and registers with the proxy
-3. **Access via URL** -- `http://<name>.localhost:1355` routes through the proxy to your app
+1. **Start the proxy**: auto-starts when you run an app, or start explicitly with `portless proxy start`
+2. **Run apps**: `portless <name> <command>` assigns a free port and registers with the proxy
+3. **Access via URL**: `https://<name>.localhost` routes through the proxy to your app
 
 ## HTTP/2 + HTTPS
 
-Enable HTTP/2 for faster dev server page loads. Browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files (Vite, Nuxt, etc.). HTTP/2 multiplexes all requests over a single connection.
-
-```bash
-# Start with HTTPS/2 -- generates certs and trusts them automatically
-portless proxy start --https
-
-# First run prompts for sudo once to add the CA to your system trust store.
-# After that, no prompts. No browser warnings.
+HTTPS with HTTP/2 is enabled by default. Browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files (Vite, Nuxt, etc.). HTTP/2 multiplexes all requests over a single connection.
 
-# Make it permanent (add to .bashrc / .zshrc)
-export PORTLESS_HTTPS=1
-portless proxy start    # HTTPS by default now
+On first run, portless generates a local CA and adds it to your system trust store. No browser warnings. No manual setup.
 
+```bash
 # Use your own certs (e.g., from mkcert)
 portless proxy start --cert ./cert.pem --key ./key.pem
 
-# If you skipped sudo on first run, trust the CA later
-sudo portless trust
+# Disable HTTPS (plain HTTP on port 80)
+portless proxy start --no-tls
+
+# If you skipped the trust prompt on first run, trust the CA later
+portless trust
 ```
 
 On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store.
@@ -135,7 +133,7 @@ On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and
 
 ```bash
 portless run [--name <name>] <cmd> [args...]  # Infer name (or override with --name), run through proxy
-portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
+portless <name> <cmd> [args...]  # Run app at https://<name>.localhost
 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
@@ -148,9 +146,9 @@ portless hosts clean             # Remove portless entries from /etc/hosts
 PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 
 # Proxy control
-portless proxy start             # Start the proxy (port 1355, daemon)
-portless proxy start --https     # Start with HTTP/2 + TLS
-portless proxy start -p 80       # Start on port 80 (requires sudo)
+portless proxy start             # Start the HTTPS proxy (port 443, daemon)
+portless proxy start --no-tls    # Start without HTTPS (port 80)
+portless proxy start -p 1355     # Start on a custom port (no sudo)
 portless proxy start --foreground  # Start in foreground (for debugging)
 portless proxy start --wildcard  # Allow unregistered subdomains to fall back to parent
 portless proxy stop              # Stop the proxy
@@ -159,11 +157,11 @@ portless proxy stop              # Stop the proxy
 ### Options
 
 ```
--p, --port <number>              Port for the proxy (default: 1355)
---https                          Enable HTTP/2 + TLS with auto-generated certs
---cert <path>                    Use a custom TLS certificate (implies --https)
---key <path>                     Use a custom TLS private key (implies --https)
---no-tls                         Disable HTTPS (overrides PORTLESS_HTTPS)
+-p, --port <number>              Port for the proxy (default: 443, or 80 with --no-tls)
+--no-tls                         Disable HTTPS (use plain HTTP on port 80)
+--https                          Enable HTTPS (default, accepted for compatibility)
+--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)
 --wildcard                       Allow unregistered subdomains to fall back to parent route
@@ -178,7 +176,7 @@ portless proxy stop              # Stop the proxy
 # Configuration
 PORTLESS_PORT=<number>           Override the default proxy port
 PORTLESS_APP_PORT=<number>       Use a fixed port for the app (same as --app-port)
-PORTLESS_HTTPS=1                 Always enable HTTPS
+PORTLESS_HTTPS                   HTTPS on by default; set to 0 to disable (same as --no-tls)
 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=1            Auto-sync /etc/hosts (auto-enabled for custom TLDs)
@@ -199,8 +197,8 @@ PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
 If Safari can't find your `.localhost` URL:
 
 ```bash
-sudo portless hosts sync    # Add current routes to /etc/hosts
-sudo portless hosts clean   # Clean up later
+portless hosts sync    # Add current routes to /etc/hosts
+portless hosts clean   # Clean up later
 ```
 
 Auto-syncs `/etc/hosts` for custom TLDs (e.g. `--tld test`). For `.localhost`, set `PORTLESS_SYNC_HOSTS=1` to enable. Disable with `PORTLESS_SYNC_HOSTS=0`.
@@ -215,7 +213,7 @@ If your frontend dev server (e.g. Vite, webpack) proxies API requests to another
 server: {
   proxy: {
     "/api": {
-      target: "http://api.myapp.localhost:1355",
+      target: "https://api.myapp.localhost",
       changeOrigin: true,
       ws: true,
     },
@@ -229,12 +227,14 @@ server: {
 devServer: {
   proxy: [{
     context: ["/api"],
-    target: "http://api.myapp.localhost:1355",
+    target: "https://api.myapp.localhost",
     changeOrigin: true,
   }],
 }
 ```
 
+If your tooling doesn't trust the portless CA, point Node.js at it: `NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem` (or `~/.portless/ca.pem` when the proxy runs on a non-privileged port like 1355). Alternatively, use `--no-tls` for plain HTTP.
+
 Portless detects this misconfiguration and responds with `508 Loop Detected` along with a message pointing to this fix.
 
 ## Development

package/dist/{chunk-KKXL2CMI.js → chunk-5BR7NCNI.js}

@@ -286,6 +286,9 @@ function getRequestHost(req) {
   if (typeof authority === "string" && authority) return authority;
   return req.headers.host || "";
 }
+function isEncrypted(req) {
+  return !!req.socket.encrypted;
+}
 function buildForwardedHeaders(req, tls) {
   const headers = {};
   const remoteAddress = req.socket.remoteAddress || "127.0.0.1";
@@ -313,8 +316,8 @@ function createProxyServer(options) {
     tls
   } = options;
   const tldSuffix = `.${tld}`;
-  const isTls = !!tls;
   const handleRequest = (req, res) => {
+    const reqTls = isEncrypted(req);
     res.setHeader(PORTLESS_HEADER, "1");
     const routes = getRoutes();
     const host = getRequestHost(req).split(":")[0];
@@ -335,7 +338,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: "http://&lt;backend&gt;${escapeHtml(tldSuffix)}:&lt;port&gt;",
+    target: "${reqTls ? "https" : "http"}://&lt;backend&gt;${escapeHtml(tldSuffix)}${reqTls ? "" : ":&lt;port&gt;"}",
     changeOrigin: true,
   },
 }</pre></div></div>`
@@ -348,7 +351,7 @@ function createProxyServer(options) {
       const safeHost = escapeHtml(host);
       const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.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, isTls))}" 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>';
+      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" });
       res.end(
         renderPage(
@@ -359,7 +362,7 @@ function createProxyServer(options) {
       );
       return;
     }
-    const forwardedHeaders = buildForwardedHeaders(req, isTls);
+    const forwardedHeaders = buildForwardedHeaders(req, reqTls);
     const proxyReqHeaders = { ...req.headers };
     for (const [key, value] of Object.entries(forwardedHeaders)) {
       proxyReqHeaders[key] = value;
@@ -380,7 +383,7 @@ function createProxyServer(options) {
       },
       (proxyRes) => {
         const responseHeaders = { ...proxyRes.headers };
-        if (isTls) {
+        if (reqTls) {
           for (const h of HOP_BY_HOP_HEADERS) {
             delete responseHeaders[h];
           }
@@ -442,7 +445,7 @@ function createProxyServer(options) {
       socket.destroy();
       return;
     }
-    const forwardedHeaders = buildForwardedHeaders(req, isTls);
+    const forwardedHeaders = buildForwardedHeaders(req, isEncrypted(req));
     const proxyReqHeaders = { ...req.headers };
     for (const [key, value] of Object.entries(forwardedHeaders)) {
       proxyReqHeaders[key] = value;
@@ -513,8 +516,19 @@ function createProxyServer(options) {
     h2Server.on("upgrade", (req, socket, head) => {
       handleUpgrade(req, socket, head);
     });
-    const plainServer = http.createServer(handleRequest);
-    plainServer.on("upgrade", handleUpgrade);
+    const plainServer = http.createServer((req, res) => {
+      const host = getRequestHost(req).split(":")[0] || "localhost";
+      const location = `https://${host}${proxyPort === 443 ? "" : `:${proxyPort}`}${req.url || "/"}`;
+      res.writeHead(302, { Location: location, [PORTLESS_HEADER]: "1" });
+      res.end();
+    });
+    plainServer.on("upgrade", (req, socket) => {
+      const host = getRequestHost(req);
+      console.warn(
+        `[portless] Dropped plain-HTTP WebSocket upgrade for ${host}; use wss:// instead`
+      );
+      socket.destroy();
+    });
     const wrapper = net.createServer((socket) => {
       socket.on("error", () => {
         socket.destroy();
@@ -545,6 +559,15 @@ function createProxyServer(options) {
   httpServer.on("upgrade", handleUpgrade);
   return httpServer;
 }
+function createHttpRedirectServer(httpsPort) {
+  return http.createServer((req, res) => {
+    const host = (req.headers.host || "localhost").split(":")[0];
+    const portSuffix = httpsPort === 443 ? "" : `:${httpsPort}`;
+    const location = `https://${host}${portSuffix}${req.url || "/"}`;
+    res.writeHead(302, { Location: location, [PORTLESS_HEADER]: "1" });
+    res.end();
+  });
+}
 
 // src/hosts.ts
 import * as fs2 from "fs";
@@ -637,7 +660,7 @@ import * as path2 from "path";
 import * as readline from "readline";
 import { execSync, spawn } from "child_process";
 var isWindows2 = process.platform === "win32";
-var DEFAULT_PROXY_PORT = 1355;
+var FALLBACK_PROXY_PORT = 1355;
 var PRIVILEGED_PORT_THRESHOLD = 1024;
 var SYSTEM_STATE_DIR = isWindows2 ? path2.join(os.tmpdir(), "portless") : "/tmp/portless";
 var USER_STATE_DIR = path2.join(os.homedir(), ".portless");
@@ -656,13 +679,16 @@ var SIGNAL_CODES = {
   SIGKILL: 9,
   SIGTERM: 15
 };
-function getDefaultPort() {
+function getProtocolPort(tls) {
+  return tls ? 443 : 80;
+}
+function getDefaultPort(tls) {
   const envPort = process.env.PORTLESS_PORT;
   if (envPort) {
     const port = parseInt(envPort, 10);
     if (!isNaN(port) && port >= 1 && port <= 65535) return port;
   }
-  return DEFAULT_PROXY_PORT;
+  return tls === void 0 ? FALLBACK_PROXY_PORT : getProtocolPort(tls);
 }
 function resolveStateDir(port) {
   if (process.env.PORTLESS_STATE_DIR) return process.env.PORTLESS_STATE_DIR;
@@ -701,15 +727,15 @@ var DEFAULT_TLD = "localhost";
 var RISKY_TLDS = /* @__PURE__ */ new Map([
   ["local", "conflicts with mDNS/Bonjour on macOS"],
   ["dev", "Google-owned; browsers force HTTPS via preloaded HSTS"],
-  ["com", "public TLD -- DNS requests will leak to the internet"],
-  ["org", "public TLD -- DNS requests will leak to the internet"],
-  ["net", "public TLD -- DNS requests will leak to the internet"],
-  ["io", "public TLD -- DNS requests will leak to the internet"],
-  ["app", "public TLD -- DNS requests will leak to the internet"],
-  ["edu", "public TLD -- DNS requests will leak to the internet"],
-  ["gov", "public TLD -- DNS requests will leak to the internet"],
-  ["mil", "public TLD -- DNS requests will leak to the internet"],
-  ["int", "public TLD -- DNS requests will leak to the internet"]
+  ["com", "public TLD; DNS requests will leak to the internet"],
+  ["org", "public TLD; DNS requests will leak to the internet"],
+  ["net", "public TLD; DNS requests will leak to the internet"],
+  ["io", "public TLD; DNS requests will leak to the internet"],
+  ["app", "public TLD; DNS requests will leak to the internet"],
+  ["edu", "public TLD; DNS requests will leak to the internet"],
+  ["gov", "public TLD; DNS requests will leak to the internet"],
+  ["mil", "public TLD; DNS requests will leak to the internet"],
+  ["int", "public TLD; DNS requests will leak to the internet"]
 ]);
 function validateTld(tld) {
   if (!tld) return "TLD cannot be empty";
@@ -745,9 +771,9 @@ function getDefaultTld() {
   if (err) throw new Error(`PORTLESS_TLD: ${err}`);
   return val;
 }
-function isHttpsEnvEnabled() {
+function isHttpsEnvDisabled() {
   const val = process.env.PORTLESS_HTTPS;
-  return val === "1" || val === "true";
+  return val === "0" || val === "false";
 }
 function isWildcardEnvEnabled() {
   const val = process.env.PORTLESS_WILDCARD;
@@ -777,8 +803,8 @@ async function discoverState() {
       return { dir: SYSTEM_STATE_DIR, port: systemPort, tls, tld };
     }
   }
-  const defaultPort = getDefaultPort();
-  const probePorts = /* @__PURE__ */ new Set([defaultPort, 443, 80]);
+  const configuredPort = getDefaultPort();
+  const probePorts = /* @__PURE__ */ new Set([443, 80, FALLBACK_PROXY_PORT, configuredPort]);
   for (const port of probePorts) {
     if (await isProxyRunning(port)) {
       const dir = resolveStateDir(port);
@@ -787,7 +813,12 @@ async function discoverState() {
       return { dir, port, tls, tld };
     }
   }
-  return { dir: resolveStateDir(defaultPort), port: defaultPort, tls: false, tld: getDefaultTld() };
+  return {
+    dir: resolveStateDir(configuredPort),
+    port: configuredPort,
+    tls: false,
+    tld: getDefaultTld()
+  };
 }
 async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
   if (minPort > maxPort) {
@@ -1093,7 +1124,8 @@ var RouteStore = class _RouteStore {
   getRoutesPath() {
     return this.routesPath;
   }
-  // -- Locking ---------------------------------------------------------------
+  // Locking
+  // ---------------------------------------------------------------------------
   static sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
   syncSleep(ms) {
     Atomics.wait(_RouteStore.sleepBuffer, 0, 0, ms);
@@ -1128,7 +1160,8 @@ var RouteStore = class _RouteStore {
     } catch {
     }
   }
-  // -- Route I/O -------------------------------------------------------------
+  // Route I/O
+  // ---------------------------------------------------------------------------
   isProcessAlive(pid) {
     try {
       process.kill(pid, 0);
@@ -1219,6 +1252,7 @@ export {
   parseHostname,
   PORTLESS_HEADER,
   createProxyServer,
+  createHttpRedirectServer,
   extractManagedBlock,
   removeBlock,
   buildBlock,
@@ -1227,18 +1261,20 @@ export {
   getManagedHostnames,
   checkHostResolution,
   isWindows2 as isWindows,
+  FALLBACK_PROXY_PORT,
   PRIVILEGED_PORT_THRESHOLD,
+  WAIT_FOR_PROXY_MAX_ATTEMPTS,
+  WAIT_FOR_PROXY_INTERVAL_MS,
+  getProtocolPort,
   getDefaultPort,
   resolveStateDir,
-  readTlsMarker,
   writeTlsMarker,
   DEFAULT_TLD,
   RISKY_TLDS,
   validateTld,
-  readTldFromDir,
   writeTldFile,
   getDefaultTld,
-  isHttpsEnvEnabled,
+  isHttpsEnvDisabled,
   isWildcardEnvEnabled,
   discoverState,
   findFreePort,