portless 0.5.2 → 0.7.0

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import {
+  DEFAULT_TLD,
   FILE_MODE,
   PRIVILEGED_PORT_THRESHOLD,
+  RISKY_TLDS,
   RouteConflictError,
   RouteStore,
   cleanHostsFile,
@@ -12,19 +14,24 @@ import {
   fixOwnership,
   formatUrl,
   getDefaultPort,
+  getDefaultTld,
   injectFrameworkFlags,
   isErrnoException,
   isHttpsEnvEnabled,
   isProxyRunning,
+  isWindows,
   parseHostname,
   prompt,
+  readTldFromDir,
   readTlsMarker,
   resolveStateDir,
   spawnCommand,
   syncHostsFile,
+  validateTld,
   waitForProxy,
+  writeTldFile,
   writeTlsMarker
-} from "./chunk-P3DHZHEZ.js";
+} from "./chunk-Y6FWHU6F.js";
 
 // src/cli.ts
 import chalk from "chalk";
@@ -213,24 +220,44 @@ function isCATrusted(stateDir) {
     return isCATrustedMacOS(caCertPath);
   } else if (process.platform === "linux") {
     return isCATrustedLinux(stateDir);
+  } else if (process.platform === "win32") {
+    return isCATrustedWindows(caCertPath);
   }
   return false;
 }
-function isCATrustedMacOS(caCertPath) {
+function isCATrustedWindows(caCertPath) {
   try {
     const fingerprint = openssl(["x509", "-in", caCertPath, "-noout", "-fingerprint", "-sha1"]).trim().replace(/^.*=/, "").replace(/:/g, "").toLowerCase();
-    for (const keychain of [loginKeychainPath(), "/Library/Keychains/System.keychain"]) {
-      try {
-        const result = execFileSync("security", ["find-certificate", "-a", "-Z", keychain], {
-          encoding: "utf-8",
-          timeout: 5e3,
-          stdio: ["pipe", "pipe", "pipe"]
-        });
-        if (result.toLowerCase().includes(fingerprint)) return true;
-      } catch {
-      }
-    }
+    const result = execFileSync("certutil", ["-store", "-user", "Root"], {
+      encoding: "utf-8",
+      timeout: 1e4,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return result.replace(/\s/g, "").toLowerCase().includes(fingerprint);
+  } catch {
     return false;
+  }
+}
+function isCATrustedMacOS(caCertPath) {
+  try {
+    const isRoot = (process.getuid?.() ?? -1) === 0;
+    const sudoUser = process.env.SUDO_USER;
+    if (isRoot && sudoUser) {
+      execFileSync(
+        "sudo",
+        ["-u", sudoUser, "security", "verify-cert", "-c", caCertPath, "-L", "-p", "ssl"],
+        {
+          stdio: "pipe",
+          timeout: 5e3
+        }
+      );
+    } else {
+      execFileSync("security", ["verify-cert", "-c", caCertPath, "-L", "-p", "ssl"], {
+        stdio: "pipe",
+        timeout: 5e3
+      });
+    }
+    return true;
   } catch {
     return false;
   }
@@ -364,12 +391,12 @@ async function generateHostCertAsync(stateDir, hostname) {
   fixOwnership(keyPath, certPath);
   return { certPath, keyPath };
 }
-function createSNICallback(stateDir, defaultCert, defaultKey) {
+function createSNICallback(stateDir, defaultCert, defaultKey, tld = "localhost") {
   const cache = /* @__PURE__ */ new Map();
   const pending = /* @__PURE__ */ new Map();
   const defaultCtx = tls.createSecureContext({ cert: defaultCert, key: defaultKey });
   return (servername, cb) => {
-    if (servername === "localhost") {
+    if (servername === tld) {
       cb(null, defaultCtx);
       return;
     }
@@ -422,12 +449,29 @@ function trustCA(stateDir) {
   }
   try {
     if (process.platform === "darwin") {
-      const keychain = loginKeychainPath();
-      execFileSync(
-        "security",
-        ["add-trusted-cert", "-r", "trustRoot", "-k", keychain, caCertPath],
-        { stdio: "pipe", timeout: 3e4 }
-      );
+      const isRoot = (process.getuid?.() ?? -1) === 0;
+      if (isRoot) {
+        execFileSync(
+          "security",
+          [
+            "add-trusted-cert",
+            "-d",
+            "-r",
+            "trustRoot",
+            "-k",
+            "/Library/Keychains/System.keychain",
+            caCertPath
+          ],
+          { stdio: "pipe", timeout: 3e4 }
+        );
+      } else {
+        const keychain = loginKeychainPath();
+        execFileSync(
+          "security",
+          ["add-trusted-cert", "-r", "trustRoot", "-k", keychain, caCertPath],
+          { stdio: "pipe", timeout: 3e4 }
+        );
+      }
       return { trusted: true };
     } else if (process.platform === "linux") {
       const config = getLinuxCATrustConfig();
@@ -438,6 +482,12 @@ function trustCA(stateDir) {
       fs.copyFileSync(caCertPath, dest);
       execFileSync(config.updateCommand, [], { stdio: "pipe", timeout: 3e4 });
       return { trusted: true };
+    } else if (process.platform === "win32") {
+      execFileSync("certutil", ["-addstore", "-user", "Root", caCertPath], {
+        stdio: "pipe",
+        timeout: 3e4
+      });
+      return { trusted: true };
     }
     return { trusted: false, error: `Unsupported platform: ${process.platform}` };
   } catch (err) {
@@ -453,11 +503,21 @@ function trustCA(stateDir) {
 }
 
 // src/auto.ts
+import { createHash } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
 import * as fs2 from "fs";
 import * as path2 from "path";
+var MAX_DNS_LABEL_LENGTH = 63;
+function truncateLabel(label) {
+  if (label.length <= MAX_DNS_LABEL_LENGTH) return label;
+  const hash = createHash("sha256").update(label).digest("hex").slice(0, 6);
+  const maxPrefixLength = MAX_DNS_LABEL_LENGTH - 7;
+  const prefix = label.slice(0, maxPrefixLength).replace(/-+$/, "");
+  return `${prefix}-${hash}`;
+}
 function sanitizeForHostname(name) {
-  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  const sanitized = name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  return truncateLabel(sanitized);
 }
 function inferProjectName(cwd = process.cwd()) {
   const pkgResult = findPackageJsonName(cwd);
@@ -546,6 +606,25 @@ function detectWorktreeViaCli(cwd) {
     });
     const worktreeCount = listOutput.split("\n").filter((l) => l.startsWith("worktree ")).length;
     if (worktreeCount <= 1) return null;
+    const gitDir = path2.resolve(
+      cwd,
+      execFileSync2("git", ["rev-parse", "--git-dir"], {
+        cwd,
+        encoding: "utf-8",
+        timeout: 5e3,
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim()
+    );
+    const gitCommonDir = path2.resolve(
+      cwd,
+      execFileSync2("git", ["rev-parse", "--git-common-dir"], {
+        cwd,
+        encoding: "utf-8",
+        timeout: 5e3,
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim()
+    );
+    if (gitDir === gitCommonDir) return null;
     const branch = execFileSync2("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
       cwd,
       encoding: "utf-8",
@@ -573,7 +652,7 @@ function detectWorktreeViaFilesystem(startDir) {
         const match = content.match(/^gitdir:\s*(.+)$/);
         if (!match) return null;
         const gitdir = match[1];
-        if (!gitdir.match(/\/worktrees\/[^/]+$/)) return null;
+        if (!gitdir.match(/[/\\]worktrees[/\\][^/\\]+$/)) return null;
         const branch = readBranchFromHead(path2.resolve(dir, gitdir));
         const prefix = branchToPrefix(branch ?? "");
         if (!prefix) return null;
@@ -598,11 +677,13 @@ function readBranchFromHead(gitdir) {
 }
 
 // src/cli.ts
+var HOSTS_DISPLAY = isWindows ? "hosts file" : "/etc/hosts";
+var SUDO_PREFIX = isWindows ? "" : "sudo ";
 var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
 var EXIT_TIMEOUT_MS = 2e3;
 var SUDO_SPAWN_TIMEOUT_MS = 3e4;
-function startProxyServer(store, proxyPort, tlsOptions) {
+function startProxyServer(store, proxyPort, tld, tlsOptions) {
   store.ensureDir();
   const isTls = !!tlsOptions;
   const routesPath = store.getRoutesPath();
@@ -618,7 +699,8 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   let debounceTimer = null;
   let watcher = null;
   let pollingInterval = null;
-  const autoSyncHosts = process.env.PORTLESS_SYNC_HOSTS === "1";
+  const syncVal = process.env.PORTLESS_SYNC_HOSTS;
+  const autoSyncHosts = syncVal === "1" || syncVal === "true" || tld !== DEFAULT_TLD && syncVal !== "0" && syncVal !== "false";
   const reloadRoutes = () => {
     try {
       cachedRoutes = store.loadRoutes();
@@ -643,6 +725,7 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
     proxyPort,
+    tld,
     onError: (msg) => console.error(chalk.red(msg)),
     tls: tlsOptions
   });
@@ -652,7 +735,11 @@ function startProxyServer(store, proxyPort, tlsOptions) {
       console.error(chalk.blue("Stop the existing proxy first:"));
       console.error(chalk.cyan("  portless proxy stop"));
       console.error(chalk.blue("Or check what is using the port:"));
-      console.error(chalk.cyan(`  lsof -ti tcp:${proxyPort}`));
+      console.error(
+        chalk.cyan(
+          isWindows ? `  netstat -ano | findstr :${proxyPort}` : `  lsof -ti tcp:${proxyPort}`
+        )
+      );
     } else if (err.code === "EACCES") {
       console.error(chalk.red(`Permission denied for port ${proxyPort}.`));
       console.error(chalk.blue("Either run with sudo:"));
@@ -668,9 +755,11 @@ 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);
+    writeTldFile(store.dir, tld);
     fixOwnership(store.dir, store.pidPath, store.portFilePath);
     const proto = isTls ? "HTTPS/2" : "HTTP";
-    console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}`));
+    const tldLabel = tld !== DEFAULT_TLD ? ` (TLD: .${tld})` : "";
+    console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}${tldLabel}`));
   });
   let exiting = false;
   const cleanup = () => {
@@ -690,6 +779,7 @@ function startProxyServer(store, proxyPort, tlsOptions) {
     } catch {
     }
     writeTlsMarker(store.dir, false);
+    writeTldFile(store.dir, DEFAULT_TLD);
     if (autoSyncHosts) cleanHostsFile();
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref();
@@ -699,12 +789,12 @@ function startProxyServer(store, proxyPort, tlsOptions) {
   console.log(chalk.cyan("\nProxy is running. Press Ctrl+C to stop.\n"));
   console.log(chalk.gray(`Routes file: ${store.getRoutesPath()}`));
 }
-async function stopProxy(store, proxyPort, tls2) {
+async function stopProxy(store, proxyPort, _tls) {
   const pidPath = store.pidPath;
-  const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+  const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
   const sudoHint = needsSudo ? "sudo " : "";
   if (!fs3.existsSync(pidPath)) {
-    if (await isProxyRunning(proxyPort, tls2)) {
+    if (await isProxyRunning(proxyPort)) {
       console.log(chalk.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
       if (pid !== null) {
@@ -717,24 +807,38 @@ async function stopProxy(store, proxyPort, tls2) {
           console.log(chalk.green(`Killed process ${pid}. Proxy stopped.`));
         } catch (err) {
           if (isErrnoException(err) && err.code === "EPERM") {
-            console.error(chalk.red("Permission denied. The proxy was started with sudo."));
+            console.error(
+              chalk.red("Permission denied. The proxy was started with elevated privileges.")
+            );
             console.error(chalk.blue("Stop it with:"));
-            console.error(chalk.cyan("  sudo portless proxy stop"));
+            console.error(
+              chalk.cyan(
+                isWindows ? "  Run portless proxy stop as Administrator" : "  sudo portless proxy stop"
+              )
+            );
           } else {
             const message = err instanceof Error ? err.message : String(err);
             console.error(chalk.red(`Failed to stop proxy: ${message}`));
             console.error(chalk.blue("Check if the process is still running:"));
-            console.error(chalk.cyan(`  lsof -ti tcp:${proxyPort}`));
+            console.error(
+              chalk.cyan(
+                isWindows ? `  netstat -ano | findstr :${proxyPort}` : `  lsof -ti tcp:${proxyPort}`
+              )
+            );
           }
         }
-      } else if (process.getuid?.() !== 0) {
+      } else if (!isWindows && process.getuid?.() !== 0) {
         console.error(chalk.red("Cannot identify the process. It may be running as root."));
         console.error(chalk.blue("Try stopping with sudo:"));
         console.error(chalk.cyan("  sudo portless proxy stop"));
       } else {
         console.error(chalk.red(`Could not identify the process on port ${proxyPort}.`));
         console.error(chalk.blue("Try manually:"));
-        console.error(chalk.cyan(`  sudo kill "$(lsof -ti tcp:${proxyPort})"`));
+        console.error(
+          chalk.cyan(
+            isWindows ? "  taskkill /F /PID <pid>" : `  sudo kill "$(lsof -ti tcp:${proxyPort})"`
+          )
+        );
       }
     } else {
       console.log(chalk.yellow("Proxy is not running."));
@@ -759,7 +863,7 @@ async function stopProxy(store, proxyPort, tls2) {
       }
       return;
     }
-    if (!await isProxyRunning(proxyPort, tls2)) {
+    if (!await isProxyRunning(proxyPort)) {
       console.log(
         chalk.yellow(
           `PID file exists but port ${proxyPort} is not listening. The PID may have been recycled.`
@@ -778,14 +882,20 @@ async function stopProxy(store, proxyPort, tls2) {
     console.log(chalk.green("Proxy stopped."));
   } catch (err) {
     if (isErrnoException(err) && err.code === "EPERM") {
-      console.error(chalk.red("Permission denied. The proxy was started with sudo."));
+      console.error(
+        chalk.red("Permission denied. The proxy was started with elevated privileges.")
+      );
       console.error(chalk.blue("Stop it with:"));
       console.error(chalk.cyan(`  ${sudoHint}portless proxy stop`));
     } else {
       const message = err instanceof Error ? err.message : String(err);
       console.error(chalk.red(`Failed to stop proxy: ${message}`));
       console.error(chalk.blue("Check if the process is still running:"));
-      console.error(chalk.cyan(`  lsof -ti tcp:${proxyPort}`));
+      console.error(
+        chalk.cyan(
+          isWindows ? `  netstat -ano | findstr :${proxyPort}` : `  lsof -ti tcp:${proxyPort}`
+        )
+      );
     }
   }
 }
@@ -806,8 +916,22 @@ function listRoutes(store, proxyPort, tls2) {
   }
   console.log();
 }
-async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, force, autoInfo, desiredPort) {
-  const hostname = parseHostname(name);
+async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2, tld, force, autoInfo, desiredPort) {
+  const hostname = parseHostname(name, tld);
+  let envTld;
+  try {
+    envTld = getDefaultTld();
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+  if (envTld !== DEFAULT_TLD && envTld !== tld) {
+    console.warn(
+      chalk.yellow(
+        `Warning: PORTLESS_TLD=${envTld} but the running proxy uses .${tld}. Using .${tld}.`
+      )
+    );
+  }
   console.log(chalk.blue.bold(`
 portless
 `));
@@ -821,7 +945,7 @@ portless
   }
   if (!await isProxyRunning(proxyPort, tls2)) {
     const defaultPort = getDefaultPort();
-    const needsSudo = defaultPort < PRIVILEGED_PORT_THRESHOLD;
+    const needsSudo = !isWindows && defaultPort < PRIVILEGED_PORT_THRESHOLD;
     const wantHttps = isHttpsEnvEnabled();
     if (needsSudo) {
       if (!process.stdin.isTTY) {
@@ -845,6 +969,7 @@ portless
       console.log(chalk.yellow("Starting proxy (requires sudo)..."));
       const startArgs = [process.execPath, process.argv[1], "proxy", "start"];
       if (wantHttps) startArgs.push("--https");
+      if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld);
       const result = spawnSync("sudo", startArgs, {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
@@ -859,6 +984,7 @@ portless
       console.log(chalk.yellow("Starting proxy..."));
       const startArgs = [process.argv[1], "proxy", "start"];
       if (wantHttps) startArgs.push("--https");
+      if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld);
       const result = spawnSync(process.execPath, startArgs, {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
@@ -871,6 +997,7 @@ portless
       }
     }
     const autoTls = readTlsMarker(stateDir);
+    tld = readTldFromDir(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 = path3.join(stateDir, "proxy.log");
@@ -918,7 +1045,7 @@ portless
       PORT: port.toString(),
       HOST: "127.0.0.1",
       PORTLESS_URL: finalUrl,
-      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: ".localhost"
+      __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`
     },
     onCleanup: () => {
       try {
@@ -953,6 +1080,7 @@ function appPortFromEnv() {
 function parseRunArgs(args) {
   let force = false;
   let appPort;
+  let name;
   let i = 0;
   while (i < args.length && args[i].startsWith("-")) {
     if (args[i] === "--") {
@@ -966,6 +1094,7 @@ ${chalk.bold("Usage:")}
   ${chalk.cyan("portless run [options] <command...>")}
 
 ${chalk.bold("Options:")}
+  --name <name>          Override the inferred base name (worktree prefix still applies)
   --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
@@ -975,11 +1104,13 @@ ${chalk.bold("Name inference (in order):")}
   2. Git repo root directory name
   3. Current directory basename
 
+  Use --name to override the inferred name while keeping worktree prefixes.
   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 --name myapp next dev  # -> http://myapp.localhost:1355
   portless run vite dev               # -> http://<project>.localhost:1355
   portless run --app-port 3000 pnpm start
 `);
@@ -989,15 +1120,23 @@ ${chalk.bold("Examples:")}
     } else if (args[i] === "--app-port") {
       i++;
       appPort = parseAppPort(args[i]);
+    } else if (args[i] === "--name") {
+      i++;
+      if (!args[i] || args[i].startsWith("-")) {
+        console.error(chalk.red("Error: --name requires a name value."));
+        console.error(chalk.cyan("  portless run --name <name> <command...>"));
+        process.exit(1);
+      }
+      name = args[i];
     } else {
       console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
-      console.error(chalk.blue("Known flags: --force, --app-port, --help"));
+      console.error(chalk.blue("Known flags: --name, --force, --app-port, --help"));
       process.exit(1);
     }
     i++;
   }
   if (!appPort) appPort = appPortFromEnv();
-  return { force, appPort, commandArgs: args.slice(i) };
+  return { force, appPort, name, commandArgs: args.slice(i) };
 }
 function parseAppArgs(args) {
   let force = false;
@@ -1058,12 +1197,13 @@ ${chalk.bold("Usage:")}
   ${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 get <name>")}              Print URL for a service (for cross-service refs)
   ${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.cyan("portless hosts sync")}              Add routes to ${HOSTS_DISPLAY} (fixes Safari)
+  ${chalk.cyan("portless hosts clean")}             Remove portless entries from ${HOSTS_DISPLAY}
 
 ${chalk.bold("Examples:")}
   portless proxy start                # Start proxy on port 1355
@@ -1073,6 +1213,7 @@ ${chalk.bold("Examples:")}
   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
+  portless get backend                 # -> http://backend.localhost:1355 (for cross-service refs)
   # Wildcard subdomains: tenant.myapp.localhost also routes to myapp
 
 ${chalk.bold("In package.json:")}
@@ -1097,7 +1238,7 @@ ${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
+  run [--name <name>] <cmd>      Infer project name (or override with --name)
                                 Adds worktree prefix in git worktrees
   -p, --port <number>           Port for the proxy to listen on (default: 1355)
                                 Ports < 1024 require sudo
@@ -1106,6 +1247,7 @@ ${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)
+  --tld <tld>                   Use a custom TLD instead of .localhost (e.g. test, dev)
   --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)
@@ -1114,10 +1256,11 @@ ${chalk.bold("Options:")}
 ${chalk.bold("Environment variables:")}
   PORTLESS_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
   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_HTTPS=1              Always enable HTTPS (set in .bashrc / .zshrc)
+  PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
+  PORTLESS_SYNC_HOSTS=1         Auto-sync ${HOSTS_DISPLAY} (auto-enabled for custom TLDs)
   PORTLESS_STATE_DIR=<path>     Override the state directory
-  PORTLESS=0 | PORTLESS=skip    Run command directly without proxy
+  PORTLESS=0                    Run command directly without proxy
 
 ${chalk.bold("Child process environment:")}
   PORT                          Ephemeral port the child should listen on
@@ -1127,26 +1270,24 @@ ${chalk.bold("Child process environment:")}
 ${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.
+  Auto-syncs ${HOSTS_DISPLAY} for custom TLDs (e.g. --tld test). For .localhost,
+  set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync:
+    ${chalk.cyan(`${SUDO_PREFIX}portless hosts sync`)}
+  Clean up later with:
+    ${chalk.cyan(`${SUDO_PREFIX}portless hosts clean`)}
 
 ${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.
+  run, get, 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.2");
+  console.log("0.7.0");
   process.exit(0);
 }
 async function handleTrust() {
@@ -1171,6 +1312,60 @@ async function handleList() {
   });
   listRoutes(store, port, tls2);
 }
+async function handleGet(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${chalk.bold("portless get")} - Print the URL for a service.
+
+${chalk.bold("Usage:")}
+  ${chalk.cyan("portless get <name>")}
+
+Constructs the URL using the same hostname and worktree logic as
+"portless run", then prints it to stdout. Useful for wiring services
+together:
+
+  BACKEND_URL=$(portless get backend)
+
+${chalk.bold("Options:")}
+  --no-worktree          Skip worktree prefix detection
+  --help, -h             Show this help
+
+${chalk.bold("Examples:")}
+  portless get backend                  # -> http://backend.localhost:1355
+  portless get backend                  # in worktree -> http://auth.backend.localhost:1355
+  portless get backend --no-worktree    # -> http://backend.localhost:1355 (skip worktree)
+`);
+    process.exit(0);
+  }
+  let skipWorktree = false;
+  const positional = [];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--no-worktree") {
+      skipWorktree = true;
+    } else if (args[i].startsWith("-")) {
+      console.error(chalk.red(`Error: Unknown flag "${args[i]}".`));
+      console.error(chalk.blue("Known flags: --no-worktree, --help"));
+      process.exit(1);
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  if (positional.length === 0) {
+    console.error(chalk.red("Error: Missing service name."));
+    console.error(chalk.blue("Usage:"));
+    console.error(chalk.cyan("  portless get <name>"));
+    console.error(chalk.blue("Example:"));
+    console.error(chalk.cyan("  portless get backend"));
+    process.exit(1);
+  }
+  const name = positional[0];
+  const worktree = skipWorktree ? null : detectWorktreePrefix();
+  const effectiveName = worktree ? `${worktree.prefix}.${name}` : name;
+  const { port, tls: tls2, tld } = await discoverState();
+  const hostname = parseHostname(effectiveName, tld);
+  const url = formatUrl(hostname, port, tls2);
+  process.stdout.write(url + "\n");
+}
 async function handleAlias(args) {
   if (args[1] === "--help" || args[1] === "-h") {
     console.log(`
@@ -1188,7 +1383,7 @@ ${chalk.bold("Examples:")}
 `);
     process.exit(0);
   }
-  const { dir } = await discoverState();
+  const { dir, tld } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
@@ -1199,7 +1394,7 @@ ${chalk.bold("Examples:")}
       console.error(chalk.cyan("  portless alias --remove <name>"));
       process.exit(1);
     }
-    const hostname2 = parseHostname(aliasName2);
+    const hostname2 = parseHostname(aliasName2, tld);
     const routes = store.loadRoutes();
     const existing = routes.find((r) => r.hostname === hostname2 && r.pid === 0);
     if (!existing) {
@@ -1221,7 +1416,7 @@ ${chalk.bold("Examples:")}
     console.error(chalk.cyan("  portless alias my-postgres 5432"));
     process.exit(1);
   }
-  const hostname = parseHostname(aliasName);
+  const hostname = parseHostname(aliasName, tld);
   const port = parseInt(aliasPort, 10);
   if (isNaN(port) || port < 1 || port > 65535) {
     console.error(chalk.red(`Error: Invalid port "${aliasPort}". Must be 1-65535.`));
@@ -1229,32 +1424,36 @@ ${chalk.bold("Examples:")}
   }
   const force = args.includes("--force");
   store.addRoute(hostname, port, 0, force);
-  console.log(chalk.green(`Alias registered: ${hostname} -> localhost:${port}`));
+  console.log(chalk.green(`Alias registered: ${hostname} -> 127.0.0.1:${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.
+${chalk.bold("portless hosts")} - Manage ${HOSTS_DISPLAY} 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.
+subdomains. This command adds entries to ${HOSTS_DISPLAY} 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.cyan(`${SUDO_PREFIX}portless hosts sync`)}    Add current routes to ${HOSTS_DISPLAY}
+  ${chalk.cyan(`${SUDO_PREFIX}portless hosts clean`)}   Remove portless entries from ${HOSTS_DISPLAY}
 
 ${chalk.bold("Auto-sync:")}
-  Set PORTLESS_SYNC_HOSTS=1 and start the proxy with sudo to auto-sync
-  /etc/hosts whenever routes change.
+  Auto-enabled for custom TLDs (e.g. --tld test). For .localhost, set
+  PORTLESS_SYNC_HOSTS=1 to enable. Disable with PORTLESS_SYNC_HOSTS=0.
 `);
     process.exit(0);
   }
   if (args[1] === "clean") {
     if (cleanHostsFile()) {
-      console.log(chalk.green("Removed portless entries from /etc/hosts."));
+      console.log(chalk.green(`Removed portless entries from ${HOSTS_DISPLAY}.`));
     } else {
-      console.error(chalk.red("Failed to update /etc/hosts (requires sudo)."));
-      console.error(chalk.cyan("  sudo portless hosts clean"));
+      console.error(
+        chalk.red(
+          `Failed to update ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : " (requires sudo)."}`
+        )
+      );
+      console.error(chalk.cyan(`  ${SUDO_PREFIX}portless hosts clean`));
       process.exit(1);
     }
     return;
@@ -1263,16 +1462,18 @@ ${chalk.bold("Auto-sync:")}
     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
+  ${chalk.cyan(`${SUDO_PREFIX}portless hosts sync`)}    Add current routes to ${HOSTS_DISPLAY}
+  ${chalk.cyan(`${SUDO_PREFIX}portless hosts clean`)}   Remove portless entries from ${HOSTS_DISPLAY}
 `);
     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"));
+    console.error(
+      chalk.cyan(`  ${SUDO_PREFIX}portless hosts sync    # Add routes to ${HOSTS_DISPLAY}`)
+    );
+    console.error(chalk.cyan(`  ${SUDO_PREFIX}portless hosts clean   # Remove portless entries`));
     process.exit(1);
   }
   const { dir } = await discoverState();
@@ -1286,13 +1487,17 @@ ${chalk.bold("Usage: portless hosts <command>")}
   }
   const hostnames = routes.map((r) => r.hostname);
   if (syncHostsFile(hostnames)) {
-    console.log(chalk.green(`Synced ${hostnames.length} hostname(s) to /etc/hosts:`));
+    console.log(chalk.green(`Synced ${hostnames.length} hostname(s) to ${HOSTS_DISPLAY}:`));
     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"));
+    console.error(
+      chalk.red(
+        `Failed to update ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : " (requires sudo)."}`
+      )
+    );
+    console.error(chalk.cyan(`  ${SUDO_PREFIX}portless hosts sync`));
     process.exit(1);
   }
 }
@@ -1315,6 +1520,7 @@ ${chalk.bold("Usage:")}
   ${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 start --tld test")}     Use .test instead of .localhost
   ${chalk.cyan("portless proxy stop")}                 Stop the proxy
 `);
     process.exit(isProxyHelp || !args[1] ? 0 : 1);
@@ -1363,6 +1569,41 @@ ${chalk.bold("Usage:")}
     console.error(chalk.red("Error: --cert and --key must be used together."));
     process.exit(1);
   }
+  let tld;
+  try {
+    tld = getDefaultTld();
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+  const tldIdx = args.indexOf("--tld");
+  if (tldIdx !== -1) {
+    const tldValue = args[tldIdx + 1];
+    if (!tldValue || tldValue.startsWith("-")) {
+      console.error(chalk.red("Error: --tld requires a TLD value (e.g. test, localhost)."));
+      process.exit(1);
+    }
+    tld = tldValue.trim().toLowerCase();
+    const tldErr = validateTld(tld);
+    if (tldErr) {
+      console.error(chalk.red(`Error: ${tldErr}`));
+      process.exit(1);
+    }
+  }
+  const riskyReason = RISKY_TLDS.get(tld);
+  if (riskyReason) {
+    console.warn(chalk.yellow(`Warning: .${tld} -- ${riskyReason}`));
+  }
+  const syncDisabled = process.env.PORTLESS_SYNC_HOSTS === "0" || process.env.PORTLESS_SYNC_HOSTS === "false";
+  if (tld !== DEFAULT_TLD && syncDisabled) {
+    console.warn(
+      chalk.yellow(
+        `Warning: .${tld} domains require ${HOSTS_DISPLAY} entries to resolve to 127.0.0.1.`
+      )
+    );
+    console.warn(chalk.yellow("Hosts sync is disabled. To add entries manually, run:"));
+    console.warn(chalk.cyan(`  ${SUDO_PREFIX}portless hosts sync`));
+  }
   const useHttps = wantHttps || !!(customCertPath && customKeyPath);
   const stateDir = resolveStateDir(proxyPort);
   const store = new RouteStore(stateDir, {
@@ -1372,13 +1613,18 @@ ${chalk.bold("Usage:")}
     if (isForeground) {
       return;
     }
-    const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
+    const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
     const sudoPrefix = needsSudo ? "sudo " : "";
+    const portFlag = proxyPort !== getDefaultPort() ? ` -p ${proxyPort}` : "";
     console.log(chalk.yellow(`Proxy is already running on port ${proxyPort}.`));
-    console.log(chalk.blue(`To restart: portless proxy stop && ${sudoPrefix}portless proxy start`));
+    console.log(
+      chalk.blue(
+        `To restart: ${sudoPrefix}portless proxy stop${portFlag} && ${sudoPrefix}portless proxy start${portFlag}`
+      )
+    );
     return;
   }
-  if (proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) {
+  if (!isWindows && 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"));
@@ -1440,13 +1686,13 @@ ${chalk.bold("Usage:")}
       tlsOptions = {
         cert,
         key,
-        SNICallback: createSNICallback(stateDir, cert, key)
+        SNICallback: createSNICallback(stateDir, cert, key, tld)
       };
     }
   }
   if (isForeground) {
     console.log(chalk.blue.bold("\nportless proxy\n"));
-    startProxyServer(store, proxyPort, tlsOptions);
+    startProxyServer(store, proxyPort, tld, tlsOptions);
     return;
   }
   store.ensureDir();
@@ -1469,10 +1715,14 @@ ${chalk.bold("Usage:")}
         daemonArgs.push("--https");
       }
     }
+    if (tld !== DEFAULT_TLD) {
+      daemonArgs.push("--tld", tld);
+    }
     const child = spawn(process.execPath, daemonArgs, {
       detached: true,
       stdio: ["ignore", logFd, logFd],
-      env: process.env
+      env: process.env,
+      windowsHide: true
     });
     child.unref();
   } finally {
@@ -1481,7 +1731,7 @@ ${chalk.bold("Usage:")}
   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;
+    const needsSudo = !isWindows && proxyPort < PRIVILEGED_PORT_THRESHOLD;
     console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start --foreground`));
     if (fs3.existsSync(logPath)) {
       console.error(chalk.gray(`Logs: ${logPath}`));
@@ -1501,10 +1751,19 @@ async function handleRunMode(args) {
     console.error(chalk.cyan("  portless run next dev"));
     process.exit(1);
   }
-  const inferred = inferProjectName();
+  let baseName;
+  let nameSource;
+  if (parsed.name) {
+    baseName = parsed.name;
+    nameSource = "--name flag";
+  } else {
+    const inferred = inferProjectName();
+    baseName = inferred.name;
+    nameSource = inferred.source;
+  }
   const worktree = detectWorktreePrefix();
-  const effectiveName = worktree ? `${worktree.prefix}.${inferred.name}` : inferred.name;
-  const { dir, port, tls: tls2 } = await discoverState();
+  const effectiveName = worktree ? `${worktree.prefix}.${baseName}` : baseName;
+  const { dir, port, tls: tls2, tld } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
@@ -1515,8 +1774,9 @@ async function handleRunMode(args) {
     effectiveName,
     parsed.commandArgs,
     tls2,
+    tld,
     parsed.force,
-    { nameSource: inferred.source, prefix: worktree?.prefix, prefixSource: worktree?.source },
+    { nameSource, prefix: worktree?.prefix, prefixSource: worktree?.source },
     parsed.appPort
   );
 }
@@ -1530,7 +1790,7 @@ async function handleNamedMode(args) {
     console.error(chalk.cyan("  portless myapp next dev"));
     process.exit(1);
   }
-  const { dir, port, tls: tls2 } = await discoverState();
+  const { dir, port, tls: tls2, tld } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
@@ -1541,6 +1801,7 @@ async function handleNamedMode(args) {
     parsed.name,
     parsed.commandArgs,
     tls2,
+    tld,
     parsed.force,
     void 0,
     parsed.appPort
@@ -1571,7 +1832,7 @@ async function main() {
       console.error(chalk.cyan("  portless --name <name> <command...>"));
       process.exit(1);
     }
-    const skipPortless2 = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
+    const skipPortless2 = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
     if (skipPortless2) {
       const { commandArgs } = parseAppArgs(args);
       if (commandArgs.length === 0) {
@@ -1588,7 +1849,7 @@ async function main() {
   if (isRunCommand) {
     args.shift();
   }
-  const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "skip";
+  const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
   if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy")) {
     const { commandArgs } = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     if (commandArgs.length === 0) {
@@ -1615,6 +1876,10 @@ async function main() {
       await handleList();
       return;
     }
+    if (args[0] === "get") {
+      await handleGet(args);
+      return;
+    }
     if (args[0] === "alias") {
       await handleAlias(args);
       return;