@inditextech/docouture-cli 0.1.0-SNAPSHOT.85.1 → 0.1.0-SNAPSHOT.90.1

package/build/bin.js

@@ -89,7 +89,9 @@ change to docs/ or antora-playbook.yml. --dir is the repository root
 (the parent of docs/), same as new/version — not the site directory.
 
 Options:
-  --port <port>  Port to listen on (default: 5000)
+  --port <port>  Port to listen on (default: 5000, falls back to a random
+                 free port if 5000 is busy — an explicit --port that's busy
+                 is still a hard error)
   --dir <path>   Repository root (default: cwd, or its enclosing repo)
 `,
     },

package/build/lib/dev-server.js

@@ -26,6 +26,7 @@ const RELOAD_PATH = '/__dev/reload';
 const CLIENT_PATH = '/__dev/client.js';
 const DEBOUNCE_MS = 150;
 const BUILD_TIMEOUT_MS = 120_000;
+const DEFAULT_PORT = 5000;
 const CLIENT_SCRIPT = `// Injected by docouture dev. Not part of the built site.
 const es = new EventSource(${JSON.stringify(RELOAD_PATH)})
 es.addEventListener('message', () => location.reload())
@@ -315,14 +316,36 @@ export async function startDevServer(options) {
         logError('initial rebuild failed, serving the previous build');
     }
     await new Promise((resolvePromise, reject) => {
-        server.once('error', reject);
-        server.listen(options.port ?? 5000, () => {
-            server.off('error', reject);
+        // `options.port` set (including 0, which a test uses to pick any free
+        // port) means the caller chose this port deliberately — a busy port
+        // there is a hard failure, same as always. Nothing set means the
+        // *default* port, which is routinely squatted by something the user
+        // never asked to avoid (macOS AirPlay Receiver on 5000, most commonly):
+        // that case retries with `listen(0)`, an OS-assigned free port, instead
+        // of failing the whole dev server over a port nobody actually chose.
+        const explicitPort = options.port !== undefined;
+        const requestedPort = options.port ?? options.defaultPort ?? DEFAULT_PORT;
+        const onListenError = (err) => {
+            if (!explicitPort && err.code === 'EADDRINUSE') {
+                server.off('error', onListenError);
+                logError(`port ${requestedPort} is already in use, falling back to a random free port`);
+                server.once('error', reject);
+                server.listen(0, () => {
+                    server.off('error', reject);
+                    resolvePromise();
+                });
+                return;
+            }
+            reject(err);
+        };
+        server.once('error', onListenError);
+        server.listen(requestedPort, () => {
+            server.off('error', onListenError);
             resolvePromise();
         });
     });
     const address = server.address();
-    const port = typeof address === 'object' && address ? address.port : (options.port ?? 5000);
+    const port = typeof address === 'object' && address ? address.port : (options.port ?? DEFAULT_PORT);
     log(`serving ${root}`);
     log(`  http://localhost:${port}${basePath}/`);
     const watchers = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inditextech/docouture-cli",
-  "version": "0.1.0-SNAPSHOT.85.1",
+  "version": "0.1.0-SNAPSHOT.90.1",
   "description": "Command-line tool for docouture documentation sites: scaffold a new site and set its Antora version outside the monorepo",
   "repository": {
     "type": "git",