portless 0.4.1 → 0.5.0

package/dist/cli.js

@@ -1,19 +1,36 @@
 #!/usr/bin/env node
 import {
   FILE_MODE,
-  PORTLESS_HEADER,
+  PRIVILEGED_PORT_THRESHOLD,
+  RouteConflictError,
   RouteStore,
+  cleanHostsFile,
   createProxyServer,
+  discoverState,
+  findFreePort,
+  findPidOnPort,
+  fixOwnership,
   formatUrl,
+  getDefaultPort,
+  injectFrameworkFlags,
   isErrnoException,
-  parseHostname
-} from "./chunk-VRBD6YAY.js";
+  isHttpsEnvEnabled,
+  isProxyRunning,
+  parseHostname,
+  prompt,
+  readTlsMarker,
+  resolveStateDir,
+  spawnCommand,
+  syncHostsFile,
+  waitForProxy,
+  writeTlsMarker
+} from "./chunk-P3DHZHEZ.js";
 
 // src/cli.ts
 import chalk from "chalk";
 import * as fs3 from "fs";
 import * as path3 from "path";
-import { spawn as spawn2, spawnSync } from "child_process";
+import { spawn, spawnSync } from "child_process";
 
 // src/certs.ts
 import * as fs from "fs";
@@ -23,17 +40,6 @@ import * as tls from "tls";
 import { execFile as execFileCb, execFileSync } from "child_process";
 import { promisify } from "util";
 var CA_VALIDITY_DAYS = 3650;
-function fixOwnership(...paths) {
-  const uid = process.env.SUDO_UID;
-  const gid = process.env.SUDO_GID;
-  if (!uid || process.getuid?.() !== 0) return;
-  for (const p of paths) {
-    try {
-      fs.chownSync(p, parseInt(uid, 10), parseInt(gid || uid, 10));
-    } catch {
-    }
-  }
-}
 var SERVER_VALIDITY_DAYS = 365;
 var EXPIRY_BUFFER_MS = 7 * 24 * 60 * 60 * 1e3;
 var CA_COMMON_NAME = "portless Local CA";
@@ -60,6 +66,17 @@ function isCertValid(certPath) {
     return false;
   }
 }
+function isCertSignatureStrong(certPath) {
+  try {
+    const text = openssl(["x509", "-in", certPath, "-noout", "-text"]);
+    const match = text.match(/Signature Algorithm:\s*(\S+)/i);
+    if (!match) return false;
+    const algo = match[1].toLowerCase();
+    return !algo.includes("sha1");
+  } catch {
+    return false;
+  }
+}
 function openssl(args, options) {
   try {
     return execFileSync("openssl", args, {
@@ -102,6 +119,7 @@ function generateCA(stateDir) {
     "req",
     "-new",
     "-x509",
+    "-sha256",
     "-key",
     keyPath,
     "-out",
@@ -142,6 +160,7 @@ function generateServerCert(stateDir) {
   openssl([
     "x509",
     "-req",
+    "-sha256",
     "-in",
     csrPath,
     "-CA",
@@ -171,12 +190,13 @@ function ensureCerts(stateDir) {
   const caCertPath = path.join(stateDir, CA_CERT_FILE);
   const caKeyPath = path.join(stateDir, CA_KEY_FILE);
   const serverCertPath = path.join(stateDir, SERVER_CERT_FILE);
+  const serverKeyPath = path.join(stateDir, SERVER_KEY_FILE);
   let caGenerated = false;
-  if (!fileExists(caCertPath) || !fileExists(caKeyPath) || !isCertValid(caCertPath)) {
+  if (!fileExists(caCertPath) || !fileExists(caKeyPath) || !isCertValid(caCertPath) || !isCertSignatureStrong(caCertPath)) {
     generateCA(stateDir);
     caGenerated = true;
   }
-  if (caGenerated || !fileExists(serverCertPath) || !isCertValid(serverCertPath)) {
+  if (caGenerated || !fileExists(serverCertPath) || !fileExists(serverKeyPath) || !isCertValid(serverCertPath) || !isCertSignatureStrong(serverCertPath)) {
     generateServerCert(stateDir);
   }
   return {
@@ -228,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();
@@ -276,6 +338,7 @@ async function generateHostCertAsync(stateDir, hostname) {
   await opensslAsync([
     "x509",
     "-req",
+    "-sha256",
     "-in",
     csrPath,
     "-CA",
@@ -301,16 +364,12 @@ async function generateHostCertAsync(stateDir, hostname) {
   fixOwnership(keyPath, certPath);
   return { certPath, keyPath };
 }
-function isSimpleLocalhostSubdomain(hostname) {
-  const parts = hostname.split(".");
-  return parts.length === 2 && parts[1] === "localhost";
-}
 function createSNICallback(stateDir, defaultCert, defaultKey) {
   const cache = /* @__PURE__ */ new Map();
   const pending = /* @__PURE__ */ new Map();
   const defaultCtx = tls.createSecureContext({ cert: defaultCert, key: defaultKey });
   return (servername, cb) => {
-    if (servername === "localhost" || isSimpleLocalhostSubdomain(servername)) {
+    if (servername === "localhost") {
       cb(null, defaultCtx);
       return;
     }
@@ -322,7 +381,7 @@ function createSNICallback(stateDir, defaultCert, defaultKey) {
     const hostDir = path.join(stateDir, HOST_CERTS_DIR);
     const certPath = path.join(hostDir, `${safeName}.pem`);
     const keyPath = path.join(hostDir, `${safeName}-key.pem`);
-    if (fileExists(certPath) && fileExists(keyPath) && isCertValid(certPath)) {
+    if (fileExists(certPath) && fileExists(keyPath) && isCertValid(certPath) && isCertSignatureStrong(certPath)) {
       try {
         const ctx = tls.createSecureContext({
           cert: fs.readFileSync(certPath),
@@ -371,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}` };
@@ -389,251 +452,150 @@ function trustCA(stateDir) {
   }
 }
 
-// src/cli-utils.ts
+// src/auto.ts
+import { execFileSync as execFileSync2 } from "child_process";
 import * as fs2 from "fs";
-import * as http from "http";
-import * as https from "https";
-import * as net from "net";
-import * as os from "os";
 import * as path2 from "path";
-import * as readline from "readline";
-import { execSync, spawn } from "child_process";
-var DEFAULT_PROXY_PORT = 1355;
-var PRIVILEGED_PORT_THRESHOLD = 1024;
-var SYSTEM_STATE_DIR = "/tmp/portless";
-var USER_STATE_DIR = path2.join(os.homedir(), ".portless");
-var MIN_APP_PORT = 4e3;
-var MAX_APP_PORT = 4999;
-var RANDOM_PORT_ATTEMPTS = 50;
-var SOCKET_TIMEOUT_MS = 500;
-var LSOF_TIMEOUT_MS = 5e3;
-var WAIT_FOR_PROXY_MAX_ATTEMPTS = 20;
-var WAIT_FOR_PROXY_INTERVAL_MS = 250;
-var SIGNAL_CODES = {
-  SIGHUP: 1,
-  SIGINT: 2,
-  SIGQUIT: 3,
-  SIGABRT: 6,
-  SIGKILL: 9,
-  SIGTERM: 15
-};
-function getDefaultPort() {
-  const envPort = process.env.PORTLESS_PORT;
-  if (envPort) {
-    const port = parseInt(envPort, 10);
-    if (!isNaN(port) && port >= 1 && port <= 65535) return port;
-  }
-  return DEFAULT_PROXY_PORT;
-}
-function resolveStateDir(port) {
-  if (process.env.PORTLESS_STATE_DIR) return process.env.PORTLESS_STATE_DIR;
-  return port < PRIVILEGED_PORT_THRESHOLD ? SYSTEM_STATE_DIR : USER_STATE_DIR;
+function sanitizeForHostname(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
 }
-function readPortFromDir(dir) {
-  try {
-    const raw = fs2.readFileSync(path2.join(dir, "proxy.port"), "utf-8").trim();
-    const port = parseInt(raw, 10);
-    return isNaN(port) ? null : port;
-  } catch {
-    return null;
+function inferProjectName(cwd = process.cwd()) {
+  const pkgResult = findPackageJsonName(cwd);
+  if (pkgResult) {
+    const sanitized2 = sanitizeForHostname(pkgResult);
+    if (sanitized2) {
+      return { name: sanitized2, source: "package.json" };
+    }
   }
-}
-var TLS_MARKER_FILE = "proxy.tls";
-function readTlsMarker(dir) {
-  try {
-    return fs2.existsSync(path2.join(dir, TLS_MARKER_FILE));
-  } catch {
-    return false;
+  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 writeTlsMarker(dir, enabled) {
-  const markerPath = path2.join(dir, TLS_MARKER_FILE);
-  if (enabled) {
-    fs2.writeFileSync(markerPath, "1", { mode: 420 });
-  } else {
+function findPackageJsonName(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    const pkgPath = path2.join(dir, "package.json");
     try {
-      fs2.unlinkSync(markerPath);
+      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 isHttpsEnvEnabled() {
-  const val = process.env.PORTLESS_HTTPS;
-  return val === "1" || val === "true";
-}
-async function discoverState() {
-  if (process.env.PORTLESS_STATE_DIR) {
-    const dir = process.env.PORTLESS_STATE_DIR;
-    const port = readPortFromDir(dir) ?? getDefaultPort();
-    const tls2 = readTlsMarker(dir);
-    return { dir, port, tls: tls2 };
-  }
-  const userPort = readPortFromDir(USER_STATE_DIR);
-  if (userPort !== null) {
-    const tls2 = readTlsMarker(USER_STATE_DIR);
-    if (await isProxyRunning(userPort, tls2)) {
-      return { dir: USER_STATE_DIR, port: userPort, tls: tls2 };
-    }
+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 {
   }
-  const systemPort = readPortFromDir(SYSTEM_STATE_DIR);
-  if (systemPort !== null) {
-    const tls2 = readTlsMarker(SYSTEM_STATE_DIR);
-    if (await isProxyRunning(systemPort, tls2)) {
-      return { dir: SYSTEM_STATE_DIR, port: systemPort, tls: tls2 };
+  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;
   }
-  const defaultPort = getDefaultPort();
-  return { dir: resolveStateDir(defaultPort), port: defaultPort, tls: false };
+  return null;
 }
-async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
-  if (minPort > maxPort) {
-    throw new Error(`minPort (${minPort}) must be <= maxPort (${maxPort})`);
-  }
-  const tryPort = (port) => {
-    return new Promise((resolve) => {
-      const server = net.createServer();
-      server.listen(port, () => {
-        server.close(() => resolve(true));
-      });
-      server.on("error", () => resolve(false));
-    });
-  };
-  for (let i = 0; i < RANDOM_PORT_ATTEMPTS; i++) {
-    const port = minPort + Math.floor(Math.random() * (maxPort - minPort + 1));
-    if (await tryPort(port)) {
-      return port;
-    }
-  }
-  for (let port = minPort; port <= maxPort; port++) {
-    if (await tryPort(port)) {
-      return port;
-    }
-  }
-  throw new Error(`No free port found in range ${minPort}-${maxPort}`);
+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 isProxyRunning(port, tls2 = false) {
-  return new Promise((resolve) => {
-    const requestFn = tls2 ? https.request : http.request;
-    const req = requestFn(
-      {
-        hostname: "127.0.0.1",
-        port,
-        path: "/",
-        method: "HEAD",
-        timeout: SOCKET_TIMEOUT_MS,
-        ...tls2 ? { rejectUnauthorized: false } : {}
-      },
-      (res) => {
-        res.resume();
-        resolve(res.headers[PORTLESS_HEADER.toLowerCase()] === "1");
-      }
-    );
-    req.on("error", () => resolve(false));
-    req.on("timeout", () => {
-      req.destroy();
-      resolve(false);
-    });
-    req.end();
-  });
+function detectWorktreePrefix(cwd = process.cwd()) {
+  const cliResult = detectWorktreeViaCli(cwd);
+  if (cliResult !== void 0) return cliResult;
+  return detectWorktreeViaFilesystem(cwd);
 }
-function findPidOnPort(port) {
+function detectWorktreeViaCli(cwd) {
   try {
-    const output = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
+    const listOutput = execFileSync2("git", ["worktree", "list", "--porcelain"], {
+      cwd,
       encoding: "utf-8",
-      timeout: LSOF_TIMEOUT_MS
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
     });
-    const pid = parseInt(output.trim().split("\n")[0], 10);
-    return isNaN(pid) ? null : pid;
+    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 null;
+    return void 0;
   }
 }
-async function waitForProxy(port, maxAttempts = WAIT_FOR_PROXY_MAX_ATTEMPTS, intervalMs = WAIT_FOR_PROXY_INTERVAL_MS, tls2 = false) {
-  for (let i = 0; i < maxAttempts; i++) {
-    await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    if (await isProxyRunning(port, tls2)) {
-      return true;
+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 false;
+  return null;
 }
-function spawnCommand(commandArgs, options) {
-  const child = spawn(commandArgs[0], commandArgs.slice(1), {
-    stdio: "inherit",
-    env: options?.env
-  });
-  let exiting = false;
-  const cleanup = () => {
-    process.removeListener("SIGINT", onSigInt);
-    process.removeListener("SIGTERM", onSigTerm);
-    options?.onCleanup?.();
-  };
-  const handleSignal = (signal) => {
-    if (exiting) return;
-    exiting = true;
-    child.kill(signal);
-    cleanup();
-    process.exit(128 + (SIGNAL_CODES[signal] || 15));
-  };
-  const onSigInt = () => handleSignal("SIGINT");
-  const onSigTerm = () => handleSignal("SIGTERM");
-  process.on("SIGINT", onSigInt);
-  process.on("SIGTERM", onSigTerm);
-  child.on("error", (err) => {
-    if (exiting) return;
-    exiting = true;
-    console.error(`Failed to run command: ${err.message}`);
-    if (err.code === "ENOENT") {
-      console.error(`Is "${commandArgs[0]}" installed and in your PATH?`);
-    }
-    cleanup();
-    process.exit(1);
-  });
-  child.on("exit", (code, signal) => {
-    if (exiting) return;
-    exiting = true;
-    cleanup();
-    if (signal) {
-      process.exit(128 + (SIGNAL_CODES[signal] || 15));
-    }
-    process.exit(code ?? 1);
-  });
-}
-var FRAMEWORKS_NEEDING_PORT = {
-  vite: { strictPort: true },
-  "react-router": { strictPort: true },
-  astro: { strictPort: false },
-  ng: { strictPort: false }
-};
-function injectFrameworkFlags(commandArgs, port) {
-  const cmd = commandArgs[0];
-  if (!cmd) return;
-  const basename2 = path2.basename(cmd);
-  const framework = FRAMEWORKS_NEEDING_PORT[basename2];
-  if (!framework) return;
-  if (!commandArgs.includes("--port")) {
-    commandArgs.push("--port", port.toString());
-    if (framework.strictPort) {
-      commandArgs.push("--strictPort");
-    }
-  }
-  if (!commandArgs.includes("--host")) {
-    commandArgs.push("--host", "127.0.0.1");
+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;
   }
 }
-function prompt(question) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  return new Promise((resolve) => {
-    rl.on("close", () => resolve(""));
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
-}
 
 // src/cli.ts
 var DEBOUNCE_MS = 100;
@@ -651,13 +613,18 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     fs3.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
+  fixOwnership(routesPath);
   let cachedRoutes = store.loadRoutes();
   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 {
     }
   };
@@ -670,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,
@@ -698,6 +668,7 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     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";
     console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}`));
   });
@@ -719,6 +690,7 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    if (autoSyncHosts) cleanHostsFile();
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref();
   };
@@ -827,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) {
+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;
@@ -906,21 +886,38 @@ portless
   } else {
     console.log(chalk.gray("-- Proxy is running"));
   }
-  const port = await findFreePort();
-  console.log(chalk.green(`-- Using port ${port}`));
-  store.addRoute(hostname, port, process.pid);
+  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) {
+    if (err instanceof RouteConflictError) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+    throw err;
+  }
   const finalUrl = formatUrl(hostname, proxyPort, tls2);
   console.log(chalk.cyan.bold(`
   -> ${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: () => {
@@ -931,23 +928,120 @@ portless
     }
   });
 }
-async function main() {
-  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"));
+function parseAppPort(value) {
+  if (!value || value.startsWith("--")) {
+    console.error(chalk.red("Error: --app-port requires a port number."));
     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;
+  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);
   }
-  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-    console.log(`
+  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);
+  }
+  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
@@ -963,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
@@ -972,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).
@@ -994,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
@@ -1001,247 +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.0");
+  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.1");
+  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 = 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);
-        }
-      } 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 = fs3.readFileSync(certs.certPath);
-        const key = fs3.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 = path3.join(stateDir, "proxy.log");
-    const logFd = fs3.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 {
-        fs3.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);
       }
-      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 = spawn2(process.execPath, daemonArgs, {
-        detached: true,
-        stdio: ["ignore", logFd, logFd],
-        env: process.env
-      });
-      child.unref();
-    } finally {
-      fs3.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 (fs3.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);
+  }
+  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 name = args[0];
-  const commandArgs = args.slice(1);
-  if (commandArgs.length === 0) {
+  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...>"));
@@ -1253,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);
+  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);