peakroute 0.5.2 → 0.5.4

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/{chunk-ENHLKLCJ.js → chunk-IVO6GF7V.js}

@@ -538,33 +538,51 @@ function collectBinPaths(cwd) {
 function augmentedPath(env) {
   const base = (env ?? process.env).PATH ?? "";
   const bins = collectBinPaths(process.cwd());
+  if (IS_WINDOWS) {
+    const systemRoot = process.env.SystemRoot ?? "C:\\Windows";
+    const essentialPaths = [
+      path2.join(systemRoot, "System32"),
+      path2.join(systemRoot, "System32", "WindowsPowerShell", "v1.0"),
+      path2.join(systemRoot, "System32", "wbem")
+      // for WMI tools
+    ];
+    const bunPaths = [
+      path2.join(process.env.USERPROFILE ?? "C:\\Users\\" + process.env.USERNAME, ".bun", "bin"),
+      path2.join(process.env.LOCALAPPDATA ?? "", "bun", "bin")
+    ];
+    const pathEntries = base.split(path2.delimiter).filter(Boolean);
+    const missingSystemPaths = essentialPaths.filter(
+      (p) => pathEntries.every((entry) => entry.toLowerCase() !== p.toLowerCase())
+    );
+    const missingBunPaths = bunPaths.filter(
+      (p) => pathEntries.every((entry) => entry.toLowerCase() !== p.toLowerCase())
+    );
+    const allMissing = [...missingSystemPaths, ...missingBunPaths];
+    if (allMissing.length > 0) {
+      const newPath = allMissing.join(path2.delimiter) + path2.delimiter + base;
+      if (bins.length > 0) {
+        return bins.join(path2.delimiter) + path2.delimiter + newPath;
+      }
+      return newPath;
+    }
+  }
   return bins.length > 0 ? bins.join(path2.delimiter) + path2.delimiter + base : base;
 }
 function spawnCommand(commandArgs, options) {
   const env = { ...options?.env ?? process.env, PATH: augmentedPath(options?.env) };
   let child;
   if (IS_WINDOWS) {
-    const isPowerShell = !!process.env.PSModulePath || process.env.TERM === "xterm-256color";
-    if (isPowerShell) {
-      const shellCmd = commandArgs.map((a) => {
-        if (/[\s"'()$;|&<>@`]/.test(a)) {
-          return `"${a.replace(/"/g, '`"')}"`;
-        }
-        return a;
-      }).join(" ");
-      child = spawn("powershell.exe", ["-Command", shellCmd + "; exit $LASTEXITCODE"], {
-        stdio: "inherit",
-        env,
-        windowsHide: true
-      });
-    } else {
-      child = spawn(commandArgs[0], commandArgs.slice(1), {
-        stdio: "inherit",
-        env,
-        shell: true,
-        windowsHide: true
-      });
-    }
+    const shellCmd = commandArgs.map((a) => {
+      if (/[\s"&<>|^]/.test(a)) {
+        return `"${a.replace(/"/g, '""')}"`;
+      }
+      return a;
+    }).join(" ");
+    child = spawn("cmd.exe", ["/c", shellCmd], {
+      stdio: "inherit",
+      env,
+      windowsHide: true
+    });
   } else {
     const shellCmd = commandArgs.map(shellEscape).join(" ");
     child = spawn("/bin/sh", ["-c", shellCmd], {

package/dist/cli.js

@@ -24,13 +24,13 @@ import {
   spawnCommand,
   waitForProxy,
   writeTlsMarker
-} from "./chunk-ENHLKLCJ.js";
+} from "./chunk-IVO6GF7V.js";
 
 // src/cli.ts
 import chalk from "chalk";
 import * as fs2 from "fs";
 import * as path2 from "path";
-import { spawn, spawnSync } from "child_process";
+import { spawn, spawnSync, execSync } from "child_process";
 
 // src/certs.ts
 import * as fs from "fs";
@@ -435,6 +435,20 @@ var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
 var EXIT_TIMEOUT_MS = 2e3;
 var SUDO_SPAWN_TIMEOUT_MS = 3e4;
+function killProcess(pid, force = false) {
+  if (IS_WINDOWS) {
+    const args = force ? ["/F", "/T", "/PID", pid.toString()] : ["/T", "/PID", pid.toString()];
+    try {
+      execSync(`taskkill ${args.join(" ")}`, { windowsHide: true });
+    } catch {
+    }
+  } else {
+    try {
+      process.kill(pid, force ? "SIGKILL" : "SIGTERM");
+    } catch {
+    }
+  }
+}
 function startProxyServer(store, proxyPort, tlsOptions) {
   store.ensureDir();
   const isTls = !!tlsOptions;
@@ -540,7 +554,7 @@ async function stopProxy(store, proxyPort, tls2) {
       const pid = findPidOnPort(proxyPort);
       if (pid !== null) {
         try {
-          process.kill(pid, "SIGTERM");
+          killProcess(pid);
           try {
             fs2.unlinkSync(store.portFilePath);
           } catch {
@@ -615,7 +629,7 @@ async function stopProxy(store, proxyPort, tls2) {
       fs2.unlinkSync(pidPath);
       return;
     }
-    process.kill(pid, "SIGTERM");
+    killProcess(pid);
     fs2.unlinkSync(pidPath);
     try {
       fs2.unlinkSync(store.portFilePath);
@@ -884,7 +898,7 @@ ${chalk.bold("Skip peakroute:")}
     process.exit(0);
   }
   if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.5.2");
+    console.log("0.5.4");
     process.exit(0);
   }
   if (args[0] === "trust") {

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   formatUrl,
   isErrnoException,
   parseHostname
-} from "./chunk-ENHLKLCJ.js";
+} from "./chunk-IVO6GF7V.js";
 export {
   DIR_MODE,
   FILE_MODE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peakroute",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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"