@luckystack/server 0.8.6 → 0.8.7

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.7] - 2026-08-18
+
+### Added
+
+- `RunningLuckyStackServer.afterListen(task, options?)` — runs post-listen work (durable queue workers, warm-up passes, reconciliation jobs) isolated from the caller's fatal boot chain. A rejection is logged loudly and swallowed by default, because the server is already accepting traffic: killing a healthy process over one unreachable dependency turns an outage into a supervisor crash-loop, while the log claims "failed to start" about a server that started fine. Pass `{ fatal: true }` when the process genuinely has no purpose without the task, and `{ label }` to name it in the failure log.
+
 ## [0.8.5] - 2026-08-17
 
 ### Added

package/CLAUDE.md

@@ -25,7 +25,8 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 
 | Function / Export | One-liner | Deep doc |
 |---|---|---|
-| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, stop, close }`. Wires HTTP + Socket.io + framework routes; after a successful listen starts the boot-UUID TTL heartbeat, and stops it during shutdown. Installs a persistent `httpServer.on('error')` listener and (in prod) SIGTERM/SIGINT → graceful `stop()`. | -> docs/create-server.md |
+| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, afterListen, stop, close }`. Wires HTTP + Socket.io + framework routes; after a successful listen starts the boot-UUID TTL heartbeat, and stops it during shutdown. Installs a persistent `httpServer.on('error')` listener and (in prod) SIGTERM/SIGINT → graceful `stop()`. | -> docs/create-server.md |
+| `RunningLuckyStackServer.afterListen(task, options?)` | Runs post-listen work (queue workers, warm-up, reconciliation) isolated from the caller's fatal boot chain. A rejection is logged loudly and swallowed by default — the server is already serving, and killing it over one broken dependency turns an outage into a supervisor crash-loop. `{ fatal: true }` re-throws for a task the process cannot run without; `{ label }` names it in the log. | -> docs/create-server.md |
 | `RunningLuckyStackServer.stop(options?)` / `.close(options?)` | Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the core `preServerStop` hook, flushes error-trackers (bounded by a per-step timeout race), then closes io + http + the Redis-adapter pub/sub clients. Each step isolated + time-bounded so one hanging step can't stall shutdown. Idempotent. `options`: `{ reason?, timeoutMs? }` (default `timeoutMs` 10000). | -> docs/create-server.md |
 | `bootstrapLuckyStack(options)` | High-level entry: auto-imports `luckystack/<pkg>/*.ts` overlay in topological order, then delegates to `createLuckyStackServer`. An overlay file that fails to import (classic: it imports a package removed via `luckystack remove`) aborts boot with an ACTIONABLE error naming the file, instead of a raw ERR_MODULE_NOT_FOUND. | -> docs/create-server.md |
 | `OVERLAY_ORDER` (exported const) | The canonical overlay walk order (`core, deploy, login, email, sentry, presence, cron, docs-ui, server`). Exported so the consumer's `scripts/bundleServer.mjs` imports it at build time — a hardcoded bundler copy once silently dropped the cron slot from prod; `overlayOrderParity.test.ts` pins the bundlers' fallback lists to this. | -> docs/create-server.md |
@@ -60,7 +61,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 | Hook payload: `PreRoomLeavePayload` | Payload type for `preRoomLeave` hook handlers. | -> docs/create-server.md |
 | Hook payload: `PostRoomLeavePayload` | Payload type for `postRoomLeave` hook handlers. | -> docs/create-server.md |
 | Hook payload: `OnLocationUpdatePayload` | Payload type for `onLocationUpdate` hook handlers. | -> docs/create-server.md |
-| Types: `CreateLuckyStackServerOptions`, `BootstrapLuckyStackOptions`, `BootstrapRequirements`, `RunningLuckyStackServer`, `StopLuckyStackServerOptions`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler`, `ProdRuntimeMapsLoaderOptions`, `ParsedServerArgv`, `SecurityHeadersBuilder`, `ErrorFormatter`, `ErrorFormatterContext` | Handler + option typing. | -> docs/create-server.md |
+| Types: `CreateLuckyStackServerOptions`, `BootstrapLuckyStackOptions`, `BootstrapRequirements`, `RunningLuckyStackServer`, `StopLuckyStackServerOptions`, `AfterListenOptions`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler`, `ProdRuntimeMapsLoaderOptions`, `ParsedServerArgv`, `SecurityHeadersBuilder`, `ErrorFormatter`, `ErrorFormatterContext` | Handler + option typing. | -> docs/create-server.md |
 
 ## Config keys (env vars + registerProjectConfig slots)
 

package/dist/index.d.ts

@@ -157,6 +157,16 @@ interface StopLuckyStackServerOptions {
      */
     timeoutMs?: number;
 }
+interface AfterListenOptions {
+    /**
+     * Re-throw instead of swallowing. Use only when the process is genuinely
+     * useless without this task. Default `false` — a listening server survives a
+     * failing post-listen task.
+     */
+    fatal?: boolean;
+    /** Label used in the failure log. Defaults to `post-listen task`. */
+    label?: string;
+}
 interface RunningLuckyStackServer {
     httpServer: Server;
     ioServer: Server$1;
@@ -165,6 +175,20 @@ interface RunningLuckyStackServer {
      * URL on success.
      */
     listen: (callback?: () => void) => Promise<Server>;
+    /**
+     * Run work that belongs AFTER the server is accepting traffic — durable queue
+     * workers, warm-up passes, reconciliation jobs.
+     *
+     * A rejection here is logged loudly and swallowed by default, because the
+     * server is already up: killing a healthy process over one broken dependency
+     * turns an outage into a crash-loop (supervisor restarts, dependency is still
+     * down, repeat). Pass `{ fatal: true }` when the process genuinely has no
+     * purpose without the task — the rejection then propagates to the caller.
+     *
+     * Never resolves to the task's value; it is fire-and-report, not a pipeline
+     * stage. Read what you need inside the callback.
+     */
+    afterListen: (task: () => void | Promise<void>, options?: AfterListenOptions) => Promise<void>;
     /**
      * Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the
      * core `preServerStop` hook, flushes error-trackers (bounded by a timeout
@@ -325,4 +349,4 @@ declare const registerSecurityHeaders: (builder: SecurityHeadersBuilder | null)
 /** Read the active builder (or null). */
 declare const getSecurityHeadersBuilder: () => SecurityHeadersBuilder | null;
 
-export { type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type OverlayEntries, type ParsedServerArgv, type PostRoomJoinPayload, type PostRoomLeavePayload, type PreRoomJoinPayload, type PreRoomLeavePayload, type ProdRuntimeMapsLoaderOptions, type RegisterCustomRouteOptions, type RouteContext, type RunningLuckyStackServer, type SecurityHeadersBuilder, type StaticFileHandler, type StopLuckyStackServerOptions, applyServerArgv, bootstrapLuckyStack, clearCustomRoutes, clearOriginExemptPaths, collectOverlayEntries, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };
+export { type AfterListenOptions, type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type OverlayEntries, type ParsedServerArgv, type PostRoomJoinPayload, type PostRoomLeavePayload, type PreRoomJoinPayload, type PreRoomLeavePayload, type ProdRuntimeMapsLoaderOptions, type RegisterCustomRouteOptions, type RouteContext, type RunningLuckyStackServer, type SecurityHeadersBuilder, type StaticFileHandler, type StopLuckyStackServerOptions, applyServerArgv, bootstrapLuckyStack, clearCustomRoutes, clearOriginExemptPaths, collectOverlayEntries, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 
 // src/createServer.ts
 import http from "http";
-import { registerBindAddress, registerBoundAddress, writeBootUuid, startBootUuidHeartbeat, getLogger as getLogger13, getProjectConfig as getProjectConfig15, tryCatch as tryCatch10, tryCatchSync as tryCatchSync3, resolveRuntimeMode, dispatchHook as dispatchHook8 } from "@luckystack/core";
+import { registerBindAddress, registerBoundAddress, writeBootUuid, startBootUuidHeartbeat, getLogger as getLogger14, getProjectConfig as getProjectConfig15, tryCatch as tryCatch11, tryCatchSync as tryCatchSync3, resolveRuntimeMode, dispatchHook as dispatchHook8 } from "@luckystack/core";
 
 // src/httpHandler.ts
 import { randomUUID } from "crypto";
@@ -2340,6 +2340,18 @@ var clearDevServerInfo = () => {
   }
 };
 
+// src/afterListen.ts
+import { getLogger as getLogger13, tryCatch as tryCatch10 } from "@luckystack/core";
+var runAfterListenTask = async (task, { fatal = false, label = "post-listen task" } = {}) => {
+  const [error] = await tryCatch10(async () => task());
+  if (!error) return;
+  if (fatal) throw error;
+  getLogger13().error(
+    `[server] ${label} failed \u2014 the server is listening and stays up. Fix the underlying cause; pass { fatal: true } to afterListen if this process should not run without it.`,
+    error
+  );
+};
+
 // src/createServer.ts
 var initDevTools = async () => {
   const { initConsolelog } = await import("@luckystack/core");
@@ -2361,19 +2373,19 @@ var initDevTools = async () => {
   });
   const devkitModuleId = "@luckystack/devkit";
   if (!canResolve(devkitModuleId)) {
-    getLogger13().warn(
+    getLogger14().warn(
       "dev tooling unavailable \u2014 @luckystack/devkit is not installed, so hot reload + type-map generation are off. Install it as a devDependency for dev, or set NODE_ENV=production to run in production mode."
     );
     return;
   }
-  const [devkitError] = await tryCatch10(async () => {
+  const [devkitError] = await tryCatch11(async () => {
     const devkit = await import(devkitModuleId);
     await devkit.initializeAll();
     devkit.setupWatchers();
   });
   if (devkitError) {
     markDevToolsInitFailed(devkitError);
-    getLogger13().error(
+    getLogger14().error(
       `dev tooling FAILED to initialize \u2014 the server is running but EVERY /api and /sync route will fail until this is fixed. Hot reload is OFF (the file watchers never started), so fix the cause below and RESTART the server. Cause: ${devkitError.message}`,
       devkitError
     );
@@ -2396,7 +2408,7 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
         return;
       }
       if (autoIncrement && attemptPort < 65535) {
-        getLogger13().warn(
+        getLogger14().warn(
           `Port ${String(attemptPort)} is in use \u2014 trying ${String(attemptPort + 1)} (auto-increment; set SERVER_PORT_AUTO_INCREMENT=0 to disable). A previous/zombie dev server is still holding :${String(attemptPort)}: a manual client pinned there will keep talking to the OLD process, while the Vite proxy follows this restart's advertised port. If this restart was meant to replace it, stop the process on :${String(attemptPort)} first.`
         );
         tryListen(attemptPort + 1);
@@ -2406,11 +2418,11 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
         const rangeError = new RangeError(
           "Port 65535 is already in use and auto-increment cannot select a valid higher TCP port."
         );
-        getLogger13().error(rangeError.message);
+        getLogger14().error(rangeError.message);
         reject(rangeError);
         return;
       }
-      getLogger13().error(
+      getLogger14().error(
         `Port ${String(attemptPort)} is already in use \u2014 the server did NOT start. Another \`npm run server\` is probably still running (stop it), or choose a free port in config.ports.ts / positional argv, or set SERVER_PORT_AUTO_INCREMENT=1 to auto-pick the next free port.`
       );
       reject(err);
@@ -2432,14 +2444,14 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
           return callbackUrl.port || (callbackUrl.protocol === "https:" ? "443" : "80");
         })[1] ?? "";
         if (callbackPort === String(startPort) && callbackPort !== String(boundPort)) {
-          getLogger13().warn(
+          getLogger14().warn(
             `OAuth port drift: the server bound :${String(boundPort)} but your OAuth callback base is configured for :${callbackPort} (${configuredCallbackBase}). The framework now auto-targets :${String(boundPort)} for OAuth so the callback reaches THIS server \u2014 but your provider (Google/GitHub/\u2026) still exact-matches its registered redirect URI, so add :${String(boundPort)} to the authorized redirect URIs, OR set SERVER_PORT_AUTO_INCREMENT=0 to pin :${callbackPort} (stop whatever holds it) instead of hopping.`
           );
         }
       }
       const config = getProjectConfig15();
       if (config.logging.socketStartup || config.logging.devLogs) {
-        getLogger13().info(`Server is running on http://${ip}:${String(boundPort)}/`);
+        getLogger14().info(`Server is running on http://${ip}:${String(boundPort)}/`);
       }
       callback?.();
       resolve(httpServer);
@@ -2470,7 +2482,7 @@ var createLuckyStackServer = async (options = {}) => {
   if (enableDevTools) {
     await initDevTools();
   }
-  const [bootUuidError] = await tryCatch10(() => writeBootUuid());
+  const [bootUuidError] = await tryCatch11(() => writeBootUuid());
   if (bootUuidError) {
     throw new Error(
       "Failed to write the boot UUID to Redis. Check REDIS_HOST / REDIS_PORT / REDIS_USER / REDIS_PASSWORD and that Redis is reachable.",
@@ -2482,7 +2494,7 @@ var createLuckyStackServer = async (options = {}) => {
   });
   httpServer.on("error", (err) => {
     if (err.code === "EADDRINUSE") return;
-    getLogger13().error("[http-server] runtime error", err);
+    getLogger14().error("[http-server] runtime error", err);
   });
   const { io: ioServer, adapterClients } = loadSocket(httpServer, {
     maxHttpBufferSize: options.maxHttpBufferSize
@@ -2513,14 +2525,14 @@ var createLuckyStackServer = async (options = {}) => {
       handleSignal("SIGINT");
     });
   }
-  return { httpServer, ioServer, listen, stop, close: stop };
+  return { httpServer, ioServer, listen, afterListen: runAfterListenTask, stop, close: stop };
 };
 
 // src/bootstrap.ts
 import path3 from "path";
 import fs2 from "fs";
 import { pathToFileURL } from "url";
-import { ROOT_DIR, tryCatch as tryCatch11, getLogger as getLogger14, isTestFile, isTestDirectory } from "@luckystack/core";
+import { ROOT_DIR, tryCatch as tryCatch12, getLogger as getLogger15, isTestFile, isTestDirectory } from "@luckystack/core";
 var OVERLAY_ORDER = [
   // Core registries first — clients, paths, routing rules. Anything below
   // depends on these being in place.
@@ -2545,7 +2557,7 @@ var OVERLAY_ORDER = [
 ];
 var importIfExists = async (filePath) => {
   if (!fs2.existsSync(filePath)) return;
-  const [error] = await tryCatch11(async () => {
+  const [error] = await tryCatch12(async () => {
     await import(pathToFileURL(filePath).href);
   });
   if (error) {
@@ -2586,7 +2598,7 @@ var loadOverlayFolder = async (overlayRoot) => {
     if (!fs2.existsSync(packageDir)) continue;
     const { fileNames, ignoredDirectoryNames } = collectOverlayEntries(packageDir);
     for (const directoryName of ignoredDirectoryNames) {
-      getLogger14().warn(
+      getLogger15().warn(
         `[luckystack:overlay] ignoring \`${overlayRoot}/${packageName}/${directoryName}/\` \u2014 the overlay walk does not recurse. Move the file(s) up into \`${overlayRoot}/${packageName}/\`, or import them from a file that is there.`
       );
     }