@statorjs/stator 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.1.0"
+    "@statorjs/stator": "1.1.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/server/banner.ts

@@ -40,12 +40,18 @@ function lanAddress(): string | undefined {
 
 export function printDevBanner(info: {
   port: number
+  /** The port originally asked for, when the server had to shift off it. */
+  requestedPort?: number
   machines: number
   routes: number
   inspector?: boolean
 }): void {
   const v = statorVersion()
   const lan = lanAddress()
+  const shifted =
+    info.requestedPort !== undefined && info.requestedPort !== info.port
+      ? [`  ${c.dim(`port ${info.requestedPort} was busy — using ${info.port}`)}`]
+      : []
   const lines = [
     '',
     `  ${c.copper(c.bold('stator'))}${v ? c.dim(` v${v}`) : ''}  ${c.dim('dev server')}`,
@@ -58,6 +64,7 @@ export function printDevBanner(info: {
         info.routes === 1 ? '' : 's'
       }${info.inspector ? ' · inspector on' : ''} — Ctrl+C to stop`,
     )}`,
+    ...shifted,
     '',
   ]
   process.stdout.write(`${lines.join('\n')}\n`)
@@ -88,3 +95,20 @@ export function installGracefulShutdown(close: () => Promise<void> | void, quiet
   process.on('SIGINT', handler)
   process.on('SIGTERM', handler)
 }
+
+/** First free TCP port at or above `start` (bounded probe). The dev plane
+ *  auto-shifts off busy ports like every modern dev server; production
+ *  never calls this — a taken port there is a deploy error to surface. */
+export async function findFreePort(start: number, attempts = 10): Promise<number> {
+  const { createServer } = await import('node:net')
+  for (let port = start; port < start + attempts; port++) {
+    const free = await new Promise<boolean>((resolve) => {
+      const probe = createServer()
+      probe.once('error', () => resolve(false))
+      probe.once('listening', () => probe.close(() => resolve(true)))
+      probe.listen(port)
+    })
+    if (free) return port
+  }
+  throw new Error(`stator: no free port found in ${start}–${start + attempts - 1}`)
+}

package/src/server/create-app.ts

@@ -76,6 +76,18 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
           logger.info({ port, machines: defs.length, routes: routes.length }, 'listening')
           resolveFn()
         })
+        // Production is strict about its port (a collision is a deploy
+        // error) — but says so in one line, not a stack trace.
+        server.on('error', (err: NodeJS.ErrnoException) => {
+          if (err.code === 'EADDRINUSE') {
+            logger.error(
+              { port },
+              `port ${port} is already in use — is another instance running? (set PORT to change it)`,
+            )
+            process.exit(1)
+          }
+          throw err
+        })
         // Ctrl+C / SIGTERM (deploy rollover) exits 0, not 130 — quiet in
         // prod: the structured logs are the record.
         installGracefulShutdown(() => new Promise<void>((done) => server.close(() => done())), true)

package/src/server/dev.ts

@@ -7,7 +7,7 @@ import { createServer as createViteServer, type ViteDevServer } from 'vite'
 import { compile } from '../compiler/index.ts'
 import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
-import { installGracefulShutdown, printDevBanner } from './banner.ts'
+import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { logger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -52,10 +52,14 @@ export interface DevApp {
 }
 
 export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
+  // stator apps side by side would fight over it (the loser's live reload
+  // silently dies). Probe a free one instead.
+  const hmrPort = await findFreePort(24678)
   const vite = await createViteServer({
     root: resolve(config.root),
     appType: 'custom',
-    server: { middlewareMode: true },
+    server: { middlewareMode: true, hmr: { port: hmrPort } },
     // machineStub keeps server machines out of browser module graphs: island
     // imports of a machine resolve to a `{ name }` stub (SSR loads are
     // untouched — `options.ssr` gates it).
@@ -199,12 +203,23 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
         await vite.close()
         await new Promise<void>((done) => server.close(() => done()))
       })
-      return new Promise((resolveFn) => {
-        server.listen(port, () => {
-          printDevBanner({ port, machines: machineCount, routes: routes.length, inspector: true })
-          resolveFn()
-        })
-      })
+      // Busy port? Shift up like every modern dev server (the requested
+      // port is someone's other project, not an error).
+      return findFreePort(port).then(
+        (freePort) =>
+          new Promise((resolveFn) => {
+            server.listen(freePort, () => {
+              printDevBanner({
+                port: freePort,
+                requestedPort: port,
+                machines: machineCount,
+                routes: routes.length,
+                inspector: true,
+              })
+              resolveFn()
+            })
+          }),
+      )
     },
     close: () => vite.close(),
   }