tina4-nodejs 3.2.1 → 3.5.0

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -0,0 +1,223 @@
+/**
+ * Tina4 MongoDB Queue Backend — uses `mongodb` npm package via dynamic import.
+ *
+ * Implements the same interface as the file-based queue but uses MongoDB
+ * for message storage and delivery. Atomic pop via findOneAndUpdate.
+ *
+ * Configure via environment variables:
+ *   TINA4_MONGO_HOST       (default: "localhost")
+ *   TINA4_MONGO_PORT       (default: 27017)
+ *   TINA4_MONGO_URI        (overrides host/port/username/password)
+ *   TINA4_MONGO_USERNAME   (optional)
+ *   TINA4_MONGO_PASSWORD   (optional)
+ *   TINA4_MONGO_DB         (default: "tina4")
+ *   TINA4_MONGO_COLLECTION (default: "tina4_queue")
+ */
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import type { QueueJob } from "../queue.js";
+
+// ── Types ────────────────────────────────────────────────────
+
+export interface MongoConfig {
+  host?: string;
+  port?: number;
+  uri?: string;
+  username?: string;
+  password?: string;
+  database?: string;
+  collection?: string;
+}
+
+export interface QueueBackend {
+  push(queue: string, payload: unknown, delay?: number): string;
+  pop(queue: string): QueueJob | null;
+  size(queue: string): number;
+  clear(queue: string): void;
+}
+
+// ── MongoDB Backend ──────────────────────────────────────────
+
+/**
+ * MongoDB queue backend using the `mongodb` npm package.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the RabbitMQ and Redis patterns.
+ * This keeps the interface synchronous as required by the Queue class.
+ */
+export class MongoBackend implements QueueBackend {
+  private host: string;
+  private port: number;
+  private uri: string;
+  private username: string;
+  private password: string;
+  private database: string;
+  private collection: string;
+
+  constructor(config?: MongoConfig) {
+    this.host = config?.host ?? process.env.TINA4_MONGO_HOST ?? "localhost";
+    this.port = config?.port
+      ?? (process.env.TINA4_MONGO_PORT ? parseInt(process.env.TINA4_MONGO_PORT, 10) : 27017);
+    this.username = config?.username ?? process.env.TINA4_MONGO_USERNAME ?? "";
+    this.password = config?.password ?? process.env.TINA4_MONGO_PASSWORD ?? "";
+    this.database = config?.database ?? process.env.TINA4_MONGO_DB ?? "tina4";
+    this.collection = config?.collection ?? process.env.TINA4_MONGO_COLLECTION ?? "tina4_queue";
+
+    // URI overrides individual host/port/auth settings
+    if (config?.uri ?? process.env.TINA4_MONGO_URI) {
+      this.uri = config?.uri ?? process.env.TINA4_MONGO_URI!;
+    } else {
+      const auth = this.username
+        ? `${encodeURIComponent(this.username)}:${encodeURIComponent(this.password)}@`
+        : "";
+      this.uri = `mongodb://${auth}${this.host}:${this.port}`;
+    }
+  }
+
+  /**
+   * Execute a MongoDB operation synchronously via a child process.
+   */
+  private execSync(operation: string, queue: string, data?: string): string {
+    const script = `
+      async function main() {
+        let mongodb;
+        try {
+          mongodb = await import("mongodb");
+        } catch {
+          process.stderr.write("mongodb package not installed — run: npm install mongodb");
+          process.exit(1);
+        }
+
+        const { MongoClient } = mongodb;
+        const uri = ${JSON.stringify(this.uri)};
+        const dbName = ${JSON.stringify(this.database)};
+        const collName = ${JSON.stringify(this.collection)};
+        const operation = ${JSON.stringify(operation)};
+        const queueName = ${JSON.stringify(queue)};
+        const data = ${JSON.stringify(data ?? "")};
+
+        const client = new MongoClient(uri, {
+          connectTimeoutMS: 5000,
+          serverSelectionTimeoutMS: 5000,
+        });
+
+        try {
+          await client.connect();
+          const db = client.db(dbName);
+          const col = db.collection(collName);
+
+          // Ensure indexes on first use
+          await col.createIndex({ queue: 1, status: 1, delayUntil: 1 });
+          await col.createIndex({ queue: 1, createdAt: 1 });
+
+          if (operation === "push") {
+            const job = JSON.parse(data);
+            await col.insertOne({ ...job, queue: queueName });
+            process.stdout.write("__PUSHED__");
+          }
+          else if (operation === "pop") {
+            const now = new Date().toISOString();
+            const result = await col.findOneAndUpdate(
+              {
+                queue: queueName,
+                status: "pending",
+                $or: [
+                  { delayUntil: null },
+                  { delayUntil: { $lte: now } },
+                ],
+              },
+              { $set: { status: "reserved" } },
+              { sort: { createdAt: 1 }, returnDocument: "before" },
+            );
+
+            if (result && result.value) {
+              // findOneAndUpdate returns { value: doc } in older drivers
+              const doc = result.value;
+              delete doc._id;
+              delete doc.queue;
+              process.stdout.write(JSON.stringify(doc));
+            } else if (result && result._id) {
+              // Some driver versions return the doc directly
+              const doc = { ...result };
+              delete doc._id;
+              delete doc.queue;
+              process.stdout.write(JSON.stringify(doc));
+            } else {
+              process.stdout.write("__EMPTY__");
+            }
+          }
+          else if (operation === "size") {
+            const count = await col.countDocuments({
+              queue: queueName,
+              status: "pending",
+            });
+            process.stdout.write(String(count));
+          }
+          else if (operation === "clear") {
+            await col.deleteMany({ queue: queueName });
+            process.stdout.write("__CLEARED__");
+          }
+        } catch (err) {
+          process.stderr.write(err.message || String(err));
+          process.exit(1);
+        } finally {
+          await client.close();
+        }
+      }
+
+      main();
+    `;
+
+    try {
+      const result = execFileSync(process.execPath, ["-e", script], {
+        encoding: "utf-8",
+        timeout: 15000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return result;
+    } catch {
+      return "";
+    }
+  }
+
+  push(queue: string, payload: unknown, delay?: number): string {
+    const id = randomUUID();
+    const now = new Date().toISOString();
+
+    const job: QueueJob = {
+      id,
+      payload,
+      status: "pending",
+      createdAt: now,
+      attempts: 0,
+      delayUntil: delay ? new Date(Date.now() + delay * 1000).toISOString() : null,
+    };
+
+    const result = this.execSync("push", queue, JSON.stringify(job));
+    if (!result.includes("__PUSHED__")) {
+      throw new Error("MongoDB push failed");
+    }
+    return id;
+  }
+
+  pop(queue: string): QueueJob | null {
+    const result = this.execSync("pop", queue);
+    if (!result || result === "__EMPTY__") return null;
+
+    try {
+      return JSON.parse(result) as QueueJob;
+    } catch {
+      return null;
+    }
+  }
+
+  size(queue: string): number {
+    const result = this.execSync("size", queue);
+    const num = parseInt(result, 10);
+    return isNaN(num) ? 0 : num;
+  }
+
+  clear(queue: string): void {
+    this.execSync("clear", queue);
+  }
+}

package/packages/core/src/request.ts

@@ -129,12 +129,12 @@ function parseMultipart(
     const partContentType = parsePartContentType(headersStr);
 
     if (disposition.filename) {
-      // File upload
+      // File upload — standardised format: filename, type, content (raw bytes), size
       files.push({
         fieldName: disposition.name,
         filename: disposition.filename,
-        contentType: partContentType ?? "application/octet-stream",
-        data: Buffer.from(content),
+        type: partContentType ?? "application/octet-stream",
+        content: Buffer.from(content),
         size: content.length,
       });
     } else if (disposition.name) {

package/packages/core/src/router.ts

@@ -7,6 +7,8 @@ interface MatchResult {
   meta?: RouteMeta;
   middlewares?: Middleware[];
   template?: string;
+  secure?: boolean;
+  cached?: boolean;
 }
 
 interface CompiledRoute {
@@ -17,28 +19,77 @@ interface CompiledRoute {
   meta?: RouteMeta;
   filePath?: string;
   middlewares?: Middleware[];
+  secure?: boolean;
   cached?: boolean;
   cacheStore?: Map<string, { data: unknown; expires: number }>;
   cacheTtl?: number;
   template?: string;
 }
 
+/**
+ * Thin reference to a registered route, enabling chained modifiers.
+ *
+ * Usage:
+ *   router.get("/api/data", handler).secure().cache();
+ */
+export class RouteRef {
+  constructor(private route: CompiledRoute) {}
+
+  /** Mark this route as requiring bearer-token authentication. */
+  secure(): this {
+    this.route.secure = true;
+    return this;
+  }
+
+  /** Mark this route's response as cacheable. */
+  cache(): this {
+    this.route.cached = true;
+    return this;
+  }
+}
+
 export interface RouteInfo {
   method: string;
   path: string;
   handler: string;
   middlewareCount: number;
   cached: boolean;
+  secure: boolean;
 }
 
 export class Router {
   private routes: Map<string, CompiledRoute[]> = new Map();
   private wsRoutes: WebSocketRouteDefinition[] = [];
 
+  /** Class-based middleware registered via `use()` / `Router.use()`. */
+  private static _classMiddlewares: any[] = [];
+
+  /**
+   * Register a class-based middleware (beforeX / afterX convention).
+   * Classes are stored globally and executed by MiddlewareRunner.
+   */
+  static use(middlewareClass: any): void {
+    Router._classMiddlewares.push(middlewareClass);
+  }
+
+  /**
+   * Get all registered class-based middleware classes.
+   */
+  static getClassMiddlewares(): any[] {
+    return Router._classMiddlewares;
+  }
+
+  /**
+   * Clear all registered class-based middleware (useful for testing).
+   */
+  static clearClassMiddlewares(): void {
+    Router._classMiddlewares = [];
+  }
+
   /**
    * Add a raw route definition (used internally and by file-based routing).
    */
-  addRoute(definition: RouteDefinition): void {
+  addRoute(definition: RouteDefinition): RouteRef {
     const method = definition.method.toUpperCase();
     const { regex, paramNames } = this.compilePattern(definition.pattern);
 
@@ -54,7 +105,7 @@ export class Router {
       routes.splice(existingIndex, 1);
     }
 
-    routes.push({
+    const compiled: CompiledRoute = {
       pattern: definition.pattern,
       regex,
       paramNames,
@@ -62,52 +113,58 @@ export class Router {
       meta: definition.meta,
       filePath: definition.filePath,
       middlewares: definition.middlewares,
+      secure: definition.secure,
+      cached: definition.cached,
       template: definition.template,
-    });
+    };
+    routes.push(compiled);
+    return new RouteRef(compiled);
   }
 
   /**
    * Register a GET route programmatically.
    */
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "GET", pattern: path, handler, middlewares, meta });
+  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "GET", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a POST route programmatically.
    */
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "POST", pattern: path, handler, middlewares, meta });
+  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "POST", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PUT route programmatically.
    */
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "PUT", pattern: path, handler, middlewares, meta });
+  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "PUT", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PATCH route programmatically.
    */
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "PATCH", pattern: path, handler, middlewares, meta });
+  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "PATCH", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a DELETE route programmatically.
    */
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
+  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a route that matches ANY HTTP method.
    */
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
+  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
-      this.addRoute({ method, pattern: path, handler, middlewares, meta });
+      lastRef = this.addRoute({ method, pattern: path, handler, middlewares, meta });
     }
+    return lastRef;
   }
 
   /**
@@ -142,6 +199,8 @@ export class Router {
           meta: route.meta,
           middlewares: route.middlewares,
           template: route.template,
+          secure: route.secure,
+          cached: route.cached,
         };
       }
     }
@@ -164,6 +223,8 @@ export class Router {
           filePath: route.filePath,
           middlewares: route.middlewares,
           template: route.template,
+          secure: route.secure,
+          cached: route.cached,
         });
       }
     }
@@ -183,6 +244,7 @@ export class Router {
           handler: route.filePath ?? (route.handler.name || "(anonymous)"),
           middlewareCount: route.middlewares?.length ?? 0,
           cached: route.cached ?? false,
+          secure: route.secure ?? false,
         });
       }
     }
@@ -228,43 +290,43 @@ export class Router {
   /**
    * Register a GET route on the default global router.
    */
-  static get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.get(path, handler, middlewares, meta);
+  static get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.get(path, handler, middlewares, meta);
   }
 
   /**
    * Register a POST route on the default global router.
    */
-  static post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.post(path, handler, middlewares, meta);
+  static post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.post(path, handler, middlewares, meta);
   }
 
   /**
    * Register a PUT route on the default global router.
    */
-  static put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.put(path, handler, middlewares, meta);
+  static put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.put(path, handler, middlewares, meta);
   }
 
   /**
    * Register a PATCH route on the default global router.
    */
-  static patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.patch(path, handler, middlewares, meta);
+  static patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.patch(path, handler, middlewares, meta);
   }
 
   /**
    * Register a DELETE route on the default global router.
    */
-  static delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.delete(path, handler, middlewares, meta);
+  static delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.delete(path, handler, middlewares, meta);
   }
 
   /**
    * Register a route that matches ANY HTTP method on the default global router.
    */
-  static any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.any(path, handler, middlewares, meta);
+  static any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.any(path, handler, middlewares, meta);
   }
 
   /**
@@ -343,8 +405,8 @@ export class RouteGroup {
     return merged.length > 0 ? merged : undefined;
   }
 
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "GET",
       pattern: this.prefix + path,
       handler,
@@ -353,8 +415,8 @@ export class RouteGroup {
     });
   }
 
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "POST",
       pattern: this.prefix + path,
       handler,
@@ -363,8 +425,8 @@ export class RouteGroup {
     });
   }
 
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "PUT",
       pattern: this.prefix + path,
       handler,
@@ -373,8 +435,8 @@ export class RouteGroup {
     });
   }
 
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "PATCH",
       pattern: this.prefix + path,
       handler,
@@ -383,8 +445,8 @@ export class RouteGroup {
     });
   }
 
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "DELETE",
       pattern: this.prefix + path,
       handler,
@@ -393,9 +455,10 @@ export class RouteGroup {
     });
   }
 
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
+  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
-      this.router.addRoute({
+      lastRef = this.router.addRoute({
         method,
         pattern: this.prefix + path,
         handler,
@@ -403,6 +466,7 @@ export class RouteGroup {
         meta,
       });
     }
+    return lastRef;
   }
 
   /**
@@ -458,29 +522,29 @@ export const defaultRouter = new Router();
  *     res.json({ id: req.params.id }, 201);
  *   });
  */
-export function get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.get(path, handler, middlewares, meta);
+export function get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.get(path, handler, middlewares, meta);
 }
 
-export function post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.post(path, handler, middlewares, meta);
+export function post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.post(path, handler, middlewares, meta);
 }
 
-export function put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.put(path, handler, middlewares, meta);
+export function put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.put(path, handler, middlewares, meta);
 }
 
-export function patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.patch(path, handler, middlewares, meta);
+export function patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.patch(path, handler, middlewares, meta);
 }
 
 // Named "del" to avoid conflict with the "delete" keyword; also exported as "delete" alias below.
-export function del(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.delete(path, handler, middlewares, meta);
+export function del(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.delete(path, handler, middlewares, meta);
 }
 
-export function any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.any(path, handler, middlewares, meta);
+export function any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.any(path, handler, middlewares, meta);
 }
 
 export function websocket(path: string, handler: WebSocketRouteHandler): void {

package/packages/core/src/server.ts

@@ -29,6 +29,38 @@ const BUILTIN_PUBLIC_DIR = resolve(__dirname, "..", "public");
 
 const TINA4_VERSION = "3.0.0";
 
+/**
+ * Test-bind each port in a subprocess to find one that is available.
+ * Falls back to `start` if none of the candidates work.
+ */
+function findAvailablePort(start: number, maxTries = 10): number {
+  const { execFileSync } = require("node:child_process");
+  for (let offset = 0; offset < maxTries; offset++) {
+    const port = start + offset;
+    try {
+      execFileSync(process.execPath, ["-e", `
+        const s = require("net").createServer();
+        s.listen(${port}, "127.0.0.1", () => { s.close(); process.exit(0); });
+        s.on("error", () => process.exit(1));
+      `], { timeout: 1000 });
+      return port;
+    } catch { continue; }
+  }
+  return start;
+}
+
+/**
+ * Open the user's default browser after a short delay so the server is ready.
+ */
+function openBrowser(url: string) {
+  const { exec } = require("node:child_process");
+  setTimeout(() => {
+    if (process.platform === "darwin") exec(`open ${url}`);
+    else if (process.platform === "win32") exec(`start "" "${url}"`);
+    else exec(`xdg-open ${url}`);
+  }, 2000);
+}
+
 /**
  * Resolve port and host with priority: explicit config > ENV var > default.
  * Exported for testability.
@@ -266,8 +298,10 @@ function deployGallery(name) {
         if (d.error) {
             alert('Deploy failed: ' + d.error);
         } else {
-            alert('Deployed "' + d.deployed + '" (' + d.files.length + ' files). Reloading...');
-            window.location.reload();
+            // Brief delay to allow newly deployed routes to register before reloading
+            setTimeout(function() {
+                window.location.reload();
+            }, 500);
         }
     })
     .catch(function(e) { alert('Deploy error: ' + e.message); });
@@ -285,7 +319,16 @@ export async function startServer(config?: Tina4Config): Promise<{
   // Load .env early so TINA4_DEBUG is available for cluster decision
   loadEnv();
 
-  const { port, host } = resolvePortAndHost(config);
+  const resolved = resolvePortAndHost(config);
+  const host = resolved.host;
+  let port = resolved.port;
+
+  // Auto-increment port if the requested one is already in use
+  const availablePort = findAvailablePort(port);
+  if (availablePort !== port) {
+    console.log(`  Port ${port} in use, using ${availablePort} instead`);
+    port = availablePort;
+  }
 
   // Cluster mode for production: fork workers based on CPU count
   // Only when not in dev mode and running as primary process
@@ -669,6 +712,7 @@ ${reset}
   Dashboard: http://localhost:${port}/__dev
   Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})
 `);
+      openBrowser(`http://${displayHost}:${port}`);
       resolvePromise({
         close: () => {
           server.close();