@luckystack/server 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-07-22
+
+### Fixed
+
+- `/readyz` now includes the recorded dev-tool initialization state. When
+  devkit boot failed and API/sync routes deliberately return 503, readiness is
+  503 too instead of advertising a hollow-green instance.
+- Port resolution is now explicitly validated and regression-tested as
+  `options.port > argv > options.defaultPort > SERVER_PORT > 80`; invalid values
+  fail before `listen`, `65535` never retries to `65536`, and `listen(0)` registers,
+  advertises, and logs the OS-assigned port from `httpServer.address()`.
+- Auto-increment, dev advertisement, and OAuth now use the same canonical
+  `resolveEnvKey()` environment classification (`LUCKYSTACK_ENV` first).
+- Dev port-file cleanup is PID-owned, so an exiting old backend cannot remove a
+  newer backend's advertisement.
+
+## [0.7.3] - 2026-07-20
+
+### Fixed
+
+- **Stale-port bug class after a dev auto-increment hop.** When the dev server
+  auto-incremented off a busy port (`:80` → `:81`), the bind-address registry
+  still held the INTENDED port, so `checkOrigin`'s same-origin CORS entry pointed
+  at a port nothing listened on. `listenLuckyStackServer` now re-registers the
+  ACTUALLY-bound port inside the listen callback, so every `getBindAddress()`
+  reader (CORS foremost) sees reality.
+- **OAuth now targets the actually-bound port after a hop.** The `/auth/api/<provider>`
+  authorize route rewrites a `localhost` OAuth `redirect_uri` to the port the
+  server bound (via core's `resolveDevCallbackUrl`), matching the token-exchange
+  side in `@luckystack/login` — so the OAuth round-trip reaches the live dev
+  server even after an auto-increment hop, instead of a frozen dead port.
+- **Loud OAuth port-drift warning on a hop.** The framework auto-targets the bound
+  port for OAuth, but a provider console still exact-matches its registered
+  redirect URI — so the server now warns (naming both ports) to add the bound port
+  to the provider's authorized redirect URIs, or pin the port with
+  `SERVER_PORT_AUTO_INCREMENT=0`.
+
 ## [0.7.1] - 2026-07-18
 
 ### 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.
+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.
 
 ## When to USE this package
 
@@ -49,7 +49,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 | `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: boot UUID + Redis ping + database check (ADR 0020: a registered `registerDbHealthCheck` probe wins; else the built-in Prisma ping when Prisma is registered/resolvable; else `'skipped'` so a deliberately DB-less project can go ready). Response `checks.database` = tri-state, `checks.prisma` kept for compat. | -> docs/http-routes.md |
+| Route handler: `handleReadyzRoute` | Readiness probe: boot UUID + dev-tool initialization state + Redis ping + database check (ADR 0020: a registered `registerDbHealthCheck` probe wins; else the built-in Prisma ping when Prisma is registered/resolvable; else `'skipped'` so a deliberately DB-less project can go ready). A recorded fatal devkit boot is 503 even when Redis/database are green. Response `checks.database` = tri-state, `checks.prisma` kept for compat. | -> 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 |
@@ -63,7 +63,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 
 ## 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. In dev, the ACTUALLY-bound port (after any `SERVER_PORT_AUTO_INCREMENT` hop off a busy port) is advertised to `node_modules/.luckystack/dev-server.json` so the template Vite proxy follows the real port instead of the stale `.env` one (written by `devServerInfo.ts`; skipped in prod + tests, removed on exit).
+- 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.
 - `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.

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

@@ -1,3 +1,28 @@
+// src/portResolution.ts
+var normalizeServerPort = (value, source = "server port") => {
+  let normalized;
+  if (typeof value === "number") normalized = value;
+  else normalized = /^\d+$/.test(value) ? Number(value) : Number.NaN;
+  if (!Number.isInteger(normalized) || normalized < 0 || normalized > 65535) {
+    throw new RangeError(
+      `[luckystack:port] ${source} must be an integer from 0 through 65535, got: "${String(value)}".`
+    );
+  }
+  return normalized;
+};
+var resolveServerPort = ({
+  optionsPort,
+  parsedPort: parsedPort2,
+  defaultPort,
+  envPort
+}) => {
+  if (optionsPort !== void 0) return normalizeServerPort(optionsPort, "options.port");
+  if (parsedPort2 !== void 0 && parsedPort2 !== null) return normalizeServerPort(parsedPort2, "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;
@@ -18,7 +43,7 @@ var parseServerArgv = (argv) => {
         `[luckystack:argv] port argument must be numeric, got: "${portArg}". Usage: npm run server -- <bundle[,bundle...]> [port]`
       );
     }
-    port = Number.parseInt(portArg, 10);
+    port = normalizeServerPort(portArg, "port argument");
   }
   return { bundles, port };
 };
@@ -36,9 +61,11 @@ var getParsedBundles = () => parsedBundles;
 var getParsedPort = () => parsedPort;
 
 export {
+  normalizeServerPort,
+  resolveServerPort,
   parseServerArgv,
   applyServerArgv,
   getParsedBundles,
   getParsedPort
 };
-//# sourceMappingURL=chunk-X3OSC5W3.js.map
+//# sourceMappingURL=chunk-QLVQ75QL.js.map

package/dist/chunk-QLVQ75QL.js.map

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

package/dist/index.js

@@ -2,12 +2,14 @@ import {
   applyServerArgv,
   getParsedBundles,
   getParsedPort,
-  parseServerArgv
-} from "./chunk-X3OSC5W3.js";
+  normalizeServerPort,
+  parseServerArgv,
+  resolveServerPort
+} from "./chunk-QLVQ75QL.js";
 
 // src/createServer.ts
 import http from "http";
-import { registerBindAddress, writeBootUuid, getLogger as getLogger13, getProjectConfig as getProjectConfig15, tryCatch as tryCatch10, isProduction as isProduction2, resolveEnvKey as resolveEnvKey5, dispatchHook as dispatchHook8 } from "@luckystack/core";
+import { registerBindAddress, registerBoundAddress, writeBootUuid, getLogger as getLogger13, getProjectConfig as getProjectConfig15, tryCatch as tryCatch10, tryCatchSync as tryCatchSync2, resolveEnvKey as resolveEnvKey5, dispatchHook as dispatchHook8 } from "@luckystack/core";
 
 // src/httpHandler.ts
 import { randomUUID } from "crypto";
@@ -299,6 +301,15 @@ import {
   resolveEnvKey,
   tryCatch
 } from "@luckystack/core";
+
+// src/devToolsStatus.ts
+var devToolsInitError = null;
+var markDevToolsInitFailed = (error) => {
+  devToolsInitError = error;
+};
+var getDevToolsInitError = () => devToolsInitError;
+
+// src/httpRoutes/healthRoutes.ts
 var pingPrisma = async () => {
   const client = prisma;
   const queryRaw = client.$queryRaw;
@@ -336,7 +347,8 @@ var handleReadyzRoute = async ({ res, routePath }) => {
   const [redisError, pong] = await tryCatch(() => redis.ping());
   const redisOk = !redisError && (pong === "PONG" || Boolean(pong));
   const databaseResult = await checkDatabaseReady();
-  const ready = Boolean(bootUuid) && redisOk && databaseResult !== false;
+  const devToolsReady = getDevToolsInitError() === null;
+  const ready = Boolean(bootUuid) && redisOk && databaseResult !== false && devToolsReady;
   res.statusCode = ready ? 200 : 503;
   res.setHeader("Content-Type", "application/json");
   res.end(JSON.stringify({
@@ -348,7 +360,8 @@ var handleReadyzRoute = async ({ res, routePath }) => {
       bootUuid: Boolean(bootUuid),
       redis: redisOk,
       database: databaseResult,
-      prisma: databaseResult !== false
+      prisma: databaseResult !== false,
+      devTools: devToolsReady
     }
   }));
   return true;
@@ -457,7 +470,8 @@ import {
   dispatchHook as dispatchHook2,
   getLogger,
   getProjectConfig as getProjectConfig5,
-  resolveClientIp
+  resolveClientIp,
+  resolveDevCallbackUrl
 } from "@luckystack/core";
 
 // src/httpRoutes/sessionCookie.ts
@@ -561,7 +575,11 @@ var handleAuthApiRoute = async ({
     );
     const authParams = new URLSearchParams({
       client_id: provider.clientID,
-      redirect_uri: provider.callbackURL,
+      //? In dev, target the port the server ACTUALLY bound (auto-increment may
+      //? have moved it off the frozen `oauthCallbackBase` port). The token
+      //? exchange applies the SAME rewrite, so the two redirect_uri values stay
+      //? byte-identical as OAuth requires. Prod / non-localhost: unchanged.
+      redirect_uri: resolveDevCallbackUrl(provider.callbackURL),
       scope: provider.scope.join(" "),
       response_type: "code",
       prompt: "select_account"
@@ -963,13 +981,6 @@ var resolveRequesterIp = (req) => {
   return rawRemoteAddress || trustProxy && (req.headers["x-forwarded-for"] || req.headers["x-real-ip"]) ? resolveClientIp3({ rawAddress: rawRemoteAddress, headers: req.headers, trustProxy, trustedProxyHopCount }) : void 0;
 };
 
-// src/devToolsStatus.ts
-var devToolsInitError = null;
-var markDevToolsInitFailed = (error) => {
-  devToolsInitError = error;
-};
-var getDevToolsInitError = () => devToolsInitError;
-
 // src/httpRoutes/apiRoute.ts
 var handleApiRoute = async ({
   req,
@@ -2293,7 +2304,10 @@ var writeDevServerInfo = (ip, port) => {
 };
 var clearDevServerInfo = () => {
   try {
-    fs.rmSync(devServerInfoPath(), { force: true });
+    const file = devServerInfoPath();
+    const info = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (info.pid !== process.pid) return;
+    fs.rmSync(file, { force: true });
   } catch {
   }
 };
@@ -2338,25 +2352,36 @@ var initDevTools = async () => {
   }
 };
 var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((resolve, reject) => {
-  const startPort = typeof port === "string" ? Number.parseInt(port, 10) : port;
+  const startPort = normalizeServerPort(port);
+  const environmentKey = resolveEnvKey5();
+  const production = environmentKey === "production";
+  const test = environmentKey === "test";
   const autoIncrementEnv = (process.env.SERVER_PORT_AUTO_INCREMENT ?? "").toLowerCase();
   let autoIncrement;
   if (["0", "false"].includes(autoIncrementEnv)) autoIncrement = false;
   else if (["1", "true"].includes(autoIncrementEnv)) autoIncrement = true;
-  else autoIncrement = !isProduction2;
+  else autoIncrement = !production;
   const tryListen = (attemptPort) => {
     const onError = (err) => {
       if (err.code !== "EADDRINUSE") {
         reject(err);
         return;
       }
-      if (autoIncrement) {
+      if (autoIncrement && attemptPort < 65535) {
         getLogger13().warn(
-          `Port ${String(attemptPort)} is in use \u2014 trying ${String(attemptPort + 1)} (auto-increment; set SERVER_PORT_AUTO_INCREMENT=0 to disable). A previous/zombie dev server is still holding :${String(attemptPort)}: anything pinned to that port (an old browser tab, the Vite proxy's cached target, a manual client) will keep talking to the OLD process, NOT this restart. If this restart was meant to replace it, stop the process on :${String(attemptPort)} first.`
+          `Port ${String(attemptPort)} is in use \u2014 trying ${String(attemptPort + 1)} (auto-increment; set SERVER_PORT_AUTO_INCREMENT=0 to disable). A previous/zombie dev server is still holding :${String(attemptPort)}: a manual client pinned there will keep talking to the OLD process, while the Vite proxy follows this restart's advertised port. If this restart was meant to replace it, stop the process on :${String(attemptPort)} first.`
         );
         tryListen(attemptPort + 1);
         return;
       }
+      if (autoIncrement) {
+        const rangeError = new RangeError(
+          "Port 65535 is already in use and auto-increment cannot select a valid higher TCP port."
+        );
+        getLogger13().error(rangeError.message);
+        reject(rangeError);
+        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.`
       );
@@ -2365,13 +2390,28 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
     httpServer.once("error", onError);
     httpServer.listen(attemptPort, ip, () => {
       httpServer.off("error", onError);
-      if (!isProduction2 && process.env.NODE_ENV !== "test") {
-        writeDevServerInfo(ip, attemptPort);
+      const address = httpServer.address();
+      const boundPort = typeof address === "object" && address !== null ? address.port : attemptPort;
+      registerBoundAddress({ ip, port: boundPort });
+      if (!production && !test) {
+        writeDevServerInfo(ip, boundPort);
         process.once("exit", clearDevServerInfo);
       }
+      if (attemptPort !== startPort && !production) {
+        const configuredCallbackBase = tryCatchSync2(() => getProjectConfig15().oauthCallbackBase)[1] ?? "";
+        const callbackPort = tryCatchSync2(() => {
+          const callbackUrl = new URL(configuredCallbackBase);
+          return callbackUrl.port || (callbackUrl.protocol === "https:" ? "443" : "80");
+        })[1] ?? "";
+        if (callbackPort === String(startPort) && callbackPort !== String(boundPort)) {
+          getLogger13().warn(
+            `OAuth port drift: the server bound :${String(boundPort)} but your OAuth callback base is configured for :${callbackPort} (${configuredCallbackBase}). The framework now auto-targets :${String(boundPort)} for OAuth so the callback reaches THIS server \u2014 but your provider (Google/GitHub/\u2026) still exact-matches its registered redirect URI, so add :${String(boundPort)} to the authorized redirect URIs, OR set SERVER_PORT_AUTO_INCREMENT=0 to pin :${callbackPort} (stop whatever holds it) instead of hopping.`
+          );
+        }
+      }
       const config = getProjectConfig15();
       if (config.logging.socketStartup || config.logging.devLogs) {
-        getLogger13().info(`Server is running on http://${ip}:${String(attemptPort)}/`);
+        getLogger13().info(`Server is running on http://${ip}:${String(boundPort)}/`);
       }
       callback?.();
       resolve(httpServer);
@@ -2391,13 +2431,15 @@ var createLuckyStackServer = async (options = {}) => {
     requireServicesConfig: options.requireServicesConfig,
     requireOAuthProviders: options.requireOAuthProviders
   });
-  const port = options.port ?? getParsedPort() ?? options.defaultPort ?? process.env.SERVER_PORT ?? 80;
+  const port = resolveServerPort({
+    optionsPort: options.port,
+    parsedPort: getParsedPort(),
+    defaultPort: options.defaultPort,
+    envPort: process.env.SERVER_PORT
+  });
   const ip = options.ip ?? process.env.SERVER_IP ?? "127.0.0.1";
   const enableDevTools = options.enableDevTools ?? resolveEnvKey5() !== "production";
-  registerBindAddress({
-    ip,
-    port: typeof port === "string" ? Number.parseInt(port, 10) : port
-  });
+  registerBindAddress({ ip, port });
   if (enableDevTools) {
     await initDevTools();
   }