@luckystack/server 0.4.1 → 0.5.0

package/README.md

@@ -1,198 +1,198 @@
-# @luckystack/server
-
-> One-call server bootstrap for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). HTTP + Socket.io + framework routes (`/api/*`, `/sync/*`, `/_health`, `/_test/reset`, `/auth/*`, `/uploads/*`) wired together. Your `server.ts` shrinks to ~20 lines.
-
-## Install
-
-```bash
-npm install @luckystack/server @luckystack/core @luckystack/api @luckystack/login @luckystack/sync @luckystack/presence socket.io
-```
-
-## Quickstart — recommended (`bootstrapLuckyStack`)
-
-`bootstrapLuckyStack` is a thin wrapper around `createLuckyStackServer` that auto-imports your `luckystack/<pkg>/*.ts` overlay files in topological order before listening, so registries (DI, hooks, providers) are populated by the time the HTTP server boots. This is what `create-luckystack-app` scaffolds.
-
-```ts
-import 'dotenv/config';
-import '../config';            // your registerProjectConfig(...)
-import '../deploy.config';     // your registerDeployConfig(...)
-import '../services.config';   // your registerServicesConfig(...)
-
-import { bootstrapLuckyStack } from '@luckystack/server';
-import { serveFile, serveFavicon } from './prod/serveFile';
-
-const server = await bootstrapLuckyStack({
-  serveFile,
-  serveFavicon,
-});
-
-await server.listen();
-```
-
-The bootstrap call runs (in order):
-
-1. Auto-imports `luckystack/core/*.ts`, `luckystack/deploy/*.ts`, `luckystack/login/*.ts`, `luckystack/sentry/*.ts`, `luckystack/presence/*.ts`, `luckystack/docs-ui/*.ts`, `luckystack/server/*.ts` (topologically sorted, then alphabetically inside each folder).
-2. Hands off to `createLuckyStackServer(options)`.
-
-Set `skipOverlayLoad: true` to handle every registration yourself, or `overlayRoot: 'custom-folder'` to load from somewhere other than `./luckystack`.
-
-### Pre-flight check — `verifyBootstrap`
-
-Call `verifyBootstrap` **after** the overlay loads (or after your manual registrations) and **before** `server.listen()` if you want to fail fast on missing registrations instead of silent runtime crashes:
-
-```ts
-import { bootstrapLuckyStack, verifyBootstrap } from '@luckystack/server';
-
-const server = await bootstrapLuckyStack({ serveFile, serveFavicon });
-
-await verifyBootstrap({
-  requireDeployConfig: true,    // single-instance deploys can omit this
-  requireServicesConfig: true,  // only true when the router will run
-  requireOAuthProviders: true,  // false if you only use credentials login
-});
-
-await server.listen();
-```
-
-`verifyBootstrap` throws a single descriptive `Error` listing every missing registration. The full check covers:
-
-- `ProjectConfig` — always required.
-- `DeployConfig` — when `requireDeployConfig: true`.
-- `ServicesConfig` — when `requireServicesConfig: true`.
-- OAuth providers — when `requireOAuthProviders: true` and only the default `credentials` entry has been registered.
-- `RuntimeMapsProvider` — hard-fails in production; loud-warns in dev because devkit hot-reload normally registers one. Without it, every API/sync request silently resolves to `notFound`.
-- `LocalizedNormalizer` — hard-fails in production; warns in dev. Without it, error responses degrade to `errorCode`-as-message (no i18n).
-
-## Lower-level entry — `createLuckyStackServer`
-
-Use this directly when you want to control the order of imports yourself or skip the overlay convention:
-
-```ts
-import { initializeSentry } from '@luckystack/error-tracking';
-import { registerPresenceHooks } from '@luckystack/presence';
-import { createLuckyStackServer } from '@luckystack/server';
-
-initializeSentry();
-registerPresenceHooks();
-
-const server = await createLuckyStackServer({
-  serveFile,
-  serveFavicon,
-});
-await server.listen();
-```
-
-Both entries handle devkit hot reload + console init in dev mode automatically — opt out with `enableDevTools: false` if you have your own.
-
-## Options
-
-```ts
-interface CreateLuckyStackServerOptions {
-  port?: number | string;          // default: process.env.SERVER_PORT ?? 80
-  ip?: string;                     // default: process.env.SERVER_IP ?? '127.0.0.1'
-  serveFile?: StaticFileHandler;   // catch-all for non-framework GETs (Vite output, SPA fallback)
-  serveFavicon?: FaviconHandler;   // /favicon.ico
-  customRoutes?: CustomRouteHandler; // pre-fallback hook; return true to mark handled
-  enableDevTools?: boolean;        // default: NODE_ENV !== 'production'
-  maxHttpBufferSize?: number;      // default: 5 MB
-}
-```
-
-`customRoutes` runs before the static file serving, so you can add project-specific HTTP endpoints (webhooks, OG image generation, etc.) without forking the package. Return `true` if you ended the response.
-
-You can also register custom routes globally via `registerCustomRoute(handler)` — the bootstrap call composes every registered handler into the running server. This is what `@luckystack/docs-ui` uses to mount `/_docs`.
-
-```ts
-import { registerCustomRoute } from '@luckystack/server';
-
-registerCustomRoute(async (req, res) => {
-  if (req.url !== '/healthz') return false;
-  res.statusCode = 200;
-  res.end('ok');
-  return true;
-});
-```
-
-## What it wires
-
-- **HTTP server** with CORS + security headers, OPTIONS preflight, method validation, cookie sliding, CSRF middleware.
-- **Socket.io server** attached to the HTTP server, with optional Redis adapter when configured in deploy config.
-- **Framework routes:** `/_health`, `/livez`, `/readyz`, `/_test/reset` (dev/test only), `/api/*` and `/sync/*` (with SSE streaming), `/auth/api`, `/auth/callback/*`, `/uploads/*`, `/assets/*`, `/csrf-token`.
-- **Presence broadcasting** (when enabled in project config): connect / disconnect / reconnect, location updates, peer notifications.
-- **Boot UUID** written on startup so the load-balancer (`@luckystack/router`) can detect rolling restarts.
-- **Dev tools** in non-production: devkit hot reload, console initializer.
-
-### HTTP route handler layout
-
-`handleHttpRequest` is now a thin (~190-line) orchestrator that sets up CORS / origin / security headers, runs the CSRF middleware, then dispatches a route-handler table. Each handler matches its own route path and returns `boolean` (handled or not). The handlers live in `packages/server/src/httpRoutes/`:
-
-| File | Routes |
-| --- | --- |
-| `csrfMiddleware.ts` + `csrfRoute.ts` | CSRF guard on writes + `GET /csrf-token` |
-| `healthRoutes.ts` | `/livez`, `/readyz`, `/_health` |
-| `testResetRoute.ts` | `/_test/reset` (dev/test only — see Security below) |
-| `faviconRoute.ts` | `/favicon.ico` |
-| `uploadsRoute.ts` | `/uploads/*` (avatar serving via `serveAvatar`) |
-| `authApiRoute.ts` | `/auth/api/*` |
-| `authCallbackRoute.ts` | `/auth/callback/*` |
-| `apiRoute.ts` | `/api/*` (delegates to `@luckystack/api`'s `handleHttpApiRequest`) |
-| `syncRoute.ts` | `/sync/*` (delegates to `@luckystack/sync`'s `handleHttpSyncRequest`) |
-| `customRoutes.ts` | Calls every handler registered via `registerCustomRoute(...)` and the inline `customRoutes` option |
-| `staticRoutes.ts` | Final fallback to the consumer's `serveFile(...)` (Vite SPA, etc.) |
-
-Top-level `handleHttpRequest` + `dispatchRoutes(handlers, ctx)` are the only orchestration; everything else is a flat list of single-purpose handlers. SSE handling, error fall-through, and dispatch order are preserved.
-
-### Security defaults that may surprise you
-
-- **CORS fail-closed.** If neither `Origin` nor `Referer` is present, only read-only methods (GET, HEAD, OPTIONS) are allowed; state-changing methods are rejected with 403. Earlier builds fell back to `Host`, which silently bypassed CORS for non-browser callers (`curl`, server-to-server). When you `curl` a write endpoint, set `-H 'Origin: https://your-allowed-origin'`.
-- **`/_test/reset` is fail-closed.** It requires both `NODE_ENV` to be exactly `development` or `test` AND a non-empty `TEST_RESET_TOKEN` env var. Any other state returns 403 (no silent allow-list). Wire `TEST_RESET_TOKEN` in your dev/test `.env.local` and pass it as the `x-test-reset-token: ${TOKEN}` header on the reset call. `@luckystack/test-runner`'s `resetServerState` reads the same env var.
-- **CSRF middleware.** Writes to `/api/*` and `/sync/*` require an `x-csrf-token` header that matches the value minted on the session record (mirrored via `GET /auth/csrf`). The `apiRequest` helper in `@luckystack/core/client` attaches it automatically. Rejections dispatch the `csrfMismatch` hook before returning 403; the payload contains presence-only token info, never the value. The header name, token length, and cookie options are customisable via `registerCsrfConfig({ headerName, tokenLength, cookieOptions })` from `@luckystack/core` — see `packages/core/docs/csrf-config.md`.
-
-## Public API
-
-| Export | Purpose |
-| --- | --- |
-| `bootstrapLuckyStack(options)` | High-level entry: verifies config, auto-imports overlay, then calls `createLuckyStackServer`. |
-| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, stop, close }` (`stop`/`close` = graceful MIS-016 shutdown). |
-| `verifyBootstrap(requirements?)` | Pre-flight check for project/deploy/services config and required env keys. |
-| `registerCustomRoute(handler)` / `getCustomRoutes()` / `clearCustomRoutes()` | Global custom-route registry composed by `bootstrapLuckyStack`. |
-| Hook payload types: `OnSocketConnectPayload`, `OnSocketDisconnectPayload`, `PreRoomJoinPayload`, `PostRoomJoinPayload`, `PreRoomLeavePayload`, `PostRoomLeavePayload`, `OnLocationUpdatePayload` | For socket-lifecycle hook handlers. |
-| Types: `CreateLuckyStackServerOptions`, `BootstrapLuckyStackOptions`, `BootstrapRequirements`, `RunningLuckyStackServer`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler` | Handler typing. |
-
-## Dependencies
-
-- Runtime: `@luckystack/api`, `@luckystack/core`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `socket.io@^4.8.0`
-- Optional peer: `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/docs-ui` — bootstrap auto-detects them but does not require them.
-
-## Selecting bundles + port at runtime
-
-`@luckystack/server/parseArgv` is a side-effect-only entrypoint. Import it as the **first line** of your `server.ts` so positional CLI args are parsed before any module that reads `process.env.SERVER_PORT` at load time (notably your project's `config.ts`).
-
-```ts
-// server.ts
-import '@luckystack/server/parseArgv';
-// ...rest of your bootstrap
-```
-
-Argv shape: `<bundle[,bundle...]> [port]`
-
-```bash
-npm run server                              # default preset, port 80
-npm run server -- billing                   # one bundle, port 80
-npm run server -- billing,vehicles 4001     # merge bundles, listen on 4001
-```
-
-When multiple presets are passed, the framework loads each preset's generated route map and shallow-merges `apis` / `syncs` / `functions`. Key collisions across presets throw at boot (services must own exactly one preset).
-
-## Related architecture docs
-
-- [`docs/ARCHITECTURE_PACKAGING.md`](../../docs/ARCHITECTURE_PACKAGING.md) — package split, multi-service builds, preset bundles.
-- [`docs/ARCHITECTURE_SOCKET.md`](../../docs/ARCHITECTURE_SOCKET.md) — Socket.io setup, Redis adapter, room model.
-- [`docs/HOSTING.md`](../../docs/HOSTING.md) — multi-instance deployment, `@luckystack/router`, health probes.
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+# @luckystack/server
+
+> One-call server bootstrap for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). HTTP + Socket.io + framework routes (`/api/*`, `/sync/*`, `/_health`, `/_test/reset`, `/auth/*`, `/uploads/*`) wired together. Your `server.ts` shrinks to ~20 lines.
+
+## Install
+
+```bash
+npm install @luckystack/server @luckystack/core @luckystack/api @luckystack/login @luckystack/sync @luckystack/presence socket.io
+```
+
+## Quickstart — recommended (`bootstrapLuckyStack`)
+
+`bootstrapLuckyStack` is a thin wrapper around `createLuckyStackServer` that auto-imports your `luckystack/<pkg>/*.ts` overlay files in topological order before listening, so registries (DI, hooks, providers) are populated by the time the HTTP server boots. This is what `create-luckystack-app` scaffolds.
+
+```ts
+import 'dotenv/config';
+import '../config';            // your registerProjectConfig(...)
+import '../deploy.config';     // your registerDeployConfig(...)
+import '../services.config';   // your registerServicesConfig(...)
+
+import { bootstrapLuckyStack } from '@luckystack/server';
+import { serveFile, serveFavicon } from './prod/serveFile';
+
+const server = await bootstrapLuckyStack({
+  serveFile,
+  serveFavicon,
+});
+
+await server.listen();
+```
+
+The bootstrap call runs (in order):
+
+1. Auto-imports `luckystack/core/*.ts`, `luckystack/deploy/*.ts`, `luckystack/login/*.ts`, `luckystack/sentry/*.ts`, `luckystack/presence/*.ts`, `luckystack/docs-ui/*.ts`, `luckystack/server/*.ts` (topologically sorted, then alphabetically inside each folder).
+2. Hands off to `createLuckyStackServer(options)`.
+
+Set `skipOverlayLoad: true` to handle every registration yourself, or `overlayRoot: 'custom-folder'` to load from somewhere other than `./luckystack`.
+
+### Pre-flight check — `verifyBootstrap`
+
+Call `verifyBootstrap` **after** the overlay loads (or after your manual registrations) and **before** `server.listen()` if you want to fail fast on missing registrations instead of silent runtime crashes:
+
+```ts
+import { bootstrapLuckyStack, verifyBootstrap } from '@luckystack/server';
+
+const server = await bootstrapLuckyStack({ serveFile, serveFavicon });
+
+await verifyBootstrap({
+  requireDeployConfig: true,    // single-instance deploys can omit this
+  requireServicesConfig: true,  // only true when the router will run
+  requireOAuthProviders: true,  // false if you only use credentials login
+});
+
+await server.listen();
+```
+
+`verifyBootstrap` throws a single descriptive `Error` listing every missing registration. The full check covers:
+
+- `ProjectConfig` — always required.
+- `DeployConfig` — when `requireDeployConfig: true`.
+- `ServicesConfig` — when `requireServicesConfig: true`.
+- OAuth providers — when `requireOAuthProviders: true` and only the default `credentials` entry has been registered.
+- `RuntimeMapsProvider` — hard-fails in production; loud-warns in dev because devkit hot-reload normally registers one. Without it, every API/sync request silently resolves to `notFound`.
+- `LocalizedNormalizer` — hard-fails in production; warns in dev. Without it, error responses degrade to `errorCode`-as-message (no i18n).
+
+## Lower-level entry — `createLuckyStackServer`
+
+Use this directly when you want to control the order of imports yourself or skip the overlay convention:
+
+```ts
+import { initializeSentry } from '@luckystack/error-tracking';
+import { registerPresenceHooks } from '@luckystack/presence';
+import { createLuckyStackServer } from '@luckystack/server';
+
+initializeSentry();
+registerPresenceHooks();
+
+const server = await createLuckyStackServer({
+  serveFile,
+  serveFavicon,
+});
+await server.listen();
+```
+
+Both entries handle devkit hot reload + console init in dev mode automatically — opt out with `enableDevTools: false` if you have your own.
+
+## Options
+
+```ts
+interface CreateLuckyStackServerOptions {
+  port?: number | string;          // default: process.env.SERVER_PORT ?? 80
+  ip?: string;                     // default: process.env.SERVER_IP ?? '127.0.0.1'
+  serveFile?: StaticFileHandler;   // catch-all for non-framework GETs (Vite output, SPA fallback)
+  serveFavicon?: FaviconHandler;   // /favicon.ico
+  customRoutes?: CustomRouteHandler; // pre-fallback hook; return true to mark handled
+  enableDevTools?: boolean;        // default: NODE_ENV !== 'production'
+  maxHttpBufferSize?: number;      // default: 5 MB
+}
+```
+
+`customRoutes` runs before the static file serving, so you can add project-specific HTTP endpoints (webhooks, OG image generation, etc.) without forking the package. Return `true` if you ended the response.
+
+You can also register custom routes globally via `registerCustomRoute(handler)` — the bootstrap call composes every registered handler into the running server. This is what `@luckystack/docs-ui` uses to mount `/_docs`.
+
+```ts
+import { registerCustomRoute } from '@luckystack/server';
+
+registerCustomRoute(async (req, res) => {
+  if (req.url !== '/healthz') return false;
+  res.statusCode = 200;
+  res.end('ok');
+  return true;
+});
+```
+
+## What it wires
+
+- **HTTP server** with CORS + security headers, OPTIONS preflight, method validation, cookie sliding, CSRF middleware.
+- **Socket.io server** attached to the HTTP server, with optional Redis adapter when configured in deploy config.
+- **Framework routes:** `/_health`, `/livez`, `/readyz`, `/_test/reset` (dev/test only), `/api/*` and `/sync/*` (with SSE streaming), `/auth/api`, `/auth/callback/*`, `/uploads/*`, `/assets/*`, `/csrf-token`.
+- **Presence broadcasting** (when enabled in project config): connect / disconnect / reconnect, location updates, peer notifications.
+- **Boot UUID** written on startup so the load-balancer (`@luckystack/router`) can detect rolling restarts.
+- **Dev tools** in non-production: devkit hot reload, console initializer.
+
+### HTTP route handler layout
+
+`handleHttpRequest` is now a thin (~190-line) orchestrator that sets up CORS / origin / security headers, runs the CSRF middleware, then dispatches a route-handler table. Each handler matches its own route path and returns `boolean` (handled or not). The handlers live in `packages/server/src/httpRoutes/`:
+
+| File | Routes |
+| --- | --- |
+| `csrfMiddleware.ts` + `csrfRoute.ts` | CSRF guard on writes + `GET /csrf-token` |
+| `healthRoutes.ts` | `/livez`, `/readyz`, `/_health` |
+| `testResetRoute.ts` | `/_test/reset` (dev/test only — see Security below) |
+| `faviconRoute.ts` | `/favicon.ico` |
+| `uploadsRoute.ts` | `/uploads/*` (avatar serving via `serveAvatar`) |
+| `authApiRoute.ts` | `/auth/api/*` |
+| `authCallbackRoute.ts` | `/auth/callback/*` |
+| `apiRoute.ts` | `/api/*` (delegates to `@luckystack/api`'s `handleHttpApiRequest`) |
+| `syncRoute.ts` | `/sync/*` (delegates to `@luckystack/sync`'s `handleHttpSyncRequest`) |
+| `customRoutes.ts` | Calls every handler registered via `registerCustomRoute(...)` and the inline `customRoutes` option |
+| `staticRoutes.ts` | Final fallback to the consumer's `serveFile(...)` (Vite SPA, etc.) |
+
+Top-level `handleHttpRequest` + `dispatchRoutes(handlers, ctx)` are the only orchestration; everything else is a flat list of single-purpose handlers. SSE handling, error fall-through, and dispatch order are preserved.
+
+### Security defaults that may surprise you
+
+- **CORS fail-closed.** If neither `Origin` nor `Referer` is present, only read-only methods (GET, HEAD, OPTIONS) are allowed; state-changing methods are rejected with 403. Earlier builds fell back to `Host`, which silently bypassed CORS for non-browser callers (`curl`, server-to-server). When you `curl` a write endpoint, set `-H 'Origin: https://your-allowed-origin'`.
+- **`/_test/reset` is fail-closed.** It requires both `NODE_ENV` to be exactly `development` or `test` AND a non-empty `TEST_RESET_TOKEN` env var. Any other state returns 403 (no silent allow-list). Wire `TEST_RESET_TOKEN` in your dev/test `.env.local` and pass it as the `x-test-reset-token: ${TOKEN}` header on the reset call. `@luckystack/test-runner`'s `resetServerState` reads the same env var.
+- **CSRF middleware.** Writes to `/api/*` and `/sync/*` require an `x-csrf-token` header that matches the value minted on the session record (mirrored via `GET /auth/csrf`). The `apiRequest` helper in `@luckystack/core/client` attaches it automatically. Rejections dispatch the `csrfMismatch` hook before returning 403; the payload contains presence-only token info, never the value. The header name, token length, and cookie options are customisable via `registerCsrfConfig({ headerName, tokenLength, cookieOptions })` from `@luckystack/core` — see `packages/core/docs/csrf-config.md`.
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `bootstrapLuckyStack(options)` | High-level entry: verifies config, auto-imports overlay, then calls `createLuckyStackServer`. |
+| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, stop, close }` (`stop`/`close` = graceful MIS-016 shutdown). |
+| `verifyBootstrap(requirements?)` | Pre-flight check for project/deploy/services config and required env keys. |
+| `registerCustomRoute(handler)` / `getCustomRoutes()` / `clearCustomRoutes()` | Global custom-route registry composed by `bootstrapLuckyStack`. |
+| Hook payload types: `OnSocketConnectPayload`, `OnSocketDisconnectPayload`, `PreRoomJoinPayload`, `PostRoomJoinPayload`, `PreRoomLeavePayload`, `PostRoomLeavePayload`, `OnLocationUpdatePayload` | For socket-lifecycle hook handlers. |
+| Types: `CreateLuckyStackServerOptions`, `BootstrapLuckyStackOptions`, `BootstrapRequirements`, `RunningLuckyStackServer`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler` | Handler typing. |
+
+## Dependencies
+
+- Runtime: `@luckystack/api`, `@luckystack/core`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`
+- Peer (canonical ranges, standardized 2026-05-07):
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
+  - `socket.io@^4.8.0`
+- Optional peer: `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/docs-ui` — bootstrap auto-detects them but does not require them.
+
+## Selecting bundles + port at runtime
+
+`@luckystack/server/parseArgv` is a side-effect-only entrypoint. Import it as the **first line** of your `server.ts` so positional CLI args are parsed before any module that reads `process.env.SERVER_PORT` at load time (notably your project's `config.ts`).
+
+```ts
+// server.ts
+import '@luckystack/server/parseArgv';
+// ...rest of your bootstrap
+```
+
+Argv shape: `<bundle[,bundle...]> [port]`
+
+```bash
+npm run server                              # default preset, port 80
+npm run server -- billing                   # one bundle, port 80
+npm run server -- billing,vehicles 4001     # merge bundles, listen on 4001
+```
+
+When multiple presets are passed, the framework loads each preset's generated route map and shallow-merges `apis` / `syncs` / `functions`. Key collisions across presets throw at boot (services must own exactly one preset).
+
+## Related architecture docs
+
+- [`docs/ARCHITECTURE_PACKAGING.md`](../../docs/ARCHITECTURE_PACKAGING.md) — package split, multi-service builds, preset bundles.
+- [`docs/ARCHITECTURE_SOCKET.md`](../../docs/ARCHITECTURE_SOCKET.md) — Socket.io setup, Redis adapter, room model.
+- [`docs/HOSTING.md`](../../docs/HOSTING.md) — multi-instance deployment, `@luckystack/router`, health probes.
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/{chunk-X3OSC5W3.js → chunk-RIVFTOTI.js}

@@ -41,4 +41,4 @@ export {
   getParsedBundles,
   getParsedPort
 };
-//# sourceMappingURL=chunk-X3OSC5W3.js.map
+//# sourceMappingURL=chunk-RIVFTOTI.js.map

package/dist/chunk-RIVFTOTI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/argv.ts"],"sourcesContent":["//? Positional argv parser for the LuckyStack server boot. Replaces\r\n//? `LUCKYSTACK_BUNDLE` + `SERVER_PORT` env-var reads with a single shape:\r\n//?\r\n//?   npm run server -- billing,vehicles 4001\r\n//?\r\n//? Arg 0 = comma-separated preset list (runtime maps merged across them).\r\n//? Arg 1 = listen port (numeric).\r\n//?\r\n//? `applyServerArgv()` is called by the side-effect module\r\n//? `@luckystack/server/parseArgv`, which consumers import as the FIRST line\r\n//? of their `server.ts` so the parsed port lands in `process.env.SERVER_PORT`\r\n//? before `config.ts` (top-level `backendUrl` const) is evaluated.\r\n\r\nexport interface ParsedServerArgv {\r\n  bundles: string[];\r\n  port: number | null;\r\n}\r\n\r\nlet parsedBundles: string[] = [];\r\nlet parsedPort: number | null = null;\r\nlet hasRun = false;\r\n\r\nconst PORT_PATTERN = /^\\d+$/;\r\n\r\nexport const parseServerArgv = (argv: string[]): ParsedServerArgv => {\r\n  if (argv.length > 2) {\r\n    throw new Error(\r\n      `[luckystack:argv] unexpected positional argument(s): \"${argv.slice(2).join(' ')}\". ` +\r\n      `Usage: npm run server -- <bundle[,bundle...]> [port]`,\r\n    );\r\n  }\r\n\r\n  const bundles = argv[0] && argv[0].length > 0\r\n    ? [...new Set(argv[0].split(',').map((s) => s.trim()).filter(Boolean))]\r\n    : [];\r\n\r\n  let port: number | null = null;\r\n  const portArg = argv[1];\r\n  if (portArg !== undefined) {\r\n    if (!PORT_PATTERN.test(portArg)) {\r\n      throw new Error(\r\n        `[luckystack:argv] port argument must be numeric, got: \"${portArg}\". ` +\r\n        `Usage: npm run server -- <bundle[,bundle...]> [port]`,\r\n      );\r\n    }\r\n    port = Number.parseInt(portArg, 10);\r\n  }\r\n\r\n  return { bundles, port };\r\n};\r\n\r\nexport const applyServerArgv = (): void => {\r\n  if (hasRun) return;\r\n  hasRun = true;\r\n\r\n  const result = parseServerArgv(process.argv.slice(2));\r\n  parsedBundles = result.bundles;\r\n  parsedPort = result.port;\r\n\r\n  //? Writeback so the downstream env-readers (`core/env.ts` Zod schema,\r\n  //? `core/bindAddress.ts` fallback, consumer `config.ts` backendUrl,\r\n  //? `oauthProviders.ts` callback URL) see the resolved port without us\r\n  //? having to refactor those four call sites. This is a deliberate\r\n  //? implementation detail — argv is the public source of truth.\r\n  if (parsedPort !== null) {\r\n    process.env.SERVER_PORT = String(parsedPort);\r\n  }\r\n};\r\n\r\nexport const getParsedBundles = (): string[] => parsedBundles;\r\nexport const getParsedPort = (): number | null => parsedPort;\r\n"],"mappings":";AAkBA,IAAI,gBAA0B,CAAC;AAC/B,IAAI,aAA4B;AAChC,IAAI,SAAS;AAEb,IAAM,eAAe;AAEd,IAAM,kBAAkB,CAAC,SAAqC;AACnE,MAAI,KAAK,SAAS,GAAG;AACnB,UAAM,IAAI;AAAA,MACR,yDAAyD,KAAK,MAAM,CAAC,EAAE,KAAK,GAAG,CAAC;AAAA,IAElF;AAAA,EACF;AAEA,QAAM,UAAU,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,SAAS,IACxC,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,EAAE,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,OAAO,CAAC,CAAC,IACpE,CAAC;AAEL,MAAI,OAAsB;AAC1B,QAAM,UAAU,KAAK,CAAC;AACtB,MAAI,YAAY,QAAW;AACzB,QAAI,CAAC,aAAa,KAAK,OAAO,GAAG;AAC/B,YAAM,IAAI;AAAA,QACR,0DAA0D,OAAO;AAAA,MAEnE;AAAA,IACF;AACA,WAAO,OAAO,SAAS,SAAS,EAAE;AAAA,EACpC;AAEA,SAAO,EAAE,SAAS,KAAK;AACzB;AAEO,IAAM,kBAAkB,MAAY;AACzC,MAAI,OAAQ;AACZ,WAAS;AAET,QAAM,SAAS,gBAAgB,QAAQ,KAAK,MAAM,CAAC,CAAC;AACpD,kBAAgB,OAAO;AACvB,eAAa,OAAO;AAOpB,MAAI,eAAe,MAAM;AACvB,YAAQ,IAAI,cAAc,OAAO,UAAU;AAAA,EAC7C;AACF;AAEO,IAAM,mBAAmB,MAAgB;AACzC,IAAM,gBAAgB,MAAqB;","names":[]}

package/dist/index.d.ts

@@ -196,6 +196,9 @@ interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
      */
     skipOverlayLoad?: boolean;
 }
+declare const OVERLAY_ORDER: string[];
+type OverlayLoader = () => Promise<void>;
+declare const registerOverlayLoader: (loader: OverlayLoader) => void;
 declare const bootstrapLuckyStack: (options?: BootstrapLuckyStackOptions) => Promise<RunningLuckyStackServer>;
 
 interface BootstrapRequirements {
@@ -307,4 +310,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, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, 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, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };
+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 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, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };

package/dist/index.js

@@ -3,11 +3,11 @@ import {
   getParsedBundles,
   getParsedPort,
   parseServerArgv
-} from "./chunk-X3OSC5W3.js";
+} from "./chunk-RIVFTOTI.js";
 
 // src/createServer.ts
 import http from "http";
-import { registerBindAddress, writeBootUuid, getLogger as getLogger13, getProjectConfig as getProjectConfig13, tryCatch as tryCatch10, isProduction as isProduction2, resolveEnvKey as resolveEnvKey5 } from "@luckystack/core";
+import { registerBindAddress, writeBootUuid, getLogger as getLogger13, getProjectConfig as getProjectConfig13, tryCatch as tryCatch10, isProduction as isProduction2, resolveEnvKey as resolveEnvKey5, dispatchHook as dispatchHook8 } from "@luckystack/core";
 
 // src/httpHandler.ts
 import { randomUUID } from "crypto";
@@ -107,6 +107,7 @@ var OPTIONAL_PACKAGES = [
   "email",
   "error-tracking",
   "presence",
+  "cron",
   "docs-ui"
 ];
 var canResolve = (specifier) => has(specifier);
@@ -281,7 +282,10 @@ var handleFaviconRoute = async ({ res, routePath, options }) => {
 import {
   computeSynchronizedEnvHashes,
   describeHealthHashConfig,
+  getDbHealthCheck,
   getProjectConfig as getProjectConfig3,
+  isPrismaClientRegistered,
+  isPrismaClientResolvable,
   prisma,
   readBootUuid,
   redis,
@@ -302,6 +306,16 @@ var pingPrisma = async () => {
   }
   return false;
 };
+var checkDatabaseReady = async () => {
+  const registered = getDbHealthCheck();
+  if (registered) {
+    const [error, result] = await tryCatch(async () => registered());
+    if (error || result === null) return false;
+    return result;
+  }
+  if (isPrismaClientRegistered() || isPrismaClientResolvable()) return pingPrisma();
+  return "skipped";
+};
 var handleLivezRoute = ({ res, routePath }) => {
   if (routePath !== getProjectConfig3().http.liveEndpoint) return Promise.resolve(false);
   res.statusCode = 200;
@@ -314,13 +328,21 @@ var handleReadyzRoute = async ({ res, routePath }) => {
   const bootUuid = await readBootUuid();
   const [redisError, pong] = await tryCatch(() => redis.ping());
   const redisOk = !redisError && (pong === "PONG" || Boolean(pong));
-  const prismaOk = await pingPrisma();
-  const ready = Boolean(bootUuid) && redisOk && prismaOk;
+  const databaseResult = await checkDatabaseReady();
+  const ready = Boolean(bootUuid) && redisOk && databaseResult !== false;
   res.statusCode = ready ? 200 : 503;
   res.setHeader("Content-Type", "application/json");
   res.end(JSON.stringify({
     status: ready ? "ready" : "not-ready",
-    checks: { bootUuid: Boolean(bootUuid), redis: redisOk, prisma: prismaOk }
+    //? `prisma` kept for backward compatibility with existing probes/dashboards
+    //? (true when the database check passed OR was deliberately skipped);
+    //? `database` carries the richer tri-state.
+    checks: {
+      bootUuid: Boolean(bootUuid),
+      redis: redisOk,
+      database: databaseResult,
+      prisma: databaseResult !== false
+    }
   }));
   return true;
 };
@@ -2081,8 +2103,21 @@ var clearDevServerInfo = () => {
 var initDevTools = async () => {
   const { initConsolelog } = await import("@luckystack/core");
   initConsolelog();
-  process.once("SIGINT", () => process.exit(0));
-  process.once("SIGTERM", () => process.exit(0));
+  const devSignalExit = (reason) => {
+    void Promise.race([
+      dispatchHook8("preServerStop", { reason, timeoutMs: 2e3 }),
+      new Promise((resolve) => {
+        setTimeout(resolve, 2e3);
+      })
+      // eslint-disable-next-line unicorn/no-process-exit -- deliberate dev hard-exit once the bounded hook window closes (mirrors the original inline handler)
+    ]).finally(() => process.exit(0));
+  };
+  process.once("SIGINT", () => {
+    devSignalExit("SIGINT");
+  });
+  process.once("SIGTERM", () => {
+    devSignalExit("SIGTERM");
+  });
   const devkitModuleId = "@luckystack/devkit";
   if (!canResolve(devkitModuleId)) {
     getLogger13().warn(
@@ -2207,7 +2242,7 @@ var createLuckyStackServer = async (options = {}) => {
 import path3 from "path";
 import fs2 from "fs";
 import { pathToFileURL } from "url";
-import { ROOT_DIR } from "@luckystack/core";
+import { ROOT_DIR, tryCatch as tryCatch11 } from "@luckystack/core";
 var OVERLAY_ORDER = [
   // Core registries first — clients, paths, routing rules. Anything below
   // depends on these being in place.
@@ -2222,6 +2257,9 @@ var OVERLAY_ORDER = [
   // Sentry / docs-ui / presence sit on top of core but don't block boot.
   "sentry",
   "presence",
+  // Cron jobs — `registerCronJob(...)` calls in `luckystack/cron/*.ts` lazily
+  // start the leader-elected scheduler (optional @luckystack/cron).
+  "cron",
   "docs-ui",
   // Server overlay last — typically empty, but a place to wire framework
   // hooks (`registerHook('onSocketConnect', ...)` etc.) before listen().
@@ -2229,7 +2267,18 @@ var OVERLAY_ORDER = [
 ];
 var importIfExists = async (filePath) => {
   if (!fs2.existsSync(filePath)) return;
-  await import(pathToFileURL(filePath).href);
+  const [error] = await tryCatch11(async () => {
+    await import(pathToFileURL(filePath).href);
+  });
+  if (error) {
+    throw new Error(
+      `[luckystack] failed to load overlay file ${filePath}: ${error.message}. If you removed an optional package (e.g. via \`luckystack remove <feature>\` or \`luckystack manage\`), delete or update the overlay files that still import it (the \`luckystack/<feature>/\` folder).`
+    );
+  }
+};
+var registeredOverlayLoader = null;
+var registerOverlayLoader = (loader) => {
+  registeredOverlayLoader = loader;
 };
 var loadOverlayFolder = async (overlayRoot) => {
   const overlayAbs = path3.isAbsolute(overlayRoot) ? overlayRoot : path3.join(ROOT_DIR, overlayRoot);
@@ -2268,7 +2317,7 @@ var bootstrapLuckyStack = async (options = {}) => {
   const overlayRoot = options.overlayRoot ?? "luckystack";
   if (!options.skipOverlayLoad) {
     await importOptionalPackageRegisters();
-    await loadOverlayFolder(overlayRoot);
+    await (registeredOverlayLoader ? registeredOverlayLoader() : loadOverlayFolder(overlayRoot));
   }
   await getLogin();
   const server = await createLuckyStackServer(options);
@@ -2282,6 +2331,7 @@ import {
   applyErrorFormatter
 } from "@luckystack/core";
 export {
+  OVERLAY_ORDER,
   applyServerArgv,
   bootstrapLuckyStack,
   clearCustomRoutes,
@@ -2300,6 +2350,7 @@ export {
   registerCustomRoute,
   registerErrorFormatter,
   registerOriginExemptPath,
+  registerOverlayLoader,
   registerProdRuntimeMapsProvider,
   registerSecurityHeaders,
   verifyBootstrap