@luckystack/server 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 
@@ -32,10 +32,10 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 | `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 +63,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 +77,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'. */

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";
@@ -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();
   }