mulmoterminal 0.1.0 → 0.1.1

package/bin/mulmoterminal.js

@@ -18,7 +18,10 @@ const PKG_DIR = join(__dirname, "..");
 const SERVER_ENTRY = join(PKG_DIR, "server", "index.ts");
 const DEFAULT_PORT = 3456;
 const READY_TIMEOUT_MS = 15_000;
-const MAX_PORT_PROBES = 20;
+const MAX_BIND_RETRIES = 5;
+// Server exit code meaning "port taken at bind time" — keep in sync with
+// server/index.ts (PORT_IN_USE_EXIT_CODE).
+const PORT_IN_USE_EXIT_CODE = 75;
 
 // Single source of truth: read the version from the shipped package.json so
 // `--version` never drifts from the published version.
@@ -45,31 +48,48 @@ function pickOpenCommand() {
   return "xdg-open";
 }
 
-// Resolve with true if nothing is listening on `port`, false otherwise.
+// Resolve with true if nothing is listening on `port`, false otherwise. Binds
+// without a host — same as the server's `server.listen(port)` (the `::`
+// dual-stack address) — so the probe and the real bind agree on availability.
+// Probing 127.0.0.1 here let a port held only on `::` slip through as "free".
 function isPortFree(port) {
   return new Promise((resolve) => {
     const probe = createServer();
     probe.once("error", () => resolve(false));
     probe.once("listening", () => probe.close(() => resolve(true)));
-    probe.listen(port, "127.0.0.1");
+    probe.listen(port);
   });
 }
 
-async function findAvailablePort(start) {
-  for (let port = start; port < start + MAX_PORT_PROBES; port++) {
-    if (await isPortFree(port)) return port;
-  }
-  return null;
+// Ask the OS for a free port (listen on 0) and return the one it assigned, or
+// null. An effectively-random fallback when the preferred port is taken; the
+// bind-retry in main() closes the small probe-to-bind race so concurrent starts
+// don't clash.
+function findEphemeralPort() {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(null));
+    probe.once("listening", () => {
+      const addr = probe.address();
+      const assigned = addr && typeof addr === "object" ? addr.port : null;
+      probe.close(() => resolve(assigned));
+    });
+    probe.listen(0);
+  });
 }
 
 // Poll the server until it answers, then call onReady; give up after the timeout
-// so the launcher never hangs on a crash loop.
+// so the launcher never hangs on a crash loop. Returns a cancel function — a
+// raced/abandoned attempt stops polling so it can't fire a stale banner.
 function waitUntilReady(port, onReady) {
   const startedAt = Date.now();
+  let timer = null;
+  let cancelled = false;
   const attempt = () => {
+    if (cancelled) return;
     const req = httpGet({ host: "127.0.0.1", port, path: "/", timeout: 1000 }, (res) => {
       res.resume();
-      onReady();
+      if (!cancelled) onReady();
     });
     req.on("error", retry);
     req.on("timeout", () => {
@@ -78,10 +98,14 @@ function waitUntilReady(port, onReady) {
     });
   };
   const retry = () => {
-    if (Date.now() - startedAt > READY_TIMEOUT_MS) return;
-    setTimeout(attempt, 300);
+    if (cancelled || Date.now() - startedAt > READY_TIMEOUT_MS) return;
+    timer = setTimeout(attempt, 300);
   };
   attempt();
+  return () => {
+    cancelled = true;
+    if (timer) clearTimeout(timer);
+  };
 }
 
 function printReadyBanner(url) {
@@ -111,15 +135,57 @@ async function choosePort(requested, explicit) {
     error(`Port ${requested} is already in use. Stop the other process or pick a different --port.`);
     process.exit(1);
   }
-  const fallback = await findAvailablePort(requested + 1);
+  const fallback = await findEphemeralPort();
   if (fallback === null) {
-    error(`Port ${requested} is in use and no free port found nearby.`);
+    error(`Port ${requested} is in use and no free port could be found.`);
     process.exit(1);
   }
   log(`Port ${requested} busy → using ${fallback} instead. (Pass --port <N> to pin.)`);
   return fallback;
 }
 
+// Spawn the server on `port` and report the child via `onChild` (so signal
+// handlers target the live process). Resolves only when the server exits because
+// the port was taken at bind time before it became ready — the caller then
+// retries on a fresh port. In every other case (clean shutdown, fatal error,
+// or the server simply running) the process exits with the server's code.
+function runServer(port, noOpen, onChild) {
+  return new Promise((resolve) => {
+    log(`Starting MulmoTerminal on port ${port}...`);
+    const server = spawn(process.execPath, ["--import", "tsx", SERVER_ENTRY], {
+      cwd: PKG_DIR,
+      env: { ...process.env, NODE_ENV: "production", PORT: String(port) },
+      stdio: "inherit",
+    });
+    onChild(server);
+
+    const url = `http://localhost:${port}`;
+    const cancelReady = waitUntilReady(port, () => {
+      printReadyBanner(url);
+      if (noOpen) return;
+      try {
+        // The command is a hardcoded literal; url is http://localhost:<numeric port>.
+        // eslint-disable-next-line sonarjs/os-command
+        execSync(`${pickOpenCommand()} ${url}`, { stdio: "pipe" });
+      } catch {
+        log(`Open your browser: ${url}`);
+      }
+    });
+
+    server.on("exit", (code) => {
+      cancelReady();
+      // Exit code 75 means this child failed to bind (EADDRINUSE) and never
+      // served — always retriable, regardless of what a probe to the port saw
+      // (another process could have answered it). Other exits are terminal.
+      if (code === PORT_IN_USE_EXIT_CODE) {
+        resolve();
+        return;
+      }
+      process.exit(code ?? 1);
+    });
+  });
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -128,7 +194,7 @@ async function main() {
 Usage: npx mulmoterminal [options]
 
 Options:
-  --port <number>   Server port (default: ${DEFAULT_PORT})
+  --port <number>   Server port (default: ${DEFAULT_PORT}; a free port is chosen if it's busy)
   --no-open         Don't open the browser automatically
   --version         Show version
   --help            Show this help
@@ -153,36 +219,39 @@ Options:
   }
 
   const { requestedPort, portExplicit } = parsePortArg(args);
-  const port = await choosePort(requestedPort, portExplicit);
-
-  log(`Starting MulmoTerminal on port ${port}...`);
-  const server = spawn(process.execPath, ["--import", "tsx", SERVER_ENTRY], {
-    cwd: PKG_DIR,
-    env: { ...process.env, NODE_ENV: "production", PORT: String(port) },
-    stdio: "inherit",
-  });
-
-  const url = `http://localhost:${port}`;
   const noOpen = args.includes("--no-open");
-  waitUntilReady(port, () => {
-    printReadyBanner(url);
-    if (noOpen) return;
-    try {
-      // The command is a hardcoded literal; url is http://localhost:<numeric port>.
-      // eslint-disable-next-line sonarjs/os-command
-      execSync(`${pickOpenCommand()} ${url}`, { stdio: "pipe" });
-    } catch {
-      log(`Open your browser: ${url}`);
-    }
-  });
 
+  // Registered once; always targets the live child across bind-retries.
+  let child = null;
   const shutdown = () => {
-    server.kill("SIGTERM");
+    child?.kill("SIGTERM");
     process.exit(0);
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
-  server.on("exit", (code) => process.exit(code ?? 1));
+
+  // Start on the chosen port; if the server loses the rare probe-to-bind race,
+  // fall back to a fresh OS-assigned port and retry. An explicit --port is not
+  // second-guessed. `runServer` only returns when the port was raced.
+  let port = await choosePort(requestedPort, portExplicit);
+  for (let attempt = 0; attempt <= MAX_BIND_RETRIES; attempt++) {
+    await runServer(port, noOpen, (c) => {
+      child = c;
+    });
+    if (portExplicit) {
+      error(`Port ${port} is already in use. Stop the other process or pick a different --port.`);
+      process.exit(1);
+    }
+    const next = await findEphemeralPort();
+    if (next === null) {
+      error("No free port available to retry on.");
+      process.exit(1);
+    }
+    log(`Port ${port} was taken at bind time → retrying on ${next}.`);
+    port = next;
+  }
+  error(`Could not bind a free port after ${MAX_BIND_RETRIES + 1} attempts.`);
+  process.exit(1);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmoterminal",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MulmoTerminal — browser terminal + GUI panel for Claude Code. One command to start.",
   "type": "module",
   "license": "MIT",

package/server/index.ts

@@ -906,6 +906,21 @@ wss.on("connection", (ws, req) => {
   ws.on("close", () => handleClientClose(entry, ws, sessionId));
 });
 
+// Exit code the launcher (bin/mulmoterminal.js) treats as "port was taken at
+// bind time" so it can retry on a fresh port. Keep in sync with the launcher.
+const PORT_IN_USE_EXIT_CODE = 75;
+
+// A bind failure (most often the port already in use) must not surface as an
+// unhandled 'error' event / stack trace — exit with a clear message instead.
+server.on("error", (err) => {
+  if (hasErrnoCode(err) && err.code === "EADDRINUSE") {
+    console.error(`[mulmoterminal] Port ${PORT} is already in use — set PORT=<n> or pass --port <n>.`);
+    process.exit(PORT_IN_USE_EXIT_CODE);
+  }
+  console.error(`[mulmoterminal] server error: ${messageOf(err)}`);
+  process.exit(1);
+});
+
 server.listen(PORT, () => {
   console.log(`mulmoterminal running at http://localhost:${PORT}`);
 });