peakroute 0.5.7 → 0.6.0

package/README.md

@@ -123,6 +123,8 @@ sudo peakroute trust
 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
+peakroute alias <host> <port>    # Register external service (e.g., Docker)
+peakroute alias remove <host>     # Remove an external route
 
 # Disable peakroute (run command directly)
 PEAKROUTE=0 bun dev              # Bypasses proxy, uses default port
@@ -164,6 +166,43 @@ Peakroute stores its state (routes, PID file, port file) in a directory that dep
 
 Override with the `PEAKROUTE_STATE_DIR` environment variable if needed.
 
+## External Services (Docker, etc.)
+
+Use the `peakroute alias` command to register routes for services not spawned by peakroute, such as Docker containers or other external processes:
+
+```bash
+# Register a Docker container running on port 3000
+peakroute alias mydocker.localhost 3000
+
+# Now access it at http://mydocker.localhost:1355
+
+# Remove the alias when done
+peakroute alias remove mydocker.localhost
+```
+
+Aliases are marked with `[external]` in the route list and are never cleaned up as "stale" since they don't have an associated process PID.
+
+```bash
+peakroute list
+# -> http://mydocker.localhost:1355 -> localhost:3000 (pid 0) [external]
+```
+
+## Git Worktree Support
+
+Peakroute automatically detects when you're running inside a [Git Worktree](https://git-scm.com/docs/git-worktree) and prepends the branch name as a subdomain prefix. This gives each worktree a unique URL without any configuration changes.
+
+```bash
+# In a worktree on branch feat/login
+peakroute myapp next dev
+# -> http://feat-login.myapp.localhost:1355
+
+# In a worktree on branch fix/auth-bug
+peakroute api next dev
+# -> http://fix-auth-bug.api.localhost:1355
+```
+
+The branch name is sanitized for use as a hostname (slashes become hyphens, invalid characters are removed).
+
 ## Development
 
 This repo is a Bun workspace monorepo using [Turborepo](https://turbo.build). The publishable package lives in `packages/peakroute/`.

package/dist/{chunk-IVO6GF7V.js → chunk-IJJU4JLF.js}

@@ -10,6 +10,7 @@ var PRIVILEGED_PORT_THRESHOLD = 1024;
 
 // src/utils.ts
 import * as fs from "fs";
+import { execSync } from "child_process";
 function chmodSafe(path4, mode) {
   if (IS_WINDOWS) return;
   try {
@@ -47,12 +48,39 @@ function formatUrl(hostname, proxyPort, tls = false) {
   const defaultPort = tls ? 443 : 80;
   return proxyPort === defaultPort ? `${proto}://${hostname}` : `${proto}://${hostname}:${proxyPort}`;
 }
+function detectGitWorktree() {
+  try {
+    const gitDir = execSync("git rev-parse --git-dir", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"]
+    }).trim();
+    const isWorktree = gitDir.includes("/worktrees/") || gitDir.includes("\\worktrees\\");
+    if (!isWorktree) return null;
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"]
+    }).trim();
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+function sanitizeBranchName(branch) {
+  return branch.replace(/\//g, "-").replace(/[^a-zA-Z0-9-]/g, "");
+}
 function parseHostname(input) {
   let hostname = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
   if (!hostname || hostname === ".localhost") {
     throw new Error("Hostname cannot be empty");
   }
-  if (!hostname.endsWith(".localhost")) {
+  if (hostname.endsWith(".localhost")) {
+    return hostname;
+  }
+  const branch = detectGitWorktree();
+  if (branch) {
+    const sanitized = sanitizeBranchName(branch);
+    hostname = `${sanitized}.${hostname}.localhost`;
+  } else {
     hostname = `${hostname}.localhost`;
   }
   const name = hostname.replace(/\.localhost$/, "");
@@ -71,6 +99,18 @@ function parseHostname(input) {
 import * as http from "http";
 import * as http2 from "http2";
 import * as net from "net";
+function findRoute(routes, host) {
+  const exact = routes.find((r) => r.hostname === host);
+  if (exact) return exact;
+  const parts = host.split(".");
+  while (parts.length > 2) {
+    parts.shift();
+    const wildcard = parts.join(".");
+    const match = routes.find((r) => r.hostname === wildcard);
+    if (match) return match;
+  }
+  return null;
+}
 var PEAKROUTE_HEADER = "X-Peakroute";
 var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
   "connection",
@@ -134,7 +174,7 @@ Fix: add changeOrigin: true to your proxy config, e.g.:
       );
       return;
     }
-    const route = routes.find((r) => r.hostname === host);
+    const route = findRoute(routes, host);
     if (!route) {
       const safeHost = escapeHtml(host);
       res.writeHead(404, { "Content-Type": "text/html" });
@@ -221,7 +261,7 @@ Fix: add changeOrigin: true to your proxy config, e.g.:
     }
     const routes = getRoutes();
     const host = getRequestHost(req).split(":")[0];
-    const route = routes.find((r) => r.hostname === host);
+    const route = findRoute(routes, host);
     if (!route) {
       socket.destroy();
       return;
@@ -333,7 +373,7 @@ import * as https from "https";
 import * as net2 from "net";
 import * as path2 from "path";
 import * as readline from "readline";
-import { execSync, spawn } from "child_process";
+import { execSync as execSync2, spawn } from "child_process";
 var DEFAULT_PROXY_PORT = 1355;
 var MIN_APP_PORT = 4e3;
 var MAX_APP_PORT = 4999;
@@ -419,7 +459,22 @@ async function discoverState() {
   const defaultPort = getDefaultPort();
   return { dir: resolveStateDir(defaultPort), port: defaultPort, tls: false };
 }
-async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net2.createServer();
+    server.listen(port, () => {
+      server.close(() => resolve(true));
+    });
+    server.on("error", () => resolve(false));
+  });
+}
+async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT, preferredPort) {
+  if (preferredPort !== void 0) {
+    if (await isPortAvailable(preferredPort)) {
+      return preferredPort;
+    }
+    throw new Error(`Port ${preferredPort} is already in use`);
+  }
   if (minPort > maxPort) {
     throw new Error(`minPort (${minPort}) must be <= maxPort (${maxPort})`);
   }
@@ -489,7 +544,7 @@ function parsePidFromNetstat(output, port) {
 function findPidOnPort(port) {
   if (IS_WINDOWS) {
     try {
-      const output = execSync(`netstat -ano -p tcp`, {
+      const output = execSync2(`netstat -ano -p tcp`, {
         encoding: "utf-8",
         timeout: LSOF_TIMEOUT_MS
       });
@@ -499,7 +554,7 @@ function findPidOnPort(port) {
     }
   }
   try {
-    const output = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
+    const output = execSync2(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
       encoding: "utf-8",
       timeout: LSOF_TIMEOUT_MS
     });
@@ -631,23 +686,91 @@ var FRAMEWORKS_NEEDING_PORT = {
   vite: { strictPort: true },
   "react-router": { strictPort: true },
   astro: { strictPort: false },
-  ng: { strictPort: false }
+  ng: { strictPort: false },
+  expo: { strictPort: false },
+  "react-native": { strictPort: false }
 };
-function injectFrameworkFlags(commandArgs, port) {
+var PACKAGE_MANAGERS = /* @__PURE__ */ new Set(["npm", "yarn", "pnpm", "bun"]);
+function detectFrameworkFromPackageJson(scriptName) {
+  try {
+    const pkgPath = path2.join(process.cwd(), "package.json");
+    if (!fs2.existsSync(pkgPath)) return null;
+    const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+    const script = pkg.scripts?.[scriptName];
+    if (!script) return null;
+    for (const [framework] of Object.entries(FRAMEWORKS_NEEDING_PORT)) {
+      const regex = new RegExp(
+        `(?:^|[\\s;&|/]|cross-env(?:\\s+[^\\s]+)*\\s+)${framework}(?=\\s|$)`,
+        "i"
+      );
+      if (regex.test(script)) {
+        return framework;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function extractScriptName(commandArgs, basename2) {
+  const runIndex = commandArgs.indexOf("run");
+  if (runIndex !== -1 && runIndex + 1 < commandArgs.length) {
+    return commandArgs[runIndex + 1];
+  }
+  if (basename2 === "yarn" || basename2 === "bun" || basename2 === "pnpm") {
+    const scriptName = commandArgs[1];
+    if (scriptName && !scriptName.startsWith("-")) {
+      return scriptName;
+    }
+  }
+  return null;
+}
+function resolveFramework(commandArgs) {
   const cmd = commandArgs[0];
-  if (!cmd) return;
+  if (!cmd) return null;
   const basename2 = path2.basename(cmd);
-  const framework = FRAMEWORKS_NEEDING_PORT[basename2];
-  if (!framework) return;
+  const directFramework = FRAMEWORKS_NEEDING_PORT[basename2];
+  if (directFramework) {
+    return { name: basename2, ...directFramework };
+  }
+  if (!PACKAGE_MANAGERS.has(basename2)) return null;
+  const scriptName = extractScriptName(commandArgs, basename2);
+  if (!scriptName) return null;
+  const detectedFramework = detectFrameworkFromPackageJson(scriptName);
+  if (!detectedFramework) return null;
+  return { name: detectedFramework, ...FRAMEWORKS_NEEDING_PORT[detectedFramework] };
+}
+function injectPortAndHostFlags(commandArgs, port, strictPort, framework) {
   if (!commandArgs.includes("--port")) {
     commandArgs.push("--port", port.toString());
-    if (framework.strictPort) {
+    if (strictPort) {
       commandArgs.push("--strictPort");
     }
   }
   if (!commandArgs.includes("--host")) {
     commandArgs.push("--host", "127.0.0.1");
   }
+  if (framework === "react-native") {
+    process.env.RCT_METRO_PORT = port.toString();
+  }
+}
+function injectFrameworkFlags(commandArgs, port, manualFramework) {
+  if (manualFramework === "force") {
+    injectPortAndHostFlags(commandArgs, port, false);
+    return;
+  }
+  if (manualFramework && FRAMEWORKS_NEEDING_PORT[manualFramework]) {
+    injectPortAndHostFlags(
+      commandArgs,
+      port,
+      FRAMEWORKS_NEEDING_PORT[manualFramework].strictPort,
+      manualFramework
+    );
+    return;
+  }
+  const framework = resolveFramework(commandArgs);
+  if (framework) {
+    injectPortAndHostFlags(commandArgs, port, framework.strictPort, framework.name);
+  }
 }
 function prompt(question) {
   const rl = readline.createInterface({
@@ -662,6 +785,83 @@ function prompt(question) {
     });
   });
 }
+var UPDATE_CHECK_CACHE_MS = 24 * 60 * 60 * 1e3;
+function getUpdateCachePath() {
+  return path2.join(USER_STATE_DIR, ".update-check.json");
+}
+function compareVersions(v1, v2) {
+  const parts1 = v1.split(".").map(Number);
+  const parts2 = v2.split(".").map(Number);
+  const maxLen = Math.max(parts1.length, parts2.length);
+  for (let i = 0; i < maxLen; i++) {
+    const a = parts1[i] || 0;
+    const b = parts2[i] || 0;
+    if (a < b) return -1;
+    if (a > b) return 1;
+  }
+  return 0;
+}
+async function checkForUpdate(currentVersion) {
+  if (process.env.PEAKROUTE_NO_UPDATE_CHECK) {
+    return null;
+  }
+  const cachePath = getUpdateCachePath();
+  try {
+    const cache = JSON.parse(fs2.readFileSync(cachePath, "utf-8"));
+    if (Date.now() - cache.lastCheck < UPDATE_CHECK_CACHE_MS) {
+      if (compareVersions(cache.version, currentVersion) > 0) {
+        return cache.version;
+      }
+      return null;
+    }
+  } catch {
+  }
+  return new Promise((resolve) => {
+    const req = https.get(
+      "https://registry.npmjs.org/peakroute/latest",
+      {
+        timeout: 3e3,
+        headers: {
+          Accept: "application/json"
+        }
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => {
+          data += chunk;
+        });
+        res.on("end", () => {
+          try {
+            const response = JSON.parse(data);
+            const latestVersion = response.version;
+            const cache = {
+              version: latestVersion,
+              lastCheck: Date.now()
+            };
+            try {
+              fs2.mkdirSync(USER_STATE_DIR, { recursive: true });
+              fs2.writeFileSync(cachePath, JSON.stringify(cache), { mode: 420 });
+            } catch {
+            }
+            if (compareVersions(latestVersion, currentVersion) > 0) {
+              resolve(latestVersion);
+            } else {
+              resolve(null);
+            }
+          } catch {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.setTimeout(3e3);
+  });
+}
 
 // src/routes.ts
 import * as fs3 from "fs";
@@ -775,6 +975,9 @@ var RouteStore = class _RouteStore {
    * is no longer alive. Stale-route cleanup is only persisted when the caller
    * already holds the lock (i.e. inside addRoute/removeRoute) to avoid
    * unprotected concurrent writes.
+   *
+   * Note: Routes with pid=0 are considered external (e.g., Docker containers)
+   * and are never filtered out as stale.
    */
   loadRoutes(persistCleanup = false) {
     if (!fs3.existsSync(this.routesPath)) {
@@ -794,7 +997,7 @@ var RouteStore = class _RouteStore {
         return [];
       }
       const routes = parsed.filter(isValidRoute);
-      const alive = routes.filter((r) => this.isProcessAlive(r.pid));
+      const alive = routes.filter((r) => r.pid === 0 || this.isProcessAlive(r.pid));
       if (persistCleanup && alive.length !== routes.length) {
         try {
           fs3.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), {
@@ -842,6 +1045,28 @@ var RouteStore = class _RouteStore {
       this.releaseLock();
     }
   }
+  /**
+   * Register an alias for an external service (e.g., Docker container).
+   * Uses pid=0 as a sentinel to indicate the route is not managed by
+   * a child process and should never be cleaned up as "stale".
+   */
+  addAlias(hostname, port) {
+    this.ensureDir();
+    if (!this.acquireLock()) {
+      throw new Error("Failed to acquire route lock");
+    }
+    try {
+      const routes = this.loadRoutes(true);
+      const existing = routes.find((r) => r.hostname === hostname);
+      if (existing) {
+        throw new Error(`Hostname "${hostname}" is already registered`);
+      }
+      routes.push({ hostname, port, pid: 0 });
+      this.saveRoutes(routes);
+    } finally {
+      this.releaseLock();
+    }
+  }
 };
 
 export {
@@ -853,6 +1078,8 @@ export {
   isErrnoException,
   escapeHtml,
   formatUrl,
+  detectGitWorktree,
+  sanitizeBranchName,
   parseHostname,
   PEAKROUTE_HEADER,
   createProxyServer,
@@ -869,6 +1096,7 @@ export {
   spawnCommand,
   injectFrameworkFlags,
   prompt,
+  checkForUpdate,
   FILE_MODE,
   DIR_MODE,
   SYSTEM_DIR_MODE,

package/dist/cli.js

@@ -5,6 +5,7 @@ import {
   PRIVILEGED_PORT_THRESHOLD,
   RouteConflictError,
   RouteStore,
+  checkForUpdate,
   chmodSafe,
   createProxyServer,
   discoverState,
@@ -24,7 +25,7 @@ import {
   spawnCommand,
   waitForProxy,
   writeTlsMarker
-} from "./chunk-IVO6GF7V.js";
+} from "./chunk-IJJU4JLF.js";
 
 // src/cli.ts
 import chalk from "chalk";
@@ -250,8 +251,80 @@ function loginKeychainPath() {
   const home = process.env.HOME || `/Users/${process.env.USER || "unknown"}`;
   return path.join(home, "Library", "Keychains", "login.keychain-db");
 }
+function detectLinuxDistro() {
+  try {
+    const osRelease = fs.readFileSync("/etc/os-release", "utf-8");
+    const idMatch = osRelease.match(/^ID=(.+)$/m);
+    const idLikeMatch = osRelease.match(/^ID_LIKE=(.+)$/m);
+    const id = idMatch?.[1]?.toLowerCase().replace(/"/g, "");
+    const idLike = idLikeMatch?.[1]?.toLowerCase().replace(/"/g, "");
+    if (id) {
+      if (id === "debian" || id === "ubuntu" || id === "linuxmint" || id === "pop") {
+        return "debian";
+      }
+      if (id === "fedora" || id === "rhel" || id === "centos" || id === "rocky" || id === "almalinux") {
+        return "fedora";
+      }
+      if (id === "arch" || id === "manjaro" || id === "endeavouros") {
+        return "arch";
+      }
+      if (id === "opensuse" || id === "opensuse-leap" || id === "opensuse-tumbleweed") {
+        return "opensuse";
+      }
+    }
+    if (idLike) {
+      if (idLike.includes("debian")) return "debian";
+      if (idLike.includes("fedora") || idLike.includes("rhel")) return "fedora";
+      if (idLike.includes("arch")) return "arch";
+      if (idLike.includes("suse")) return "opensuse";
+    }
+  } catch {
+  }
+  try {
+    execFileSync("which", ["update-ca-certificates"], { stdio: "pipe" });
+    return "debian";
+  } catch {
+  }
+  try {
+    execFileSync("which", ["update-ca-trust"], { stdio: "pipe" });
+    return "fedora";
+  } catch {
+  }
+  return "unknown";
+}
+function getLinuxCertConfig(distro) {
+  switch (distro) {
+    case "fedora":
+      return {
+        certDir: "/etc/pki/ca-trust/source/anchors",
+        certFilename: "peakroute-ca.crt",
+        updateCommand: ["update-ca-trust", "extract"]
+      };
+    case "arch":
+      return {
+        certDir: "/etc/ca-certificates/trust-source/anchors",
+        certFilename: "peakroute-ca.crt",
+        updateCommand: ["update-ca-trust"]
+      };
+    case "opensuse":
+      return {
+        certDir: "/etc/pki/trust/anchors",
+        certFilename: "peakroute-ca.crt",
+        updateCommand: ["update-ca-certificates"]
+      };
+    case "debian":
+    default:
+      return {
+        certDir: "/usr/local/share/ca-certificates",
+        certFilename: "peakroute-ca.crt",
+        updateCommand: ["update-ca-certificates"]
+      };
+  }
+}
 function isCATrustedLinux(stateDir) {
-  const systemCertPath = `/usr/local/share/ca-certificates/peakroute-ca.crt`;
+  const distro = detectLinuxDistro();
+  const config = getLinuxCertConfig(distro);
+  const systemCertPath = path.join(config.certDir, config.certFilename);
   if (!fileExists(systemCertPath)) return false;
   try {
     const ours = fs.readFileSync(path.join(stateDir, CA_CERT_FILE), "utf-8").trim();
@@ -409,9 +482,17 @@ function trustCA(stateDir) {
       );
       return { trusted: true };
     } else if (process.platform === "linux") {
-      const dest = "/usr/local/share/ca-certificates/peakroute-ca.crt";
+      const distro = detectLinuxDistro();
+      const config = getLinuxCertConfig(distro);
+      const dest = path.join(config.certDir, config.certFilename);
+      if (!fs.existsSync(config.certDir)) {
+        fs.mkdirSync(config.certDir, { recursive: true });
+      }
       fs.copyFileSync(caCertPath, dest);
-      execFileSync("update-ca-certificates", [], { stdio: "pipe", timeout: 3e4 });
+      execFileSync(config.updateCommand[0], config.updateCommand.slice(1), {
+        stdio: "pipe",
+        timeout: 3e4
+      });
       return { trusted: true };
     } else if (IS_WINDOWS) {
       trustCAWindows(caCertPath);
@@ -670,13 +751,14 @@ function listRoutes(store, proxyPort, tls2) {
   console.log(chalk.blue.bold("\nActive routes:\n"));
   for (const route of routes) {
     const url = formatUrl(route.hostname, proxyPort, tls2);
+    const externalIndicator = route.pid === 0 ? chalk.gray(" [external]") : "";
     console.log(
-      `  ${chalk.cyan(url)}  ${chalk.gray("->")}  ${chalk.white(`localhost:${route.port}`)}  ${chalk.gray(`(pid ${route.pid})`)}`
+      `  ${chalk.cyan(url)}  ${chalk.gray("->")}  ${chalk.white(`localhost:${route.port}`)}  ${chalk.gray(`(pid ${route.pid})`)}${externalIndicator}`
     );
   }
   console.log();
 }
-async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, force) {
+async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, force, inject, preferredAppPort) {
   const hostname = parseHostname(name);
   console.log(chalk.blue.bold(`
 peakroute
@@ -772,7 +854,7 @@ peakroute
   } else {
     console.log(chalk.gray("-- Proxy is running"));
   }
-  const port = await findFreePort();
+  const port = await findFreePort(void 0, void 0, preferredAppPort);
   console.log(chalk.green(`-- Using port ${port}`));
   try {
     store.addRoute(hostname, port, process.pid, force);
@@ -787,7 +869,7 @@ peakroute
   console.log(chalk.cyan.bold(`
   -> ${finalUrl}
 `));
-  injectFrameworkFlags(commandArgs, port);
+  injectFrameworkFlags(commandArgs, port, inject ? "force" : void 0);
   console.log(chalk.gray(`Running: PORT=${port} HOST=127.0.0.1 ${commandArgs.join(" ")}
 `));
   spawnCommand(commandArgs, {
@@ -795,6 +877,7 @@ peakroute
       ...process.env,
       PORT: port.toString(),
       HOST: "127.0.0.1",
+      PEAKROUTE_URL: finalUrl,
       __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: ".localhost"
     },
     onCleanup: () => {
@@ -806,6 +889,7 @@ peakroute
   });
 }
 async function main() {
+  const updatePromise = checkForUpdate("0.6.0");
   if (process.stdin.isTTY) {
     process.on("exit", () => {
       try {
@@ -815,6 +899,15 @@ async function main() {
     });
   }
   const args = process.argv.slice(2);
+  const newerVersion = await updatePromise;
+  if (newerVersion) {
+    console.log(
+      chalk.yellow(`
+\u2192 Update available: ${chalk.bold(newerVersion)} (current: ${"0.6.0"})`)
+    );
+    console.log(chalk.gray(`  Run: npm install -g peakroute
+`));
+  }
   const isNpx = process.env.npm_command === "exec" && !process.env.npm_lifecycle_event;
   const isPnpmDlx = !!process.env.PNPM_SCRIPT_SRC_DIR && !process.env.npm_lifecycle_event;
   if (isNpx || isPnpmDlx) {
@@ -847,6 +940,8 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("peakroute <name> <cmd>")}            Run your app through the proxy
   ${chalk.cyan("peakroute list")}                    Show active routes
   ${chalk.cyan("peakroute trust")}                   Add local CA to system trust store
+  ${chalk.cyan("peakroute alias <host> <port>")}    Register a route for external services (e.g. Docker)
+  ${chalk.cyan("peakroute alias remove <host>")}     Remove an external route
 
 ${chalk.bold("Examples:")}
   peakroute proxy start                # Start proxy on port 1355
@@ -884,9 +979,12 @@ ${chalk.bold("Options:")}
   --no-tls                      Disable HTTPS (overrides PEAKROUTE_HTTPS)
   --foreground                  Run proxy in foreground (for debugging)
   --force                       Override an existing route registered by another process
+  --inject                      Force injection of --port and --host flags (when auto-detection fails)
+  --app-port <number>           Use a specific port for the app (instead of auto-finding one)
 
 ${chalk.bold("Environment variables:")}
   PEAKROUTE_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
+  PEAKROUTE_APP_PORT=<number>    Use a specific port for the app (alternative to --app-port)
   PEAKROUTE_HTTPS=1              Always enable HTTPS (set in .bashrc / .zshrc)
   PEAKROUTE_STATE_DIR=<path>     Override the state directory
   PEAKROUTE=0 | PEAKROUTE=skip    Run command directly without proxy
@@ -898,7 +996,7 @@ ${chalk.bold("Skip peakroute:")}
     process.exit(0);
   }
   if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.5.7");
+    console.log("0.6.0");
     process.exit(0);
   }
   if (args[0] === "trust") {
@@ -928,6 +1026,54 @@ ${chalk.bold("Skip peakroute:")}
     listRoutes(store2, port2, tls3);
     return;
   }
+  if (args[0] === "alias") {
+    const { dir: dir2 } = await discoverState();
+    const store2 = new RouteStore(dir2, {
+      onWarning: (msg) => console.warn(chalk.yellow(msg))
+    });
+    if (args[1] === "remove") {
+      const hostname2 = args[2];
+      if (!hostname2) {
+        console.error(chalk.red("Error: Missing hostname."));
+        console.error(chalk.blue("Usage:"));
+        console.error(chalk.cyan("  peakroute alias remove <hostname>"));
+        process.exit(1);
+      }
+      try {
+        store2.removeRoute(parseHostname(hostname2));
+        console.log(chalk.green(`Alias removed: ${hostname2}`));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Failed to remove alias: ${message}`));
+        process.exit(1);
+      }
+      return;
+    }
+    const hostname = args[1];
+    const portStr = args[2];
+    if (!hostname || !portStr) {
+      console.error(chalk.red("Error: Missing arguments."));
+      console.error(chalk.blue("Usage:"));
+      console.error(chalk.cyan("  peakroute alias <hostname> <port>"));
+      console.error(chalk.cyan("  peakroute alias remove <hostname>"));
+      process.exit(1);
+    }
+    const portNum = parseInt(portStr, 10);
+    if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+      console.error(chalk.red(`Error: Invalid port number: ${portStr}`));
+      console.error(chalk.blue("Port must be between 1 and 65535."));
+      process.exit(1);
+    }
+    try {
+      store2.addAlias(parseHostname(hostname), portNum);
+      console.log(chalk.green(`Alias registered: ${hostname} -> localhost:${portNum}`));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(chalk.red(`Failed to register alias: ${message}`));
+      process.exit(1);
+    }
+    return;
+  }
   if (args[0] === "proxy") {
     if (args[1] === "stop") {
       const { dir: dir2, port: port2, tls: tls3 } = await discoverState();
@@ -1133,9 +1279,40 @@ ${chalk.bold("Usage: peakroute proxy <command>")}
     console.log(chalk.green(`${proto} proxy started on port ${proxyPort}`));
     return;
   }
+  const parsedFlags = /* @__PURE__ */ new Set();
   const forceIdx = args.indexOf("--force");
   const force = forceIdx >= 0 && forceIdx <= 1;
-  const appArgs = force ? [...args.slice(0, forceIdx), ...args.slice(forceIdx + 1)] : args;
+  if (force) parsedFlags.add(forceIdx);
+  const injectIdx = args.indexOf("--inject");
+  const injectFlag = injectIdx >= 0 && injectIdx <= 1;
+  if (injectFlag) parsedFlags.add(injectIdx);
+  let preferredAppPort;
+  const appPortIdx = args.indexOf("--app-port");
+  if (appPortIdx >= 0 && appPortIdx <= 1) {
+    const portValue = args[appPortIdx + 1];
+    if (!portValue || portValue.startsWith("-")) {
+      console.error(chalk.red("Error: --app-port requires a port number."));
+      console.error(chalk.blue("Usage:"));
+      console.error(chalk.cyan("  peakroute myapp --app-port 3000 next dev"));
+      process.exit(1);
+    }
+    const parsedPort = parseInt(portValue, 10);
+    if (isNaN(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+      console.error(chalk.red(`Error: Invalid port number: ${portValue}`));
+      console.error(chalk.blue("Port must be between 1 and 65535."));
+      process.exit(1);
+    }
+    preferredAppPort = parsedPort;
+    parsedFlags.add(appPortIdx);
+    parsedFlags.add(appPortIdx + 1);
+  }
+  if (preferredAppPort === void 0 && process.env.PEAKROUTE_APP_PORT) {
+    const envPort = parseInt(process.env.PEAKROUTE_APP_PORT, 10);
+    if (!isNaN(envPort) && envPort >= 1 && envPort <= 65535) {
+      preferredAppPort = envPort;
+    }
+  }
+  const appArgs = args.filter((_, i) => !parsedFlags.has(i));
   const name = appArgs[0];
   const commandArgs = appArgs.slice(1);
   if (commandArgs.length === 0) {
@@ -1150,7 +1327,7 @@ ${chalk.bold("Usage: peakroute proxy <command>")}
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
-  await runApp(store, port, dir, name, commandArgs, tls2, force);
+  await runApp(store, port, dir, name, commandArgs, tls2, force, injectFlag, preferredAppPort);
 }
 main().catch((err) => {
   const message = err instanceof Error ? err.message : String(err);

package/dist/index.d.ts

@@ -90,11 +90,20 @@ declare class RouteStore {
      * is no longer alive. Stale-route cleanup is only persisted when the caller
      * already holds the lock (i.e. inside addRoute/removeRoute) to avoid
      * unprotected concurrent writes.
+     *
+     * Note: Routes with pid=0 are considered external (e.g., Docker containers)
+     * and are never filtered out as stale.
      */
     loadRoutes(persistCleanup?: boolean): RouteMapping[];
     private saveRoutes;
     addRoute(hostname: string, port: number, pid: number, force?: boolean): void;
     removeRoute(hostname: string): void;
+    /**
+     * Register an alias for an external service (e.g., Docker container).
+     * Uses pid=0 as a sentinel to indicate the route is not managed by
+     * a child process and should never be cleaned up as "stale".
+     */
+    addAlias(hostname: string, port: number): void;
 }
 
 /**
@@ -123,10 +132,21 @@ declare function escapeHtml(str: string): string;
  * (80 for HTTP, 443 for HTTPS).
  */
 declare function formatUrl(hostname: string, proxyPort: number, tls?: boolean): string;
+/**
+ * Detect if we're in a git worktree and return the branch name.
+ * Returns null if not in a worktree or if git is not available.
+ */
+declare function detectGitWorktree(): string | null;
+/**
+ * Sanitize branch name for use in hostname.
+ * Replaces / with - and removes invalid characters.
+ */
+declare function sanitizeBranchName(branch: string): string;
 /**
  * Parse and normalize a hostname input for use as a .localhost subdomain.
  * Strips protocol prefixes, validates characters, and appends .localhost if needed.
+ * When in a git worktree, prepends the branch name as a subdomain prefix.
  */
 declare function parseHostname(input: string): string;
 
-export { DIR_MODE, FILE_MODE, PEAKROUTE_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, chmodSafe, chmodSafeAsync, createProxyServer, escapeHtml, fixOwnership, formatUrl, isErrnoException, parseHostname };
+export { DIR_MODE, FILE_MODE, PEAKROUTE_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, chmodSafe, chmodSafeAsync, createProxyServer, detectGitWorktree, escapeHtml, fixOwnership, formatUrl, isErrnoException, parseHostname, sanitizeBranchName };

package/dist/index.js

@@ -9,12 +9,14 @@ import {
   chmodSafe,
   chmodSafeAsync,
   createProxyServer,
+  detectGitWorktree,
   escapeHtml,
   fixOwnership,
   formatUrl,
   isErrnoException,
-  parseHostname
-} from "./chunk-IVO6GF7V.js";
+  parseHostname,
+  sanitizeBranchName
+} from "./chunk-IJJU4JLF.js";
 export {
   DIR_MODE,
   FILE_MODE,
@@ -26,9 +28,11 @@ export {
   chmodSafe,
   chmodSafeAsync,
   createProxyServer,
+  detectGitWorktree,
   escapeHtml,
   fixOwnership,
   formatUrl,
   isErrnoException,
-  parseHostname
+  parseHostname,
+  sanitizeBranchName
 };

package/package.json

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