@luckystack/server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@luckystack/server` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial public release as part of the LuckyStack package split.

package/CLAUDE.md

@@ -0,0 +1,83 @@
+# @luckystack/server
+
+> AI summary + function INDEX. For deep specs see `docs/` next to this file.
+
+## What this package does
+
+One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js HTTP server, Socket.io (with optional Redis adapter), framework routes (`/api/*`, `/sync/*`, `/_health`, `/livez`, `/readyz`, `/_test/reset`, `/auth/*`, `/uploads/*`, `/csrf-token`), CSRF middleware, CORS + security headers, presence broadcasting, and dev-only hot reload. Consumer's `server.ts` shrinks to roughly twenty lines. Boots are gated by `verifyBootstrap` so missing registrations surface a single readable error instead of mid-request crashes.
+
+## When to USE this package
+
+- Project needs the full LuckyStack runtime (HTTP + sockets + framework routes wired in one call).
+- Multi-bundle or multi-service deploys that need positional argv parsing (`npm run server -- <bundles> <port>`) and merged runtime maps across presets.
+- Consumers that want framework-shipped health / liveness / readiness probes, CSRF protection, and dev hot reload without building plumbing themselves.
+- Adding project-specific HTTP endpoints via `registerCustomRoute(...)` or the `customRoutes` option without forking the package.
+- Plugins / framework packages that ship socket-lifecycle behavior via the exported hook payload types (e.g. `@luckystack/presence`).
+
+## When to NOT suggest this (yet)
+
+- Standalone microservices that do not use the LuckyStack registries (project config, deploy config, runtime maps, localized normalizer) — there is nothing for `verifyBootstrap` to verify, and the wiring overhead buys nothing.
+- A pure router / load-balancer process — use `@luckystack/router` instead; `@luckystack/server` is for the actual service nodes behind the router.
+- Build-time tooling, code generation, or migration scripts that never accept HTTP / socket traffic.
+- Replacing the HTTP layer with Express / Fastify — the package owns the raw Node HTTP server and dispatch table; bringing a second framework on top breaks the route handler contract.
+
+## Function Index
+
+| Function / Export | One-liner | Deep doc |
+|---|---|---|
+| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen }`. Wires HTTP + Socket.io + framework routes. | -> docs/create-server.md |
+| `bootstrapLuckyStack(options)` | High-level entry: auto-imports `luckystack/<pkg>/*.ts` overlay in topological order, then delegates to `createLuckyStackServer`. | -> docs/create-server.md |
+| `verifyBootstrap(requirements?)` | Pre-flight check for ProjectConfig / DeployConfig / ServicesConfig / OAuth / RuntimeMapsProvider / LocalizedNormalizer. Throws one descriptive `Error`. | -> docs/create-server.md |
+| `parseServerArgv(argv)` | Pure parser: validates positional `<bundles> [port]` and returns `{ bundles, port }`. Throws on malformed input. | -> docs/argv-parsing.md |
+| `applyServerArgv()` | Side-effect runner: parses `process.argv.slice(2)`, stores bundles + port, writes `process.env.SERVER_PORT` for downstream env readers. Idempotent. | -> docs/argv-parsing.md |
+| `getParsedBundles()` | Returns the preset list parsed by `applyServerArgv()` (empty array before first call). | -> docs/argv-parsing.md |
+| `getParsedPort()` | Returns the port parsed by `applyServerArgv()` (`null` if argv omitted it). | -> docs/argv-parsing.md |
+| `@luckystack/server/parseArgv` (side-effect import) | First-line import that runs `applyServerArgv()` before any module reads `process.env.SERVER_PORT` (notably `config.ts`). | -> docs/argv-parsing.md |
+| `createProdRuntimeMapsProvider(options)` | Build a `RuntimeMapsProvider` that loads generated maps in prod and delegates to devkit discovery in dev. Returns the provider without registering. | -> docs/runtime-maps.md |
+| `registerProdRuntimeMapsProvider(options)` | Convenience wrapper: builds the provider AND calls `registerRuntimeMapsProvider`. Most consumers want this. | -> docs/runtime-maps.md |
+| `registerCustomRoute(handler, options?)` | Append a custom HTTP route handler. `options.phase`: `'post-params'` (default, runs after body parse) or `'pre-params'` (runs before `getParams`, raw `req` stream intact — webhooks + streaming uploads). | -> /docs/ARCHITECTURE_HTTP.md |
+| `getCustomRoutes()` | Read the `'post-params'` registry snapshot (the default phase). | -> /docs/ARCHITECTURE_HTTP.md |
+| `getPreParamsCustomRoutes()` | Read the `'pre-params'` registry snapshot. | -> /docs/ARCHITECTURE_HTTP.md |
+| `clearCustomRoutes()` | Clear both phases (used by test resets). | -> /docs/ARCHITECTURE_HTTP.md |
+| `registerOriginExemptPath({ pathPrefix })` | Exempt a path prefix from the browser origin gate so a server-to-server webhook (no `Origin`/`Referer`) reaches its handler. Empty/fail-closed by default. **Exemption ≠ auth** — the handler MUST verify a signature/secret. | -> /docs/ARCHITECTURE_HTTP.md |
+| `getOriginExemptPaths()` / `clearOriginExemptPaths()` / `isOriginExemptPath(routePath)` | Read / clear / test the exempt-path registry. | -> /docs/ARCHITECTURE_HTTP.md |
+| `registerSecurityHeaders(builder)` | Override / extend the security-headers builder applied to every HTTP response. | -> docs/security-defaults.md |
+| `getSecurityHeadersBuilder()` | Read the currently registered builder (defaults to framework headers when no override set). | -> docs/security-defaults.md |
+| `registerErrorFormatter(formatter)` | Override the JSON error shape returned by framework error responses. | -> docs/security-defaults.md |
+| `getErrorFormatter()` | Read the currently registered formatter. | -> docs/security-defaults.md |
+| Route handler: `handleLivezRoute` | Liveness probe at `projectConfig.http.liveEndpoint`. Always 200 when reachable. | -> docs/http-routes.md |
+| Route handler: `handleReadyzRoute` | Readiness probe: checks boot UUID + Redis ping + Prisma ping. 503 until all three pass. | -> docs/http-routes.md |
+| Route handler: `handleHealthRoute` | Health endpoint: returns boot UUID + env hashes for router topology checks. | -> docs/http-routes.md |
+| Route handler: `handleTestResetRoute` | Destructive test reset. Fail-closed on `NODE_ENV` and `TEST_RESET_TOKEN`. | -> docs/security-defaults.md |
+| Hook payload: `OnSocketConnectPayload` | Payload type for `onSocketConnect` lifecycle hook handlers. | -> docs/create-server.md |
+| Hook payload: `OnSocketDisconnectPayload` | Payload type for `onSocketDisconnect` lifecycle hook handlers. | -> docs/create-server.md |
+| Hook payload: `PreRoomJoinPayload` | Payload type for `preRoomJoin` hook handlers. | -> docs/create-server.md |
+| Hook payload: `PostRoomJoinPayload` | Payload type for `postRoomJoin` hook handlers. | -> docs/create-server.md |
+| 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`, `RouteContext`, `StaticFileHandler`, `FaviconHandler`, `CustomRouteHandler`, `ProdRuntimeMapsLoaderOptions`, `ParsedServerArgv`, `SecurityHeadersBuilder`, `ErrorFormatter`, `ErrorFormatterContext` | Handler + option typing. | -> docs/create-server.md |
+
+## Config keys (env vars + registerProjectConfig slots)
+
+- `SERVER_PORT` (env, optional) — fallback when neither `options.port` nor positional argv supplies one. Written back by `applyServerArgv()` when argv carries a port.
+- `SERVER_IP` (env, optional, default `127.0.0.1`) — bind address fallback when `options.ip` is omitted.
+- `NODE_ENV` (env, required for security-sensitive branches) — `development` / `test` toggle devkit hot reload + REPL and gate `/_test/reset`.
+- `TEST_RESET_TOKEN` (env, required for `/_test/reset` to be reachable at all) — must match the `x-test-reset-token` request header. No fallback "no auth" mode.
+- `projectConfig.http.healthEndpoint` (config) — path served by `handleHealthRoute`. Default `/_health`.
+- `projectConfig.http.liveEndpoint` (config) — path served by `handleLivezRoute`. Default `/livez`.
+- `projectConfig.http.readyEndpoint` (config) — path served by `handleReadyzRoute`. Default `/readyz`.
+- `projectConfig.http.testResetEndpoint` (config) — path served by `handleTestResetRoute`. Default `/_test/reset`.
+- `projectConfig.logging.socketStartup` / `projectConfig.logging.devLogs` (config) — gate the boot log line emitted by `listen()`.
+- Positional argv `<bundles> [port]` — preset list (merged in `createProdRuntimeMapsProvider`) and listen port.
+
+## Peer dependencies
+
+- **Required (runtime deps)**: `@luckystack/api`, `@luckystack/core`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`.
+- **Peer (canonical ranges)**: `@prisma/client@^6.19.0` (transitive via core), `socket.io@^4.8.0`.
+- **Optional**: `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/docs-ui` (auto-detected by `bootstrapLuckyStack`; not required), `@luckystack/devkit` (dev-only, dynamically imported by `enableDevTools` branch).
+
+## Related
+
+- Architecture deep-dives: `/docs/ARCHITECTURE_API.md`, `/docs/ARCHITECTURE_SOCKET.md`, `/docs/ARCHITECTURE_PACKAGING.md`, `/docs/HOSTING.md`.
+- README (consumer quickstart): `./README.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +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).

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+import { IncomingMessage, ServerResponse, Server } from 'node:http';
+import { Server as Server$1 } from 'socket.io';
+import { RuntimeMapsProvider } from '@luckystack/core';
+export { ErrorFormatter, ErrorFormatterContext, getErrorFormatter, registerErrorFormatter } from '@luckystack/core';
+
+/**
+ * Module augmentation: extends `@luckystack/core`'s `HookPayloads` interface
+ * with socket lifecycle hooks owned by this package. Side-effect imported
+ * by `index.ts` so consumers get the augmentation automatically.
+ *
+ * Hook semantics:
+ *   - `on*` hooks are notifications. Handlers may side-effect; return values
+ *     are ignored.
+ *   - `pre*` hooks may return a `HookStopSignal` to abort the main flow. The
+ *     stop signal carries an `errorCode` that's emitted back to the client.
+ *   - `post*` hooks fire after the side-effect succeeds.
+ */
+interface OnSocketConnectPayload {
+    socketId: string;
+    token: string | null;
+    ip: string;
+}
+interface OnSocketDisconnectPayload {
+    socketId: string;
+    token: string | null;
+    reason: string;
+}
+interface PreRoomJoinPayload {
+    token: string;
+    room: string;
+}
+interface PostRoomJoinPayload {
+    token: string;
+    room: string;
+    allRooms: string[];
+}
+interface PreRoomLeavePayload {
+    token: string;
+    room: string;
+}
+interface PostRoomLeavePayload {
+    token: string;
+    room: string;
+    allRooms: string[];
+}
+interface OnLocationUpdatePayload {
+    token: string;
+    oldLocation: {
+        pathName: string;
+        searchParams?: Record<string, string>;
+    } | undefined;
+    newLocation: {
+        pathName: string;
+        searchParams?: Record<string, string>;
+    };
+}
+declare module '@luckystack/core' {
+    interface HookPayloads {
+        onSocketConnect: OnSocketConnectPayload;
+        onSocketDisconnect: OnSocketDisconnectPayload;
+        preRoomJoin: PreRoomJoinPayload;
+        postRoomJoin: PostRoomJoinPayload;
+        preRoomLeave: PreRoomLeavePayload;
+        postRoomLeave: PostRoomLeavePayload;
+        onLocationUpdate: OnLocationUpdatePayload;
+    }
+}
+
+interface RouteContext {
+    routePath: string;
+    method: string;
+    queryString: string | undefined;
+    token: string | null;
+}
+type StaticFileHandler = (req: IncomingMessage, res: ServerResponse) => unknown;
+type FaviconHandler = (res: ServerResponse) => unknown;
+type CustomRouteHandler = (req: IncomingMessage, res: ServerResponse, ctx: RouteContext) => Promise<boolean> | boolean;
+type CustomRoutePhase = 'pre-params' | 'post-params';
+interface CreateLuckyStackServerOptions {
+    /**
+     * Port the HTTP server listens on. Resolution order:
+     *   1. This option (`options.port`)
+     *   2. Second positional argv (`npm run server -- <bundles> <port>`), parsed
+     *      by `@luckystack/server/parseArgv`
+     *   3. `process.env.SERVER_PORT` (back-compat for boots that skip `parseArgv`)
+     *   4. `80`
+     */
+    port?: number | string;
+    /** Bind address. Defaults to process.env.SERVER_IP or '127.0.0.1'. */
+    ip?: string;
+    /** Project-side static file handler (Vite output, etc.). Used as the catch-all. */
+    serveFile?: StaticFileHandler;
+    /** Project-side favicon handler. */
+    serveFavicon?: FaviconHandler;
+    /**
+     * Optional pre-fallback hook for project-specific HTTP routes. Return `true`
+     * if the route was handled (response ended). Return `false` (or omit return)
+     * to fall through to the framework's static file serving.
+     */
+    customRoutes?: CustomRouteHandler;
+    /**
+     * Enable dev-mode tooling (devkit hot reload, REPL, console init).
+     * Defaults to `process.env.NODE_ENV !== 'production'`.
+     */
+    enableDevTools?: boolean;
+    /**
+     * Maximum HTTP buffer size for socket.io. Defaults to 5 MB. Adjust if you
+     * stream large payloads through sockets.
+     */
+    maxHttpBufferSize?: number;
+    /** Fail boot if no DeployConfig has been registered. Default: false. */
+    requireDeployConfig?: boolean;
+    /** Fail boot if no ServicesConfig has been registered. Default: false. */
+    requireServicesConfig?: boolean;
+    /** Fail boot if no OAuth providers have been registered. Default: false. */
+    requireOAuthProviders?: boolean;
+    /**
+     * Dynamic-import callback for production runtime maps. When provided, the
+     * framework registers its built-in `RuntimeMapsProvider` and the consumer
+     * no longer needs a hand-rolled `server/prod/runtimeMaps.ts`. Pass a
+     * function that calls `import()` with a path relative to the consumer's
+     * server module — the framework cannot resolve that path on the
+     * consumer's behalf because dynamic-import resolution is module-scoped.
+     *
+     * @example
+     * loadGeneratedMaps: (preset) => import(`./prod/generatedApis.${preset}`)
+     */
+    loadGeneratedMaps?: (preset: string) => Promise<unknown>;
+    /**
+     * Override the preset(s) to load (skips argv lookup). Pass a single preset
+     * name or an array for multi-preset boots. Default: the first positional
+     * argv arg parsed by `@luckystack/server/parseArgv`, falling back to
+     * `'default'`.
+     */
+    runtimeMapsPreset?: string | string[];
+}
+interface RunningLuckyStackServer {
+    httpServer: Server;
+    ioServer: Server$1;
+    /**
+     * Start listening. Resolves when the HTTP server is ready. Logs the bound
+     * URL on success.
+     */
+    listen: (callback?: () => void) => Promise<Server>;
+}
+
+/**
+ * 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 {
+    /**
+     * Folder name (relative to project root) that contains the overlay files.
+     * Default: `luckystack`. Each subfolder mirrors a framework package and
+     * holds the project's overrides for that package.
+     */
+    overlayRoot?: string;
+    /**
+     * Skip auto-loading the overlay folder. Useful for tests that build the
+     * registries by hand.
+     */
+    skipOverlayLoad?: boolean;
+}
+declare const bootstrapLuckyStack: (options?: BootstrapLuckyStackOptions) => Promise<RunningLuckyStackServer>;
+
+interface BootstrapRequirements {
+    /**
+     * If true, require a deploy config to have been registered. Defaults to
+     * false because single-instance deployments don't need one.
+     */
+    requireDeployConfig?: boolean;
+    /**
+     * If true, require a services config to have been registered. Defaults to
+     * false; only needed when running the router.
+     */
+    requireServicesConfig?: boolean;
+    /**
+     * If true, require an OAuth provider list to have been registered.
+     * Defaults to false (an app may use credentials only).
+     */
+    requireOAuthProviders?: boolean;
+}
+declare const verifyBootstrap: (requirements?: BootstrapRequirements) => Promise<void>;
+
+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).
+     *
+     * Pass a function that calls `import()` with a path relative to YOUR
+     * server-side module — the framework cannot resolve a relative path on
+     * your behalf because dynamic-import resolution is module-scoped.
+     *
+     * @example
+     * loadGenerated: (preset) => import(`./prod/generatedApis.${preset}`)
+     */
+    loadGenerated: (preset: string) => Promise<unknown>;
+    /**
+     * Override the preset(s) to load. Skips the argv lookup. Accepts a single
+     * preset name or an array. Useful in tests or when the preset list comes
+     * from a non-argv source.
+     */
+    preset?: string | string[];
+}
+declare const createProdRuntimeMapsProvider: (options: ProdRuntimeMapsLoaderOptions) => RuntimeMapsProvider;
+/**
+ * Convenience wrapper around `createProdRuntimeMapsProvider` +
+ * `registerRuntimeMapsProvider`. Most consumers want this — pass the
+ * loader callback once and the runtime is wired.
+ */
+declare const registerProdRuntimeMapsProvider: (options: ProdRuntimeMapsLoaderOptions) => RuntimeMapsProvider;
+
+interface ParsedServerArgv {
+    bundles: string[];
+    port: number | null;
+}
+declare const parseServerArgv: (argv: string[]) => ParsedServerArgv;
+declare const applyServerArgv: () => void;
+declare const getParsedBundles: () => string[];
+declare const getParsedPort: () => number | null;
+
+interface RegisterCustomRouteOptions {
+    /** Pipeline phase the handler runs in. Defaults to `'post-params'`. */
+    phase?: CustomRoutePhase;
+}
+declare const registerCustomRoute: (handler: CustomRouteHandler, options?: RegisterCustomRouteOptions) => void;
+declare const getCustomRoutes: () => readonly CustomRouteHandler[];
+declare const getPreParamsCustomRoutes: () => readonly CustomRouteHandler[];
+declare const clearCustomRoutes: () => void;
+
+interface OriginExemptMatcher {
+    /** A route is exempt when its path starts with this prefix. */
+    pathPrefix: string;
+}
+declare const registerOriginExemptPath: (matcher: OriginExemptMatcher) => void;
+declare const getOriginExemptPaths: () => readonly OriginExemptMatcher[];
+declare const clearOriginExemptPaths: () => void;
+declare const isOriginExemptPath: (routePath: string) => boolean;
+
+type SecurityHeadersBuilder = (req: IncomingMessage) => Record<string, string> | null | undefined;
+/**
+ * Register a custom security-headers builder. Called for every HTTP
+ * request; return a plain object that gets merged on top of the framework
+ * defaults. Use for Content-Security-Policy, HSTS, Permissions-Policy.
+ *
+ * Last-write-wins: subsequent calls replace the previous builder. Pass
+ * `null` to unregister.
+ */
+declare const registerSecurityHeaders: (builder: SecurityHeadersBuilder | null) => void;
+/** 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 };