@luckystack/server 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `collectOverlayEntries(packageDir)` — the single owner of what a `luckystack/<pkg>/` folder contributes at boot, exported so `scripts/bundleServer.mjs` decides identically instead of reimplementing the walk (ADR 0047).
+
+### Fixed
+
+- Test files in a `luckystack/<pkg>/` overlay folder are no longer imported at boot or bundled into the production server. A test file that only performs side effects (registering a stub adapter, say) previously ran in production without failing loudly. Covers `.tests.` / `.test.` / `.spec.` plus `__tests__` / `__mocks__` folders.
+- A subdirectory inside an overlay package folder is now reported instead of skipped in silence. The walk is flat by design, so overlay code parked one level down never ran and nothing pointed at it.
+
+- Composed presets accept a repeated NESTED function namespace. Equivalence is now checked recursively, so a namespace object rebuilt per preset (any function module living in a subdirectory of a `serverFunctionDirs` root) no longer reads as a differing implementation and rejects the compose at boot. A genuinely differing leaf implementation still fails closed.
+
+## [0.8.4] - 2026-08-17
+
+### Changed
+
+- Port resolution is now `options.port > positional argv registry override >
+  options.defaultPort > 80`. The legacy `SERVER_PORT` environment fallback and
+  argv-to-environment writeback are removed. Migrate by editing
+  `config.ports.ts`, passing `port` / `defaultPort`, or supplying the second
+  positional argv.
+- `@luckystack/server/parseArgv` now registers its port through the browser-safe
+  `@luckystack/core/config` registry, keeping consumer OAuth config and server
+  listen resolution aligned without environment mutation.
+
+### Fixed
+
+- Declare `@luckystack/cron` as an optional peer so the auto-detected cron overlay is represented in the server package contract.
+- Programmatic `options.port` can now rewrite an OAuth callback that still names
+  `options.defaultPort`, while explicit local router/reverse-proxy ingress ports
+  remain authoritative.
+
 ## [0.8.2] - 2026-07-27
 
 ### Fixed

package/CLAUDE.md

@@ -4,7 +4,7 @@
 
 ## 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. If devkit initialization fails, API/sync dispatch and `/readyz` all fail closed with 503.
+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/*`, including `GET /auth/csrf`), 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. If devkit initialization fails, API/sync dispatch and `/readyz` all fail closed with 503.
 
 ## When to USE this package
 
@@ -29,13 +29,14 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 | `RunningLuckyStackServer.stop(options?)` / `.close(options?)` | Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the core `preServerStop` hook, flushes error-trackers (bounded by a per-step timeout race), then closes io + http + the Redis-adapter pub/sub clients. Each step isolated + time-bounded so one hanging step can't stall shutdown. Idempotent. `options`: `{ reason?, timeoutMs? }` (default `timeoutMs` 10000). | -> docs/create-server.md |
 | `bootstrapLuckyStack(options)` | High-level entry: auto-imports `luckystack/<pkg>/*.ts` overlay in topological order, then delegates to `createLuckyStackServer`. An overlay file that fails to import (classic: it imports a package removed via `luckystack remove`) aborts boot with an ACTIONABLE error naming the file, instead of a raw ERR_MODULE_NOT_FOUND. | -> docs/create-server.md |
 | `OVERLAY_ORDER` (exported const) | The canonical overlay walk order (`core, deploy, login, email, sentry, presence, cron, docs-ui, server`). Exported so the consumer's `scripts/bundleServer.mjs` imports it at build time — a hardcoded bundler copy once silently dropped the cron slot from prod; `overlayOrderParity.test.ts` pins the bundlers' fallback lists to this. | -> docs/create-server.md |
+| `collectOverlayEntries(packageDir)` | Single owner of what one `luckystack/<pkg>/` folder contributes: `{ fileNames, ignoredDirectoryNames }`. `index.*` first, then the rest alphabetically; `.ts`/`.js` only; **test files excluded** (`.tests.`/`.test.`/`.spec.`, plus `__tests__`/`__mocks__` folders) so they never boot or reach the production bundle. The walk is FLAT — any other subdirectory comes back in `ignoredDirectoryNames` and the loader warns, instead of dropping overlay code in silence. Exported so `scripts/bundleServer.mjs` decides identically. ADR 0047. | -> docs/create-server.md |
 | `registerOverlayLoader(loader)` | Production-bundle seam: the server bundler (`scripts/bundleServer.mjs`) generates an entry that statically imports the overlay files and registers this loader; `bootstrapLuckyStack` then runs it INSTEAD of the runtime `.ts` folder walk (plain `node` cannot import `.ts` — ERR_UNKNOWN_FILE_EXTENSION). | -> 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 |
+| `applyServerArgv()` | Side-effect runner: parses `process.argv.slice(2)`, stores bundles, and registers the port through browser-safe `@luckystack/core/config`. 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 |
+| `@luckystack/server/parseArgv` (side-effect import) | First-line import that runs `applyServerArgv()` before consumer `config.ts` reads the typed override registry. | -> docs/argv-parsing.md |
 | `createProdRuntimeMapsProvider(options)` | Build a `RuntimeMapsProvider` that loads generated maps in prod and delegates to devkit discovery in dev. Composed presets reject duplicate API/sync ownership, deduplicate equivalent full-registry function entries, and reject differing function implementations. 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 |
@@ -63,7 +64,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 
 ## Config keys (env vars + registerProjectConfig slots)
 
-- Port precedence — `options.port` → positional argv → `options.defaultPort` (the scaffold passes `config.ports.backend`) → legacy `SERVER_PORT` → `80`. Inputs must be integer ports in `0..65535`. After bind, `httpServer.address().port` is authoritative (including `listen(0)`). In dev, that port is advertised to `node_modules/.luckystack/dev-server.json`; cleanup removes it only when the exiting PID still owns it. The Vite proxy follows the advertisement for HTTP + WebSocket requests.
+- Port precedence — `options.port` → positional argv registry override → `options.defaultPort` (the scaffold passes `config.ports.backend`) → `80`. Inputs must be integer ports in `0..65535`. After bind, `httpServer.address().port` is authoritative (including `listen(0)`). In dev, that port is advertised to `node_modules/.luckystack/dev-server.json`; cleanup removes it only when the exiting PID still owns it. The Vite proxy follows the advertisement for HTTP + WebSocket requests.
 - `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.
@@ -77,8 +78,8 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 ## Peer dependencies
 
 - **Required (runtime deps)**: `@luckystack/api`, `@luckystack/core`.
-- **Peer (canonical ranges)**: `@prisma/client@^6.19.0` (transitive via core), `socket.io@^4.8.0`.
-- **Optional (all auto-detected by `bootstrapLuckyStack`; the server degrades gracefully when absent — `auth.disabled` / `sync.disabled`, presence skipped)**: `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`, `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/cron`, `@luckystack/docs-ui`, `@luckystack/devkit` (dev-only, dynamically imported by the `enableDevTools` branch).
+- **Required peer**: `socket.io@^4.8.0`.
+- **Optional (all auto-detected by `bootstrapLuckyStack`; the server degrades gracefully when absent — `auth.disabled` / `sync.disabled`, presence skipped)**: `@prisma/client@^6.19.0`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`, `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/cron`, `@luckystack/docs-ui`, `@luckystack/devkit` (dev-only, dynamically imported by the `enableDevTools` branch).
   - **0.2.0 install-anything-anytime**: `bootstrapLuckyStack` runs an auto-detect phase BEFORE the consumer overlay that imports each installed optional package's `@luckystack/<pkg>/register` side-effect subpath (`OPTIONAL_PACKAGES` in `capabilities.ts` = `login, email, error-tracking, presence, cron, docs-ui`). So `npm i @luckystack/<pkg>` + env + restart self-wires the BACKEND with zero code edits. Detection uses `import.meta.resolve` (the `@luckystack/*` exports maps are import-only — a CJS `require.resolve` reports them absent). Client-side mounts (presence JSX, login pages) need `npx luckystack add <feature>` (`@luckystack/cli`) because Vite can't statically import an uninstalled package and file-routing only scans `src/`.
 
 ## Related

package/README.md

@@ -5,7 +5,11 @@
 ## Install
 
 ```bash
-npm install @luckystack/server @luckystack/core @luckystack/api @luckystack/login @luckystack/sync @luckystack/presence socket.io
+npm install @luckystack/server socket.io
+
+# Add the features your project uses; the server auto-detects these optional peers.
+# For the standard API + realtime stack, for example:
+npm install @luckystack/api @luckystack/sync
 ```
 
 ## Quickstart — recommended (`bootstrapLuckyStack`)
@@ -31,7 +35,7 @@ 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).
+1. Auto-imports `luckystack/core/*.ts`, `luckystack/deploy/*.ts`, `luckystack/login/*.ts`, `luckystack/email/*.ts`, `luckystack/sentry/*.ts`, `luckystack/presence/*.ts`, `luckystack/cron/*.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`.
@@ -88,7 +92,8 @@ Both entries handle devkit hot reload + console init in dev mode automatically
 
 ```ts
 interface CreateLuckyStackServerOptions {
-  port?: number | string;          // default: process.env.SERVER_PORT ?? 80
+  port?: number | string;          // options.port > argv > defaultPort > 80
+  defaultPort?: number;             // scaffold's config.ports.ts backend default
   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
@@ -117,7 +122,7 @@ registerCustomRoute(async (req, res) => {
 
 - **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`.
+- **Framework routes:** `/_health`, `/livez`, `/readyz`, `/_test/reset` (dev/test only), `/api/*` and `/sync/*` (with SSE streaming), `/auth/api`, `/auth/callback/*`, `GET /auth/csrf`, `/uploads/*`, and `/assets/*`.
 - **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.
@@ -128,7 +133,7 @@ registerCustomRoute(async (req, res) => {
 
 | File | Routes |
 | --- | --- |
-| `csrfMiddleware.ts` + `csrfRoute.ts` | CSRF guard on writes + `GET /csrf-token` |
+| `csrfMiddleware.ts` + `csrfRoute.ts` | CSRF guard on cookie-mode writes + `GET /auth/csrf` token issue |
 | `healthRoutes.ts` | `/livez`, `/readyz`, `/_health` |
 | `testResetRoute.ts` | `/_test/reset` (dev/test only — see Security below) |
 | `faviconRoute.ts` | `/favicon.ico` |
@@ -146,7 +151,7 @@ Top-level `handleHttpRequest` + `dispatchRoutes(handlers, ctx)` are the only orc
 
 - **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`.
+- **CSRF middleware.** In cookie mode, state-changing framework routes and eligible custom routes require the configured CSRF header (default `x-csrf-token`). With login installed it must match the session-bound token; without login it must match the stateless double-submit cookie issued by `GET /auth/csrf`. The `apiRequest` helper in `@luckystack/core/client` fetches and attaches it automatically. Auth bootstrap/callback routes and explicitly origin-exempt paths are excluded. Rejections dispatch `csrfMismatch` before returning 403; the hook receives token presence only, never the value. Configure the header name, token length, and cookie name/options through `registerCsrfConfig(...)` — see `packages/core/docs/csrf-config.md` and `packages/server/docs/security-defaults.md`.
 
 ## Public API
 
@@ -161,15 +166,13 @@ Top-level `handleHttpRequest` + `dispatchRoutes(handlers, ctx)` are the only orc
 
 ## 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.
+- Runtime: `@luckystack/api`, `@luckystack/core`
+- Required peer: `socket.io@^4.8.0`
+- Optional peers: `@prisma/client@^6.19.0`, `@luckystack/login`, `@luckystack/presence`, `@luckystack/sync`, `@luckystack/error-tracking`, `@luckystack/email`, `@luckystack/cron`, `@luckystack/docs-ui`, and `@luckystack/devkit` (dev-only). Bootstrap auto-detects installed optional peers and degrades when they are absent.
 
 ## 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`).
+`@luckystack/server/parseArgv` is a side-effect-only entrypoint. Import it as the **first line** of your `server.ts` so a positional CLI port reaches the browser-safe `@luckystack/core/config` registry before your project's `config.ts` evaluates.
 
 ```ts
 // server.ts
@@ -177,11 +180,13 @@ import '@luckystack/server/parseArgv';
 // ...rest of your bootstrap
 ```
 
-Argv shape: `<bundle[,bundle...]> [port]`
+Argv shape: `<bundle[,bundle...]> [port]`. The positional port overrides the
+scaffold's `defaultPort: ports.backend`. Generic boots with no explicit,
+positional, or default port retain the numeric fallback `80`.
 
 ```bash
-npm run server                              # default preset, port 80
-npm run server -- billing                   # one bundle, port 80
+npm run server                              # default preset, config.ports.ts backend
+npm run server -- billing                   # one bundle, config.ports.ts backend
 npm run server -- billing,vehicles 4001     # merge bundles, listen on 4001
 ```
 

package/dist/{chunk-QLVQ75QL.js → chunk-HJXOI6LY.js}

@@ -1,3 +1,6 @@
+// src/argv.ts
+import { getPortOverride, registerPortOverride } from "@luckystack/core/config";
+
 // src/portResolution.ts
 var normalizeServerPort = (value, source = "server port") => {
   let normalized;
@@ -12,20 +15,17 @@ var normalizeServerPort = (value, source = "server port") => {
 };
 var resolveServerPort = ({
   optionsPort,
-  parsedPort: parsedPort2,
-  defaultPort,
-  envPort
+  parsedPort,
+  defaultPort
 }) => {
   if (optionsPort !== void 0) return normalizeServerPort(optionsPort, "options.port");
-  if (parsedPort2 !== void 0 && parsedPort2 !== null) return normalizeServerPort(parsedPort2, "argv port");
+  if (parsedPort !== void 0 && parsedPort !== null) return normalizeServerPort(parsedPort, "argv port");
   if (defaultPort !== void 0) return normalizeServerPort(defaultPort, "options.defaultPort");
-  if (envPort !== void 0) return normalizeServerPort(envPort, "SERVER_PORT");
   return 80;
 };
 
 // src/argv.ts
 var parsedBundles = [];
-var parsedPort = null;
 var hasRun = false;
 var PORT_PATTERN = /^\d+$/;
 var parseServerArgv = (argv) => {
@@ -52,13 +52,10 @@ var applyServerArgv = () => {
   hasRun = true;
   const result = parseServerArgv(process.argv.slice(2));
   parsedBundles = result.bundles;
-  parsedPort = result.port;
-  if (parsedPort !== null) {
-    process.env.SERVER_PORT = String(parsedPort);
-  }
+  registerPortOverride(result.port);
 };
 var getParsedBundles = () => parsedBundles;
-var getParsedPort = () => parsedPort;
+var getParsedPort = () => getPortOverride() ?? null;
 
 export {
   normalizeServerPort,
@@ -68,4 +65,4 @@ export {
   getParsedBundles,
   getParsedPort
 };
-//# sourceMappingURL=chunk-QLVQ75QL.js.map
+//# sourceMappingURL=chunk-HJXOI6LY.js.map

package/dist/chunk-HJXOI6LY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/argv.ts","../src/portResolution.ts"],"sourcesContent":["//? Positional argv parser for the LuckyStack server boot. Replaces legacy\n//? environment toggles 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 the browser-safe core/config\n//? registry before `config.ts` evaluates its top-level OAuth callback base.\n\nimport { getPortOverride, registerPortOverride } from '@luckystack/core/config';\nimport { normalizeServerPort } from './portResolution';\n\nexport interface ParsedServerArgv {\n  bundles: string[];\n  port: number | null;\n}\n\nlet parsedBundles: string[] = [];\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 = normalizeServerPort(portArg, 'port argument');\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  registerPortOverride(result.port);\n};\n\nexport const getParsedBundles = (): string[] => parsedBundles;\nexport const getParsedPort = (): number | null => getPortOverride() ?? null;\n","export interface ResolveServerPortInput {\n  optionsPort?: number | string;\n  parsedPort?: number | null;\n  defaultPort?: number | string;\n}\n\nexport const normalizeServerPort = (\n  value: number | string,\n  source = 'server port',\n): number => {\n  let normalized: number;\n  if (typeof value === 'number') normalized = value;\n  else normalized = /^\\d+$/.test(value) ? Number(value) : Number.NaN;\n\n  if (!Number.isInteger(normalized) || normalized < 0 || normalized > 65_535) {\n    throw new RangeError(\n      `[luckystack:port] ${source} must be an integer from 0 through 65535, got: \"${String(value)}\".`,\n    );\n  }\n\n  return normalized;\n};\n\n//? One explicit, testable precedence chain. The scaffold passes ports.backend as\n//? `defaultPort`; generic consumers that omit every source retain port 80.\nexport const resolveServerPort = ({\n  optionsPort,\n  parsedPort,\n  defaultPort,\n}: ResolveServerPortInput): number => {\n  if (optionsPort !== undefined) return normalizeServerPort(optionsPort, 'options.port');\n  if (parsedPort !== undefined && parsedPort !== null) return normalizeServerPort(parsedPort, 'argv port');\n  if (defaultPort !== undefined) return normalizeServerPort(defaultPort, 'options.defaultPort');\n  return 80;\n};\n"],"mappings":";AAaA,SAAS,iBAAiB,4BAA4B;;;ACP/C,IAAM,sBAAsB,CACjC,OACA,SAAS,kBACE;AACX,MAAI;AACJ,MAAI,OAAO,UAAU,SAAU,cAAa;AAAA,MACvC,cAAa,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,IAAI,OAAO;AAE/D,MAAI,CAAC,OAAO,UAAU,UAAU,KAAK,aAAa,KAAK,aAAa,OAAQ;AAC1E,UAAM,IAAI;AAAA,MACR,qBAAqB,MAAM,mDAAmD,OAAO,KAAK,CAAC;AAAA,IAC7F;AAAA,EACF;AAEA,SAAO;AACT;AAIO,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,MAAsC;AACpC,MAAI,gBAAgB,OAAW,QAAO,oBAAoB,aAAa,cAAc;AACrF,MAAI,eAAe,UAAa,eAAe,KAAM,QAAO,oBAAoB,YAAY,WAAW;AACvG,MAAI,gBAAgB,OAAW,QAAO,oBAAoB,aAAa,qBAAqB;AAC5F,SAAO;AACT;;;ADbA,IAAI,gBAA0B,CAAC;AAC/B,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,oBAAoB,SAAS,eAAe;AAAA,EACrD;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,uBAAqB,OAAO,IAAI;AAClC;AAEO,IAAM,mBAAmB,MAAgB;AACzC,IAAM,gBAAgB,MAAqB,gBAAgB,KAAK;","names":[]}

package/dist/index.d.ts

@@ -84,16 +84,14 @@ interface CreateLuckyStackServerOptions {
      *      by `@luckystack/server/parseArgv`
      *   3. `options.defaultPort` (the project's single-instance default, e.g. the
      *      `backend` port from `config.ports.ts`)
-     *   4. `process.env.SERVER_PORT` (back-compat for boots that skip `parseArgv`)
-     *   5. `80`
+     *   4. `80` for generic consumers that supplied no port source
      */
     port?: number | string;
     /**
      * Project's single-instance default backend port. Sits BELOW positional argv
-     * so a multi-instance boot (`npm run server -- <preset> <port>`) still wins,
-     * but ABOVE the legacy `SERVER_PORT` env. The scaffold passes the `backend`
-     * value from `config.ports.ts` here, so the listen port has ONE source of
-     * truth without re-introducing `SERVER_PORT` to `.env`.
+     * so a multi-instance boot (`npm run server -- <preset> <port>`) still wins.
+     * The scaffold passes the `backend` value from `config.ports.ts` here, so the
+     * listen port has one static source of truth.
      */
     defaultPort?: number;
     /** Bind address. Defaults to process.env.SERVER_IP or '127.0.0.1'. */
@@ -199,6 +197,23 @@ interface BootstrapLuckyStackOptions extends CreateLuckyStackServerOptions {
 declare const OVERLAY_ORDER: string[];
 type OverlayLoader = () => Promise<void>;
 declare const registerOverlayLoader: (loader: OverlayLoader) => void;
+interface OverlayEntries {
+    /** Files to import, in load order: `index.*` first, then the rest alphabetically. */
+    fileNames: string[];
+    /**
+     * Subdirectories the flat walk skipped, minus conventional test folders.
+     * The caller warns about these — silently dropping them meant overlay code
+     * one level down simply never ran, with nothing to point at.
+     */
+    ignoredDirectoryNames: string[];
+}
+/**
+ * Decide what a single overlay package folder contributes. Exported because
+ * both the runtime walk here and `scripts/bundleServer.mjs` must agree exactly:
+ * a file the bundler includes but the loader skips (or the reverse) is a
+ * dev/prod divergence, which is the defect class ADR 0046 exists for.
+ */
+declare const collectOverlayEntries: (packageDir: string) => OverlayEntries;
 declare const bootstrapLuckyStack: (options?: BootstrapLuckyStackOptions) => Promise<RunningLuckyStackServer>;
 
 interface BootstrapRequirements {
@@ -310,4 +325,4 @@ declare const registerSecurityHeaders: (builder: SecurityHeadersBuilder | null)
 /** Read the active builder (or null). */
 declare const getSecurityHeadersBuilder: () => SecurityHeadersBuilder | null;
 
-export { type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type 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 };
+export { type BootstrapLuckyStackOptions, type BootstrapRequirements, type CreateLuckyStackServerOptions, type CustomRouteHandler, type CustomRoutePhase, type FaviconHandler, type GeneratedRuntimeMapsModule, OVERLAY_ORDER, type OnLocationUpdatePayload, type OnSocketConnectPayload, type OnSocketDisconnectPayload, type OriginExemptMatcher, type OverlayEntries, type ParsedServerArgv, type PostRoomJoinPayload, type PostRoomLeavePayload, type PreRoomJoinPayload, type PreRoomLeavePayload, type ProdRuntimeMapsLoaderOptions, type RegisterCustomRouteOptions, type RouteContext, type RunningLuckyStackServer, type SecurityHeadersBuilder, type StaticFileHandler, type StopLuckyStackServerOptions, applyServerArgv, bootstrapLuckyStack, clearCustomRoutes, clearOriginExemptPaths, collectOverlayEntries, createLuckyStackServer, createProdRuntimeMapsProvider, getCustomRoutes, getOriginExemptPaths, getParsedBundles, getParsedPort, getPreParamsCustomRoutes, getSecurityHeadersBuilder, isOriginExemptPath, parseServerArgv, registerCustomRoute, registerOriginExemptPath, registerOverlayLoader, registerProdRuntimeMapsProvider, registerSecurityHeaders, verifyBootstrap };

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   normalizeServerPort,
   parseServerArgv,
   resolveServerPort
-} from "./chunk-QLVQ75QL.js";
+} from "./chunk-HJXOI6LY.js";
 
 // src/createServer.ts
 import http from "http";
@@ -2156,7 +2156,7 @@ var areEquivalentFunctionEntries = (left, right) => {
   if (!isRuntimeMapRecord(left) || !isRuntimeMapRecord(right)) return false;
   const leftKeys = Object.keys(left);
   const rightKeys = Object.keys(right);
-  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(left[key], right[key]));
+  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && areEquivalentFunctionEntries(left[key], right[key]));
 };
 var mergeInto = (target, source, kind, fromPreset, keyOrigin) => {
   for (const key of Object.keys(source)) {
@@ -2326,7 +2326,7 @@ var writeDevServerInfo = (ip, port) => {
 `);
   } catch (error) {
     getLogger12().debug(
-      `[dev-server-info] could not write port file (proxy will fall back to SERVER_PORT): ${error instanceof Error ? error.message : String(error)}`
+      `[dev-server-info] could not write port file (proxy will fall back to config.ports.ts): ${error instanceof Error ? error.message : String(error)}`
     );
   }
 };
@@ -2411,7 +2411,7 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
         return;
       }
       getLogger13().error(
-        `Port ${String(attemptPort)} is already in use \u2014 the server did NOT start. Another \`npm run server\` is probably still running (stop it), or set SERVER_PORT to a free port, or set SERVER_PORT_AUTO_INCREMENT=1 to auto-pick the next free port.`
+        `Port ${String(attemptPort)} is already in use \u2014 the server did NOT start. Another \`npm run server\` is probably still running (stop it), or choose a free port in config.ports.ts / positional argv, or set SERVER_PORT_AUTO_INCREMENT=1 to auto-pick the next free port.`
       );
       reject(err);
     };
@@ -2462,12 +2462,11 @@ var createLuckyStackServer = async (options = {}) => {
   const port = resolveServerPort({
     optionsPort: options.port,
     parsedPort: getParsedPort(),
-    defaultPort: options.defaultPort,
-    envPort: process.env.SERVER_PORT
+    defaultPort: options.defaultPort
   });
   const ip = options.ip ?? process.env.SERVER_IP ?? "127.0.0.1";
   const enableDevTools = options.enableDevTools ?? resolveRuntimeMode() !== "production";
-  registerBindAddress({ ip, port });
+  registerBindAddress({ ip, port, configuredPort: options.defaultPort });
   if (enableDevTools) {
     await initDevTools();
   }
@@ -2521,7 +2520,7 @@ var createLuckyStackServer = async (options = {}) => {
 import path3 from "path";
 import fs2 from "fs";
 import { pathToFileURL } from "url";
-import { ROOT_DIR, tryCatch as tryCatch11 } from "@luckystack/core";
+import { ROOT_DIR, tryCatch as tryCatch11, getLogger as getLogger14, isTestFile, isTestDirectory } from "@luckystack/core";
 var OVERLAY_ORDER = [
   // Core registries first — clients, paths, routing rules. Anything below
   // depends on these being in place.
@@ -2559,6 +2558,24 @@ var registeredOverlayLoader = null;
 var registerOverlayLoader = (loader) => {
   registeredOverlayLoader = loader;
 };
+var collectOverlayEntries = (packageDir) => {
+  const indexCandidates = ["index.ts", "index.js"];
+  const entries = fs2.readdirSync(packageDir, { withFileTypes: true }).toSorted((left, right) => left.name.localeCompare(right.name));
+  const ignoredDirectoryNames = [];
+  const rest = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!isTestDirectory(entry.name)) ignoredDirectoryNames.push(entry.name);
+      continue;
+    }
+    if (indexCandidates.includes(entry.name)) continue;
+    if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".js")) continue;
+    if (isTestFile(entry.name)) continue;
+    rest.push(entry.name);
+  }
+  const indexFileNames = indexCandidates.filter((candidate) => entries.some((entry) => entry.isFile() && entry.name === candidate));
+  return { fileNames: [...indexFileNames, ...rest], ignoredDirectoryNames };
+};
 var loadOverlayFolder = async (overlayRoot) => {
   const overlayAbs = path3.isAbsolute(overlayRoot) ? overlayRoot : path3.join(ROOT_DIR, overlayRoot);
   if (!fs2.existsSync(overlayAbs)) {
@@ -2567,15 +2584,14 @@ var loadOverlayFolder = async (overlayRoot) => {
   for (const packageName of OVERLAY_ORDER) {
     const packageDir = path3.join(overlayAbs, packageName);
     if (!fs2.existsSync(packageDir)) continue;
-    const indexCandidates = ["index.ts", "index.js"];
-    for (const candidate of indexCandidates) {
-      await importIfExists(path3.join(packageDir, candidate));
+    const { fileNames, ignoredDirectoryNames } = collectOverlayEntries(packageDir);
+    for (const directoryName of ignoredDirectoryNames) {
+      getLogger14().warn(
+        `[luckystack:overlay] ignoring \`${overlayRoot}/${packageName}/${directoryName}/\` \u2014 the overlay walk does not recurse. Move the file(s) up into \`${overlayRoot}/${packageName}/\`, or import them from a file that is there.`
+      );
     }
-    const entries = fs2.readdirSync(packageDir).toSorted();
-    for (const entry of entries) {
-      if (indexCandidates.includes(entry)) continue;
-      if (!entry.endsWith(".ts") && !entry.endsWith(".js")) continue;
-      await importIfExists(path3.join(packageDir, entry));
+    for (const fileName of fileNames) {
+      await importIfExists(path3.join(packageDir, fileName));
     }
   }
 };
@@ -2615,6 +2631,7 @@ export {
   bootstrapLuckyStack,
   clearCustomRoutes,
   clearOriginExemptPaths,
+  collectOverlayEntries,
   createLuckyStackServer,
   createProdRuntimeMapsProvider,
   getCustomRoutes,