portless 0.9.6 → 0.10.1

package/README.md

@@ -32,7 +32,7 @@ portless myapp next dev
 
 HTTPS with HTTP/2 is enabled by default. On first run, portless generates a local CA, trusts it, and binds port 443 (auto-elevates with sudo on macOS/Linux). Use `--no-tls` for plain HTTP.
 
-The proxy auto-starts when you run an app. A random port (4000--4999) is assigned via the `PORT` environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore `PORT` (Vite, Astro, React Router, Angular, Expo, React Native), portless auto-injects `--port` and `--host` flags.
+The proxy auto-starts when you run an app. A random port (4000--4999) is assigned via the `PORT` environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore `PORT` (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the right `--port` flag and, when needed, a matching `--host` flag.
 
 ## Use in package.json
 
@@ -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).
 
@@ -129,6 +129,33 @@ portless trust
 
 On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). On Windows, it uses `certutil` to add the CA to the system trust store.
 
+## LAN mode
+
+```bash
+portless proxy start --lan
+portless proxy start --lan --https
+portless proxy start --lan --ip 192.168.1.42
+```
+
+`--lan` switches the proxy to mDNS discovery: services are advertised as `<name>.local` and reachable from any device on the same network. Portless auto-detects your LAN IP and follows Wi-Fi/IP changes automatically, but you can pin another address with `--ip <address>` or by exporting `PORTLESS_LAN_IP`. Set `PORTLESS_LAN=1` in your shell (0/1 boolean) to make LAN mode the default whenever the proxy starts.
+
+Portless remembers LAN mode via `proxy.lan`, so if you stop a LAN proxy and start it again, it stays in LAN mode. Other proxy settings still follow the current flags and env vars. Use `PORTLESS_LAN=0` for one start to switch back to `.localhost` mode. If a proxy is already running with different explicit LAN/TLS/TLD settings, portless warns and asks you to stop it first.
+
+LAN mode depends on the system mDNS tools that portless already spawns: macOS ships with `dns-sd`, while Linux uses `avahi-publish-address` from `avahi-utils` (install via `sudo apt install avahi-utils` or your distro’s equivalent). If the command is missing or your network isn’t reachable, `portless proxy start --lan` prints the relevant error and exits.
+
+### Framework notes
+
+- **Next.js**: add your `.local` hostnames to `allowedDevOrigins`:
+
+  ```js
+  // next.config.js
+  module.exports = {
+    allowedDevOrigins: ["myapp.local", "*.myapp.local"],
+  };
+  ```
+
+- **Expo / React Native**: portless always injects `--port`. React Native also gets `--host 127.0.0.1`. Expo gets `--host localhost` outside LAN mode, but in LAN mode portless leaves Metro on its default LAN host behavior instead of forcing `--host` or `HOST`.
+
 ## Commands
 
 ```bash
@@ -139,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
 
@@ -148,6 +176,7 @@ PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 # Proxy control
 portless proxy start             # Start the HTTPS proxy (port 443, daemon)
 portless proxy start --no-tls    # Start without HTTPS (port 80)
+portless proxy start --lan       # Start in LAN mode (mDNS .local for devices)
 portless proxy start -p 1355     # Start on a custom port (no sudo)
 portless proxy start --foreground  # Start in foreground (for debugging)
 portless proxy start --wildcard  # Allow unregistered subdomains to fall back to parent
@@ -160,6 +189,8 @@ portless proxy stop              # Stop the proxy
 -p, --port <number>              Port for the proxy (default: 443, or 80 with --no-tls)
 --no-tls                         Disable HTTPS (use plain HTTP on port 80)
 --https                          Enable HTTPS (default, accepted for compatibility)
+--lan                            Enable LAN mode (mDNS .local for real devices)
+--ip <address>                   Pin a specific LAN IP (disables auto-follow; use with --lan)
 --cert <path>                    Use a custom TLS certificate
 --key <path>                     Use a custom TLS private key
 --foreground                     Run proxy in foreground instead of daemon
@@ -176,19 +207,30 @@ portless proxy stop              # Stop the proxy
 # Configuration
 PORTLESS_PORT=<number>           Override the default proxy port
 PORTLESS_APP_PORT=<number>       Use a fixed port for the app (same as --app-port)
-PORTLESS_HTTPS                   HTTPS on by default; set to 0 to disable (same as --no-tls)
+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
 PORT                             Ephemeral port the child should listen on
-HOST                             Always 127.0.0.1
+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
 
@@ -201,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-OPTRASOS.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();
@@ -670,6 +673,8 @@ import { execSync, spawn } from "child_process";
 var isWindows2 = process.platform === "win32";
 var FALLBACK_PROXY_PORT = 1355;
 var PRIVILEGED_PORT_THRESHOLD = 1024;
+var INTERNAL_LAN_IP_ENV = "PORTLESS_INTERNAL_LAN_IP";
+var INTERNAL_LAN_IP_FLAG = "--lan-ip-auto";
 var SYSTEM_STATE_DIR = isWindows2 ? path2.join(os.tmpdir(), "portless") : "/tmp/portless";
 var USER_STATE_DIR = path2.join(os.homedir(), ".portless");
 var MIN_APP_PORT = 4e3;
@@ -816,6 +821,26 @@ function writeTlsMarker(dir, enabled) {
     }
   }
 }
+var LAN_MARKER_FILE = "proxy.lan";
+function readLanMarker(dir) {
+  try {
+    const raw = fs3.readFileSync(path2.join(dir, LAN_MARKER_FILE), "utf-8").trim();
+    return raw || null;
+  } catch {
+    return null;
+  }
+}
+function writeLanMarker(dir, ip) {
+  const markerPath = path2.join(dir, LAN_MARKER_FILE);
+  if (!ip) {
+    try {
+      fs3.unlinkSync(markerPath);
+    } catch {
+    }
+  } else {
+    fs3.writeFileSync(markerPath, ip, { mode: 420 });
+  }
+}
 var DEFAULT_TLD = "localhost";
 var RISKY_TLDS = /* @__PURE__ */ new Map([
   ["local", "conflicts with mDNS/Bonjour on macOS"],
@@ -872,20 +897,78 @@ function isWildcardEnvEnabled() {
   const val = process.env.PORTLESS_WILDCARD;
   return val === "1" || val === "true";
 }
+function isLanEnvEnabled() {
+  const val = process.env.PORTLESS_LAN;
+  return val === "1" || val === "true";
+}
+function buildProxyStartConfig(options) {
+  const effectiveTld = options.lanMode ? "local" : options.tld;
+  const args = [];
+  if (options.foreground) {
+    args.push("--foreground");
+  }
+  if (options.includePort && options.proxyPort !== void 0) {
+    args.push("--port", options.proxyPort.toString());
+  }
+  if (options.useHttps) {
+    if (options.customCertPath && options.customKeyPath) {
+      args.push("--cert", options.customCertPath, "--key", options.customKeyPath);
+    } else {
+      args.push("--https");
+    }
+  } else {
+    args.push("--no-tls");
+  }
+  if (options.lanMode) {
+    args.push("--lan");
+    if (options.lanIp) {
+      if (options.lanIpExplicit) {
+        args.push("--ip", options.lanIp);
+      } else {
+        args.push(INTERNAL_LAN_IP_FLAG, options.lanIp);
+      }
+    }
+  } else if (effectiveTld !== DEFAULT_TLD) {
+    args.push("--tld", effectiveTld);
+  }
+  if (options.useWildcard) {
+    args.push("--wildcard");
+  }
+  return { effectiveTld, args };
+}
 async function discoverState() {
   if (process.env.PORTLESS_STATE_DIR) {
-    const dir = process.env.PORTLESS_STATE_DIR;
-    const port = readPortFromDir(dir) ?? getDefaultPort();
-    const tls = readTlsMarker(dir);
-    const tld = readTldFromDir(dir);
-    return { dir, port, tls, tld };
+    const dir2 = process.env.PORTLESS_STATE_DIR;
+    const port = readPortFromDir(dir2) ?? getDefaultPort();
+    const lanIp = readLanMarker(dir2);
+    if (await isProxyRunning(port) || await isPortListening(port)) {
+      const tls = readTlsMarker(dir2);
+      const tld = readTldFromDir(dir2);
+      return { dir: dir2, port, tls, tld, lanMode: lanIp !== null || tld === "local", lanIp };
+    }
+    return {
+      dir: dir2,
+      port,
+      tls: readTlsMarker(dir2),
+      tld: readTldFromDir(dir2),
+      lanMode: lanIp !== null,
+      lanIp: null
+    };
   }
   const userPort = readPortFromDir(USER_STATE_DIR);
   if (userPort !== null) {
     if (await isProxyRunning(userPort)) {
       const tls = readTlsMarker(USER_STATE_DIR);
       const tld = readTldFromDir(USER_STATE_DIR);
-      return { dir: USER_STATE_DIR, port: userPort, tls, tld };
+      const lanIp = readLanMarker(USER_STATE_DIR);
+      return {
+        dir: USER_STATE_DIR,
+        port: userPort,
+        tls,
+        tld,
+        lanMode: lanIp !== null || tld === "local",
+        lanIp
+      };
     }
   }
   const systemPort = readPortFromDir(SYSTEM_STATE_DIR);
@@ -893,24 +976,36 @@ async function discoverState() {
     if (await isProxyRunning(systemPort)) {
       const tls = readTlsMarker(SYSTEM_STATE_DIR);
       const tld = readTldFromDir(SYSTEM_STATE_DIR);
-      return { dir: SYSTEM_STATE_DIR, port: systemPort, tls, tld };
+      const lanIp = readLanMarker(SYSTEM_STATE_DIR);
+      return {
+        dir: SYSTEM_STATE_DIR,
+        port: systemPort,
+        tls,
+        tld,
+        lanMode: lanIp !== null || tld === "local",
+        lanIp
+      };
     }
   }
   const configuredPort = getDefaultPort();
   const probePorts = /* @__PURE__ */ new Set([443, 80, FALLBACK_PROXY_PORT, configuredPort]);
   for (const port of probePorts) {
     if (await isProxyRunning(port)) {
-      const dir = resolveStateDir(port);
-      const tls = readTlsMarker(dir);
-      const tld = readTldFromDir(dir);
-      return { dir, port, tls, tld };
+      const dir2 = resolveStateDir(port);
+      const tls = readTlsMarker(dir2);
+      const tld = readTldFromDir(dir2);
+      const lanIp = readLanMarker(dir2);
+      return { dir: dir2, port, tls, tld, lanMode: lanIp !== null || tld === "local", lanIp };
     }
   }
+  const dir = resolveStateDir(configuredPort);
   return {
-    dir: resolveStateDir(configuredPort),
+    dir,
     port: configuredPort,
     tls: false,
-    tld: getDefaultTld()
+    tld: getDefaultTld(),
+    lanMode: readLanMarker(dir) !== null,
+    lanIp: null
   };
 }
 async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
@@ -964,6 +1059,22 @@ function isProxyRunning(port, tls = false) {
     req.end();
   });
 }
+function isPortListening(port) {
+  return new Promise((resolve) => {
+    const socket = net2.createConnection({ host: "127.0.0.1", port });
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(SOCKET_TIMEOUT_MS);
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.once("timeout", () => finish(false));
+  });
+}
 function parsePidFromNetstat(output, port) {
   for (const line of output.split(/\r?\n/)) {
     if (!line.includes("LISTENING")) continue;
@@ -1091,6 +1202,7 @@ function spawnCommand(commandArgs, options) {
 }
 var FRAMEWORKS_NEEDING_PORT = {
   vite: { strictPort: true },
+  vp: { strictPort: true },
   "react-router": { strictPort: true },
   astro: { strictPort: false },
   ng: { strictPort: false },
@@ -1136,6 +1248,8 @@ function injectFrameworkFlags(commandArgs, port) {
     }
   }
   if (!commandArgs.includes("--host")) {
+    const isExpoLan = basename2 === "expo" && isLanEnvEnabled();
+    if (isExpoLan) return;
     const hostValue = basename2 === "expo" ? "localhost" : "127.0.0.1";
     commandArgs.push("--host", hostValue);
   }
@@ -1364,6 +1478,7 @@ export {
   extractManagedBlock,
   removeBlock,
   buildBlock,
+  shouldAutoSyncHosts,
   syncHostsFile,
   cleanHostsFile,
   getManagedHostnames,
@@ -1371,22 +1486,32 @@ export {
   isWindows2 as isWindows,
   FALLBACK_PROXY_PORT,
   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,
-  getProtocolPort,
   getDefaultPort,
   resolveStateDir,
+  readTlsMarker,
   writeTlsMarker,
+  readLanMarker,
+  writeLanMarker,
   DEFAULT_TLD,
   RISKY_TLDS,
   validateTld,
+  readTldFromDir,
   writeTldFile,
   getDefaultTld,
   isHttpsEnvDisabled,
   isWildcardEnvEnabled,
+  isLanEnvEnabled,
+  buildProxyStartConfig,
   discoverState,
   findFreePort,
   isProxyRunning,
+  isPortListening,
   findPidOnPort,
   waitForProxy,
   spawnCommand,