portless 0.4.2 → 0.5.1

package/dist/cli.js

@@ -4,6 +4,7 @@ import {
   PRIVILEGED_PORT_THRESHOLD,
   RouteConflictError,
   RouteStore,
+  cleanHostsFile,
   createProxyServer,
   discoverState,
   findFreePort,
@@ -20,14 +21,15 @@ import {
   readTlsMarker,
   resolveStateDir,
   spawnCommand,
+  syncHostsFile,
   waitForProxy,
   writeTlsMarker
-} from "./chunk-JMRTQAVX.js";
+} from "./chunk-P3DHZHEZ.js";
 
 // src/cli.ts
 import chalk from "chalk";
-import * as fs2 from "fs";
-import * as path2 from "path";
+import * as fs3 from "fs";
+import * as path3 from "path";
 import { spawn, spawnSync } from "child_process";
 
 // src/certs.ts
@@ -246,8 +248,50 @@ function loginKeychainPath() {
   const home = process.env.HOME || `/Users/${process.env.USER || "unknown"}`;
   return path.join(home, "Library", "Keychains", "login.keychain-db");
 }
+var LINUX_CA_TRUST_CONFIGS = {
+  debian: {
+    certDir: "/usr/local/share/ca-certificates",
+    updateCommand: "update-ca-certificates"
+  },
+  arch: {
+    certDir: "/etc/ca-certificates/trust-source/anchors",
+    updateCommand: "update-ca-trust"
+  },
+  fedora: {
+    certDir: "/etc/pki/ca-trust/source/anchors",
+    updateCommand: "update-ca-trust"
+  },
+  suse: {
+    certDir: "/etc/pki/trust/anchors",
+    updateCommand: "update-ca-certificates"
+  }
+};
+function detectLinuxDistro() {
+  try {
+    const osRelease = fs.readFileSync("/etc/os-release", "utf-8").toLowerCase();
+    if (osRelease.includes("arch")) return "arch";
+    if (osRelease.includes("fedora") || osRelease.includes("rhel") || osRelease.includes("centos"))
+      return "fedora";
+    if (osRelease.includes("suse")) return "suse";
+    if (osRelease.includes("debian") || osRelease.includes("ubuntu")) return "debian";
+  } catch {
+  }
+  for (const [distro, config] of Object.entries(LINUX_CA_TRUST_CONFIGS)) {
+    try {
+      execFileSync("which", [config.updateCommand], { stdio: "pipe", timeout: 5e3 });
+      if (fs.existsSync(path.dirname(config.certDir))) return distro;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function getLinuxCATrustConfig() {
+  const distro = detectLinuxDistro();
+  return LINUX_CA_TRUST_CONFIGS[distro ?? "debian"];
+}
 function isCATrustedLinux(stateDir) {
-  const systemCertPath = `/usr/local/share/ca-certificates/portless-ca.crt`;
+  const config = getLinuxCATrustConfig();
+  const systemCertPath = path.join(config.certDir, "portless-ca.crt");
   if (!fileExists(systemCertPath)) return false;
   try {
     const ours = fs.readFileSync(path.join(stateDir, CA_CERT_FILE), "utf-8").trim();
@@ -386,9 +430,13 @@ function trustCA(stateDir) {
       );
       return { trusted: true };
     } else if (process.platform === "linux") {
-      const dest = "/usr/local/share/ca-certificates/portless-ca.crt";
+      const config = getLinuxCATrustConfig();
+      if (!fs.existsSync(config.certDir)) {
+        fs.mkdirSync(config.certDir, { recursive: true });
+      }
+      const dest = path.join(config.certDir, "portless-ca.crt");
       fs.copyFileSync(caCertPath, dest);
-      execFileSync("update-ca-certificates", [], { stdio: "pipe", timeout: 3e4 });
+      execFileSync(config.updateCommand, [], { stdio: "pipe", timeout: 3e4 });
       return { trusted: true };
     }
     return { trusted: false, error: `Unsupported platform: ${process.platform}` };
@@ -404,6 +452,151 @@ function trustCA(stateDir) {
   }
 }
 
+// src/auto.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import * as fs2 from "fs";
+import * as path2 from "path";
+function sanitizeForHostname(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+}
+function inferProjectName(cwd = process.cwd()) {
+  const pkgResult = findPackageJsonName(cwd);
+  if (pkgResult) {
+    const sanitized2 = sanitizeForHostname(pkgResult);
+    if (sanitized2) {
+      return { name: sanitized2, source: "package.json" };
+    }
+  }
+  const gitRoot = findGitRoot(cwd);
+  if (gitRoot) {
+    const sanitized2 = sanitizeForHostname(path2.basename(gitRoot));
+    if (sanitized2) {
+      return { name: sanitized2, source: "git root" };
+    }
+  }
+  const sanitized = sanitizeForHostname(path2.basename(cwd));
+  if (sanitized) {
+    return { name: sanitized, source: "directory name" };
+  }
+  throw new Error("Could not infer a project name from package.json, git root, or directory name");
+}
+function findPackageJsonName(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    const pkgPath = path2.join(dir, "package.json");
+    try {
+      const raw = fs2.readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(raw);
+      if (typeof pkg.name === "string" && pkg.name) {
+        return pkg.name.replace(/^@[^/]+\//, "");
+      }
+    } catch {
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function findGitRoot(startDir) {
+  try {
+    const toplevel = execFileSync2("git", ["rev-parse", "--show-toplevel"], {
+      cwd: startDir,
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (toplevel) return toplevel;
+  } catch {
+  }
+  let dir = startDir;
+  for (; ; ) {
+    const gitPath = path2.join(dir, ".git");
+    try {
+      const stat = fs2.statSync(gitPath);
+      if (stat.isDirectory()) return dir;
+      if (stat.isFile()) return dir;
+    } catch {
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+var DEFAULT_BRANCHES = /* @__PURE__ */ new Set(["main", "master"]);
+function branchToPrefix(branch) {
+  if (!branch || branch === "HEAD" || DEFAULT_BRANCHES.has(branch)) return null;
+  const lastSegment = branch.split("/").pop();
+  const prefix = sanitizeForHostname(lastSegment);
+  return prefix || null;
+}
+function detectWorktreePrefix(cwd = process.cwd()) {
+  const cliResult = detectWorktreeViaCli(cwd);
+  if (cliResult !== void 0) return cliResult;
+  return detectWorktreeViaFilesystem(cwd);
+}
+function detectWorktreeViaCli(cwd) {
+  try {
+    const listOutput = execFileSync2("git", ["worktree", "list", "--porcelain"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const worktreeCount = listOutput.split("\n").filter((l) => l.startsWith("worktree ")).length;
+    if (worktreeCount <= 1) return null;
+    const branch = execFileSync2("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    const prefix = branchToPrefix(branch);
+    if (!prefix) return null;
+    return { prefix, source: "git branch" };
+  } catch {
+    return void 0;
+  }
+}
+function detectWorktreeViaFilesystem(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    const gitPath = path2.join(dir, ".git");
+    try {
+      const stat = fs2.statSync(gitPath);
+      if (stat.isDirectory()) {
+        return null;
+      }
+      if (stat.isFile()) {
+        const content = fs2.readFileSync(gitPath, "utf-8").trim();
+        const match = content.match(/^gitdir:\s*(.+)$/);
+        if (!match) return null;
+        const gitdir = match[1];
+        if (!gitdir.match(/\/worktrees\/[^/]+$/)) return null;
+        const branch = readBranchFromHead(path2.resolve(dir, gitdir));
+        const prefix = branchToPrefix(branch ?? "");
+        if (!prefix) return null;
+        return { prefix, source: "git branch" };
+      }
+    } catch {
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function readBranchFromHead(gitdir) {
+  try {
+    const head = fs2.readFileSync(path2.join(gitdir, "HEAD"), "utf-8").trim();
+    const refMatch = head.match(/^ref: refs\/heads\/(.+)$/);
+    return refMatch ? refMatch[1] : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/cli.ts
 var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
@@ -413,11 +606,11 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   store.ensureDir();
   const isTls = !!tlsOptions;
   const routesPath = store.getRoutesPath();
-  if (!fs2.existsSync(routesPath)) {
-    fs2.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
+  if (!fs3.existsSync(routesPath)) {
+    fs3.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
   }
   try {
-    fs2.chmodSync(routesPath, FILE_MODE);
+    fs3.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
   fixOwnership(routesPath);
@@ -425,14 +618,18 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   let debounceTimer = null;
   let watcher = null;
   let pollingInterval = null;
+  const autoSyncHosts = process.env.PORTLESS_SYNC_HOSTS === "1";
   const reloadRoutes = () => {
     try {
       cachedRoutes = store.loadRoutes();
+      if (autoSyncHosts) {
+        syncHostsFile(cachedRoutes.map((r) => r.hostname));
+      }
     } catch {
     }
   };
   try {
-    watcher = fs2.watch(routesPath, () => {
+    watcher = fs3.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
@@ -440,6 +637,9 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     console.warn(chalk.yellow("fs.watch unavailable; falling back to polling for route changes"));
     pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS);
   }
+  if (autoSyncHosts) {
+    syncHostsFile(cachedRoutes.map((r) => r.hostname));
+  }
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
     proxyPort,
@@ -465,8 +665,8 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     process.exit(1);
   });
   server.listen(proxyPort, () => {
-    fs2.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
-    fs2.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
+    fs3.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+    fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
     fixOwnership(store.dir, store.pidPath, store.portFilePath);
     const proto = isTls ? "HTTPS/2" : "HTTP";
@@ -482,14 +682,15 @@ function startProxyServer(store, proxyPort, tlsOptions) {
       watcher.close();
     }
     try {
-      fs2.unlinkSync(store.pidPath);
+      fs3.unlinkSync(store.pidPath);
     } catch {
     }
     try {
-      fs2.unlinkSync(store.portFilePath);
+      fs3.unlinkSync(store.portFilePath);
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    if (autoSyncHosts) cleanHostsFile();
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref();
   };
@@ -502,7 +703,7 @@ async function stopProxy(store, proxyPort, tls2) {
   const pidPath = store.pidPath;
   const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
   const sudoHint = needsSudo ? "sudo " : "";
-  if (!fs2.existsSync(pidPath)) {
+  if (!fs3.existsSync(pidPath)) {
     if (await isProxyRunning(proxyPort, tls2)) {
       console.log(chalk.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
@@ -510,7 +711,7 @@ async function stopProxy(store, proxyPort, tls2) {
         try {
           process.kill(pid, "SIGTERM");
           try {
-            fs2.unlinkSync(store.portFilePath);
+            fs3.unlinkSync(store.portFilePath);
           } catch {
           }
           console.log(chalk.green(`Killed process ${pid}. Proxy stopped.`));
@@ -541,19 +742,19 @@ async function stopProxy(store, proxyPort, tls2) {
     return;
   }
   try {
-    const pid = parseInt(fs2.readFileSync(pidPath, "utf-8"), 10);
+    const pid = parseInt(fs3.readFileSync(pidPath, "utf-8"), 10);
     if (isNaN(pid)) {
       console.error(chalk.red("Corrupted PID file. Removing it."));
-      fs2.unlinkSync(pidPath);
+      fs3.unlinkSync(pidPath);
       return;
     }
     try {
       process.kill(pid, 0);
     } catch {
       console.log(chalk.yellow("Proxy process is no longer running. Cleaning up stale files."));
-      fs2.unlinkSync(pidPath);
+      fs3.unlinkSync(pidPath);
       try {
-        fs2.unlinkSync(store.portFilePath);
+        fs3.unlinkSync(store.portFilePath);
       } catch {
       }
       return;
@@ -565,13 +766,13 @@ async function stopProxy(store, proxyPort, tls2) {
         )
       );
       console.log(chalk.yellow("Removing stale PID file."));
-      fs2.unlinkSync(pidPath);
+      fs3.unlinkSync(pidPath);
       return;
     }
     process.kill(pid, "SIGTERM");
-    fs2.unlinkSync(pidPath);
+    fs3.unlinkSync(pidPath);
     try {
-      fs2.unlinkSync(store.portFilePath);
+      fs3.unlinkSync(store.portFilePath);
     } catch {
     }
     console.log(chalk.green("Proxy stopped."));
@@ -598,18 +799,26 @@ 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 label = route.pid === 0 ? "(alias)" : `(pid ${route.pid})`;
     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(label)}`
     );
   }
   console.log();
 }
-async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, force) {
+async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, force, autoInfo, desiredPort) {
   const hostname = parseHostname(name);
   console.log(chalk.blue.bold(`
 portless
 `));
   console.log(chalk.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`));
+  if (autoInfo) {
+    const baseName = autoInfo.prefix ? name.slice(autoInfo.prefix.length + 1) : name;
+    console.log(chalk.gray(`-- Name "${baseName}" (from ${autoInfo.nameSource})`));
+    if (autoInfo.prefix) {
+      console.log(chalk.gray(`-- Prefix "${autoInfo.prefix}" (from ${autoInfo.prefixSource})`));
+    }
+  }
   if (!await isProxyRunning(proxyPort, tls2)) {
     const defaultPort = getDefaultPort();
     const needsSudo = defaultPort < PRIVILEGED_PORT_THRESHOLD;
@@ -664,10 +873,10 @@ portless
     const autoTls = readTlsMarker(stateDir);
     if (!await waitForProxy(defaultPort, void 0, void 0, autoTls)) {
       console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
-      const logPath = path2.join(stateDir, "proxy.log");
+      const logPath = path3.join(stateDir, "proxy.log");
       console.error(chalk.blue("Try starting the proxy manually to see the error:"));
       console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start`));
-      if (fs2.existsSync(logPath)) {
+      if (fs3.existsSync(logPath)) {
         console.error(chalk.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
@@ -677,8 +886,12 @@ portless
   } else {
     console.log(chalk.gray("-- Proxy is running"));
   }
-  const port = await findFreePort();
-  console.log(chalk.green(`-- Using port ${port}`));
+  const port = desiredPort ?? await findFreePort();
+  if (desiredPort) {
+    console.log(chalk.green(`-- Using port ${port} (fixed)`));
+  } else {
+    console.log(chalk.green(`-- Using port ${port}`));
+  }
   try {
     store.addRoute(hostname, port, process.pid, force);
   } catch (err) {
@@ -693,13 +906,18 @@ portless
   -> ${finalUrl}
 `));
   injectFrameworkFlags(commandArgs, port);
-  console.log(chalk.gray(`Running: PORT=${port} HOST=127.0.0.1 ${commandArgs.join(" ")}
-`));
+  console.log(
+    chalk.gray(
+      `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}
+`
+    )
+  );
   spawnCommand(commandArgs, {
     env: {
       ...process.env,
       PORT: port.toString(),
       HOST: "127.0.0.1",
+      PORTLESS_URL: finalUrl,
       __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: ".localhost"
     },
     onCleanup: () => {
@@ -710,31 +928,120 @@ portless
     }
   });
 }
-async function main() {
-  if (process.stdin.isTTY) {
-    process.on("exit", () => {
-      try {
-        process.stdin.setRawMode(false);
-      } catch {
-      }
-    });
+function parseAppPort(value) {
+  if (!value || value.startsWith("--")) {
+    console.error(chalk.red("Error: --app-port requires a port number."));
+    process.exit(1);
   }
-  const args = process.argv.slice(2);
-  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) {
-    console.error(chalk.red("Error: portless should not be run via npx or pnpm dlx."));
-    console.error(chalk.blue("Install globally instead:"));
-    console.error(chalk.cyan("  npm install -g portless"));
+  const port = parseInt(value, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(chalk.red(`Error: Invalid app port "${value}". Must be 1-65535.`));
     process.exit(1);
   }
-  const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
-  if (skipPortless && args.length >= 2 && args[0] !== "proxy") {
-    spawnCommand(args.slice(1));
-    return;
+  return port;
+}
+function appPortFromEnv() {
+  const envVal = process.env.PORTLESS_APP_PORT;
+  if (!envVal) return void 0;
+  const port = parseInt(envVal, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(chalk.red(`Error: Invalid PORTLESS_APP_PORT="${envVal}". Must be 1-65535.`));
+    process.exit(1);
   }
-  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-    console.log(`
+  return port;
+}
+function parseRunArgs(args) {
+  let force = false;
+  let appPort;
+  let i = 0;
+  while (i < args.length && args[i].startsWith("-")) {
+    if (args[i] === "--") {
+      i++;
+      break;
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      console.log(`
+${chalk.bold("portless run")} - Infer project name and run through the proxy.
+
+${chalk.bold("Usage:")}
+  ${chalk.cyan("portless run [options] <command...>")}
+
+${chalk.bold("Options:")}
+  --force                Override an existing route registered by another process
+  --app-port <number>    Use a fixed port for the app (skip auto-assignment)
+  --help, -h             Show this help
+
+${chalk.bold("Name inference (in order):")}
+  1. package.json "name" field (walks up directories)
+  2. Git repo root directory name
+  3. Current directory basename
+
+  In git worktrees, the branch name is prepended as a subdomain prefix
+  (e.g. feature-auth.myapp.localhost).
+
+${chalk.bold("Examples:")}
+  portless run next dev               # -> http://<project>.localhost:1355
+  portless run vite dev               # -> http://<project>.localhost:1355
+  portless run --app-port 3000 pnpm start
+`);
+      process.exit(0);
+    } else if (args[i] === "--force") {
+      force = true;
+    } else if (args[i] === "--app-port") {
+      i++;
+      appPort = parseAppPort(args[i]);
+    } else {
+      console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
+      console.error(chalk.blue("Known flags: --force, --app-port, --help"));
+      process.exit(1);
+    }
+    i++;
+  }
+  if (!appPort) appPort = appPortFromEnv();
+  return { force, appPort, commandArgs: args.slice(i) };
+}
+function parseAppArgs(args) {
+  let force = false;
+  let appPort;
+  let i = 0;
+  while (i < args.length && args[i].startsWith("-")) {
+    if (args[i] === "--") {
+      i++;
+      break;
+    } else if (args[i] === "--force") {
+      force = true;
+    } else if (args[i] === "--app-port") {
+      i++;
+      appPort = parseAppPort(args[i]);
+    } else {
+      console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
+      console.error(chalk.blue("Known flags: --force, --app-port"));
+      process.exit(1);
+    }
+    i++;
+  }
+  const name = args[i];
+  i++;
+  while (i < args.length && args[i].startsWith("--")) {
+    if (args[i] === "--") {
+      i++;
+      break;
+    } else if (args[i] === "--force") {
+      force = true;
+    } else if (args[i] === "--app-port") {
+      i++;
+      appPort = parseAppPort(args[i]);
+    } else {
+      console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
+      console.error(chalk.blue("Known flags: --force, --app-port"));
+      process.exit(1);
+    }
+    i++;
+  }
+  if (!appPort) appPort = appPortFromEnv();
+  return { force, appPort, name, commandArgs: args.slice(i) };
+}
+function printHelp() {
+  console.log(`
 ${chalk.bold("portless")} - Replace port numbers with stable, named .localhost URLs. For humans and agents.
 
 Eliminates port conflicts, memorizing port numbers, and cookie/storage
@@ -750,8 +1057,13 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("portless proxy start -p 80")}       Start on port 80 (requires sudo)
   ${chalk.cyan("portless proxy stop")}              Stop the proxy
   ${chalk.cyan("portless <name> <cmd>")}            Run your app through the proxy
+  ${chalk.cyan("portless run <cmd>")}               Infer name from project, run through proxy
+  ${chalk.cyan("portless alias <name> <port>")}     Register a static route (e.g. for Docker)
+  ${chalk.cyan("portless alias --remove <name>")}   Remove a static route
   ${chalk.cyan("portless list")}                    Show active routes
   ${chalk.cyan("portless trust")}                   Add local CA to system trust store
+  ${chalk.cyan("portless hosts sync")}              Add routes to /etc/hosts (fixes Safari)
+  ${chalk.cyan("portless hosts clean")}             Remove portless entries from /etc/hosts
 
 ${chalk.bold("Examples:")}
   portless proxy start                # Start proxy on port 1355
@@ -759,21 +1071,25 @@ ${chalk.bold("Examples:")}
   portless myapp next dev             # -> http://myapp.localhost:1355
   portless myapp vite dev             # -> http://myapp.localhost:1355
   portless api.myapp pnpm start       # -> http://api.myapp.localhost:1355
+  portless run next dev               # -> http://<project>.localhost:1355
+  portless run next dev               # in worktree -> http://<worktree>.<project>.localhost:1355
+  # Wildcard subdomains: tenant.myapp.localhost also routes to myapp
 
 ${chalk.bold("In package.json:")}
   {
     "scripts": {
-      "dev": "portless myapp next dev"
+      "dev": "portless run next dev"
     }
   }
 
 ${chalk.bold("How it works:")}
   1. Start the proxy once (listens on port 1355 by default, no sudo needed)
   2. Run your apps - they auto-start the proxy and register automatically
+     (apps get a random port in the 4000-4999 range via PORT)
   3. Access via http://<name>.localhost:1355
   4. .localhost domains auto-resolve to 127.0.0.1
-  5. Frameworks that ignore PORT (Vite, Astro, React Router, Angular) get
-     --port and --host flags injected automatically
+  5. Frameworks that ignore PORT (Vite, Astro, React Router, Angular,
+     Expo, React Native) get --port and --host flags injected automatically
 
 ${chalk.bold("HTTP/2 + HTTPS:")}
   Use --https for HTTP/2 multiplexing (faster dev server page loads).
@@ -781,6 +1097,8 @@ ${chalk.bold("HTTP/2 + HTTPS:")}
   system trust store. No browser warnings. No sudo required on macOS.
 
 ${chalk.bold("Options:")}
+  run <cmd>                      Infer project name from package.json / git / cwd
+                                Adds worktree prefix in git worktrees
   -p, --port <number>           Port for the proxy to listen on (default: 1355)
                                 Ports < 1024 require sudo
   --https                       Enable HTTP/2 + TLS with auto-generated certs
@@ -788,252 +1106,423 @@ ${chalk.bold("Options:")}
   --key <path>                  Use a custom TLS private key (implies --https)
   --no-tls                      Disable HTTPS (overrides PORTLESS_HTTPS)
   --foreground                  Run proxy in foreground (for debugging)
+  --app-port <number>           Use a fixed port for the app (skip auto-assignment)
   --force                       Override an existing route registered by another process
+  --name <name>                 Use <name> as the app name (bypasses subcommand dispatch)
+  --                            Stop flag parsing; everything after is passed to the child
 
 ${chalk.bold("Environment variables:")}
   PORTLESS_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
-  PORTLESS_HTTPS=1              Always enable HTTPS (set in .bashrc / .zshrc)
+  PORTLESS_APP_PORT=<number>    Use a fixed port for the app (same as --app-port)
+  PORTLESS_HTTPS=1|true         Always enable HTTPS (set in .bashrc / .zshrc)
+  PORTLESS_SYNC_HOSTS=1         Auto-sync /etc/hosts (requires sudo proxy start)
   PORTLESS_STATE_DIR=<path>     Override the state directory
   PORTLESS=0 | PORTLESS=skip    Run command directly without proxy
 
+${chalk.bold("Child process environment:")}
+  PORT                          Ephemeral port the child should listen on
+  HOST                          Always 127.0.0.1
+  PORTLESS_URL                  Public URL of the app (e.g. http://myapp.localhost:1355)
+
+${chalk.bold("Safari / DNS:")}
+  .localhost subdomains auto-resolve in Chrome, Firefox, and Edge.
+  Safari relies on the system DNS resolver, which may not handle them.
+  If Safari can't find your .localhost URL, run:
+    ${chalk.cyan("sudo portless hosts sync")}
+  This adds entries to /etc/hosts. Clean up later with:
+    ${chalk.cyan("sudo portless hosts clean")}
+  To auto-sync whenever routes change, set PORTLESS_SYNC_HOSTS=1 and
+  start the proxy with sudo.
+
 ${chalk.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
   PORTLESS=skip pnpm dev        # Same as above
+
+${chalk.bold("Reserved names:")}
+  run, alias, hosts, list, trust, proxy are subcommands and cannot be
+  used as app names directly. Use "portless run" to infer the name, or
+  "portless --name <name>" to force any name including reserved ones.
+`);
+  process.exit(0);
+}
+function printVersion() {
+  console.log("0.5.1");
+  process.exit(0);
+}
+async function handleTrust() {
+  const { dir } = await discoverState();
+  const result = trustCA(dir);
+  if (result.trusted) {
+    console.log(chalk.green("Local CA added to system trust store."));
+    console.log(chalk.gray("Browsers will now trust portless HTTPS certificates."));
+  } else {
+    console.error(chalk.red(`Failed to trust CA: ${result.error}`));
+    if (result.error?.includes("sudo")) {
+      console.error(chalk.blue("Run with sudo:"));
+      console.error(chalk.cyan("  sudo portless trust"));
+    }
+    process.exit(1);
+  }
+}
+async function handleList() {
+  const { dir, port, tls: tls2 } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(chalk.yellow(msg))
+  });
+  listRoutes(store, port, tls2);
+}
+async function handleAlias(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${chalk.bold("portless alias")} - Register a static route for services not managed by portless.
+
+${chalk.bold("Usage:")}
+  ${chalk.cyan("portless alias <name> <port>")}        Register a route
+  ${chalk.cyan("portless alias --remove <name>")}      Remove a route
+  ${chalk.cyan("portless alias <name> <port> --force")} Override existing route
+
+${chalk.bold("Examples:")}
+  portless alias my-postgres 5432     # -> http://my-postgres.localhost:1355
+  portless alias redis 6379           # -> http://redis.localhost:1355
+  portless alias --remove my-postgres # Remove the alias
 `);
     process.exit(0);
   }
-  if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.4.2");
+  const { dir } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(chalk.yellow(msg))
+  });
+  if (args[1] === "--remove") {
+    const aliasName2 = args[2];
+    if (!aliasName2) {
+      console.error(chalk.red("Error: No alias name provided."));
+      console.error(chalk.cyan("  portless alias --remove <name>"));
+      process.exit(1);
+    }
+    const hostname2 = parseHostname(aliasName2);
+    const routes = store.loadRoutes();
+    const existing = routes.find((r) => r.hostname === hostname2 && r.pid === 0);
+    if (!existing) {
+      console.error(chalk.red(`Error: No alias found for "${hostname2}".`));
+      process.exit(1);
+    }
+    store.removeRoute(hostname2);
+    console.log(chalk.green(`Removed alias: ${hostname2}`));
+    return;
+  }
+  const aliasName = args[1];
+  const aliasPort = args[2];
+  if (!aliasName || !aliasPort) {
+    console.error(chalk.red("Error: Missing arguments."));
+    console.error(chalk.blue("Usage:"));
+    console.error(chalk.cyan("  portless alias <name> <port>"));
+    console.error(chalk.cyan("  portless alias --remove <name>"));
+    console.error(chalk.blue("Example:"));
+    console.error(chalk.cyan("  portless alias my-postgres 5432"));
+    process.exit(1);
+  }
+  const hostname = parseHostname(aliasName);
+  const port = parseInt(aliasPort, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(chalk.red(`Error: Invalid port "${aliasPort}". Must be 1-65535.`));
+    process.exit(1);
+  }
+  const force = args.includes("--force");
+  store.addRoute(hostname, port, 0, force);
+  console.log(chalk.green(`Alias registered: ${hostname} -> localhost:${port}`));
+}
+async function handleHosts(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${chalk.bold("portless hosts")} - Manage /etc/hosts entries for .localhost subdomains.
+
+Safari relies on the system DNS resolver, which may not handle .localhost
+subdomains. This command adds entries to /etc/hosts as a workaround.
+
+${chalk.bold("Usage:")}
+  ${chalk.cyan("sudo portless hosts sync")}    Add current routes to /etc/hosts
+  ${chalk.cyan("sudo portless hosts clean")}   Remove portless entries from /etc/hosts
+
+${chalk.bold("Auto-sync:")}
+  Set PORTLESS_SYNC_HOSTS=1 and start the proxy with sudo to auto-sync
+  /etc/hosts whenever routes change.
+`);
     process.exit(0);
   }
-  if (args[0] === "trust") {
-    const { dir: dir2 } = await discoverState();
-    const result = trustCA(dir2);
-    if (result.trusted) {
-      console.log(chalk.green("Local CA added to system trust store."));
-      console.log(chalk.gray("Browsers will now trust portless HTTPS certificates."));
+  if (args[1] === "clean") {
+    if (cleanHostsFile()) {
+      console.log(chalk.green("Removed portless entries from /etc/hosts."));
     } else {
-      console.error(chalk.red(`Failed to trust CA: ${result.error}`));
-      if (result.error?.includes("sudo")) {
-        console.error(chalk.blue("Run with sudo:"));
-        console.error(chalk.cyan("  sudo portless trust"));
-      }
+      console.error(chalk.red("Failed to update /etc/hosts (requires sudo)."));
+      console.error(chalk.cyan("  sudo portless hosts clean"));
       process.exit(1);
     }
     return;
   }
-  if (args[0] === "list") {
-    const { dir: dir2, port: port2, tls: tls3 } = await discoverState();
-    const store2 = new RouteStore(dir2, {
+  if (!args[1]) {
+    console.log(`
+${chalk.bold("Usage: portless hosts <command>")}
+
+  ${chalk.cyan("sudo portless hosts sync")}    Add current routes to /etc/hosts
+  ${chalk.cyan("sudo portless hosts clean")}   Remove portless entries from /etc/hosts
+`);
+    process.exit(0);
+  }
+  if (args[1] !== "sync") {
+    console.error(chalk.red(`Error: Unknown hosts subcommand "${args[1]}".`));
+    console.error(chalk.blue("Usage:"));
+    console.error(chalk.cyan("  portless hosts sync    # Add routes to /etc/hosts"));
+    console.error(chalk.cyan("  portless hosts clean   # Remove portless entries"));
+    process.exit(1);
+  }
+  const { dir } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(chalk.yellow(msg))
+  });
+  const routes = store.loadRoutes();
+  if (routes.length === 0) {
+    console.log(chalk.yellow("No active routes to sync."));
+    return;
+  }
+  const hostnames = routes.map((r) => r.hostname);
+  if (syncHostsFile(hostnames)) {
+    console.log(chalk.green(`Synced ${hostnames.length} hostname(s) to /etc/hosts:`));
+    for (const h of hostnames) {
+      console.log(chalk.cyan(`  127.0.0.1 ${h}`));
+    }
+  } else {
+    console.error(chalk.red("Failed to update /etc/hosts (requires sudo)."));
+    console.error(chalk.cyan("  sudo portless hosts sync"));
+    process.exit(1);
+  }
+}
+async function handleProxy(args) {
+  if (args[1] === "stop") {
+    const { dir, port, tls: tls2 } = await discoverState();
+    const store2 = new RouteStore(dir, {
       onWarning: (msg) => console.warn(chalk.yellow(msg))
     });
-    listRoutes(store2, port2, tls3);
+    await stopProxy(store2, port, tls2);
     return;
   }
-  if (args[0] === "proxy") {
-    if (args[1] === "stop") {
-      const { dir: dir2, port: port2, tls: tls3 } = await discoverState();
-      const store3 = new RouteStore(dir2, {
-        onWarning: (msg) => console.warn(chalk.yellow(msg))
-      });
-      await stopProxy(store3, port2, tls3);
-      return;
-    }
-    if (args[1] !== "start") {
-      console.log(`
-${chalk.bold("Usage: portless proxy <command>")}
+  const isProxyHelp = args[1] === "--help" || args[1] === "-h";
+  if (isProxyHelp || args[1] !== "start") {
+    console.log(`
+${chalk.bold("portless proxy")} - Manage the portless proxy server.
 
+${chalk.bold("Usage:")}
   ${chalk.cyan("portless proxy start")}                Start the proxy (daemon)
   ${chalk.cyan("portless proxy start --https")}        Start with HTTP/2 + TLS
   ${chalk.cyan("portless proxy start --foreground")}   Start in foreground (for debugging)
   ${chalk.cyan("portless proxy start -p 80")}          Start on port 80 (requires sudo)
   ${chalk.cyan("portless proxy stop")}                 Stop the proxy
 `);
-      process.exit(args[1] ? 1 : 0);
-    }
-    const isForeground = args.includes("--foreground");
-    let proxyPort = getDefaultPort();
-    let portFlagIndex = args.indexOf("--port");
-    if (portFlagIndex === -1) portFlagIndex = args.indexOf("-p");
-    if (portFlagIndex !== -1) {
-      const portValue = args[portFlagIndex + 1];
-      if (!portValue || portValue.startsWith("-")) {
-        console.error(chalk.red("Error: --port / -p requires a port number."));
-        console.error(chalk.blue("Usage:"));
-        console.error(chalk.cyan("  portless proxy start -p 8080"));
-        process.exit(1);
-      }
-      proxyPort = parseInt(portValue, 10);
-      if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
-        console.error(chalk.red(`Error: Invalid port number: ${portValue}`));
-        console.error(chalk.blue("Port must be between 1 and 65535."));
-        process.exit(1);
-      }
-    }
-    const hasNoTls = args.includes("--no-tls");
-    const hasHttpsFlag = args.includes("--https");
-    const wantHttps = !hasNoTls && (hasHttpsFlag || isHttpsEnvEnabled());
-    let customCertPath = null;
-    let customKeyPath = null;
-    const certIdx = args.indexOf("--cert");
-    if (certIdx !== -1) {
-      customCertPath = args[certIdx + 1] || null;
-      if (!customCertPath || customCertPath.startsWith("-")) {
-        console.error(chalk.red("Error: --cert requires a file path."));
-        process.exit(1);
-      }
-    }
-    const keyIdx = args.indexOf("--key");
-    if (keyIdx !== -1) {
-      customKeyPath = args[keyIdx + 1] || null;
-      if (!customKeyPath || customKeyPath.startsWith("-")) {
-        console.error(chalk.red("Error: --key requires a file path."));
-        process.exit(1);
-      }
-    }
-    if (customCertPath && !customKeyPath || !customCertPath && customKeyPath) {
-      console.error(chalk.red("Error: --cert and --key must be used together."));
+    process.exit(isProxyHelp || !args[1] ? 0 : 1);
+  }
+  const isForeground = args.includes("--foreground");
+  let proxyPort = getDefaultPort();
+  let portFlagIndex = args.indexOf("--port");
+  if (portFlagIndex === -1) portFlagIndex = args.indexOf("-p");
+  if (portFlagIndex !== -1) {
+    const portValue = args[portFlagIndex + 1];
+    if (!portValue || portValue.startsWith("-")) {
+      console.error(chalk.red("Error: --port / -p requires a port number."));
+      console.error(chalk.blue("Usage:"));
+      console.error(chalk.cyan("  portless proxy start -p 8080"));
       process.exit(1);
     }
-    const useHttps = wantHttps || !!(customCertPath && customKeyPath);
-    const stateDir = resolveStateDir(proxyPort);
-    const store2 = new RouteStore(stateDir, {
-      onWarning: (msg) => console.warn(chalk.yellow(msg))
-    });
-    if (await isProxyRunning(proxyPort)) {
-      if (isForeground) {
-        return;
-      }
-      const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
-      const sudoPrefix = needsSudo ? "sudo " : "";
-      console.log(chalk.yellow(`Proxy is already running on port ${proxyPort}.`));
-      console.log(
-        chalk.blue(`To restart: portless proxy stop && ${sudoPrefix}portless proxy start`)
-      );
-      return;
+    proxyPort = parseInt(portValue, 10);
+    if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
+      console.error(chalk.red(`Error: Invalid port number: ${portValue}`));
+      console.error(chalk.blue("Port must be between 1 and 65535."));
+      process.exit(1);
     }
-    if (proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
-      console.error(chalk.red(`Error: Port ${proxyPort} requires sudo.`));
-      console.error(chalk.blue("Either run with sudo:"));
-      console.error(chalk.cyan("  sudo portless proxy start -p 80"));
-      console.error(chalk.blue("Or use the default port (no sudo needed):"));
-      console.error(chalk.cyan("  portless proxy start"));
+  }
+  const hasNoTls = args.includes("--no-tls");
+  const hasHttpsFlag = args.includes("--https");
+  const wantHttps = !hasNoTls && (hasHttpsFlag || isHttpsEnvEnabled());
+  let customCertPath = null;
+  let customKeyPath = null;
+  const certIdx = args.indexOf("--cert");
+  if (certIdx !== -1) {
+    customCertPath = args[certIdx + 1] || null;
+    if (!customCertPath || customCertPath.startsWith("-")) {
+      console.error(chalk.red("Error: --cert requires a file path."));
       process.exit(1);
     }
-    let tlsOptions;
-    if (useHttps) {
-      store2.ensureDir();
-      if (customCertPath && customKeyPath) {
-        try {
-          const cert = fs2.readFileSync(customCertPath);
-          const key = fs2.readFileSync(customKeyPath);
-          const certStr = cert.toString("utf-8");
-          const keyStr = key.toString("utf-8");
-          if (!certStr.includes("-----BEGIN CERTIFICATE-----")) {
-            console.error(chalk.red(`Error: ${customCertPath} is not a valid PEM certificate.`));
-            console.error(chalk.gray("Expected a file starting with -----BEGIN CERTIFICATE-----"));
-            process.exit(1);
-          }
-          if (!keyStr.match(/-----BEGIN [\w\s]*PRIVATE KEY-----/)) {
-            console.error(chalk.red(`Error: ${customKeyPath} is not a valid PEM private key.`));
-            console.error(
-              chalk.gray("Expected a file starting with -----BEGIN ...PRIVATE KEY-----")
-            );
-            process.exit(1);
-          }
-          tlsOptions = { cert, key };
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          console.error(chalk.red(`Error reading certificate files: ${message}`));
-          process.exit(1);
-        }
-      } else {
-        console.log(chalk.gray("Ensuring TLS certificates..."));
-        const certs = ensureCerts(stateDir);
-        if (certs.caGenerated) {
-          console.log(chalk.green("Generated local CA certificate."));
-        }
-        if (!isCATrusted(stateDir)) {
-          console.log(chalk.yellow("Adding CA to system trust store..."));
-          const trustResult = trustCA(stateDir);
-          if (trustResult.trusted) {
-            console.log(
-              chalk.green("CA added to system trust store. Browsers will trust portless certs.")
-            );
-          } else {
-            console.warn(chalk.yellow("Could not add CA to system trust store."));
-            if (trustResult.error) {
-              console.warn(chalk.gray(trustResult.error));
-            }
-            console.warn(
-              chalk.yellow("Browsers will show certificate warnings. To fix this later, run:")
-            );
-            console.warn(chalk.cyan("  portless trust"));
-          }
-        }
-        const cert = fs2.readFileSync(certs.certPath);
-        const key = fs2.readFileSync(certs.keyPath);
-        tlsOptions = {
-          cert,
-          key,
-          SNICallback: createSNICallback(stateDir, cert, key)
-        };
-      }
+  }
+  const keyIdx = args.indexOf("--key");
+  if (keyIdx !== -1) {
+    customKeyPath = args[keyIdx + 1] || null;
+    if (!customKeyPath || customKeyPath.startsWith("-")) {
+      console.error(chalk.red("Error: --key requires a file path."));
+      process.exit(1);
     }
+  }
+  if (customCertPath && !customKeyPath || !customCertPath && customKeyPath) {
+    console.error(chalk.red("Error: --cert and --key must be used together."));
+    process.exit(1);
+  }
+  const useHttps = wantHttps || !!(customCertPath && customKeyPath);
+  const stateDir = resolveStateDir(proxyPort);
+  const store = new RouteStore(stateDir, {
+    onWarning: (msg) => console.warn(chalk.yellow(msg))
+  });
+  if (await isProxyRunning(proxyPort)) {
     if (isForeground) {
-      console.log(chalk.blue.bold("\nportless proxy\n"));
-      startProxyServer(store2, proxyPort, tlsOptions);
       return;
     }
-    store2.ensureDir();
-    const logPath = path2.join(stateDir, "proxy.log");
-    const logFd = fs2.openSync(logPath, "a");
-    try {
+    const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+    const sudoPrefix = needsSudo ? "sudo " : "";
+    console.log(chalk.yellow(`Proxy is already running on port ${proxyPort}.`));
+    console.log(chalk.blue(`To restart: portless proxy stop && ${sudoPrefix}portless proxy start`));
+    return;
+  }
+  if (proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
+    console.error(chalk.red(`Error: Port ${proxyPort} requires sudo.`));
+    console.error(chalk.blue("Either run with sudo:"));
+    console.error(chalk.cyan("  sudo portless proxy start -p 80"));
+    console.error(chalk.blue("Or use the default port (no sudo needed):"));
+    console.error(chalk.cyan("  portless proxy start"));
+    process.exit(1);
+  }
+  let tlsOptions;
+  if (useHttps) {
+    store.ensureDir();
+    if (customCertPath && customKeyPath) {
       try {
-        fs2.chmodSync(logPath, FILE_MODE);
-      } catch {
+        const cert = fs3.readFileSync(customCertPath);
+        const key = fs3.readFileSync(customKeyPath);
+        const certStr = cert.toString("utf-8");
+        const keyStr = key.toString("utf-8");
+        if (!certStr.includes("-----BEGIN CERTIFICATE-----")) {
+          console.error(chalk.red(`Error: ${customCertPath} is not a valid PEM certificate.`));
+          console.error(chalk.gray("Expected a file starting with -----BEGIN CERTIFICATE-----"));
+          process.exit(1);
+        }
+        if (!keyStr.match(/-----BEGIN [\w\s]*PRIVATE KEY-----/)) {
+          console.error(chalk.red(`Error: ${customKeyPath} is not a valid PEM private key.`));
+          console.error(chalk.gray("Expected a file starting with -----BEGIN ...PRIVATE KEY-----"));
+          process.exit(1);
+        }
+        tlsOptions = { cert, key };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Error reading certificate files: ${message}`));
+        process.exit(1);
       }
-      fixOwnership(logPath);
-      const daemonArgs = [process.argv[1], "proxy", "start", "--foreground"];
-      if (portFlagIndex !== -1) {
-        daemonArgs.push("--port", proxyPort.toString());
+    } else {
+      console.log(chalk.gray("Ensuring TLS certificates..."));
+      const certs = ensureCerts(stateDir);
+      if (certs.caGenerated) {
+        console.log(chalk.green("Generated local CA certificate."));
       }
-      if (useHttps) {
-        if (customCertPath && customKeyPath) {
-          daemonArgs.push("--cert", customCertPath, "--key", customKeyPath);
+      if (!isCATrusted(stateDir)) {
+        console.log(chalk.yellow("Adding CA to system trust store..."));
+        const trustResult = trustCA(stateDir);
+        if (trustResult.trusted) {
+          console.log(
+            chalk.green("CA added to system trust store. Browsers will trust portless certs.")
+          );
         } else {
-          daemonArgs.push("--https");
+          console.warn(chalk.yellow("Could not add CA to system trust store."));
+          if (trustResult.error) {
+            console.warn(chalk.gray(trustResult.error));
+          }
+          console.warn(
+            chalk.yellow("Browsers will show certificate warnings. To fix this later, run:")
+          );
+          console.warn(chalk.cyan("  portless trust"));
         }
       }
-      const child = spawn(process.execPath, daemonArgs, {
-        detached: true,
-        stdio: ["ignore", logFd, logFd],
-        env: process.env
-      });
-      child.unref();
-    } finally {
-      fs2.closeSync(logFd);
+      const cert = fs3.readFileSync(certs.certPath);
+      const key = fs3.readFileSync(certs.keyPath);
+      tlsOptions = {
+        cert,
+        key,
+        SNICallback: createSNICallback(stateDir, cert, key)
+      };
     }
-    if (!await waitForProxy(proxyPort, void 0, void 0, useHttps)) {
-      console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
-      console.error(chalk.blue("Try starting the proxy in the foreground to see the error:"));
-      const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
-      console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start --foreground`));
-      if (fs2.existsSync(logPath)) {
-        console.error(chalk.gray(`Logs: ${logPath}`));
+  }
+  if (isForeground) {
+    console.log(chalk.blue.bold("\nportless proxy\n"));
+    startProxyServer(store, proxyPort, tlsOptions);
+    return;
+  }
+  store.ensureDir();
+  const logPath = path3.join(stateDir, "proxy.log");
+  const logFd = fs3.openSync(logPath, "a");
+  try {
+    try {
+      fs3.chmodSync(logPath, FILE_MODE);
+    } catch {
+    }
+    fixOwnership(logPath);
+    const daemonArgs = [process.argv[1], "proxy", "start", "--foreground"];
+    if (portFlagIndex !== -1) {
+      daemonArgs.push("--port", proxyPort.toString());
+    }
+    if (useHttps) {
+      if (customCertPath && customKeyPath) {
+        daemonArgs.push("--cert", customCertPath, "--key", customKeyPath);
+      } else {
+        daemonArgs.push("--https");
       }
-      process.exit(1);
     }
-    const proto = useHttps ? "HTTPS/2" : "HTTP";
-    console.log(chalk.green(`${proto} proxy started on port ${proxyPort}`));
-    return;
+    const child = spawn(process.execPath, daemonArgs, {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: process.env
+    });
+    child.unref();
+  } finally {
+    fs3.closeSync(logFd);
   }
-  const forceIdx = args.indexOf("--force");
-  const force = forceIdx >= 0 && forceIdx <= 1;
-  const appArgs = force ? [...args.slice(0, forceIdx), ...args.slice(forceIdx + 1)] : args;
-  const name = appArgs[0];
-  const commandArgs = appArgs.slice(1);
-  if (commandArgs.length === 0) {
+  if (!await waitForProxy(proxyPort, void 0, void 0, useHttps)) {
+    console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
+    console.error(chalk.blue("Try starting the proxy in the foreground to see the error:"));
+    const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+    console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start --foreground`));
+    if (fs3.existsSync(logPath)) {
+      console.error(chalk.gray(`Logs: ${logPath}`));
+    }
+    process.exit(1);
+  }
+  const proto = useHttps ? "HTTPS/2" : "HTTP";
+  console.log(chalk.green(`${proto} proxy started on port ${proxyPort}`));
+}
+async function handleRunMode(args) {
+  const parsed = parseRunArgs(args);
+  if (parsed.commandArgs.length === 0) {
+    console.error(chalk.red("Error: No command provided."));
+    console.error(chalk.blue("Usage:"));
+    console.error(chalk.cyan("  portless run <command...>"));
+    console.error(chalk.blue("Example:"));
+    console.error(chalk.cyan("  portless run next dev"));
+    process.exit(1);
+  }
+  const inferred = inferProjectName();
+  const worktree = detectWorktreePrefix();
+  const effectiveName = worktree ? `${worktree.prefix}.${inferred.name}` : inferred.name;
+  const { dir, port, tls: tls2 } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(chalk.yellow(msg))
+  });
+  await runApp(
+    store,
+    port,
+    dir,
+    effectiveName,
+    parsed.commandArgs,
+    tls2,
+    parsed.force,
+    { nameSource: inferred.source, prefix: worktree?.prefix, prefixSource: worktree?.source },
+    parsed.appPort
+  );
+}
+async function handleNamedMode(args) {
+  const parsed = parseAppArgs(args);
+  if (parsed.commandArgs.length === 0) {
     console.error(chalk.red("Error: No command provided."));
     console.error(chalk.blue("Usage:"));
     console.error(chalk.cyan("  portless <name> <command...>"));
@@ -1045,7 +1534,105 @@ ${chalk.bold("Usage: portless 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,
+    parsed.name,
+    parsed.commandArgs,
+    tls2,
+    parsed.force,
+    void 0,
+    parsed.appPort
+  );
+}
+async function main() {
+  if (process.stdin.isTTY) {
+    process.on("exit", () => {
+      try {
+        process.stdin.setRawMode(false);
+      } catch {
+      }
+    });
+  }
+  const args = process.argv.slice(2);
+  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) {
+    console.error(chalk.red("Error: portless should not be run via npx or pnpm dlx."));
+    console.error(chalk.blue("Install globally instead:"));
+    console.error(chalk.cyan("  npm install -g portless"));
+    process.exit(1);
+  }
+  if (args[0] === "--name") {
+    args.shift();
+    if (!args[0]) {
+      console.error(chalk.red("Error: --name requires an app name."));
+      console.error(chalk.cyan("  portless --name <name> <command...>"));
+      process.exit(1);
+    }
+    const skipPortless2 = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
+    if (skipPortless2) {
+      const { commandArgs } = parseAppArgs(args);
+      if (commandArgs.length === 0) {
+        console.error(chalk.red("Error: No command provided."));
+        process.exit(1);
+      }
+      spawnCommand(commandArgs);
+      return;
+    }
+    await handleNamedMode(args);
+    return;
+  }
+  const isRunCommand = args[0] === "run";
+  if (isRunCommand) {
+    args.shift();
+  }
+  const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
+  if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy")) {
+    const { commandArgs } = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
+    if (commandArgs.length === 0) {
+      console.error(chalk.red("Error: No command provided."));
+      process.exit(1);
+    }
+    spawnCommand(commandArgs);
+    return;
+  }
+  if (!isRunCommand) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+      printHelp();
+      return;
+    }
+    if (args[0] === "--version" || args[0] === "-v") {
+      printVersion();
+      return;
+    }
+    if (args[0] === "trust") {
+      await handleTrust();
+      return;
+    }
+    if (args[0] === "list") {
+      await handleList();
+      return;
+    }
+    if (args[0] === "alias") {
+      await handleAlias(args);
+      return;
+    }
+    if (args[0] === "hosts") {
+      await handleHosts(args);
+      return;
+    }
+    if (args[0] === "proxy") {
+      await handleProxy(args);
+      return;
+    }
+  }
+  if (isRunCommand) {
+    await handleRunMode(args);
+  } else {
+    await handleNamedMode(args);
+  }
 }
 main().catch((err) => {
   const message = err instanceof Error ? err.message : String(err);