@luckystack/server 0.1.9 → 0.2.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 }`. |
-| `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 }`. |
+| `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

@@ -0,0 +1,44 @@
+// src/argv.ts
+var parsedBundles = [];
+var parsedPort = null;
+var hasRun = false;
+var PORT_PATTERN = /^\d+$/;
+var parseServerArgv = (argv) => {
+  if (argv.length > 2) {
+    throw new Error(
+      `[luckystack:argv] unexpected positional argument(s): "${argv.slice(2).join(" ")}". Usage: npm run server -- <bundle[,bundle...]> [port]`
+    );
+  }
+  const bundles = argv[0] && argv[0].length > 0 ? [...new Set(argv[0].split(",").map((s) => s.trim()).filter(Boolean))] : [];
+  let port = null;
+  const portArg = argv[1];
+  if (portArg !== void 0) {
+    if (!PORT_PATTERN.test(portArg)) {
+      throw new Error(
+        `[luckystack:argv] port argument must be numeric, got: "${portArg}". Usage: npm run server -- <bundle[,bundle...]> [port]`
+      );
+    }
+    port = Number.parseInt(portArg, 10);
+  }
+  return { bundles, port };
+};
+var applyServerArgv = () => {
+  if (hasRun) return;
+  hasRun = true;
+  const result = parseServerArgv(process.argv.slice(2));
+  parsedBundles = result.bundles;
+  parsedPort = result.port;
+  if (parsedPort !== null) {
+    process.env.SERVER_PORT = String(parsedPort);
+  }
+};
+var getParsedBundles = () => parsedBundles;
+var getParsedPort = () => parsedPort;
+
+export {
+  parseServerArgv,
+  applyServerArgv,
+  getParsedBundles,
+  getParsedPort
+};
+//# sourceMappingURL=chunk-X3OSC5W3.js.map

package/dist/chunk-X3OSC5W3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/argv.ts"],"sourcesContent":["//? Positional argv parser for the LuckyStack server boot. Replaces\n//? `LUCKYSTACK_BUNDLE` + `SERVER_PORT` env-var reads with a single shape:\n//?\n//?   npm run server -- billing,vehicles 4001\n//?\n//? Arg 0 = comma-separated preset list (runtime maps merged across them).\n//? Arg 1 = listen port (numeric).\n//?\n//? `applyServerArgv()` is called by the side-effect module\n//? `@luckystack/server/parseArgv`, which consumers import as the FIRST line\n//? of their `server.ts` so the parsed port lands in `process.env.SERVER_PORT`\n//? before `config.ts` (top-level `backendUrl` const) is evaluated.\n\nexport interface ParsedServerArgv {\n  bundles: string[];\n  port: number | null;\n}\n\nlet parsedBundles: string[] = [];\nlet parsedPort: number | null = null;\nlet hasRun = false;\n\nconst PORT_PATTERN = /^\\d+$/;\n\nexport const parseServerArgv = (argv: string[]): ParsedServerArgv => {\n  if (argv.length > 2) {\n    throw new Error(\n      `[luckystack:argv] unexpected positional argument(s): \"${argv.slice(2).join(' ')}\". ` +\n      `Usage: npm run server -- <bundle[,bundle...]> [port]`,\n    );\n  }\n\n  const bundles = argv[0] && argv[0].length > 0\n    ? [...new Set(argv[0].split(',').map((s) => s.trim()).filter(Boolean))]\n    : [];\n\n  let port: number | null = null;\n  const portArg = argv[1];\n  if (portArg !== undefined) {\n    if (!PORT_PATTERN.test(portArg)) {\n      throw new Error(\n        `[luckystack:argv] port argument must be numeric, got: \"${portArg}\". ` +\n        `Usage: npm run server -- <bundle[,bundle...]> [port]`,\n      );\n    }\n    port = Number.parseInt(portArg, 10);\n  }\n\n  return { bundles, port };\n};\n\nexport const applyServerArgv = (): void => {\n  if (hasRun) return;\n  hasRun = true;\n\n  const result = parseServerArgv(process.argv.slice(2));\n  parsedBundles = result.bundles;\n  parsedPort = result.port;\n\n  //? Writeback so the downstream env-readers (`core/env.ts` Zod schema,\n  //? `core/bindAddress.ts` fallback, consumer `config.ts` backendUrl,\n  //? `oauthProviders.ts` callback URL) see the resolved port without us\n  //? having to refactor those four call sites. This is a deliberate\n  //? implementation detail — argv is the public source of truth.\n  if (parsedPort !== null) {\n    process.env.SERVER_PORT = String(parsedPort);\n  }\n};\n\nexport const getParsedBundles = (): string[] => parsedBundles;\nexport const getParsedPort = (): number | null => parsedPort;\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

@@ -134,6 +134,21 @@ interface CreateLuckyStackServerOptions {
      */
     runtimeMapsPreset?: string | string[];
 }
+interface StopLuckyStackServerOptions {
+    /**
+     * Why the server is stopping — threaded into the `preServerStop` hook payload.
+     * Defaults to `'manual'` for a programmatic `stop()`; the signal handlers pass
+     * the received signal name.
+     */
+    reason?: 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'manual';
+    /**
+     * Soft budget (ms) for the whole shutdown sequence — the `preServerStop` hook
+     * fan-out, the bounded `flushErrorTrackers()` race, and closing the
+     * http/io/redis-adapter handles. Each step is wrapped so a single hanging step
+     * cannot stall the others past this deadline. Defaults to `10000`.
+     */
+    timeoutMs?: number;
+}
 interface RunningLuckyStackServer {
     httpServer: Server;
     ioServer: Server$1;
@@ -142,46 +157,20 @@ interface RunningLuckyStackServer {
      * URL on success.
      */
     listen: (callback?: () => void) => Promise<Server>;
+    /**
+     * Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the
+     * core `preServerStop` hook, flushes error-trackers (bounded by a timeout
+     * race), and closes the Socket.io server, the HTTP server, and the
+     * Redis-adapter pub/sub clients. Every step is isolated + time-bounded so one
+     * failing/hanging step cannot hang the whole shutdown. Idempotent — a second
+     * call returns the in-flight shutdown promise. Resolves once shutdown
+     * completes (or the timeout forces it to finish).
+     */
+    stop: (options?: StopLuckyStackServerOptions) => Promise<void>;
+    /** Alias of {@link stop} matching the `net.Server`-style `close({ timeoutMs })` API. */
+    close: (options?: StopLuckyStackServerOptions) => Promise<void>;
 }
 
-/**
- * One-call server bootstrap for a LuckyStack project.
- *
- * Wires together:
- * - HTTP server with framework routes (`/api/*`, `/sync/*`, `/_health`,
- *   `/_test/reset`, `/uploads/*`, `/auth/api`, `/auth/callback`)
- * - Socket.io server with the Redis adapter, room handlers, presence
- *   integration, location sync
- * - Boot-UUID write so the router's handshake can verify topology
- * - Optional dev-mode tooling (devkit hot reload + REPL)
- *
- * Project responsibilities (passed in as options):
- * - `serveFile` / `serveFavicon` — your project's static file handlers
- * - `customRoutes` — any additional HTTP routes your app needs
- *
- * Pre-conditions:
- * - `registerProjectConfig(...)` must have run (side-effect import of your
- *   `config.ts` does this).
- * - `registerDeployConfig(...)` must have run (side-effect import of your
- *   `deploy.config.ts`).
- * - `registerRuntimeMapsProvider(...)` must have run (side-effect import of
- *   your `server/prod/runtimeMaps.ts`).
- * - `registerLocalizedNormalizer(...)` must have run (side-effect import of
- *   your `server/utils/responseNormalizer.ts`).
- *
- * @example
- * ```ts
- * import './config';
- * import './deploy.config';
- * import './prod/runtimeMaps';
- * import './utils/responseNormalizer';
- * import { createLuckyStackServer } from '@luckystack/server';
- * import { serveFile, serveFavicon } from './prod/serveFile';
- *
- * const server = await createLuckyStackServer({ serveFile, serveFavicon });
- * await server.listen();
- * ```
- */
 declare const createLuckyStackServer: (options?: CreateLuckyStackServerOptions) => Promise<RunningLuckyStackServer>;
 
 interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
@@ -218,13 +207,27 @@ interface BootstrapRequirements {
 }
 declare const verifyBootstrap: (requirements?: BootstrapRequirements) => Promise<void>;
 
+type RuntimeMapRecord = Record<string, unknown>;
+/**
+ * The shape that the generated maps module must export. `scripts/generateServerRequests.ts`
+ * emits exactly this shape: `{ apis, syncs, functions }` where each value is a
+ * `Record<string, Handler>`. Consumers can import this type to validate their
+ * generated file in CI or type-check the `loadGenerated` callback return.
+ */
+interface GeneratedRuntimeMapsModule {
+    apis: RuntimeMapRecord;
+    syncs: RuntimeMapRecord;
+    functions: RuntimeMapRecord;
+}
 interface ProdRuntimeMapsLoaderOptions {
     /**
      * Dynamic-import callback for the generated maps module of a given preset.
      * Called once per preset per process lifetime; the result is cached.
      *
      * The resolved module must have shape `{ apis, syncs, functions }` (the
-     * shape `scripts/generateServerRequests.ts` emits).
+     * shape `scripts/generateServerRequests.ts` emits — see
+     * {@link GeneratedRuntimeMapsModule}). A mis-shaped module logs a warning
+     * and results in every route for that preset returning `notFound`.
      *
      * Pass a function that calls `import()` with a path relative to YOUR
      * server-side module — the framework cannot resolve a relative path on
@@ -289,4 +292,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 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, 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, 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 };