peakroute 0.5.3 → 0.5.5

package/README.md

@@ -0,0 +1,217 @@
+[![npm version](https://img.shields.io/npm/v/peakroute)](https://www.npmjs.com/package/peakroute) [![GitHub](https://img.shields.io/badge/GitHub-repository-black?logo=github)](https://github.com/faladev/peakroute)
+![Windows](https://img.shields.io/badge/Windows-supported-brightgreen?logo=windows) ![macOS](https://img.shields.io/badge/macOS-supported-black?logo=apple) ![Linux](https://img.shields.io/badge/Linux-supported-yellow?logo=linux)
+
+# peakroute
+
+> [!NOTE]
+> **📌 Fork Notice:** This is a continuation fork of [vercel-labs/portless](https://github.com/vercel-labs/portless). We maintain and extend the project with additional features and platform support.
+
+> [!IMPORTANT]
+> **🪟 Windows Support Added!** This fork includes full Windows support alongside macOS and Linux. No platform limitations!
+
+Replace port numbers with stable, named .localhost URLs. For humans and agents.
+
+```diff
+- "dev": "next dev"              # http://localhost:3000
++ "dev": "peakroute myapp next dev"  # http://myapp.localhost:1355
+```
+
+## Quick Start
+
+```bash
+# Install
+npm install -g peakroute
+
+# Start the proxy (once, no sudo needed)
+peakroute proxy start
+
+# Run your app (auto-starts the proxy if needed)
+peakroute myapp next dev
+# -> http://myapp.localhost:1355
+```
+
+> The proxy auto-starts when you run an app. You can also start it explicitly with `peakroute 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
+
+Peakroute fixes all of this by giving each dev server a stable, named `.localhost` URL that both humans and agents can rely on.
+
+## Usage
+
+```bash
+# Basic
+peakroute myapp next dev
+# -> http://myapp.localhost:1355
+
+# Subdomains
+peakroute api.myapp npm start
+# -> http://api.myapp.localhost:1355
+
+peakroute docs.myapp next dev
+# -> http://docs.myapp.localhost:1355
+```
+
+### In package.json
+
+```json
+{
+  "scripts": {
+    "dev": "peakroute myapp next dev"
+  }
+}
+```
+
+The proxy auto-starts when you run an app. Or start it explicitly: `peakroute proxy start`.
+
+## How It Works
+
+```mermaid
+flowchart TD
+    Browser["Browser<br/>myapp.localhost:1355"]
+    Proxy["peakroute proxy<br/>(port 1355)"]
+    App1[":4123<br/>myapp"]
+    App2[":4567<br/>api"]
+
+    Browser -->|port 1355| Proxy
+    Proxy --> App1
+    Proxy --> App2
+```
+
+1. **Start the proxy** -- auto-starts when you run an app, or start explicitly with `peakroute proxy start`
+2. **Run apps** -- `peakroute <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
+
+Apps are assigned a random port (4000-4999) via the `PORT` and `HOST` environment variables. Most frameworks (Next.js, Express, Nuxt, etc.) respect these automatically. For frameworks that ignore `PORT` (Vite, Astro, React Router, Angular), peakroute auto-injects the correct `--port` and `--host` flags.
+
+## 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
+peakroute 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.
+
+# Make it permanent (add to .bashrc / .zshrc)
+export PEAKROUTE_HTTPS=1
+peakroute proxy start    # HTTPS by default now
+
+# Use your own certs (e.g., from mkcert)
+peakroute proxy start --cert ./cert.pem --key ./key.pem
+
+# If you skipped sudo on first run, trust the CA later
+sudo peakroute trust
+```
+
+## Commands
+
+```bash
+peakroute <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
+peakroute list                    # Show active routes
+peakroute trust                   # Add local CA to system trust store
+
+# Disable peakroute (run command directly)
+PEAKROUTE=0 bun dev              # Bypasses proxy, uses default port
+# Also accepts PEAKROUTE=skip
+
+# Proxy control
+peakroute proxy start             # Start the proxy (port 1355, daemon)
+peakroute proxy start --https     # Start with HTTP/2 + TLS
+peakroute proxy start -p 80       # Start on port 80 (requires sudo)
+peakroute proxy start --foreground  # Start in foreground (for debugging)
+peakroute proxy stop              # Stop the proxy
+
+# Options
+-p, --port <number>              # Port for the proxy (default: 1355)
+                                 # Ports < 1024 require sudo
+--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 PEAKROUTE_HTTPS)
+--foreground                     # Run proxy in foreground instead of daemon
+--force                          # Override a route registered by another process
+
+# Environment variables
+PEAKROUTE_PORT=<number>           # Override the default proxy port
+PEAKROUTE_HTTPS=1                 # Always enable HTTPS
+PEAKROUTE_STATE_DIR=<path>        # Override the state directory
+
+# Info
+peakroute --help                  # Show help
+peakroute --version               # Show version
+```
+
+## State Directory
+
+Peakroute stores its state (routes, PID file, port file) in a directory that depends on the proxy port:
+
+- **Port < 1024** (sudo required): `/tmp/peakroute` -- shared between root and user processes
+- **Port >= 1024** (no sudo): `~/.peakroute` -- user-scoped, no root involvement
+
+Override with the `PEAKROUTE_STATE_DIR` environment variable if needed.
+
+## Development
+
+This repo is a Bun workspace monorepo using [Turborepo](https://turbo.build). The publishable package lives in `packages/peakroute/`.
+
+```bash
+bun install          # Install all dependencies
+bun run build        # Build all packages
+bun run test         # Run tests
+bun run test:coverage # Run tests with coverage
+bun run test:watch   # Run tests in watch mode
+bun run lint         # Lint all packages
+bun run typecheck    # Type-check all packages
+bun run format       # Format all files with Prettier
+```
+
+## Proxying Between Peakroute Apps
+
+If your frontend dev server (e.g. Vite, webpack) proxies API requests to another peakroute app, make sure the proxy rewrites the `Host` header. Without this, the proxy sends the **original** Host header, causing peakroute to route the request back to the frontend in an infinite loop.
+
+**Vite** (`vite.config.ts`):
+
+```ts
+server: {
+  proxy: {
+    "/api": {
+      target: "http://api.myapp.localhost:1355",
+      changeOrigin: true,  // Required: rewrites Host header to match target
+      ws: true,
+    },
+  },
+}
+```
+
+**webpack-dev-server** (`webpack.config.js`):
+
+```js
+devServer: {
+  proxy: [{
+    context: ["/api"],
+    target: "http://api.myapp.localhost:1355",
+    changeOrigin: true,  // Required: rewrites Host header to match target
+  }],
+}
+```
+
+Peakroute detects this misconfiguration and responds with `508 Loop Detected` along with a message pointing to this fix.
+
+## Requirements
+
+- Node.js 20+
+- macOS, Linux, or Windows

package/dist/cli.js

@@ -898,7 +898,7 @@ ${chalk.bold("Skip peakroute:")}
     process.exit(0);
   }
   if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.5.3");
+    console.log("0.5.5");
     process.exit(0);
   }
   if (args[0] === "trust") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peakroute",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents. (Formerly portless)",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,8 @@
     "peakroute": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
     "node": ">=20"