laxy-verify 1.3.1 → 1.3.2

package/README.md

@@ -161,6 +161,8 @@ Or enable them in `.laxy.yml` and just run:
 npx laxy-verify .
 ```
 
+If the default or configured dev port is already occupied, `laxy-verify` automatically starts its temporary verification server on the next available port. Use `--port` only when you want to attach to an already-running server yourself.
+
 ## Example output
 
 ```text
@@ -432,6 +434,11 @@ It is a pre-merge and pre-release verification layer, not your entire quality sy
 
 ## Changelog
 
+### v1.3.2 - Auto port fallback
+
+- If port `3000` or your configured verification port is already in use, `laxy-verify` now starts its temporary dev server on the next available port automatically
+- `--port` keeps its existing meaning: attach to an already-running server instead of starting a temporary one
+
 ### v1.3.1 - Publish fix
 
 - Fix npm package contents so `login`, `logout`, and `whoami` ship with the required `dist/init-analysis.js` runtime dependency

package/dist/cli.js

@@ -113,12 +113,6 @@ function exitGracefully(code) {
     }
     process.exit(code);
 }
-async function ensurePortAvailableForVerification(port) {
-    const status = await (0, serve_js_1.probeServerStatus)(port);
-    if (status === null)
-        return;
-    throw new Error(`An existing local server is already responding on port ${port} (HTTP ${status}). Stop the running app before using laxy-verify, because the verification build can invalidate an active dev session.`);
-}
 function parseArgs() {
     const raw = process.argv.slice(2);
     let projectDir = ".";
@@ -405,7 +399,7 @@ async function run() {
     --config <path>   Path to .laxy.yml
     --fail-on         unverified | bronze | silver | gold
     --skip-lighthouse Skip Lighthouse but still run build and E2E
-    --port <port>     Use an already-running dev server on this port (skip build & server start)
+    --port <port>     Use an already-running dev server on this port (skip build & server start)
     --share           Create a public share link for this verification result (Pro)
     --compare <url>   Compare Lighthouse scores against a reference environment URL (Pro)
     --plan-override   free | pro | team (testing metadata only)
@@ -427,9 +421,10 @@ async function run() {
     2   Configuration error
 
   Examples:
-    npx laxy-verify --init --run        # Setup + first verification
-    npx laxy-verify .                   # Run in current directory
-    npx laxy-verify . --ci              # CI mode
+    npx laxy-verify --init --run        # Setup + first verification
+    npx laxy-verify .                   # Run in current directory
+    npx laxy-verify .                   # Auto-falls back if port 3000 is already busy
+    npx laxy-verify . --ci              # CI mode
     npx laxy-verify . --fail-on silver  # Block Bronze or worse
     npx laxy-verify . --port 3001       # Use existing dev server on port 3001
     npx laxy-verify . --share           # Save and share a public verification link
@@ -566,28 +561,25 @@ async function run() {
     }
     const buildCmd = config.build_command || detected.buildCmd;
     const devCmd = config.dev_command || detected.devCmd;
-    const port = args.port ?? config.port;
+    const requestedPort = args.port ?? config.port;
     const useExistingServer = args.port !== undefined;
+    let verificationPort = requestedPort;
     if (!useExistingServer) {
-        try {
-            await ensurePortAvailableForVerification(port);
-        }
-        catch (err) {
-            console.error(`Preflight error: ${err instanceof Error ? err.message : String(err)}`);
-            exitGracefully(2);
-            return;
+        verificationPort = await (0, serve_js_1.findAvailablePort)(requestedPort);
+        if (verificationPort !== requestedPort && args.format !== "json") {
+            console.log(`Port ${requestedPort} is busy. laxy-verify will start its temporary dev server on port ${verificationPort} for this run.`);
         }
     }
     else {
         // Verify the existing server is actually reachable
-        const status = await (0, serve_js_1.probeServerStatus)(port);
+        const status = await (0, serve_js_1.probeServerStatus)(verificationPort);
         if (status === null) {
-            console.error(`Preflight error: No server responding on port ${port}. Make sure the dev server is running before using --port.`);
+            console.error(`Preflight error: No server responding on port ${verificationPort}. Make sure the dev server is running before using --port.`);
             exitGracefully(2);
             return;
         }
         if (args.format !== "json") {
-            console.log(`Using existing dev server on port ${port} (HTTP ${status})`);
+            console.log(`Using existing dev server on port ${verificationPort} (HTTP ${status})`);
         }
     }
     let buildResult;
@@ -677,11 +669,12 @@ async function run() {
         let servePid;
         try {
             if (!useExistingServer) {
-                const serve = await (0, serve_js_1.startDevServer)(devCmd, port, config.dev_timeout, args.projectDir);
+                const serve = await (0, serve_js_1.startDevServer)(devCmd, verificationPort, config.dev_timeout, args.projectDir);
                 servePid = serve.pid;
                 activeDevServerPid = serve.pid;
+                verificationPort = serve.port;
             }
-            const verifyUrl = `http://localhost:${port}/`;
+            const verifyUrl = `http://localhost:${verificationPort}/`;
             const verificationTier = (0, index_js_1.planToVerificationTier)(effectiveFeatures.plan);
             try {
                 const runtimeRouteDiscovery = await (0, route_discovery_js_1.discoverRuntimeRoutes)(verifyUrl);
@@ -702,13 +695,13 @@ async function run() {
                             : undefined;
                     if (explicitRoutes && explicitRoutes.length > 0) {
                         // Multi-route mode: run on all explicitly configured routes
-                        multiRouteLhResult = await (0, lighthouse_js_1.runLighthouseOnRoutes)(port, config.lighthouse_runs, explicitRoutes);
+                        multiRouteLhResult = await (0, lighthouse_js_1.runLighthouseOnRoutes)(verificationPort, config.lighthouse_runs, explicitRoutes);
                         lighthouseErrorCount = multiRouteLhResult.perRoute.reduce((n, r) => n + r.errors.length, 0);
                         scores = multiRouteLhResult.aggregated ?? undefined;
                     }
                     else {
                         // Single-route mode (default): root only
-                        const lhResult = await (0, lighthouse_js_1.runLighthouse)(port, config.lighthouse_runs);
+                        const lhResult = await (0, lighthouse_js_1.runLighthouse)(verificationPort, config.lighthouse_runs);
                         lighthouseErrorCount = lhResult.errors.length;
                         scores = lhResult.scores ?? undefined;
                     }
@@ -728,7 +721,7 @@ async function run() {
             }
             if (!args.skipLighthouse) {
                 try {
-                    multiViewportScores = await (0, multi_viewport_js_1.runMultiViewportLighthouse)(port);
+                    multiViewportScores = await (0, multi_viewport_js_1.runMultiViewportLighthouse)(verificationPort);
                     (0, multi_viewport_js_1.printMultiViewportResults)(multiViewportScores, adjustedThresholds);
                     allViewportsOk = (0, multi_viewport_js_1.allViewportsPass)(multiViewportScores, adjustedThresholds);
                     if (multiViewportScores.screenshotDiffs) {
@@ -844,7 +837,7 @@ async function run() {
                         ...lastCrawlRoutes,
                     ]).slice(0, config.max_lighthouse_routes);
                     console.log(`\n  Running Lighthouse on ${crawlRoutes.length} discovered routes...`);
-                    multiRouteLhResult = await (0, lighthouse_js_1.runLighthouseOnRoutes)(port, config.lighthouse_runs, crawlRoutes);
+                    multiRouteLhResult = await (0, lighthouse_js_1.runLighthouseOnRoutes)(verificationPort, config.lighthouse_runs, crawlRoutes);
                     if (multiRouteLhResult.aggregated) {
                         scores = multiRouteLhResult.aggregated;
                         lighthouseResult = {
@@ -895,7 +888,7 @@ async function run() {
             // Mobile Lighthouse (standalone — not part of multi-viewport)
             if (!args.skipLighthouse && !args.multiViewport) {
                 try {
-                    mobileLighthouseScores = await (0, multi_viewport_js_1.runMobileLighthouse)(port);
+                    mobileLighthouseScores = await (0, multi_viewport_js_1.runMobileLighthouse)(verificationPort);
                 }
                 catch (mlErr) {
                     console.error(`Mobile Lighthouse error: ${mlErr instanceof Error ? mlErr.message : String(mlErr)}`);
@@ -984,7 +977,7 @@ async function run() {
             // Pro: multi-environment comparison
             if (effectiveFeatures.compare_env && args.compareUrl) {
                 try {
-                    compareEnvResult = await (0, compare_env_js_1.runEnvComparison)(port, args.compareUrl, 1);
+                    compareEnvResult = await (0, compare_env_js_1.runEnvComparison)(verificationPort, args.compareUrl, 1);
                 }
                 catch (cmpErr) {
                     console.error(`Env comparison error: ${cmpErr instanceof Error ? cmpErr.message : String(cmpErr)}`);

package/dist/serve.d.ts

@@ -9,5 +9,6 @@ export interface ServeResult {
     port: number;
 }
 export declare function probeServerStatus(port: number): Promise<number | null>;
+export declare function findAvailablePort(preferredPort: number, maxAttempts?: number): Promise<number>;
 export declare function startDevServer(command: string, port: number, timeoutSec: number, cwd?: string): Promise<ServeResult>;
 export declare function stopDevServer(pid: number): Promise<void>;

package/dist/serve.js

@@ -38,11 +38,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DevServerTimeoutError = exports.PortConflictError = void 0;
 exports.probeServerStatus = probeServerStatus;
+exports.findAvailablePort = findAvailablePort;
 exports.startDevServer = startDevServer;
 exports.stopDevServer = stopDevServer;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
+const net = __importStar(require("node:net"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const tree_kill_1 = __importDefault(require("tree-kill"));
@@ -158,6 +160,40 @@ function httpGet(url) {
 function probeServerStatus(port) {
     return httpGet(`http://localhost:${port}/`);
 }
+async function canBindPort(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref?.();
+        server.once("error", () => {
+            resolve(false);
+        });
+        server.listen(port, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+async function findAvailablePort(preferredPort, maxAttempts = 20) {
+    for (let offset = 0; offset <= maxAttempts; offset++) {
+        const candidate = preferredPort + offset;
+        if (await canBindPort(candidate)) {
+            return candidate;
+        }
+    }
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref?.();
+        server.once("error", reject);
+        server.listen(0, () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close(() => reject(new Error("Failed to resolve an available port.")));
+                return;
+            }
+            const { port } = address;
+            server.close(() => resolve(port));
+        });
+    });
+}
 async function startDevServer(command, port, timeoutSec, cwd) {
     return new Promise((resolve, reject) => {
         console.log(`Starting dev server: ${command}${cwd ? ` (cwd: ${cwd})` : ""}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laxy-verify",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Frontend verification CLI for build checks, Lighthouse, E2E, and release readiness",
   "license": "MIT",
   "type": "commonjs",