portless 0.1.0 → 0.2.1

package/README.md

@@ -80,7 +80,7 @@ flowchart TD
     Proxy --> App2
 ```
 
-1. **Start the proxy** -- runs on port 80 in the background (requires sudo once)
+1. **Start the proxy** -- runs on port 80 by default in the background (requires sudo once)
 2. **Run apps** -- `portless <name> <command>` assigns a free port and registers with the proxy
 3. **Access via URL** -- `http://<name>.localhost` routes through the proxy to your app
 
@@ -97,9 +97,14 @@ PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 # Also accepts PORTLESS=skip
 
 # Proxy control
-sudo portless proxy              # Start the proxy
+sudo portless proxy              # Start the proxy (port 80)
+sudo portless proxy --port 8080  # Start the proxy on a custom port
 sudo portless proxy stop         # Stop the proxy
 
+# Options
+--port <number>                  # Port for the proxy (default: 80)
+                                 # Ports >= 1024 do not require sudo
+
 # Info
 portless --help                  # Show help
 portless --version               # Show version

package/dist/cli.js

@@ -11,7 +11,7 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as readline from "readline";
-import { spawn, spawnSync } from "child_process";
+import { execSync, spawn, spawnSync } from "child_process";
 
 // src/cli-utils.ts
 import * as net from "net";
@@ -71,13 +71,37 @@ function prompt(question) {
   });
 }
 var PORTLESS_DIR = "/tmp/portless";
+var PROXY_PORT_PATH = path.join(PORTLESS_DIR, "proxy.port");
+var DEFAULT_PROXY_PORT = 80;
 var store = new RouteStore(PORTLESS_DIR, {
   onWarning: (msg) => console.warn(chalk.yellow(msg))
 });
-async function waitForProxy(maxAttempts = 20, intervalMs = 250) {
+function readProxyPort() {
+  try {
+    const raw = fs.readFileSync(PROXY_PORT_PATH, "utf-8").trim();
+    const port = parseInt(raw, 10);
+    return isNaN(port) ? DEFAULT_PROXY_PORT : port;
+  } catch {
+    return DEFAULT_PROXY_PORT;
+  }
+}
+function findPidOnPort(port) {
+  try {
+    const output = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
+      encoding: "utf-8",
+      timeout: 5e3
+    });
+    const pid = parseInt(output.trim().split("\n")[0], 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+async function waitForProxy(proxyPort, maxAttempts = 20, intervalMs = 250) {
+  const port = proxyPort ?? readProxyPort();
   for (let i = 0; i < maxAttempts; i++) {
     await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    if (await isProxyRunning()) {
+    if (await isProxyRunning(port)) {
       return true;
     }
   }
@@ -115,7 +139,7 @@ function spawnCommand(commandArgs, options) {
     process.exit(code ?? 1);
   });
 }
-function startProxyServer() {
+function startProxyServer(proxyPort) {
   store.ensureDir();
   const routesPath = store.getRoutesPath();
   if (!fs.existsSync(routesPath)) {
@@ -149,7 +173,7 @@ function startProxyServer() {
   });
   server.on("error", (err) => {
     if (err.code === "EADDRINUSE") {
-      console.error(chalk.red("Port 80 is already in use"));
+      console.error(chalk.red(`Port ${proxyPort} is already in use`));
     } else if (err.code === "EACCES") {
       console.error(chalk.red("Permission denied. Use: sudo portless proxy"));
     } else {
@@ -157,9 +181,10 @@ function startProxyServer() {
     }
     process.exit(1);
   });
-  server.listen(80, () => {
+  server.listen(proxyPort, () => {
     fs.writeFileSync(store.pidPath, process.pid.toString(), { mode: 420 });
-    console.log(chalk.green("HTTP proxy listening on port 80"));
+    fs.writeFileSync(PROXY_PORT_PATH, proxyPort.toString(), { mode: 420 });
+    console.log(chalk.green(`HTTP proxy listening on port ${proxyPort}`));
   });
   let exiting = false;
   const cleanup = () => {
@@ -172,6 +197,10 @@ function startProxyServer() {
       fs.unlinkSync(store.pidPath);
     } catch {
     }
+    try {
+      fs.unlinkSync(PROXY_PORT_PATH);
+    } catch {
+    }
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), 2e3).unref();
   };
@@ -182,8 +211,38 @@ function startProxyServer() {
 }
 async function stopProxy() {
   const pidPath = store.pidPath;
+  const proxyPort = readProxyPort();
   if (!fs.existsSync(pidPath)) {
-    console.log(chalk.yellow("Proxy is not running."));
+    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) {
+        try {
+          process.kill(pid, "SIGTERM");
+          try {
+            fs.unlinkSync(PROXY_PORT_PATH);
+          } catch {
+          }
+          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 runs as root."));
+            console.log(chalk.blue("Use: sudo portless proxy stop"));
+          } else {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red("Failed to stop proxy:"), message);
+          }
+        }
+      } else if (process.getuid?.() !== 0) {
+        console.error(chalk.red("Permission denied. The proxy likely runs as root."));
+        console.log(chalk.blue("Use: sudo portless proxy stop"));
+      } else {
+        console.error(chalk.red(`Could not identify the process on port ${proxyPort}.`));
+        console.log(chalk.blue(`Try: sudo kill "$(lsof -ti tcp:${proxyPort})"`));
+      }
+    } else {
+      console.log(chalk.yellow("Proxy is not running."));
+    }
     return;
   }
   try {
@@ -200,10 +259,10 @@ async function stopProxy() {
       fs.unlinkSync(pidPath);
       return;
     }
-    if (!await isProxyRunning()) {
+    if (!await isProxyRunning(proxyPort)) {
       console.log(
         chalk.yellow(
-          "PID file exists but port 80 is not listening. The PID may have been recycled."
+          `PID file exists but port ${proxyPort} is not listening. The PID may have been recycled.`
         )
       );
       console.log(chalk.yellow("Removing stale PID file."));
@@ -212,6 +271,10 @@ async function stopProxy() {
     }
     process.kill(pid, "SIGTERM");
     fs.unlinkSync(pidPath);
+    try {
+      fs.unlinkSync(PROXY_PORT_PATH);
+    } catch {
+    }
     console.log(chalk.green("Proxy stopped."));
   } catch (err) {
     if (isErrnoException(err) && err.code === "EPERM") {
@@ -240,11 +303,12 @@ function listRoutes() {
 }
 async function runApp(name, commandArgs) {
   const hostname = parseHostname(name);
+  const proxyPort = readProxyPort();
   console.log(chalk.blue.bold(`
 portless
 `));
   console.log(chalk.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`));
-  if (!await isProxyRunning()) {
+  if (!await isProxyRunning(proxyPort)) {
     if (process.stdin.isTTY) {
       const answer = await prompt(chalk.yellow("Proxy not running. Start it? [Y/n/skip] "));
       if (answer === "n" || answer === "no") {
@@ -316,10 +380,11 @@ Eliminates port conflicts, memorizing port numbers, and cookie/storage
 clashes by giving each dev server a stable .localhost URL.
 
 ${chalk.bold("Usage:")}
-  ${chalk.cyan("sudo portless proxy")}       Start the proxy (run once, keep open)
-  ${chalk.cyan("sudo portless proxy stop")}  Stop the proxy
-  ${chalk.cyan("portless <name> <cmd>")}     Run your app through the proxy
-  ${chalk.cyan("portless list")}             Show active routes
+  ${chalk.cyan("sudo portless proxy")}              Start the proxy (run once, keep open)
+  ${chalk.cyan("sudo portless proxy --port 8080")}  Start the proxy on a custom port
+  ${chalk.cyan("sudo portless proxy stop")}         Stop the proxy
+  ${chalk.cyan("portless <name> <cmd>")}            Run your app through the proxy
+  ${chalk.cyan("portless list")}                    Show active routes
 
 ${chalk.bold("Examples:")}
   sudo portless proxy              # Start proxy in terminal 1
@@ -334,11 +399,15 @@ ${chalk.bold("In package.json:")}
   }
 
 ${chalk.bold("How it works:")}
-  1. Start the proxy once with sudo (listens on port 80)
+  1. Start the proxy once with sudo (listens on port 80 by default)
   2. Run your apps - they register automatically  
   3. Access via http://<name>.localhost
   4. .localhost domains auto-resolve to 127.0.0.1
 
+${chalk.bold("Options:")}
+  --port <number>               Port for the proxy to listen on (default: 80)
+                                Ports >= 1024 do not require sudo
+
 ${chalk.bold("Skip portless:")}
   PORTLESS=0 pnpm dev           # Runs command directly without proxy
   PORTLESS=skip pnpm dev        # Same as above
@@ -346,7 +415,7 @@ ${chalk.bold("Skip portless:")}
     process.exit(0);
   }
   if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.1.0");
+    console.log("0.2.1");
     process.exit(0);
   }
   if (args[0] === "list") {
@@ -359,15 +428,31 @@ ${chalk.bold("Skip portless:")}
       return;
     }
     const isDaemon = args.includes("--daemon");
-    if (await isProxyRunning()) {
+    let proxyPort = DEFAULT_PROXY_PORT;
+    const portFlagIndex = args.indexOf("--port");
+    if (portFlagIndex !== -1) {
+      const portValue = args[portFlagIndex + 1];
+      if (!portValue || portValue.startsWith("-")) {
+        console.error(chalk.red("Error: --port requires a port number"));
+        console.log(chalk.blue("Usage: portless proxy --port 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.log(chalk.blue("Port must be between 1 and 65535"));
+        process.exit(1);
+      }
+    }
+    if (await isProxyRunning(proxyPort)) {
       if (!isDaemon) {
         console.log(chalk.yellow("Proxy is already running."));
         console.log(chalk.blue("To restart: portless proxy stop && sudo portless proxy"));
       }
       return;
     }
-    if (process.getuid() !== 0) {
-      console.error(chalk.red("Error: Proxy requires sudo for port 80"));
+    if (proxyPort < 1024 && process.getuid() !== 0) {
+      console.error(chalk.red(`Error: Proxy requires sudo for port ${proxyPort}`));
       console.log(chalk.blue("Usage: sudo portless proxy"));
       process.exit(1);
     }
@@ -379,14 +464,18 @@ ${chalk.bold("Skip portless:")}
         fs.chmodSync(logPath, 420);
       } catch {
       }
-      const child = spawn(process.execPath, [process.argv[1], "proxy"], {
+      const daemonArgs = [process.argv[1], "proxy"];
+      if (portFlagIndex !== -1) {
+        daemonArgs.push("--port", proxyPort.toString());
+      }
+      const child = spawn(process.execPath, daemonArgs, {
         detached: true,
         stdio: ["ignore", logFd, logFd],
         env: process.env
       });
       child.unref();
       fs.closeSync(logFd);
-      if (!await waitForProxy()) {
+      if (!await waitForProxy(proxyPort)) {
         console.error(chalk.red("Proxy failed to start"));
         if (fs.existsSync(logPath)) {
           console.log(chalk.gray(`Check logs: ${logPath}`));
@@ -396,7 +485,7 @@ ${chalk.bold("Skip portless:")}
       return;
     }
     console.log(chalk.blue.bold("\nportless proxy\n"));
-    startProxyServer();
+    startProxyServer(proxyPort);
     return;
   }
   const name = args[0];

package/package.json

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