portless 0.10.0 → 0.10.1

package/README.md

@@ -88,7 +88,7 @@ portless myapp next dev
 # -> https://myapp.test
 ```
 
-The proxy auto-syncs `/etc/hosts` for custom TLDs, so `.test` domains resolve correctly.
+The proxy auto-syncs `/etc/hosts` for route hostnames (including `.test`), so those domains resolve on your machine.
 
 Recommended: `.test` (IANA-reserved, no collision risk). Avoid `.local` (conflicts with mDNS/Bonjour) and `.dev` (Google-owned, forces HTTPS via HSTS).
 
@@ -166,6 +166,7 @@ portless alias <name> <port> --force  # Overwrite an existing route
 portless alias --remove <name>   # Remove a static route
 portless list                    # Show active routes
 portless trust                   # Add local CA to system trust store
+portless clean                   # Remove state, CA trust entry, and hosts block
 portless hosts sync              # Add routes to /etc/hosts (fixes Safari)
 portless hosts clean             # Remove portless entries from /etc/hosts
 
@@ -210,7 +211,7 @@ PORTLESS_HTTPS=0                 Disable HTTPS (same as --no-tls)
 PORTLESS_LAN=1                   Enable LAN mode when set to 1 (auto-detects LAN IP)
 PORTLESS_TLD=<tld>               Use a custom TLD (e.g. test; default: localhost)
 PORTLESS_WILDCARD=1              Allow unregistered subdomains to fall back to parent route
-PORTLESS_SYNC_HOSTS=1            Auto-sync /etc/hosts (auto-enabled for custom TLDs)
+PORTLESS_SYNC_HOSTS=0            Disable auto-sync of /etc/hosts (on by default)
 PORTLESS_STATE_DIR=<path>        Override the state directory
 
 # Injected into child processes
@@ -219,7 +220,17 @@ HOST                             Usually 127.0.0.1 (omitted for Expo in LAN mode
 PORTLESS_URL                     Public URL (e.g. https://myapp.localhost)
 ```
 
-> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+> **Reserved names:** `run`, `get`, `alias`, `hosts`, `list`, `trust`, `clean`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run <cmd>` to infer the name from your project, or `portless --name <name> <cmd>` to force any name including reserved ones.
+
+## Uninstall / reset
+
+To remove portless data from your machine (proxy state under `~/.portless` and the system state directory, the local CA from the OS trust store when portless installed it, and the portless block in `/etc/hosts`):
+
+```bash
+portless clean
+```
+
+macOS/Linux may prompt for `sudo`. Custom certificate paths passed with `--cert` and `--key` are not deleted.
 
 ## Safari / DNS
 
@@ -232,7 +243,7 @@ portless hosts sync    # Add current routes to /etc/hosts
 portless hosts clean   # Clean up later
 ```
 
-Auto-syncs `/etc/hosts` for custom TLDs (e.g. `--tld test`). For `.localhost`, set `PORTLESS_SYNC_HOSTS=1` to enable. Disable with `PORTLESS_SYNC_HOSTS=0`.
+Auto-syncs `/etc/hosts` for route hostnames by default (`.localhost`, custom TLDs, LAN `.local`). Set `PORTLESS_SYNC_HOSTS=0` to disable.
 
 ## Proxying Between Portless Apps
 

package/dist/{chunk-WXEE5QH6.js → chunk-FM7IA4AF.js}

@@ -614,6 +614,9 @@ function buildBlock(hostnames) {
 ${entries}
 ${MARKER_END}`;
 }
+function shouldAutoSyncHosts(syncVal) {
+  return syncVal !== "0" && syncVal !== "false";
+}
 function syncHostsFile(hostnames) {
   try {
     const content = readHostsFile();
@@ -1475,6 +1478,7 @@ export {
   extractManagedBlock,
   removeBlock,
   buildBlock,
+  shouldAutoSyncHosts,
   syncHostsFile,
   cleanHostsFile,
   getManagedHostnames,
@@ -1484,6 +1488,8 @@ export {
   PRIVILEGED_PORT_THRESHOLD,
   INTERNAL_LAN_IP_ENV,
   INTERNAL_LAN_IP_FLAG,
+  SYSTEM_STATE_DIR,
+  USER_STATE_DIR,
   WAIT_FOR_PROXY_MAX_ATTEMPTS,
   WAIT_FOR_PROXY_INTERVAL_MS,
   getDefaultPort,

package/dist/cli.js

@@ -9,6 +9,8 @@ import {
   RISKY_TLDS,
   RouteConflictError,
   RouteStore,
+  SYSTEM_STATE_DIR,
+  USER_STATE_DIR,
   WAIT_FOR_PROXY_INTERVAL_MS,
   WAIT_FOR_PROXY_MAX_ATTEMPTS,
   buildProxyStartConfig,
@@ -36,6 +38,7 @@ import {
   readTldFromDir,
   readTlsMarker,
   resolveStateDir,
+  shouldAutoSyncHosts,
   spawnCommand,
   syncHostsFile,
   validateTld,
@@ -43,7 +46,7 @@ import {
   writeLanMarker,
   writeTldFile,
   writeTlsMarker
-} from "./chunk-WXEE5QH6.js";
+} from "./chunk-FM7IA4AF.js";
 
 // src/colors.ts
 function supportsColor() {
@@ -71,8 +74,8 @@ var gray = wrap("90", "39");
 var colors_default = { bold, red, green, yellow, blue, cyan, white, gray };
 
 // src/cli.ts
-import * as fs3 from "fs";
-import * as path3 from "path";
+import * as fs4 from "fs";
+import * as path4 from "path";
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 
 // src/certs.ts
@@ -608,6 +611,129 @@ function trustCA(stateDir) {
     return { trusted: false, error: message };
   }
 }
+function untrustCA(stateDir) {
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  if (!fileExists(caCertPath)) {
+    return { removed: true };
+  }
+  if (!isCATrusted(stateDir)) {
+    return { removed: true };
+  }
+  try {
+    if (process.platform === "darwin") {
+      return untrustCAMacOS(caCertPath);
+    }
+    if (process.platform === "linux") {
+      return untrustCALinux(stateDir);
+    }
+    if (process.platform === "win32") {
+      return untrustCAWindows(caCertPath);
+    }
+    return { removed: false, error: `Unsupported platform: ${process.platform}` };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { removed: false, error: message };
+  }
+}
+function untrustCAMacOS(caCertPath) {
+  const errors = [];
+  const tryExec = (args) => {
+    try {
+      execFileSync("security", args, { stdio: "pipe", timeout: 3e4 });
+      return true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push(message);
+      return false;
+    }
+  };
+  if (tryExec(["remove-trusted-cert", caCertPath])) {
+    return isCATrustedMacOSAfterAttempt(caCertPath) ? { removed: false, error: errors.join("; ") || "Trust entry may still be present" } : { removed: true };
+  }
+  const login = loginKeychainPath();
+  tryExec(["delete-certificate", "-c", CA_COMMON_NAME, login]);
+  tryExec(["delete-certificate", "-c", CA_COMMON_NAME, "/Library/Keychains/System.keychain"]);
+  return isCATrustedMacOSAfterAttempt(caCertPath) ? { removed: false, error: errors.join("; ") || "Could not remove CA from keychain (try sudo)" } : { removed: true };
+}
+function isCATrustedMacOSAfterAttempt(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;
+  }
+}
+function untrustCALinux(stateDir) {
+  const errors = [];
+  let deletedAny = false;
+  for (const config of Object.values(LINUX_CA_TRUST_CONFIGS)) {
+    const dest = path.join(config.certDir, "portless-ca.crt");
+    try {
+      if (fileExists(dest)) {
+        const ours = fs.readFileSync(path.join(stateDir, CA_CERT_FILE), "utf-8").trim();
+        const installed = fs.readFileSync(dest, "utf-8").trim();
+        if (ours === installed) {
+          fs.unlinkSync(dest);
+          deletedAny = true;
+        }
+      }
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  if (deletedAny) {
+    try {
+      const config = getLinuxCATrustConfig();
+      execFileSync(config.updateCommand, [], { stdio: "pipe", timeout: 3e4 });
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  if (isCATrusted(stateDir)) {
+    return {
+      removed: false,
+      error: errors.join("; ") || "CA still trusted (remove portless-ca.crt and run the distro CA update command, often with sudo)"
+    };
+  }
+  return { removed: true };
+}
+function untrustCAWindows(caCertPath) {
+  try {
+    const fingerprint = openssl(["x509", "-in", caCertPath, "-noout", "-fingerprint", "-sha1"]).trim().replace(/^.*=/, "").replace(/:/g, "").toLowerCase();
+    const storeListing = execFileSync("certutil", ["-store", "-user", "Root"], {
+      encoding: "utf-8",
+      timeout: 1e4,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const normalized = storeListing.replace(/\s/g, "").toLowerCase();
+    if (!normalized.includes(fingerprint)) {
+      return { removed: true };
+    }
+    execFileSync("certutil", ["-delstore", "-user", "Root", "portless Local CA"], {
+      stdio: "pipe",
+      timeout: 3e4
+    });
+    if (isCATrustedWindows(caCertPath)) {
+      return { removed: false, error: "certutil could not remove the portless CA from Root" };
+    }
+    return { removed: true };
+  } catch (err) {
+    return { removed: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
 
 // src/auto.ts
 import { createHash } from "crypto";
@@ -783,6 +909,53 @@ function readBranchFromHead(gitdir) {
   }
 }
 
+// src/clean-utils.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+var PORTLESS_STATE_FILES = [
+  "routes.json",
+  "routes.lock",
+  "proxy.pid",
+  "proxy.port",
+  "proxy.log",
+  "proxy.tls",
+  "proxy.tld",
+  "proxy.lan",
+  "ca-key.pem",
+  "ca.pem",
+  "server-key.pem",
+  "server.pem",
+  "server.csr",
+  "server-ext.cnf",
+  "ca.srl"
+];
+var HOST_CERTS_DIR2 = "host-certs";
+function collectStateDirsForCleanup() {
+  const dirs = /* @__PURE__ */ new Set();
+  const add = (d) => {
+    const trimmed = d?.trim();
+    if (!trimmed) return;
+    const resolved = path3.resolve(trimmed);
+    if (fs3.existsSync(resolved)) dirs.add(resolved);
+  };
+  add(USER_STATE_DIR);
+  add(SYSTEM_STATE_DIR);
+  add(process.env.PORTLESS_STATE_DIR);
+  return [...dirs];
+}
+function removePortlessStateFiles(dir) {
+  for (const f of PORTLESS_STATE_FILES) {
+    try {
+      fs3.unlinkSync(path3.join(dir, f));
+    } catch {
+    }
+  }
+  try {
+    fs3.rmSync(path3.join(dir, HOST_CERTS_DIR2), { recursive: true, force: true });
+  } catch {
+  }
+}
+
 // src/mdns.ts
 import { spawn, spawnSync } from "child_process";
 
@@ -815,7 +988,7 @@ function isInternalInterface(iname, macStr, internal) {
   return false;
 }
 function probeDefaultRouteIPv4() {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const socket = createSocket({ type: "udp4", reuseAddr: true });
     socket.on("error", (error) => {
       socket.close();
@@ -827,7 +1000,7 @@ function probeDefaultRouteIPv4() {
       socket.close();
       socket.unref();
       if (addr && "address" in addr && addr.address && addr.address !== NO_ROUTE_IP) {
-        resolve2(addr.address);
+        resolve3(addr.address);
       } else {
         reject(new Error("No route to host"));
       }
@@ -1138,10 +1311,10 @@ function getEntryScript() {
 function isLocallyInstalled() {
   let dir = process.cwd();
   for (; ; ) {
-    if (fs3.existsSync(path3.join(dir, "node_modules", "portless", "package.json"))) {
+    if (fs4.existsSync(path4.join(dir, "node_modules", "portless", "package.json"))) {
       return true;
     }
-    const parent = path3.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -1177,11 +1350,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     console.warn(chalk.yellow(`LAN mode disabled: ${reason}`));
   }
   const routesPath = store.getRoutesPath();
-  if (!fs3.existsSync(routesPath)) {
-    fs3.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
+  if (!fs4.existsSync(routesPath)) {
+    fs4.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
   }
   try {
-    fs3.chmodSync(routesPath, FILE_MODE);
+    fs4.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
   fixOwnership(routesPath);
@@ -1189,8 +1362,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
   let debounceTimer = null;
   let watcher = null;
   let pollingInterval = null;
-  const syncVal = process.env.PORTLESS_SYNC_HOSTS;
-  const autoSyncHosts = syncVal === "1" || syncVal === "true" || tld !== DEFAULT_TLD && !activeLanIp && syncVal !== "0" && syncVal !== "false";
+  const autoSyncHosts = shouldAutoSyncHosts(process.env.PORTLESS_SYNC_HOSTS);
   const onMdnsError = (msg) => console.warn(chalk.yellow(msg));
   const publishCachedRoutes = () => {
     if (!activeLanIp) return;
@@ -1242,7 +1414,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     }
   };
   try {
-    watcher = fs3.watch(routesPath, () => {
+    watcher = fs4.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
@@ -1292,8 +1464,8 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
     redirectServer.listen(80);
   }
   server.listen(proxyPort, () => {
-    fs3.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
-    fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
+    fs4.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+    fs4.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
     writeTlsMarker(store.dir, isTls);
     writeTldFile(store.dir, tld);
     writeLanMarker(store.dir, activeLanIp);
@@ -1309,7 +1481,7 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
       console.log(chalk.gray("Services are discoverable as <name>.local on your network"));
       if (isTls) {
         console.log(chalk.yellow("For HTTPS on devices, install the CA certificate:"));
-        console.log(chalk.gray(`  ${path3.join(store.dir, "ca.pem")}`));
+        console.log(chalk.gray(`  ${path4.join(store.dir, "ca.pem")}`));
       }
       if (!lanIpPinned) {
         lanMonitor = startLanIpMonitor({
@@ -1341,11 +1513,11 @@ function startProxyServer(store, proxyPort, tld, tlsOptions, lanIp, strict) {
       redirectServer.close();
     }
     try {
-      fs3.unlinkSync(store.pidPath);
+      fs4.unlinkSync(store.pidPath);
     } catch {
     }
     try {
-      fs3.unlinkSync(store.portFilePath);
+      fs4.unlinkSync(store.portFilePath);
     } catch {
     }
     writeTlsMarker(store.dir, false);
@@ -1374,7 +1546,7 @@ function sudoStopOrHint(port) {
 }
 async function stopProxy(store, proxyPort, _tls) {
   const pidPath = store.pidPath;
-  if (!fs3.existsSync(pidPath)) {
+  if (!fs4.existsSync(pidPath)) {
     if (await isProxyRunning(proxyPort)) {
       console.log(colors_default.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
@@ -1382,7 +1554,7 @@ async function stopProxy(store, proxyPort, _tls) {
         try {
           process.kill(pid, "SIGTERM");
           try {
-            fs3.unlinkSync(store.portFilePath);
+            fs4.unlinkSync(store.portFilePath);
           } catch {
           }
           console.log(colors_default.green(`Killed process ${pid}. Proxy stopped.`));
@@ -1417,10 +1589,10 @@ async function stopProxy(store, proxyPort, _tls) {
     return;
   }
   try {
-    const pid = parseInt(fs3.readFileSync(pidPath, "utf-8"), 10);
+    const pid = parseInt(fs4.readFileSync(pidPath, "utf-8"), 10);
     if (isNaN(pid)) {
       console.error(colors_default.red("Corrupted PID file. Removing it."));
-      fs3.unlinkSync(pidPath);
+      fs4.unlinkSync(pidPath);
       return;
     }
     try {
@@ -1431,9 +1603,9 @@ async function stopProxy(store, proxyPort, _tls) {
         return;
       }
       console.log(colors_default.yellow("Proxy process is no longer running. Cleaning up stale files."));
-      fs3.unlinkSync(pidPath);
+      fs4.unlinkSync(pidPath);
       try {
-        fs3.unlinkSync(store.portFilePath);
+        fs4.unlinkSync(store.portFilePath);
       } catch {
       }
       return;
@@ -1445,13 +1617,13 @@ async function stopProxy(store, proxyPort, _tls) {
         )
       );
       console.log(colors_default.yellow("Removing stale PID file."));
-      fs3.unlinkSync(pidPath);
+      fs4.unlinkSync(pidPath);
       return;
     }
     process.kill(pid, "SIGTERM");
-    fs3.unlinkSync(pidPath);
+    fs4.unlinkSync(pidPath);
     try {
-      fs3.unlinkSync(store.portFilePath);
+      fs4.unlinkSync(store.portFilePath);
     } catch {
     }
     console.log(colors_default.green("Proxy stopped."));
@@ -1581,10 +1753,10 @@ portless
     if (!discovered) {
       console.error(colors_default.red("Failed to start proxy."));
       const fallbackDir = resolveStateDir(getDefaultPort(desiredConfig.useHttps));
-      const logPath = path3.join(fallbackDir, "proxy.log");
+      const logPath = path4.join(fallbackDir, "proxy.log");
       console.error(colors_default.blue("Try starting it manually:"));
       console.error(colors_default.cyan(`  ${manualStartCommand}`));
-      if (fs3.existsSync(logPath)) {
+      if (fs4.existsSync(logPath)) {
         console.error(colors_default.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
@@ -1657,7 +1829,7 @@ portless
     console.log(chalk.green(`  LAN -> ${finalUrl}`));
     console.log(chalk.gray("  (accessible from other devices on the same WiFi network)\n"));
   }
-  const basename3 = path3.basename(commandArgs[0]);
+  const basename3 = path4.basename(commandArgs[0]);
   const isExpo = basename3 === "expo";
   const isExpoLan = isExpo && (lanMode || isLanEnvEnabled());
   const hostBind = isExpoLan ? void 0 : "127.0.0.1";
@@ -1839,6 +2011,7 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless alias --remove <name>")}   Remove a static route
   ${colors_default.cyan("portless list")}                    Show active routes
   ${colors_default.cyan("portless trust")}                   Add local CA to system trust store
+  ${colors_default.cyan("portless clean")}                   Remove portless state, trust entry, and hosts block
   ${colors_default.cyan("portless hosts sync")}              Add routes to ${HOSTS_DISPLAY} (fixes Safari)
   ${colors_default.cyan("portless hosts clean")}             Remove portless entries from ${HOSTS_DISPLAY}
 
@@ -1916,7 +2089,7 @@ ${colors_default.bold("Environment variables:")}
   PORTLESS_LAN=1                Enable LAN mode when set to 1 (set in .bashrc / .zshrc)
   PORTLESS_TLD=<tld>            Use a custom TLD (e.g. test, dev; default: localhost)
   PORTLESS_WILDCARD=1           Allow unregistered subdomains to fall back to parent route
-  PORTLESS_SYNC_HOSTS=1         Auto-sync ${HOSTS_DISPLAY} (auto-enabled for custom TLDs)
+  PORTLESS_SYNC_HOSTS=0         Disable auto-sync of ${HOSTS_DISPLAY} (on by default)
   PORTLESS_STATE_DIR=<path>     Override the state directory
   PORTLESS=0                    Run command directly without proxy
 
@@ -1929,8 +2102,8 @@ ${colors_default.bold("Child process environment:")}
 ${colors_default.bold("Safari / DNS:")}
   .localhost subdomains auto-resolve in Chrome, Firefox, and Edge.
   Safari relies on the system DNS resolver, which may not handle them.
-  Auto-syncs ${HOSTS_DISPLAY} for custom TLDs (e.g. --tld test). For .localhost,
-  set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync:
+  Auto-syncs ${HOSTS_DISPLAY} for route hostnames by default (including .localhost,
+  custom TLDs, and LAN .local). Set PORTLESS_SYNC_HOSTS=0 to disable. To manually sync:
     ${colors_default.cyan("portless hosts sync")}
   Clean up later with:
     ${colors_default.cyan("portless hosts clean")}
@@ -1939,20 +2112,20 @@ ${colors_default.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
 
 ${colors_default.bold("Reserved names:")}
-  run, get, alias, hosts, list, trust, proxy are subcommands and cannot
+  run, get, alias, hosts, list, trust, clean, 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.10.0");
+  console.log("0.10.1");
   process.exit(0);
 }
 async function handleTrust() {
   const { dir } = await discoverState();
-  if (!fs3.existsSync(dir)) {
-    fs3.mkdirSync(dir, { recursive: true });
+  if (!fs4.existsSync(dir)) {
+    fs4.mkdirSync(dir, { recursive: true });
   }
   const { caGenerated } = ensureCerts(dir);
   if (caGenerated) {
@@ -1988,6 +2161,90 @@ async function handleTrust() {
   console.error(colors_default.red(`Failed to trust CA: ${result.error}`));
   process.exit(1);
 }
+async function handleClean(args) {
+  if (args[1] === "--help" || args[1] === "-h") {
+    console.log(`
+${colors_default.bold("portless clean")} - Remove portless artifacts from this machine.
+
+Stops the proxy if it is running, removes the local CA from the OS trust store
+when it was installed by portless, deletes known files under state directories
+(~/.portless, the system state directory, and PORTLESS_STATE_DIR when set),
+and removes the portless block from ${HOSTS_DISPLAY}.
+
+Only allowlisted filenames under each state directory are deleted. Custom
+certificate paths from --cert and --key are never removed.
+
+macOS/Linux may prompt for sudo when the proxy, trust store, or ${HOSTS_DISPLAY}
+require elevated privileges. On Windows, run as Administrator if needed.
+
+${colors_default.bold("Usage:")}
+  ${colors_default.cyan("portless clean")}
+
+${colors_default.bold("Options:")}
+  --help, -h             Show this help
+`);
+    process.exit(0);
+  }
+  if (args.length > 1) {
+    console.error(colors_default.red(`Error: Unknown argument "${args[1]}".`));
+    console.error(colors_default.cyan("  portless clean --help"));
+    process.exit(1);
+  }
+  console.log(colors_default.cyan("Stopping proxy if it is running..."));
+  const { dir, port, tls: tls2 } = await discoverState();
+  const store = new RouteStore(dir, {
+    onWarning: (msg) => console.warn(colors_default.yellow(msg))
+  });
+  await stopProxy(store, port, tls2);
+  const stateDirs = collectStateDirsForCleanup();
+  for (const stateDir of stateDirs) {
+    const caPath = path4.join(stateDir, "ca.pem");
+    if (!fs4.existsSync(caPath)) continue;
+    const wasTrusted = isCATrusted(stateDir);
+    if (!wasTrusted) continue;
+    const untrustResult = untrustCA(stateDir);
+    if (untrustResult.removed) {
+      console.log(colors_default.green("Removed local CA from the system trust store."));
+    } else if (untrustResult.error) {
+      console.warn(
+        colors_default.yellow(
+          `Could not remove CA from trust store: ${untrustResult.error}
+Try: sudo portless clean (Linux), or delete the certificate manually.`
+        )
+      );
+    }
+  }
+  for (const stateDir of stateDirs) {
+    removePortlessStateFiles(stateDir);
+  }
+  console.log(colors_default.green("Removed portless state files from known state directories."));
+  if (cleanHostsFile()) {
+    console.log(colors_default.green(`Removed portless entries from ${HOSTS_DISPLAY}.`));
+  } else if (!isWindows && process.getuid?.() !== 0) {
+    console.log(
+      colors_default.yellow(`Updating ${HOSTS_DISPLAY} requires elevated privileges. Requesting sudo...`)
+    );
+    const result = spawnSync2(
+      "sudo",
+      ["env", ...collectPortlessEnvArgs(), process.execPath, getEntryScript(), "clean"],
+      {
+        stdio: "inherit",
+        timeout: SUDO_SPAWN_TIMEOUT_MS
+      }
+    );
+    if (result.status !== 0) {
+      console.error(colors_default.red(`Failed to update ${HOSTS_DISPLAY}. Run: sudo portless clean`));
+      process.exit(1);
+    }
+  } else {
+    console.warn(
+      colors_default.yellow(
+        `Could not remove portless entries from ${HOSTS_DISPLAY}${isWindows ? " (run as Administrator)." : "."}`
+      )
+    );
+  }
+  console.log(colors_default.green("Clean finished."));
+}
 async function handleList() {
   const { dir, port, tls: tls2 } = await discoverState();
   const store = new RouteStore(dir, {
@@ -2122,8 +2379,8 @@ ${colors_default.bold("Usage:")}
   ${colors_default.cyan("portless hosts clean")}   Remove portless entries from ${HOSTS_DISPLAY}
 
 ${colors_default.bold("Auto-sync:")}
-  Auto-enabled for custom TLDs (e.g. --tld test). For .localhost, set
-  PORTLESS_SYNC_HOSTS=1 to enable. Disable with PORTLESS_SYNC_HOSTS=0.
+  The proxy updates ${HOSTS_DISPLAY} for route hostnames by default. Disable with
+  PORTLESS_SYNC_HOSTS=0.
 `);
     process.exit(0);
   }
@@ -2491,8 +2748,8 @@ ${colors_default.bold("LAN mode (--lan):")}
           console.log(colors_default.green(`Proxy started on port ${proxyPort}.`));
         } else {
           console.error(colors_default.red("Proxy process started but is not responding."));
-          const logPath2 = path3.join(resolveStateDir(proxyPort), "proxy.log");
-          if (fs3.existsSync(logPath2)) {
+          const logPath2 = path4.join(resolveStateDir(proxyPort), "proxy.log");
+          if (fs4.existsSync(logPath2)) {
             console.error(colors_default.gray(`Logs: ${logPath2}`));
           }
         }
@@ -2531,8 +2788,8 @@ ${colors_default.bold("LAN mode (--lan):")}
     store.ensureDir();
     if (customCertPath && customKeyPath) {
       try {
-        const cert = fs3.readFileSync(customCertPath);
-        const key = fs3.readFileSync(customKeyPath);
+        const cert = fs4.readFileSync(customCertPath);
+        const key = fs4.readFileSync(customKeyPath);
         const certStr = cert.toString("utf-8");
         const keyStr = key.toString("utf-8");
         if (!certStr.includes("-----BEGIN CERTIFICATE-----")) {
@@ -2577,9 +2834,9 @@ ${colors_default.bold("LAN mode (--lan):")}
           console.warn(colors_default.cyan("  portless trust"));
         }
       }
-      const cert = fs3.readFileSync(certs.certPath);
-      const key = fs3.readFileSync(certs.keyPath);
-      const ca = fs3.readFileSync(certs.caPath);
+      const cert = fs4.readFileSync(certs.certPath);
+      const key = fs4.readFileSync(certs.keyPath);
+      const ca = fs4.readFileSync(certs.caPath);
       tlsOptions = {
         cert,
         key,
@@ -2594,11 +2851,11 @@ ${colors_default.bold("LAN mode (--lan):")}
     return;
   }
   store.ensureDir();
-  const logPath = path3.join(stateDir, "proxy.log");
-  const logFd = fs3.openSync(logPath, "a");
+  const logPath = path4.join(stateDir, "proxy.log");
+  const logFd = fs4.openSync(logPath, "a");
   try {
     try {
-      fs3.chmodSync(logPath, FILE_MODE);
+      fs4.chmodSync(logPath, FILE_MODE);
     } catch {
     }
     fixOwnership(logPath);
@@ -2628,13 +2885,13 @@ ${colors_default.bold("LAN mode (--lan):")}
     });
     child.unref();
   } finally {
-    fs3.closeSync(logFd);
+    fs4.closeSync(logFd);
   }
   if (!await waitForProxy(proxyPort, void 0, void 0, useHttps)) {
     console.error(colors_default.red("Proxy failed to start (timed out waiting for it to listen)."));
     console.error(colors_default.blue("Try starting the proxy in the foreground to see the error:"));
     console.error(colors_default.cyan("  portless proxy start --foreground"));
-    if (fs3.existsSync(logPath)) {
+    if (fs4.existsSync(logPath)) {
       console.error(colors_default.gray(`Logs: ${logPath}`));
     }
     process.exit(1);
@@ -2795,7 +3052,7 @@ async function main() {
     args.shift();
   }
   const skipPortless = process.env.PORTLESS === "0" || process.env.PORTLESS === "false" || process.env.PORTLESS === "skip";
-  if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy")) {
+  if (skipPortless && (isRunCommand || args.length >= 2 && args[0] !== "proxy" && args[0] !== "clean")) {
     const { commandArgs } = isRunCommand ? parseRunArgs(args) : parseAppArgs(args);
     if (commandArgs.length === 0) {
       console.error(colors_default.red("Error: No command provided."));
@@ -2817,6 +3074,10 @@ async function main() {
       await handleTrust();
       return;
     }
+    if (args[0] === "clean") {
+      await handleClean(args);
+      return;
+    }
     if (args[0] === "list") {
       await handleList();
       return;

package/dist/index.d.ts

@@ -157,6 +157,11 @@ declare function removeBlock(content: string): string;
  * Build a portless-managed block for the given hostnames.
  */
 declare function buildBlock(hostnames: string[]): string;
+/**
+ * Whether the proxy should write route hostnames to the hosts file.
+ * Disabled only when `PORTLESS_SYNC_HOSTS` is `0` or `false` (opt-out).
+ */
+declare function shouldAutoSyncHosts(syncVal: string | undefined): boolean;
 /**
  * Sync /etc/hosts to include entries for all given hostnames.
  * Replaces any existing portless-managed block. Requires root access.
@@ -178,4 +183,4 @@ declare function getManagedHostnames(): string[];
  */
 declare function checkHostResolution(hostname: string): Promise<boolean>;
 
-export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, syncHostsFile };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, buildBlock, checkHostResolution, cleanHostsFile, createHttpRedirectServer, createProxyServer, escapeHtml, extractManagedBlock, fixOwnership, formatUrl, getManagedHostnames, isErrnoException, parseHostname, removeBlock, shouldAutoSyncHosts, syncHostsFile };

package/dist/index.js

@@ -19,8 +19,9 @@ import {
   isErrnoException,
   parseHostname,
   removeBlock,
+  shouldAutoSyncHosts,
   syncHostsFile
-} from "./chunk-WXEE5QH6.js";
+} from "./chunk-FM7IA4AF.js";
 export {
   DIR_MODE,
   FILE_MODE,
@@ -42,5 +43,6 @@ export {
   isErrnoException,
   parseHostname,
   removeBlock,
+  shouldAutoSyncHosts,
   syncHostsFile
 };

package/package.json

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