portless 0.2.1 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Replace port numbers with stable, named .localhost URLs. For humans and agents.
 
 ```diff
 - "dev": "next dev"              # http://localhost:3000
-+ "dev": "portless myapp next dev"  # http://myapp.localhost
++ "dev": "portless myapp next dev"  # http://myapp.localhost:1355
 ```
 
 ## Quick Start
@@ -13,29 +13,29 @@ Replace port numbers with stable, named .localhost URLs. For humans and agents.
 # Install
 npm install -g portless
 
-# Start the proxy (once, requires sudo for port 80)
-sudo portless proxy
+# Start the proxy (once, no sudo needed)
+portless proxy start
 
-# Run your app
+# Run your app (auto-starts the proxy if needed)
 portless myapp next dev
-# → http://myapp.localhost
+# -> http://myapp.localhost:1355
 ```
 
-> When run directly in your terminal, portless can auto-start the proxy for you (prompts for sudo once). Via package scripts, start the proxy manually first.
+> The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`.
 
 ## Why
 
 Local dev with port numbers is fragile:
 
-- **Port conflicts** — two projects default to the same port and you get `EADDRINUSE`
-- **Memorizing ports** — was the API on 3001 or 8080?
-- **Refreshing shows the wrong app** — stop one server, start another on the same port, and your open tab now shows something completely different
-- **Monorepo multiplier** — every problem above scales with each service in the repo
-- **Agents test the wrong port** — AI coding agents guess or hardcode the wrong port, especially in monorepos
-- **Cookie and storage clashes** — cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
-- **Hardcoded ports in config** — CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
-- **Sharing URLs with teammates** — "what port is that on?" becomes a Slack question
-- **Browser history is useless** — your history for `localhost:3000` is a jumble of unrelated projects
+- **Port conflicts** -- two projects default to the same port and you get `EADDRINUSE`
+- **Memorizing ports** -- was the API on 3001 or 8080?
+- **Refreshing shows the wrong app** -- stop one server, start another on the same port, and your open tab now shows something completely different
+- **Monorepo multiplier** -- every problem above scales with each service in the repo
+- **Agents test the wrong port** -- AI coding agents guess or hardcode the wrong port, especially in monorepos
+- **Cookie and storage clashes** -- cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
+- **Hardcoded ports in config** -- CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
+- **Sharing URLs with teammates** -- "what port is that on?" becomes a Slack question
+- **Browser history is useless** -- your history for `localhost:3000` is a jumble of unrelated projects
 
 Portless fixes all of this by giving each dev server a stable, named `.localhost` URL that both humans and agents can rely on.
 
@@ -44,14 +44,14 @@ Portless fixes all of this by giving each dev server a stable, named `.localhost
 ```bash
 # Basic
 portless myapp next dev
-# → http://myapp.localhost
+# -> http://myapp.localhost:1355
 
 # Subdomains
 portless api.myapp pnpm start
-# → http://api.myapp.localhost
+# -> http://api.myapp.localhost:1355
 
 portless docs.myapp next dev
-# → http://docs.myapp.localhost
+# -> http://docs.myapp.localhost:1355
 ```
 
 ### In package.json
@@ -64,32 +64,32 @@ portless docs.myapp next dev
 }
 ```
 
-Start the proxy once (`sudo portless proxy`), then just `pnpm dev`.
+The proxy auto-starts when you run an app. Or start it explicitly: `portless proxy start`.
 
 ## How It Works
 
 ```mermaid
 flowchart TD
-    Browser["Browser\nmyapp.localhost"]
-    Proxy["portless proxy\n(port 80)"]
+    Browser["Browser\nmyapp.localhost:1355"]
+    Proxy["portless proxy\n(port 1355)"]
     App1[":4123\nmyapp"]
     App2[":4567\napi"]
 
-    Browser -->|port 80| Proxy
+    Browser -->|port 1355| Proxy
     Proxy --> App1
     Proxy --> App2
 ```
 
-1. **Start the proxy** -- runs on port 80 by default in the background (requires sudo once)
+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` routes through the proxy to your app
+3. **Access via URL** -- `http://<name>.localhost:1355` routes through the proxy to your app
 
 Apps are assigned a random port (4000-4999) via the `PORT` environment variable. Most frameworks (Next.js, Vite, etc.) respect this automatically.
 
 ## Commands
 
 ```bash
-portless <name> <cmd> [args...]  # Run app at http://<name>.localhost
+portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
 portless list                    # Show active routes
 
 # Disable portless (run command directly)
@@ -97,19 +97,34 @@ PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 # Also accepts PORTLESS=skip
 
 # Proxy control
-sudo portless proxy              # Start the proxy (port 80)
-sudo portless proxy --port 8080  # Start the proxy on a custom port
-sudo portless proxy stop         # Stop the proxy
+portless proxy start             # Start the proxy (port 1355, daemon)
+portless proxy start -p 80       # Start on port 80 (requires sudo)
+portless proxy start --foreground  # Start in foreground (for debugging)
+portless proxy stop              # Stop the proxy
 
 # Options
---port <number>                  # Port for the proxy (default: 80)
-                                 # Ports >= 1024 do not require sudo
+-p, --port <number>              # Port for the proxy (default: 1355)
+                                 # Ports < 1024 require sudo
+--foreground                     # Run proxy in foreground instead of daemon
+
+# Environment variables
+PORTLESS_PORT=<number>           # Override the default proxy port
+PORTLESS_STATE_DIR=<path>        # Override the state directory
 
 # Info
 portless --help                  # Show help
 portless --version               # Show version
 ```
 
+## State Directory
+
+Portless stores its state (routes, PID file, port file) in a directory that depends on the proxy port:
+
+- **Port < 1024** (sudo required): `/tmp/portless` -- shared between root and user processes
+- **Port >= 1024** (no sudo): `~/.portless` -- user-scoped, no root involvement
+
+Override with the `PORTLESS_STATE_DIR` environment variable if needed.
+
 ## Requirements
 
 - Node.js 20+

package/dist/{chunk-SE7KL62V.js → chunk-Y5OVKUR4.js}

@@ -1,10 +1,13 @@
 // src/utils.ts
 function isErrnoException(err) {
-  return err instanceof Error && "code" in err;
+  return err instanceof Error && "code" in err && typeof err.code === "string";
 }
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+function formatUrl(hostname, proxyPort) {
+  return proxyPort === 80 ? `http://${hostname}` : `http://${hostname}:${proxyPort}`;
+}
 function parseHostname(input) {
   let hostname = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
   if (!hostname || hostname === ".localhost") {
@@ -27,23 +30,22 @@ function parseHostname(input) {
 
 // src/proxy.ts
 import * as http from "http";
-import httpProxy from "http-proxy";
+var PORTLESS_HEADER = "X-Portless";
+function buildForwardedHeaders(req) {
+  const headers = {};
+  const remoteAddress = req.socket.remoteAddress || "127.0.0.1";
+  const proto = "http";
+  const hostHeader = req.headers.host || "";
+  headers["x-forwarded-for"] = req.headers["x-forwarded-for"] ? `${req.headers["x-forwarded-for"]}, ${remoteAddress}` : remoteAddress;
+  headers["x-forwarded-proto"] = req.headers["x-forwarded-proto"] || proto;
+  headers["x-forwarded-host"] = req.headers["x-forwarded-host"] || hostHeader;
+  headers["x-forwarded-port"] = req.headers["x-forwarded-port"] || hostHeader.split(":")[1] || "80";
+  return headers;
+}
 function createProxyServer(options) {
-  const { getRoutes, onError = (msg) => console.error(msg) } = options;
-  const proxy = httpProxy.createProxyServer({});
-  proxy.on("error", (err, req, res) => {
-    onError(`Proxy error for ${req.headers.host}: ${err.message}`);
-    if (res && "writeHead" in res) {
-      const serverRes = res;
-      if (!serverRes.headersSent) {
-        const errWithCode = err;
-        const message = errWithCode.code === "ECONNREFUSED" ? "Bad Gateway: the target app is not responding. It may have crashed." : "Bad Gateway: the target app may not be running.";
-        serverRes.writeHead(502, { "Content-Type": "text/plain" });
-        serverRes.end(message);
-      }
-    }
-  });
+  const { getRoutes, proxyPort, onError = (msg) => console.error(msg) } = options;
   const handleRequest = (req, res) => {
+    res.setHeader(PORTLESS_HEADER, "1");
     const routes = getRoutes();
     const host = (req.headers.host || "").split(":")[0];
     if (!host) {
@@ -64,7 +66,7 @@ function createProxyServer(options) {
             ${routes.length > 0 ? `
               <h2>Active apps:</h2>
               <ul>
-                ${routes.map((r) => `<li><a href="http://${escapeHtml(r.hostname)}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
+                ${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort))}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
               </ul>
             ` : "<p><em>No apps running.</em></p>"}
             <p>Start an app with: <code>portless ${safeHost.replace(".localhost", "")} your-command</code></p>
@@ -73,10 +75,44 @@ function createProxyServer(options) {
       `);
       return;
     }
-    proxy.web(req, res, {
-      target: `http://127.0.0.1:${route.port}`,
-      xfwd: true
+    const forwardedHeaders = buildForwardedHeaders(req);
+    const proxyReqHeaders = { ...req.headers };
+    for (const [key, value] of Object.entries(forwardedHeaders)) {
+      proxyReqHeaders[key] = value;
+    }
+    const proxyReq = http.request(
+      {
+        hostname: "127.0.0.1",
+        port: route.port,
+        path: req.url,
+        method: req.method,
+        headers: proxyReqHeaders
+      },
+      (proxyRes) => {
+        res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
+        proxyRes.pipe(res);
+      }
+    );
+    proxyReq.on("error", (err) => {
+      onError(`Proxy error for ${req.headers.host}: ${err.message}`);
+      if (!res.headersSent) {
+        const errWithCode = err;
+        const message = errWithCode.code === "ECONNREFUSED" ? "Bad Gateway: the target app is not responding. It may have crashed." : "Bad Gateway: the target app may not be running.";
+        res.writeHead(502, { "Content-Type": "text/plain" });
+        res.end(message);
+      }
+    });
+    res.on("close", () => {
+      if (!proxyReq.destroyed) {
+        proxyReq.destroy();
+      }
     });
+    req.on("error", () => {
+      if (!proxyReq.destroyed) {
+        proxyReq.destroy();
+      }
+    });
+    req.pipe(proxyReq);
   };
   const handleUpgrade = (req, socket, head) => {
     const routes = getRoutes();
@@ -86,10 +122,56 @@ function createProxyServer(options) {
       socket.destroy();
       return;
     }
-    proxy.ws(req, socket, head, {
-      target: `http://127.0.0.1:${route.port}`,
-      xfwd: true
+    const forwardedHeaders = buildForwardedHeaders(req);
+    const proxyReqHeaders = { ...req.headers };
+    for (const [key, value] of Object.entries(forwardedHeaders)) {
+      proxyReqHeaders[key] = value;
+    }
+    const proxyReq = http.request({
+      hostname: "127.0.0.1",
+      port: route.port,
+      path: req.url,
+      method: req.method,
+      headers: proxyReqHeaders
     });
+    proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => {
+      let response = `HTTP/1.1 101 Switching Protocols\r
+`;
+      for (let i = 0; i < proxyRes.rawHeaders.length; i += 2) {
+        response += `${proxyRes.rawHeaders[i]}: ${proxyRes.rawHeaders[i + 1]}\r
+`;
+      }
+      response += "\r\n";
+      socket.write(response);
+      if (proxyHead.length > 0) {
+        socket.write(proxyHead);
+      }
+      proxySocket.pipe(socket);
+      socket.pipe(proxySocket);
+      proxySocket.on("error", () => socket.destroy());
+      socket.on("error", () => proxySocket.destroy());
+    });
+    proxyReq.on("error", (err) => {
+      onError(`WebSocket proxy error for ${req.headers.host}: ${err.message}`);
+      socket.destroy();
+    });
+    proxyReq.on("response", (res) => {
+      if (!socket.destroyed) {
+        let response = `HTTP/1.1 ${res.statusCode} ${res.statusMessage}\r
+`;
+        for (let i = 0; i < res.rawHeaders.length; i += 2) {
+          response += `${res.rawHeaders[i]}: ${res.rawHeaders[i + 1]}\r
+`;
+        }
+        response += "\r\n";
+        socket.write(response);
+        res.pipe(socket);
+      }
+    });
+    if (head.length > 0) {
+      proxyReq.write(head);
+    }
+    proxyReq.end();
   };
   const httpServer = http.createServer(handleRequest);
   httpServer.on("upgrade", handleUpgrade);
@@ -99,6 +181,11 @@ function createProxyServer(options) {
 // src/routes.ts
 import * as fs from "fs";
 import * as path from "path";
+var STALE_LOCK_THRESHOLD_MS = 1e4;
+var LOCK_MAX_RETRIES = 20;
+var LOCK_RETRY_DELAY_MS = 50;
+var FILE_MODE = 420;
+var DIR_MODE = 493;
 function isValidRoute(value) {
   return typeof value === "object" && value !== null && typeof value.hostname === "string" && typeof value.port === "number" && typeof value.pid === "number";
 }
@@ -107,20 +194,22 @@ var RouteStore = class _RouteStore {
   routesPath;
   lockPath;
   pidPath;
+  portFilePath;
   onWarning;
   constructor(dir, options) {
     this.dir = dir;
     this.routesPath = path.join(dir, "routes.json");
     this.lockPath = path.join(dir, "routes.lock");
     this.pidPath = path.join(dir, "proxy.pid");
+    this.portFilePath = path.join(dir, "proxy.port");
     this.onWarning = options?.onWarning;
   }
   ensureDir() {
     if (!fs.existsSync(this.dir)) {
-      fs.mkdirSync(this.dir, { recursive: true, mode: 493 });
+      fs.mkdirSync(this.dir, { recursive: true, mode: DIR_MODE });
     }
     try {
-      fs.chmodSync(this.dir, 493);
+      fs.chmodSync(this.dir, DIR_MODE);
     } catch {
     }
   }
@@ -132,7 +221,7 @@ var RouteStore = class _RouteStore {
   syncSleep(ms) {
     Atomics.wait(_RouteStore.sleepBuffer, 0, 0, ms);
   }
-  acquireLock(maxRetries = 20, retryDelayMs = 50) {
+  acquireLock(maxRetries = LOCK_MAX_RETRIES, retryDelayMs = LOCK_RETRY_DELAY_MS) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         fs.mkdirSync(this.lockPath);
@@ -141,7 +230,7 @@ var RouteStore = class _RouteStore {
         if (isErrnoException(err) && err.code === "EEXIST") {
           try {
             const stat = fs.statSync(this.lockPath);
-            if (Date.now() - stat.mtimeMs > 1e4) {
+            if (Date.now() - stat.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
               fs.rmSync(this.lockPath, { recursive: true });
               continue;
             }
@@ -198,7 +287,7 @@ var RouteStore = class _RouteStore {
       const alive = routes.filter((r) => this.isProcessAlive(r.pid));
       if (persistCleanup && alive.length !== routes.length) {
         try {
-          fs.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), { mode: 420 });
+          fs.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), { mode: FILE_MODE });
         } catch {
         }
       }
@@ -208,8 +297,7 @@ var RouteStore = class _RouteStore {
     }
   }
   saveRoutes(routes) {
-    this.ensureDir();
-    fs.writeFileSync(this.routesPath, JSON.stringify(routes, null, 2), { mode: 420 });
+    fs.writeFileSync(this.routesPath, JSON.stringify(routes, null, 2), { mode: FILE_MODE });
   }
   addRoute(hostname, port, pid) {
     this.ensureDir();
@@ -241,7 +329,11 @@ var RouteStore = class _RouteStore {
 export {
   isErrnoException,
   escapeHtml,
+  formatUrl,
   parseHostname,
+  PORTLESS_HEADER,
   createProxyServer,
+  FILE_MODE,
+  DIR_MODE,
   RouteStore
 };