@warlock.js/core 5.3.1 → 5.4.0

package/esm/http/boot-port-preflight.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"boot-port-preflight.mjs","names":[],"sources":["../../../../../../../core/src/http/boot-port-preflight.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { assertPortIsAvailable, PortInUseError } from \"./port-preflight\";\n\n/**\n * Host used when `http.host` is unset — the same default `HttpConnector`\n * binds with, so the probe tests the address the server will actually take.\n */\nconst DEFAULT_BIND_HOST = \"localhost\";\n\n/**\n * Probe the port declared in `src/config/http.ts`, if there is one.\n *\n * Reads config rather than taking arguments because the only honest answer to\n * \"which port will this boot bind\" lives in the loaded config, and the callers\n * that need this check (the generated production entry) run before anything\n * that could hand it over.\n *\n * A no-op for an app with no `http` config, or an `http.port` that is not a\n * usable port number — those apps never bind, so there is nothing to preflight\n * and nothing to fail on.\n *\n * @throws {PortInUseError} when the configured port is already taken.\n */\nexport async function assertConfiguredHttpPortIsFree(): Promise<void> {\n  const httpConfig = config.get(\"http\");\n\n  if (!httpConfig) {\n    return;\n  }\n\n  const port = Number(httpConfig.port);\n\n  if (!Number.isInteger(port) || port <= 0 || port > 65_535) {\n    return;\n  }\n\n  await assertPortIsAvailable(port, httpConfig.host || DEFAULT_BIND_HOST);\n}\n\n/**\n * Fail the boot immediately, and by name, when the http port is already taken.\n *\n * Called from the generated production entry BEFORE the early-phase connectors,\n * because the port is the cheapest thing in the boot to check and the one most\n * likely to be wrong. `HttpConnector` is a LATE-phase connector, so its own\n * preflight is not reached until the database has connected, the cache has\n * connected and every module of app code has been imported — 7-13 seconds of\n * work, all of it discarded, before anyone learns the port was busy. This check\n * costs a bind-and-release on a socket that is never served.\n *\n * It does NOT replace `HttpConnector`'s preflight: a port can be taken in the\n * seconds between the two, and only the connector's check sits immediately\n * before the real `listen()`. This one exists to make the common case fast and\n * legible.\n *\n * Reports through `console.error` and NOT through `log.fatal`: the logger has\n * no channels yet at this point in the boot (the logger connector is part of\n * the early phase this runs ahead of), so a logged message here would reach\n * nobody. stderr always reaches the terminal, and `warlock start` forwards the\n * child's stderr verbatim.\n *\n * A probe that fails for any OTHER reason is deliberately swallowed: this is a\n * fast-fail convenience, and it must never be the thing that stops an app which\n * would otherwise have booted. `HttpConnector` still runs the real check.\n */\nexport async function preflightConfiguredHttpPort(): Promise<void> {\n  try {\n    await assertConfiguredHttpPortIsFree();\n  } catch (error) {\n    if (!(error instanceof PortInUseError)) {\n      return;\n    }\n\n    reportPortInUse(error);\n\n    process.exit(1);\n  }\n}\n\n/**\n * Print the collision the way the developer needs to read it: the errno they\n * grep for, the port and host by name, and the command that names the process\n * holding it — the supervisor cannot discover the owning PID for them, but it\n * can hand them the one line that will.\n */\nfunction reportPortInUse(error: PortInUseError): void {\n  const ownerCommand =\n    process.platform === \"win32\"\n      ? `netstat -ano | findstr :${error.port}`\n      : `lsof -i :${error.port}`;\n\n  const lines = [\n    \"\",\n    `  ✖ EADDRINUSE: port ${error.port} is already in use on ${error.host}`,\n    `  the application cannot start because something else is already listening there.`,\n    `  find the owning process: ${ownerCommand}`,\n    `  then stop it, or change http.port in src/config/http.ts and rebuild.`,\n    \"\",\n  ];\n\n  for (const line of lines) {\n    console.error(line);\n  }\n}\n"],"mappings":";;;;;;;;AAOA,MAAM,oBAAoB;;;;;;;;;;;;;;;AAgB1B,eAAsB,iCAAgD;CACpE,MAAM,aAAa,OAAO,IAAI,MAAM;CAEpC,IAAI,CAAC,YACH;CAGF,MAAM,OAAO,OAAO,WAAW,IAAI;CAEnC,IAAI,CAAC,OAAO,UAAU,IAAI,KAAK,QAAQ,KAAK,OAAO,OACjD;CAGF,MAAM,sBAAsB,MAAM,WAAW,QAAQ,iBAAiB;AACxE;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,eAAsB,8BAA6C;CACjE,IAAI;EACF,MAAM,+BAA+B;CACvC,SAAS,OAAO;EACd,IAAI,EAAE,iBAAiB,iBACrB;EAGF,gBAAgB,KAAK;EAErB,QAAQ,KAAK,CAAC;CAChB;AACF;;;;;;;AAQA,SAAS,gBAAgB,OAA6B;CACpD,MAAM,eACJ,QAAQ,aAAa,UACjB,2BAA2B,MAAM,SACjC,YAAY,MAAM;CAExB,MAAM,QAAQ;EACZ;EACA,wBAAwB,MAAM,KAAK,wBAAwB,MAAM;EACjE;EACA,8BAA8B;EAC9B;EACA;CACF;CAEA,KAAK,MAAM,QAAQ,OACjB,QAAQ,MAAM,IAAI;AAEtB"}
+{"version":3,"file":"boot-port-preflight.mjs","names":[],"sources":["../../../../../../../core/src/http/boot-port-preflight.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { assertPortIsAvailable, PortInUseError } from \"./port-preflight\";\nimport { resolveBindPort } from \"./resolve-bind-port\";\n\n/**\n * Mirrors `dev-server/supervisor.ts`'s `BOOT_PRECONDITION_EXIT_CODE`. Kept as\n * its own literal here (rather than imported) so this file — reached by both\n * the dev-preload path and the generated, standalone production entry — never\n * pulls dev-server's supervisor module (child_process, TTY handling, ...)\n * into a production bundle that has no supervisor at all. EX_CONFIG.\n */\nconst BOOT_PRECONDITION_EXIT_CODE = 78;\n\n/**\n * Host used when `http.host` is unset — the same default `HttpConnector`\n * binds with, so the probe tests the address the server will actually take.\n */\nconst DEFAULT_BIND_HOST = \"localhost\";\n\n/**\n * Probe the port declared in `src/config/http.ts`, if there is one.\n *\n * Reads config rather than taking arguments because the only honest answer to\n * \"which port will this boot bind\" lives in the loaded config, and the callers\n * that need this check (the generated production entry) run before anything\n * that could hand it over.\n *\n * A no-op for an app with no `http` config, or an `http.port` that is not a\n * usable port number — those apps never bind, so there is nothing to preflight\n * and nothing to fail on.\n *\n * @throws {PortInUseError} when the configured port is already taken.\n */\nexport async function assertConfiguredHttpPortIsFree(): Promise<void> {\n  const httpConfig = config.get(\"http\");\n\n  if (!httpConfig) {\n    return;\n  }\n\n  // This runs BEFORE the connectors in the generated production entry, and\n  // `preflightConfiguredHttpPort()` below only exits on `PortInUseError` —\n  // any other throw is swallowed there. So a bad port must not throw HERE:\n  // it stays a no-op, exactly like the previous hand-rolled coercion, and\n  // `HttpConnector` (which now also calls `resolveBindPort`) is the one that\n  // reports it, a moment later, with a channel a developer will actually see.\n  let port: number;\n\n  try {\n    port = resolveBindPort(httpConfig.port);\n  } catch {\n    return;\n  }\n\n  // Port 0 asks the OS to pick a free one, so there is nothing to preflight:\n  // probing 0 binds SOME unrelated ephemeral port and \"passes\" without proving\n  // anything about the port this boot will end up on. The hand-rolled coercion\n  // this replaced skipped 0 by rejecting `port <= 0`; `resolveBindPort` accepts\n  // 0 as a legitimate TCP value, so the skip has to be stated here instead of\n  // falling out of a range check.\n  if (port === 0) {\n    return;\n  }\n\n  await assertPortIsAvailable(port, httpConfig.host || DEFAULT_BIND_HOST);\n}\n\n/**\n * Fail the boot immediately, and by name, when the http port is already taken.\n *\n * Called from the generated production entry BEFORE the early-phase connectors,\n * because the port is the cheapest thing in the boot to check and the one most\n * likely to be wrong. `HttpConnector` is a LATE-phase connector, so its own\n * preflight is not reached until the database has connected, the cache has\n * connected and every module of app code has been imported — 7-13 seconds of\n * work, all of it discarded, before anyone learns the port was busy. This check\n * costs a bind-and-release on a socket that is never served.\n *\n * It does NOT replace `HttpConnector`'s preflight: a port can be taken in the\n * seconds between the two, and only the connector's check sits immediately\n * before the real `listen()`. This one exists to make the common case fast and\n * legible.\n *\n * Reports through `console.error` and NOT through `log.fatal`: the logger has\n * no channels yet at this point in the boot (the logger connector is part of\n * the early phase this runs ahead of), so a logged message here would reach\n * nobody. stderr always reaches the terminal, and `warlock start` forwards the\n * child's stderr verbatim.\n *\n * A probe that fails for any OTHER reason is deliberately swallowed: this is a\n * fast-fail convenience, and it must never be the thing that stops an app which\n * would otherwise have booted. `HttpConnector` still runs the real check.\n */\nexport async function preflightConfiguredHttpPort(): Promise<void> {\n  try {\n    await assertConfiguredHttpPortIsFree();\n  } catch (error) {\n    if (!(error instanceof PortInUseError)) {\n      return;\n    }\n\n    reportPortInUse(error);\n\n    process.exit(BOOT_PRECONDITION_EXIT_CODE);\n  }\n}\n\n/**\n * Print the collision the way the developer needs to read it: the errno they\n * grep for, the port and host by name, and the command that names the process\n * holding it — the supervisor cannot discover the owning PID for them, but it\n * can hand them the one line that will.\n */\nfunction reportPortInUse(error: PortInUseError): void {\n  const ownerCommand =\n    process.platform === \"win32\"\n      ? `netstat -ano | findstr :${error.port}`\n      : `lsof -i :${error.port}`;\n\n  const lines = [\n    \"\",\n    `  ✖ EADDRINUSE: port ${error.port} is already in use on ${error.host}`,\n    `  the application cannot start because something else is already listening there.`,\n    `  find the owning process: ${ownerCommand}`,\n    `  then stop it, or change http.port in src/config/http.ts and rebuild.`,\n    \"\",\n  ];\n\n  for (const line of lines) {\n    console.error(line);\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAM,8BAA8B;;;;;AAMpC,MAAM,oBAAoB;;;;;;;;;;;;;;;AAgB1B,eAAsB,iCAAgD;CACpE,MAAM,aAAa,OAAO,IAAI,MAAM;CAEpC,IAAI,CAAC,YACH;CASF,IAAI;CAEJ,IAAI;EACF,OAAO,gBAAgB,WAAW,IAAI;CACxC,QAAQ;EACN;CACF;CAQA,IAAI,SAAS,GACX;CAGF,MAAM,sBAAsB,MAAM,WAAW,QAAQ,iBAAiB;AACxE;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,eAAsB,8BAA6C;CACjE,IAAI;EACF,MAAM,+BAA+B;CACvC,SAAS,OAAO;EACd,IAAI,EAAE,iBAAiB,iBACrB;EAGF,gBAAgB,KAAK;EAErB,QAAQ,KAAK,2BAA2B;CAC1C;AACF;;;;;;;AAQA,SAAS,gBAAgB,OAA6B;CACpD,MAAM,eACJ,QAAQ,aAAa,UACjB,2BAA2B,MAAM,SACjC,YAAY,MAAM;CAExB,MAAM,QAAQ;EACZ;EACA,wBAAwB,MAAM,KAAK,wBAAwB,MAAM;EACjE;EACA,8BAA8B;EAC9B;EACA;CACF;CAEA,KAAK,MAAM,QAAQ,OACjB,QAAQ,MAAM,IAAI;AAEtB"}

package/esm/http/resolve-bind-port.mjs

@@ -0,0 +1,51 @@
+import { defaultHttpConfigurations } from "./config.mjs";
+
+//#region ../core/src/http/resolve-bind-port.ts
+/**
+* Fallback used only if `defaultHttpConfigurations.port` is ever unset —
+* `HttpConfigurations.port` is typed optional for consumers, but the
+* framework's own default configuration always declares one. Keeps
+* `resolveBindPort`'s return type a plain `number` without an `as`.
+*/
+const FALLBACK_PORT = 3e3;
+/**
+* Resolve a raw, possibly-stringy `http.port` value into the number the
+* socket layer will actually bind.
+*
+* `env()` only coerces a `.env` value to a number when it round-trips
+* exactly (`String(Number(v)) === v`), so values like `"03999"`, `" 3999"`,
+* `"+3999"` or `"1e3"` arrive here as strings. `net.Server.listen({ port })`
+* happily accepts every one of those and binds SOMETHING — `"1e3"` binds
+* port 1000 with no diagnostic anywhere — so this is the one place the
+* configured port is turned into a canonical integer before anything binds,
+* logs, or reports it.
+*
+* `undefined`/`null` (no `http.port` configured at all) resolves to the
+* framework default rather than throwing — that case is not misconfiguration.
+*
+* @throws {Error} when the raw value cannot be resolved to a usable TCP port
+* (0-65535, finite integer) — naming the raw value and where to fix it.
+*/
+function resolveBindPort(rawPort) {
+	if (rawPort === void 0 || rawPort === null) return defaultHttpConfigurations.port ?? FALLBACK_PORT;
+	const resolved = Number(String(rawPort).trim());
+	if (!Number.isInteger(resolved) || resolved < 0 || resolved > 65535) throw new Error(`Invalid http port ${JSON.stringify(rawPort)}: it does not resolve to a usable TCP port (0-65535, whole number). Fix HTTP_PORT in .env, or http.port in src/config/http.ts.`);
+	return resolved;
+}
+/**
+* Whether `rawPort` was already the canonical value `resolveBindPort`
+* returned for it — i.e. nothing needed normalising.
+*
+* Lets a caller print exactly one notice when the configured port and the
+* bound port differ in representation (`"03999"` -> `3999`), and stay silent
+* for the ordinary case (a plain number, or a string that was already
+* canonical).
+*/
+function isCanonicalPortValue(rawPort, resolved) {
+	if (typeof rawPort === "number" || rawPort === void 0 || rawPort === null) return true;
+	return String(rawPort) === String(resolved);
+}
+
+//#endregion
+export { isCanonicalPortValue, resolveBindPort };
+//# sourceMappingURL=resolve-bind-port.mjs.map

package/esm/http/resolve-bind-port.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-bind-port.mjs","names":[],"sources":["../../../../../../../core/src/http/resolve-bind-port.ts"],"sourcesContent":["import { defaultHttpConfigurations } from \"./config\";\n\n/**\n * Fallback used only if `defaultHttpConfigurations.port` is ever unset —\n * `HttpConfigurations.port` is typed optional for consumers, but the\n * framework's own default configuration always declares one. Keeps\n * `resolveBindPort`'s return type a plain `number` without an `as`.\n */\nconst FALLBACK_PORT = 3000;\n\n/**\n * Resolve a raw, possibly-stringy `http.port` value into the number the\n * socket layer will actually bind.\n *\n * `env()` only coerces a `.env` value to a number when it round-trips\n * exactly (`String(Number(v)) === v`), so values like `\"03999\"`, `\" 3999\"`,\n * `\"+3999\"` or `\"1e3\"` arrive here as strings. `net.Server.listen({ port })`\n * happily accepts every one of those and binds SOMETHING — `\"1e3\"` binds\n * port 1000 with no diagnostic anywhere — so this is the one place the\n * configured port is turned into a canonical integer before anything binds,\n * logs, or reports it.\n *\n * `undefined`/`null` (no `http.port` configured at all) resolves to the\n * framework default rather than throwing — that case is not misconfiguration.\n *\n * @throws {Error} when the raw value cannot be resolved to a usable TCP port\n * (0-65535, finite integer) — naming the raw value and where to fix it.\n */\nexport function resolveBindPort(rawPort: unknown): number {\n  if (rawPort === undefined || rawPort === null) {\n    return defaultHttpConfigurations.port ?? FALLBACK_PORT;\n  }\n\n  const resolved = Number(String(rawPort).trim());\n\n  if (!Number.isInteger(resolved) || resolved < 0 || resolved > 65_535) {\n    throw new Error(\n      `Invalid http port ${JSON.stringify(rawPort)}: it does not resolve to a usable TCP port ` +\n        `(0-65535, whole number). Fix HTTP_PORT in .env, or http.port in src/config/http.ts.`,\n    );\n  }\n\n  return resolved;\n}\n\n/**\n * Whether `rawPort` was already the canonical value `resolveBindPort`\n * returned for it — i.e. nothing needed normalising.\n *\n * Lets a caller print exactly one notice when the configured port and the\n * bound port differ in representation (`\"03999\"` -> `3999`), and stay silent\n * for the ordinary case (a plain number, or a string that was already\n * canonical).\n */\nexport function isCanonicalPortValue(rawPort: unknown, resolved: number): boolean {\n  if (typeof rawPort === \"number\" || rawPort === undefined || rawPort === null) {\n    return true;\n  }\n\n  return String(rawPort) === String(resolved);\n}\n"],"mappings":";;;;;;;;;AAQA,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;AAoBtB,SAAgB,gBAAgB,SAA0B;CACxD,IAAI,YAAY,UAAa,YAAY,MACvC,OAAO,0BAA0B,QAAQ;CAG3C,MAAM,WAAW,OAAO,OAAO,OAAO,CAAC,CAAC,KAAK,CAAC;CAE9C,IAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,WAAW,KAAK,WAAW,OAC5D,MAAM,IAAI,MACR,qBAAqB,KAAK,UAAU,OAAO,EAAE,+HAE/C;CAGF,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,qBAAqB,SAAkB,UAA2B;CAChF,IAAI,OAAO,YAAY,YAAY,YAAY,UAAa,YAAY,MACtE,OAAO;CAGT,OAAO,OAAO,OAAO,MAAM,OAAO,QAAQ;AAC5C"}

package/esm/tests/test-helpers.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.d.mts","names":[],"sources":["../../../../../../../core/src/tests/test-helpers.ts"],"mappings":";;AAYA;;;;AAAgC;AAehC;;AAfgC,iBAAhB,gBAAA;;;;;iBAeM,WAAA,CAAY,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAgD9D,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;AAhDY;iBAuDtE,QAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,OAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,UAAA,CAAW,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAO7D,SAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;AAxC6E;AAOxF;iBAwCsB,iBAAA,IAAqB,QAAA,EAAU,QAAA,GAAW,OAAA,CAAQ,CAAA;;;;iBAOlD,UAAA,IAAc,QAAA,EAAU,QAAA,EAAU,cAAA,YAAuB,OAAA,CAAQ,CAAA"}
+{"version":3,"file":"test-helpers.d.mts","names":[],"sources":["../../../../../../../core/src/tests/test-helpers.ts"],"mappings":";;AAaA;;;;AAAgC;AA6BhC;;AA7BgC,iBAAhB,gBAAA;;;;;iBA6BM,WAAA,CAAY,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAgD9D,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;AAhDY;iBAuDtE,QAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAWW,OAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;;;iBAOW,UAAA,CAAW,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAO7D,SAAA,CACpB,IAAA,UACA,IAAA,YACA,OAAA,GAAS,WAAA,GACR,OAAA,CAAQ,QAAA;;AA5C6E;AAOxF;iBAgDsB,iBAAA,IAAqB,QAAA,EAAU,QAAA,GAAW,OAAA,CAAQ,CAAA;;;;iBAOlD,UAAA,IAAc,QAAA,EAAU,QAAA,EAAU,cAAA,YAAuB,OAAA,CAAQ,CAAA"}

package/esm/tests/test-helpers.mjs

@@ -1,5 +1,6 @@
 import { config } from "../config/config-getter.mjs";
 import "../config/index.mjs";
+import { getHttpReadyReport } from "../http/ready-report.mjs";
 import { TEST_SERVER_PORT_ENV_KEY } from "./test-server-port-channel.mjs";
 
 //#region ../core/src/tests/test-helpers.ts
@@ -12,7 +13,9 @@ import { TEST_SERVER_PORT_ENV_KEY } from "./test-server-port-channel.mjs";
 * Get the test server base URL
 */
 function getTestServerUrl() {
-	const port = process.env["WARLOCK_TEST_SERVER_PORT"] || config.key("http.port", 2031);
+	const publishedPort = process.env[TEST_SERVER_PORT_ENV_KEY];
+	const boundPort = getHttpReadyReport()?.port;
+	const port = publishedPort || boundPort || config.key("http.port", 2031);
 	return `http://${config.key("http.host", "localhost")}:${port}`;
 }
 /**

package/esm/tests/test-helpers.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.mjs","names":[],"sources":["../../../../../../../core/src/tests/test-helpers.ts"],"sourcesContent":["/**\n * Warlock.js Test Helpers\n *\n * Utilities for testing Warlock.js applications.\n */\n\nimport { config } from \"../config\";\nimport { TEST_SERVER_PORT_ENV_KEY } from \"./test-server-port-channel\";\n\n/**\n * Get the test server base URL\n */\nexport function getTestServerUrl(): string {\n  // `startHttpTestServer` publishes the port it actually bound. Test workers are\n  // separate processes whose own config resolves `http.port` from `.env`, so\n  // without this a suite started on an explicit port would send every request to\n  // the `.env` port instead of the one the server is listening on.\n  const publishedPort = process.env[TEST_SERVER_PORT_ENV_KEY];\n  const port = publishedPort || config.key(\"http.port\", 2031);\n  const host = config.key(\"http.host\", \"localhost\");\n  return `http://${host}:${port}`;\n}\n\n/**\n * Simple HTTP request helper for test server\n * Uses native fetch - lightweight, no extra dependencies\n */\nexport async function testRequest(path: string, options: RequestInit = {}): Promise<Response> {\n  return sendRequest(path, options, false);\n}\n\n/**\n * The single place a request is actually built.\n *\n * `serializedJson` says whether THIS module turned the caller's value into a\n * JSON string. It is the only thing that justifies setting a JSON content type:\n * a `FormData` body carries a multipart boundary the runtime generates, and\n * labelling it `application/json` produces a request no server can parse.\n */\nasync function sendRequest(\n  path: string,\n  options: RequestInit,\n  serializedJson: boolean,\n): Promise<Response> {\n  const baseUrl = getTestServerUrl();\n  const url = path.startsWith(\"/\") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;\n\n  // Normalised through `Headers` rather than object-spread: `RequestInit.headers`\n  // may be a record, a `Headers` instance, or a list of `[name, value]` tuples,\n  // and spreading the last two silently produces an object with numeric keys —\n  // the header is simply lost, with no error anywhere.\n  const headers = new Headers(options.headers);\n\n  if (serializedJson && !headers.has(\"content-type\")) {\n    headers.set(\"content-type\", \"application/json\");\n  }\n\n  return fetch(url, { ...options, headers });\n}\n\n/**\n * Serialize a body for a JSON request.\n *\n * `undefined` means the caller omitted the argument; every other value —\n * including `false`, `0`, `\"\"` and `null` — is a legal JSON document and must\n * be sent. The old check was `body ? JSON.stringify(body) : undefined`, which\n * dropped all four.\n */\nfunction jsonBody(body: unknown): string | undefined {\n  return body === undefined ? undefined : JSON.stringify(body);\n}\n\n/**\n * GET request helper\n */\nexport async function testGet(path: string, options: RequestInit = {}): Promise<Response> {\n  return testRequest(path, { ...options, method: \"GET\" });\n}\n\n/**\n * POST request helper\n */\nexport async function testPost(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(path, { ...options, method: \"POST\", body: jsonBody(body) }, body !== undefined);\n}\n\n/**\n * PUT request helper\n */\nexport async function testPut(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(path, { ...options, method: \"PUT\", body: jsonBody(body) }, body !== undefined);\n}\n\n/**\n * DELETE request helper\n */\nexport async function testDelete(path: string, options: RequestInit = {}): Promise<Response> {\n  return testRequest(path, { ...options, method: \"DELETE\" });\n}\n\n/**\n * PATCH request helper\n */\nexport async function testPatch(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(path, { ...options, method: \"PATCH\", body: jsonBody(body) }, body !== undefined);\n}\n\n/**\n * Parse JSON response with type safety\n */\nexport async function parseJsonResponse<T>(response: Response): Promise<T> {\n  return response.json() as Promise<T>;\n}\n\n/**\n * Assert response status and return parsed JSON\n */\nexport async function expectJson<T>(response: Response, expectedStatus = 200): Promise<T> {\n  if (response.status !== expectedStatus) {\n    const text = await response.text();\n    throw new Error(`Expected status ${expectedStatus}, got ${response.status}. Body: ${text}`);\n  }\n  return parseJsonResponse<T>(response);\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,mBAA2B;CAMzC,MAAM,OADgB,QAAQ,mCACA,OAAO,IAAI,aAAa,IAAI;CAE1D,OAAO,UADM,OAAO,IAAI,aAAa,WACjB,EAAE,GAAG;AAC3B;;;;;AAMA,eAAsB,YAAY,MAAc,UAAuB,CAAC,GAAsB;CAC5F,OAAO,YAAY,MAAM,SAAS,KAAK;AACzC;;;;;;;;;AAUA,eAAe,YACb,MACA,SACA,gBACmB;CACnB,MAAM,UAAU,iBAAiB;CACjC,MAAM,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,SAAS,GAAG,QAAQ,GAAG;CAMvE,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;CAE3C,IAAI,kBAAkB,CAAC,QAAQ,IAAI,cAAc,GAC/C,QAAQ,IAAI,gBAAgB,kBAAkB;CAGhD,OAAO,MAAM,KAAK;EAAE,GAAG;EAAS;CAAQ,CAAC;AAC3C;;;;;;;;;AAUA,SAAS,SAAS,MAAmC;CACnD,OAAO,SAAS,SAAY,SAAY,KAAK,UAAU,IAAI;AAC7D;;;;AAKA,eAAsB,QAAQ,MAAc,UAAuB,CAAC,GAAsB;CACxF,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;CAAM,CAAC;AACxD;;;;AAKA,eAAsB,SACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;EAAQ,MAAM,SAAS,IAAI;CAAE,GAAG,SAAS,MAAS;AACnG;;;;AAKA,eAAsB,QACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;EAAO,MAAM,SAAS,IAAI;CAAE,GAAG,SAAS,MAAS;AAClG;;;;AAKA,eAAsB,WAAW,MAAc,UAAuB,CAAC,GAAsB;CAC3F,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;CAAS,CAAC;AAC3D;;;;AAKA,eAAsB,UACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;EAAS,MAAM,SAAS,IAAI;CAAE,GAAG,SAAS,MAAS;AACpG;;;;AAKA,eAAsB,kBAAqB,UAAgC;CACzE,OAAO,SAAS,KAAK;AACvB;;;;AAKA,eAAsB,WAAc,UAAoB,iBAAiB,KAAiB;CACxF,IAAI,SAAS,WAAW,gBAAgB;EACtC,MAAM,OAAO,MAAM,SAAS,KAAK;EACjC,MAAM,IAAI,MAAM,mBAAmB,eAAe,QAAQ,SAAS,OAAO,UAAU,MAAM;CAC5F;CACA,OAAO,kBAAqB,QAAQ;AACtC"}
+{"version":3,"file":"test-helpers.mjs","names":[],"sources":["../../../../../../../core/src/tests/test-helpers.ts"],"sourcesContent":["/**\n * Warlock.js Test Helpers\n *\n * Utilities for testing Warlock.js applications.\n */\n\nimport { config } from \"../config\";\nimport { getHttpReadyReport } from \"../http/ready-report\";\nimport { TEST_SERVER_PORT_ENV_KEY } from \"./test-server-port-channel\";\n\n/**\n * Get the test server base URL\n */\nexport function getTestServerUrl(): string {\n  // `startHttpTestServer` publishes the port it actually bound. Test workers are\n  // separate processes whose own config resolves `http.port` from `.env`, so\n  // without this a suite started on an explicit port would send every request to\n  // the `.env` port instead of the one the server is listening on.\n  const publishedPort = process.env[TEST_SERVER_PORT_ENV_KEY];\n\n  // Same-process fallback: a test that boots the HTTP connector directly\n  // (rather than through `startHttpTestServer`'s cross-process channel) never\n  // writes `TEST_SERVER_PORT_ENV_KEY`, so without this the next fallback —\n  // `config.key(\"http.port\", 2031)` — was the only source left, and it holds\n  // the CONFIGURED port, not the bound one. For `http.port: 0` that is `0`,\n  // producing `http://host:0` even though `HttpConnector.start()` had already\n  // recorded the real bound port right here in `ready-report.ts`.\n  const boundPort = getHttpReadyReport()?.port;\n\n  // `config.key`'s default only substitutes for `undefined` — `0` is a\n  // defined configured value, not an absent one — so it cannot be trusted to\n  // paper over an unresolved port 0 either. `boundPort` is read first for\n  // that exact reason.\n  const port = publishedPort || boundPort || config.key(\"http.port\", 2031);\n  const host = config.key(\"http.host\", \"localhost\");\n  return `http://${host}:${port}`;\n}\n\n/**\n * Simple HTTP request helper for test server\n * Uses native fetch - lightweight, no extra dependencies\n */\nexport async function testRequest(path: string, options: RequestInit = {}): Promise<Response> {\n  return sendRequest(path, options, false);\n}\n\n/**\n * The single place a request is actually built.\n *\n * `serializedJson` says whether THIS module turned the caller's value into a\n * JSON string. It is the only thing that justifies setting a JSON content type:\n * a `FormData` body carries a multipart boundary the runtime generates, and\n * labelling it `application/json` produces a request no server can parse.\n */\nasync function sendRequest(\n  path: string,\n  options: RequestInit,\n  serializedJson: boolean,\n): Promise<Response> {\n  const baseUrl = getTestServerUrl();\n  const url = path.startsWith(\"/\") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;\n\n  // Normalised through `Headers` rather than object-spread: `RequestInit.headers`\n  // may be a record, a `Headers` instance, or a list of `[name, value]` tuples,\n  // and spreading the last two silently produces an object with numeric keys —\n  // the header is simply lost, with no error anywhere.\n  const headers = new Headers(options.headers);\n\n  if (serializedJson && !headers.has(\"content-type\")) {\n    headers.set(\"content-type\", \"application/json\");\n  }\n\n  return fetch(url, { ...options, headers });\n}\n\n/**\n * Serialize a body for a JSON request.\n *\n * `undefined` means the caller omitted the argument; every other value —\n * including `false`, `0`, `\"\"` and `null` — is a legal JSON document and must\n * be sent. The old check was `body ? JSON.stringify(body) : undefined`, which\n * dropped all four.\n */\nfunction jsonBody(body: unknown): string | undefined {\n  return body === undefined ? undefined : JSON.stringify(body);\n}\n\n/**\n * GET request helper\n */\nexport async function testGet(path: string, options: RequestInit = {}): Promise<Response> {\n  return testRequest(path, { ...options, method: \"GET\" });\n}\n\n/**\n * POST request helper\n */\nexport async function testPost(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(\n    path,\n    { ...options, method: \"POST\", body: jsonBody(body) },\n    body !== undefined,\n  );\n}\n\n/**\n * PUT request helper\n */\nexport async function testPut(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(path, { ...options, method: \"PUT\", body: jsonBody(body) }, body !== undefined);\n}\n\n/**\n * DELETE request helper\n */\nexport async function testDelete(path: string, options: RequestInit = {}): Promise<Response> {\n  return testRequest(path, { ...options, method: \"DELETE\" });\n}\n\n/**\n * PATCH request helper\n */\nexport async function testPatch(\n  path: string,\n  body?: unknown,\n  options: RequestInit = {},\n): Promise<Response> {\n  return sendRequest(\n    path,\n    { ...options, method: \"PATCH\", body: jsonBody(body) },\n    body !== undefined,\n  );\n}\n\n/**\n * Parse JSON response with type safety\n */\nexport async function parseJsonResponse<T>(response: Response): Promise<T> {\n  return response.json() as Promise<T>;\n}\n\n/**\n * Assert response status and return parsed JSON\n */\nexport async function expectJson<T>(response: Response, expectedStatus = 200): Promise<T> {\n  if (response.status !== expectedStatus) {\n    const text = await response.text();\n    throw new Error(`Expected status ${expectedStatus}, got ${response.status}. Body: ${text}`);\n  }\n  return parseJsonResponse<T>(response);\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,mBAA2B;CAKzC,MAAM,gBAAgB,QAAQ,IAAI;CASlC,MAAM,YAAY,mBAAmB,CAAC,EAAE;CAMxC,MAAM,OAAO,iBAAiB,aAAa,OAAO,IAAI,aAAa,IAAI;CAEvE,OAAO,UADM,OAAO,IAAI,aAAa,WACjB,EAAE,GAAG;AAC3B;;;;;AAMA,eAAsB,YAAY,MAAc,UAAuB,CAAC,GAAsB;CAC5F,OAAO,YAAY,MAAM,SAAS,KAAK;AACzC;;;;;;;;;AAUA,eAAe,YACb,MACA,SACA,gBACmB;CACnB,MAAM,UAAU,iBAAiB;CACjC,MAAM,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,SAAS,GAAG,QAAQ,GAAG;CAMvE,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;CAE3C,IAAI,kBAAkB,CAAC,QAAQ,IAAI,cAAc,GAC/C,QAAQ,IAAI,gBAAgB,kBAAkB;CAGhD,OAAO,MAAM,KAAK;EAAE,GAAG;EAAS;CAAQ,CAAC;AAC3C;;;;;;;;;AAUA,SAAS,SAAS,MAAmC;CACnD,OAAO,SAAS,SAAY,SAAY,KAAK,UAAU,IAAI;AAC7D;;;;AAKA,eAAsB,QAAQ,MAAc,UAAuB,CAAC,GAAsB;CACxF,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;CAAM,CAAC;AACxD;;;;AAKA,eAAsB,SACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YACL,MACA;EAAE,GAAG;EAAS,QAAQ;EAAQ,MAAM,SAAS,IAAI;CAAE,GACnD,SAAS,MACX;AACF;;;;AAKA,eAAsB,QACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;EAAO,MAAM,SAAS,IAAI;CAAE,GAAG,SAAS,MAAS;AAClG;;;;AAKA,eAAsB,WAAW,MAAc,UAAuB,CAAC,GAAsB;CAC3F,OAAO,YAAY,MAAM;EAAE,GAAG;EAAS,QAAQ;CAAS,CAAC;AAC3D;;;;AAKA,eAAsB,UACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YACL,MACA;EAAE,GAAG;EAAS,QAAQ;EAAS,MAAM,SAAS,IAAI;CAAE,GACpD,SAAS,MACX;AACF;;;;AAKA,eAAsB,kBAAqB,UAAgC;CACzE,OAAO,SAAS,KAAK;AACvB;;;;AAKA,eAAsB,WAAc,UAAoB,iBAAiB,KAAiB;CACxF,IAAI,SAAS,WAAW,gBAAgB;EACtC,MAAM,OAAO,MAAM,SAAS,KAAK;EACjC,MAAM,IAAI,MAAM,mBAAmB,eAAe,QAAQ,SAAS,OAAO,UAAU,MAAM;CAC5F;CACA,OAAO,kBAAqB,QAAQ;AACtC"}

package/esm/utils/detect-environment-overrides.mjs

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+
+//#region ../core/src/utils/detect-environment-overrides.ts
+/**
+* Minimal `KEY=VALUE` line parser: `#` comments, blank lines, and one layer
+* of surrounding quotes.
+*
+* Deliberately NOT `@mongez/dotenv`'s own `parseLine` / `parseValue`: those
+* live in the same module as `loadEnv`, and `tests/unit/utils/load-environment.test.ts`
+* replaces that whole module with `vi.mock("@mongez/dotenv", () => ({ loadEnv:
+* ... }))`. Importing any other named export from `@mongez/dotenv` here would
+* resolve to `undefined` under that mock and crash detection during those
+* tests. Comments, blank lines and a surrounding quote pair are the entire
+* feature set this comparison needs — the actual load still goes through the
+* real `@mongez/dotenv` parser via `loadEnv()`.
+*/
+function parseEnvLine(line) {
+	const trimmed = line.trim();
+	if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) return;
+	const separatorIndex = trimmed.indexOf("=");
+	const key = trimmed.slice(0, separatorIndex).trim();
+	let value = trimmed.slice(separatorIndex + 1).trim();
+	const quote = value[0];
+	if ((quote === "\"" || quote === "'" || quote === "`") && value.length > 1 && value.endsWith(quote)) value = value.slice(1, -1);
+	return [key, value];
+}
+/**
+* Which of the given `.env` files' keys lost to a value the ambient process
+* environment already carried.
+*
+* `snapshot` must be captured BEFORE `loadEnv()` runs: the loader writes into
+* `process.env` for every key the file supplies, so a snapshot taken
+* afterwards can no longer tell an ambient override from a value the loader
+* itself just wrote.
+*
+* `files` should be given in the same order `loadEnv()` actually reads them
+* (`.env.shared` first, then the applicable `.env`/`.env.<NODE_ENV>`), so a
+* key declared in more than one file resolves to the value the real loader
+* would have used absent any ambient override.
+*/
+function detectEnvironmentOverrides(files, snapshot) {
+	const fileValues = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		if (!existsSync(file)) continue;
+		const lines = readFileSync(file, "utf8").split(/\r\n|\n/);
+		for (const line of lines) {
+			const parsed = parseEnvLine(line);
+			if (!parsed) continue;
+			fileValues.set(parsed[0], parsed[1]);
+		}
+	}
+	const overrides = [];
+	for (const [key, fileValue] of fileValues) {
+		if (!Object.prototype.hasOwnProperty.call(snapshot, key)) continue;
+		const effectiveValue = snapshot[key];
+		if (effectiveValue !== fileValue) overrides.push({
+			key,
+			effectiveValue,
+			fileValue
+		});
+	}
+	return overrides;
+}
+
+//#endregion
+export { detectEnvironmentOverrides };
+//# sourceMappingURL=detect-environment-overrides.mjs.map

package/esm/utils/detect-environment-overrides.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-environment-overrides.mjs","names":[],"sources":["../../../../../../../core/src/utils/detect-environment-overrides.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\n\n/**\n * One `.env` key whose file value lost to an ambient `process.env` value that\n * was already set before the file was read.\n */\nexport type EnvironmentOverride = {\n  key: string;\n  effectiveValue: string;\n  fileValue: string;\n};\n\n/**\n * Minimal `KEY=VALUE` line parser: `#` comments, blank lines, and one layer\n * of surrounding quotes.\n *\n * Deliberately NOT `@mongez/dotenv`'s own `parseLine` / `parseValue`: those\n * live in the same module as `loadEnv`, and `tests/unit/utils/load-environment.test.ts`\n * replaces that whole module with `vi.mock(\"@mongez/dotenv\", () => ({ loadEnv:\n * ... }))`. Importing any other named export from `@mongez/dotenv` here would\n * resolve to `undefined` under that mock and crash detection during those\n * tests. Comments, blank lines and a surrounding quote pair are the entire\n * feature set this comparison needs — the actual load still goes through the\n * real `@mongez/dotenv` parser via `loadEnv()`.\n */\nfunction parseEnvLine(line: string): [string, string] | undefined {\n  const trimmed = line.trim();\n\n  if (!trimmed || trimmed.startsWith(\"#\") || !trimmed.includes(\"=\")) {\n    return undefined;\n  }\n\n  const separatorIndex = trimmed.indexOf(\"=\");\n  const key = trimmed.slice(0, separatorIndex).trim();\n  let value = trimmed.slice(separatorIndex + 1).trim();\n\n  const quote = value[0];\n\n  if (\n    (quote === '\"' || quote === \"'\" || quote === \"`\") &&\n    value.length > 1 &&\n    value.endsWith(quote)\n  ) {\n    value = value.slice(1, -1);\n  }\n\n  return [key, value];\n}\n\n/**\n * Which of the given `.env` files' keys lost to a value the ambient process\n * environment already carried.\n *\n * `snapshot` must be captured BEFORE `loadEnv()` runs: the loader writes into\n * `process.env` for every key the file supplies, so a snapshot taken\n * afterwards can no longer tell an ambient override from a value the loader\n * itself just wrote.\n *\n * `files` should be given in the same order `loadEnv()` actually reads them\n * (`.env.shared` first, then the applicable `.env`/`.env.<NODE_ENV>`), so a\n * key declared in more than one file resolves to the value the real loader\n * would have used absent any ambient override.\n */\nexport function detectEnvironmentOverrides(\n  files: string[],\n  snapshot: NodeJS.ProcessEnv,\n): EnvironmentOverride[] {\n  const fileValues = new Map<string, string>();\n\n  for (const file of files) {\n    if (!existsSync(file)) {\n      continue;\n    }\n\n    const lines = readFileSync(file, \"utf8\").split(/\\r\\n|\\n/);\n\n    for (const line of lines) {\n      const parsed = parseEnvLine(line);\n\n      if (!parsed) {\n        continue;\n      }\n\n      fileValues.set(parsed[0], parsed[1]);\n    }\n  }\n\n  const overrides: EnvironmentOverride[] = [];\n\n  for (const [key, fileValue] of fileValues) {\n    if (!Object.prototype.hasOwnProperty.call(snapshot, key)) {\n      continue;\n    }\n\n    const effectiveValue = snapshot[key] as string;\n\n    if (effectiveValue !== fileValue) {\n      overrides.push({ key, effectiveValue, fileValue });\n    }\n  }\n\n  return overrides;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,SAAS,aAAa,MAA4C;CAChE,MAAM,UAAU,KAAK,KAAK;CAE1B,IAAI,CAAC,WAAW,QAAQ,WAAW,GAAG,KAAK,CAAC,QAAQ,SAAS,GAAG,GAC9D;CAGF,MAAM,iBAAiB,QAAQ,QAAQ,GAAG;CAC1C,MAAM,MAAM,QAAQ,MAAM,GAAG,cAAc,CAAC,CAAC,KAAK;CAClD,IAAI,QAAQ,QAAQ,MAAM,iBAAiB,CAAC,CAAC,CAAC,KAAK;CAEnD,MAAM,QAAQ,MAAM;CAEpB,KACG,UAAU,QAAO,UAAU,OAAO,UAAU,QAC7C,MAAM,SAAS,KACf,MAAM,SAAS,KAAK,GAEpB,QAAQ,MAAM,MAAM,GAAG,EAAE;CAG3B,OAAO,CAAC,KAAK,KAAK;AACpB;;;;;;;;;;;;;;;AAgBA,SAAgB,2BACd,OACA,UACuB;CACvB,MAAM,6BAAa,IAAI,IAAoB;CAE3C,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,CAAC,WAAW,IAAI,GAClB;EAGF,MAAM,QAAQ,aAAa,MAAM,MAAM,CAAC,CAAC,MAAM,SAAS;EAExD,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,SAAS,aAAa,IAAI;GAEhC,IAAI,CAAC,QACH;GAGF,WAAW,IAAI,OAAO,IAAI,OAAO,EAAE;EACrC;CACF;CAEA,MAAM,YAAmC,CAAC;CAE1C,KAAK,MAAM,CAAC,KAAK,cAAc,YAAY;EACzC,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,UAAU,GAAG,GACrD;EAGF,MAAM,iBAAiB,SAAS;EAEhC,IAAI,mBAAmB,WACrB,UAAU,KAAK;GAAE;GAAK;GAAgB;EAAU,CAAC;CAErD;CAEA,OAAO;AACT"}

package/esm/utils/load-environment.mjs

@@ -1,3 +1,5 @@
+import { detectEnvironmentOverrides } from "./detect-environment-overrides.mjs";
+import { reportEnvironmentOverrides } from "./report-environment-overrides.mjs";
 import { loadEnv } from "@mongez/dotenv";
 import path from "node:path";
 import { existsSync } from "node:fs";
@@ -44,6 +46,26 @@ function candidateEnvFiles(directory) {
 	return files;
 }
 /**
+* The files `loadEnv()` will actually read, in its own read order.
+*
+* Differs from {@link candidateEnvFiles}, which lists every candidate to
+* answer "is there anything to load at all". `loadEnv()` itself only ever
+* reads `.env.shared` (if present) plus ONE of `.env.<NODE_ENV>` /
+* `.env` — the NODE_ENV-specific file when it exists, `.env` otherwise —
+* never both. Override detection has to mirror that exactly, or a key
+* declared only in a file `loadEnv()` would not have touched could be
+* reported as having "lost" a comparison it was never actually part of.
+*/
+function resolveLoadedEnvFiles(directory) {
+	const files = [];
+	const sharedFile = path.join(directory, ".env.shared");
+	if (existsSync(sharedFile)) files.push(sharedFile);
+	const nodeEnvFile = process.env.NODE_ENV ? path.join(directory, `.env.${process.env.NODE_ENV}`) : void 0;
+	const derivedFile = nodeEnvFile && existsSync(nodeEnvFile) ? nodeEnvFile : path.join(directory, ".env");
+	if (existsSync(derivedFile)) files.push(derivedFile);
+	return files;
+}
+/**
 * Whether this process has already loaded its env files.
 *
 * Two callers reach here on a bootstrapping command — the CLI preload phase and
@@ -79,6 +101,8 @@ async function loadEnvironmentFiles(directory = process.cwd()) {
 	if (environmentLoaded) return;
 	if (!candidateEnvFiles(directory).some((file) => existsSync(file))) return;
 	environmentLoaded = true;
+	const processEnvironmentSnapshot = { ...process.env };
+	reportEnvironmentOverrides(detectEnvironmentOverrides(resolveLoadedEnvFiles(directory), processEnvironmentSnapshot));
 	await loadEnv(void 0, {
 		...environmentLoaderOptions,
 		dir: directory

package/esm/utils/load-environment.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-environment.mjs","names":[],"sources":["../../../../../../../core/src/utils/load-environment.ts"],"sourcesContent":["import { loadEnv, type EnvLoaderOptions } from \"@mongez/dotenv\";\nimport { existsSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/**\n * Core's env precedence policy, in one place because two callers load env:\n * this module at boot, and the dev server when an `.env` file changes.\n *\n * `@mongez/dotenv` defaults to `precedence: \"file-wins\"`, which is backwards.\n * The `.env` file is a checked-in DEFAULT; a variable already exported into\n * `process.env` is the deliberate, situational override — a second instance on\n * another port, CI pointed at another database, a container's configuration.\n * Under the default, `PORT=6060 warlock dev` produced a server on the `.env`\n * file's 3000 and said nothing. A default that silently beats an explicit\n * instruction is the wrong way round, so core opts into `process-wins`:\n * the file supplies only the keys the environment does not already carry.\n *\n * EMPTY STRING — `FOO=` in the environment counts as SET, and wins, so the\n * file's value is discarded and `env(\"FOO\")` returns `\"\"`. Chosen over\n * \"empty means absent\" because the loader cannot tell a deliberate blanking\n * from an accident, and only one of the two readings is expressible: an\n * operator who wants the file's value can unset the variable, whereas under\n * \"empty means absent\" an operator who wants a blank value has no way to ask\n * for one. It also matches POSIX (an exported empty variable is set), dotenv,\n * dotenv-flow and Vite. Note the consequence: a blank export beats the second\n * argument too, so `env(\"FOO\", \"fallback\")` yields `\"\"`, not the fallback.\n *\n * Keys this loader itself wrote are tracked by the library and are NOT treated\n * as process-provided, so editing `.env` during a dev session still takes\n * effect on reload rather than being pinned by the previous load's own writes.\n */\nexport const environmentLoaderOptions: EnvLoaderOptions = {\n  precedence: \"process-wins\",\n};\n\n/**\n * The files `loadEnv()` will look for, in the order it considers them.\n *\n * Mirrors `@mongez/dotenv`'s own resolution — `.env.shared` first, then\n * `.env.<NODE_ENV>` if it exists, else plain `.env` — because the presence\n * check has to ask the same question the loader is about to ask.\n */\nfunction candidateEnvFiles(directory: string): string[] {\n  const files = [path.join(directory, \".env\"), path.join(directory, \".env.shared\")];\n\n  if (process.env.NODE_ENV) {\n    files.push(path.join(directory, `.env.${process.env.NODE_ENV}`));\n  }\n\n  return files;\n}\n\n/**\n * Whether this process has already loaded its env files.\n *\n * Two callers reach here on a bootstrapping command — the CLI preload phase and\n * `bootstrap()` — and `loadEnv()` defaults to `override: true`, so a second pass\n * re-parses the same files and re-writes `process.env`. Anything set in between\n * (a `warlock.config.ts` module body, a config file, an orchestrator) would be\n * silently clobbered by the later load. Same shape as the defect where a\n * caller's test-server port was overwritten by a re-read of `.env`.\n *\n * A deliberate reload is still possible and still used: the dev server calls\n * `loadEnv()` directly when an `.env` file changes on disk, which is a reload\n * the user asked for rather than an accidental second pass.\n */\nlet environmentLoaded = false;\n\n/**\n * Load `.env` files when there are any, and do nothing when there are not.\n *\n * Loads at most **once per process** — see {@link environmentLoaded}.\n *\n * `@mongez/dotenv`'s `loadEnvFile` **throws** when the file is absent. That was\n * survivable while only `dev` loaded env; now that every command loads it —\n * because `warlock.config.ts` calls `env()` in its module body and had been\n * evaluated against an empty store under every command — an unguarded call\n * would turn \"this project has no .env\" from a non-event into a hard failure\n * of `warlock build`. A project without a `.env` is legitimate: config files\n * carry defaults, and containers inject their own variables.\n *\n * The guard lives here rather than waiting on a fix in `@mongez/dotenv`: core\n * decides its own env policy and must not depend on another package's release\n * schedule to avoid crashing a working build.\n */\nexport async function loadEnvironmentFiles(directory: string = process.cwd()): Promise<void> {\n  if (environmentLoaded) {\n    return;\n  }\n\n  const hasEnvFile = candidateEnvFiles(directory).some((file) => existsSync(file));\n\n  if (!hasEnvFile) {\n    // Not latched: a project may create its `.env` between a command's preload\n    // and its bootstrap, and there is nothing to protect from a second override\n    // when the first pass loaded nothing.\n    return;\n  }\n\n  environmentLoaded = true;\n\n  // `dir` has to be forwarded: `loadEnv()` defaults it to `process.cwd()`, so\n  // without this the existence check above asks about `directory` while the\n  // load itself reads somewhere else entirely. Identical in production, where\n  // `directory` IS `process.cwd()`.\n  await loadEnv(undefined, { ...environmentLoaderOptions, dir: directory });\n}\n\n/**\n * Forget that env has been loaded, so the next call loads again.\n *\n * @internal For tests, which run many boots inside one process.\n */\nexport function resetLoadedEnvironment(): void {\n  environmentLoaded = false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,2BAA6C,EACxD,YAAY,eACd;;;;;;;;AASA,SAAS,kBAAkB,WAA6B;CACtD,MAAM,QAAQ,CAAC,KAAK,KAAK,WAAW,MAAM,GAAG,KAAK,KAAK,WAAW,aAAa,CAAC;CAEhF,IAAI,QAAQ,IAAI,UACd,MAAM,KAAK,KAAK,KAAK,WAAW,QAAQ,QAAQ,IAAI,UAAU,CAAC;CAGjE,OAAO;AACT;;;;;;;;;;;;;;;AAgBA,IAAI,oBAAoB;;;;;;;;;;;;;;;;;;AAmBxB,eAAsB,qBAAqB,YAAoB,QAAQ,IAAI,GAAkB;CAC3F,IAAI,mBACF;CAKF,IAAI,CAFe,kBAAkB,SAAS,CAAC,CAAC,MAAM,SAAS,WAAW,IAAI,CAEhE,GAIZ;CAGF,oBAAoB;CAMpB,MAAM,QAAQ,QAAW;EAAE,GAAG;EAA0B,KAAK;CAAU,CAAC;AAC1E"}
+{"version":3,"file":"load-environment.mjs","names":[],"sources":["../../../../../../../core/src/utils/load-environment.ts"],"sourcesContent":["import { loadEnv, type EnvLoaderOptions } from \"@mongez/dotenv\";\nimport { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { detectEnvironmentOverrides } from \"./detect-environment-overrides\";\nimport { reportEnvironmentOverrides } from \"./report-environment-overrides\";\n\n/**\n * Core's env precedence policy, in one place because two callers load env:\n * this module at boot, and the dev server when an `.env` file changes.\n *\n * `@mongez/dotenv` defaults to `precedence: \"file-wins\"`, which is backwards.\n * The `.env` file is a checked-in DEFAULT; a variable already exported into\n * `process.env` is the deliberate, situational override — a second instance on\n * another port, CI pointed at another database, a container's configuration.\n * Under the default, `PORT=6060 warlock dev` produced a server on the `.env`\n * file's 3000 and said nothing. A default that silently beats an explicit\n * instruction is the wrong way round, so core opts into `process-wins`:\n * the file supplies only the keys the environment does not already carry.\n *\n * EMPTY STRING — `FOO=` in the environment counts as SET, and wins, so the\n * file's value is discarded and `env(\"FOO\")` returns `\"\"`. Chosen over\n * \"empty means absent\" because the loader cannot tell a deliberate blanking\n * from an accident, and only one of the two readings is expressible: an\n * operator who wants the file's value can unset the variable, whereas under\n * \"empty means absent\" an operator who wants a blank value has no way to ask\n * for one. It also matches POSIX (an exported empty variable is set), dotenv,\n * dotenv-flow and Vite. Note the consequence: a blank export beats the second\n * argument too, so `env(\"FOO\", \"fallback\")` yields `\"\"`, not the fallback.\n *\n * Keys this loader itself wrote are tracked by the library and are NOT treated\n * as process-provided, so editing `.env` during a dev session still takes\n * effect on reload rather than being pinned by the previous load's own writes.\n */\nexport const environmentLoaderOptions: EnvLoaderOptions = {\n  precedence: \"process-wins\",\n};\n\n/**\n * The files `loadEnv()` will look for, in the order it considers them.\n *\n * Mirrors `@mongez/dotenv`'s own resolution — `.env.shared` first, then\n * `.env.<NODE_ENV>` if it exists, else plain `.env` — because the presence\n * check has to ask the same question the loader is about to ask.\n */\nfunction candidateEnvFiles(directory: string): string[] {\n  const files = [path.join(directory, \".env\"), path.join(directory, \".env.shared\")];\n\n  if (process.env.NODE_ENV) {\n    files.push(path.join(directory, `.env.${process.env.NODE_ENV}`));\n  }\n\n  return files;\n}\n\n/**\n * The files `loadEnv()` will actually read, in its own read order.\n *\n * Differs from {@link candidateEnvFiles}, which lists every candidate to\n * answer \"is there anything to load at all\". `loadEnv()` itself only ever\n * reads `.env.shared` (if present) plus ONE of `.env.<NODE_ENV>` /\n * `.env` — the NODE_ENV-specific file when it exists, `.env` otherwise —\n * never both. Override detection has to mirror that exactly, or a key\n * declared only in a file `loadEnv()` would not have touched could be\n * reported as having \"lost\" a comparison it was never actually part of.\n */\nfunction resolveLoadedEnvFiles(directory: string): string[] {\n  const files: string[] = [];\n  const sharedFile = path.join(directory, \".env.shared\");\n\n  if (existsSync(sharedFile)) {\n    files.push(sharedFile);\n  }\n\n  const nodeEnvFile = process.env.NODE_ENV\n    ? path.join(directory, `.env.${process.env.NODE_ENV}`)\n    : undefined;\n  const derivedFile =\n    nodeEnvFile && existsSync(nodeEnvFile) ? nodeEnvFile : path.join(directory, \".env\");\n\n  if (existsSync(derivedFile)) {\n    files.push(derivedFile);\n  }\n\n  return files;\n}\n\n/**\n * Whether this process has already loaded its env files.\n *\n * Two callers reach here on a bootstrapping command — the CLI preload phase and\n * `bootstrap()` — and `loadEnv()` defaults to `override: true`, so a second pass\n * re-parses the same files and re-writes `process.env`. Anything set in between\n * (a `warlock.config.ts` module body, a config file, an orchestrator) would be\n * silently clobbered by the later load. Same shape as the defect where a\n * caller's test-server port was overwritten by a re-read of `.env`.\n *\n * A deliberate reload is still possible and still used: the dev server calls\n * `loadEnv()` directly when an `.env` file changes on disk, which is a reload\n * the user asked for rather than an accidental second pass.\n */\nlet environmentLoaded = false;\n\n/**\n * Load `.env` files when there are any, and do nothing when there are not.\n *\n * Loads at most **once per process** — see {@link environmentLoaded}.\n *\n * `@mongez/dotenv`'s `loadEnvFile` **throws** when the file is absent. That was\n * survivable while only `dev` loaded env; now that every command loads it —\n * because `warlock.config.ts` calls `env()` in its module body and had been\n * evaluated against an empty store under every command — an unguarded call\n * would turn \"this project has no .env\" from a non-event into a hard failure\n * of `warlock build`. A project without a `.env` is legitimate: config files\n * carry defaults, and containers inject their own variables.\n *\n * The guard lives here rather than waiting on a fix in `@mongez/dotenv`: core\n * decides its own env policy and must not depend on another package's release\n * schedule to avoid crashing a working build.\n */\nexport async function loadEnvironmentFiles(directory: string = process.cwd()): Promise<void> {\n  if (environmentLoaded) {\n    return;\n  }\n\n  const hasEnvFile = candidateEnvFiles(directory).some((file) => existsSync(file));\n\n  if (!hasEnvFile) {\n    // Not latched: a project may create its `.env` between a command's preload\n    // and its bootstrap, and there is nothing to protect from a second override\n    // when the first pass loaded nothing.\n    return;\n  }\n\n  environmentLoaded = true;\n\n  // Snapshot BEFORE `loadEnv()` runs: the loader writes into `process.env` for\n  // every key its files supply, so a snapshot taken afterwards could no\n  // longer distinguish an ambient override from a value the loader itself\n  // just wrote — see `detectEnvironmentOverrides`.\n  const processEnvironmentSnapshot = { ...process.env };\n\n  // The precedence itself is correct (see `environmentLoaderOptions` above);\n  // the defect this guards against is the SILENCE — `.env` losing to an\n  // ambient value with no diagnostic at all.\n  reportEnvironmentOverrides(\n    detectEnvironmentOverrides(resolveLoadedEnvFiles(directory), processEnvironmentSnapshot),\n  );\n\n  // `dir` has to be forwarded: `loadEnv()` defaults it to `process.cwd()`, so\n  // without this the existence check above asks about `directory` while the\n  // load itself reads somewhere else entirely. Identical in production, where\n  // `directory` IS `process.cwd()`.\n  await loadEnv(undefined, { ...environmentLoaderOptions, dir: directory });\n}\n\n/**\n * Forget that env has been loaded, so the next call loads again.\n *\n * @internal For tests, which run many boots inside one process.\n */\nexport function resetLoadedEnvironment(): void {\n  environmentLoaded = false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,MAAa,2BAA6C,EACxD,YAAY,eACd;;;;;;;;AASA,SAAS,kBAAkB,WAA6B;CACtD,MAAM,QAAQ,CAAC,KAAK,KAAK,WAAW,MAAM,GAAG,KAAK,KAAK,WAAW,aAAa,CAAC;CAEhF,IAAI,QAAQ,IAAI,UACd,MAAM,KAAK,KAAK,KAAK,WAAW,QAAQ,QAAQ,IAAI,UAAU,CAAC;CAGjE,OAAO;AACT;;;;;;;;;;;;AAaA,SAAS,sBAAsB,WAA6B;CAC1D,MAAM,QAAkB,CAAC;CACzB,MAAM,aAAa,KAAK,KAAK,WAAW,aAAa;CAErD,IAAI,WAAW,UAAU,GACvB,MAAM,KAAK,UAAU;CAGvB,MAAM,cAAc,QAAQ,IAAI,WAC5B,KAAK,KAAK,WAAW,QAAQ,QAAQ,IAAI,UAAU,IACnD;CACJ,MAAM,cACJ,eAAe,WAAW,WAAW,IAAI,cAAc,KAAK,KAAK,WAAW,MAAM;CAEpF,IAAI,WAAW,WAAW,GACxB,MAAM,KAAK,WAAW;CAGxB,OAAO;AACT;;;;;;;;;;;;;;;AAgBA,IAAI,oBAAoB;;;;;;;;;;;;;;;;;;AAmBxB,eAAsB,qBAAqB,YAAoB,QAAQ,IAAI,GAAkB;CAC3F,IAAI,mBACF;CAKF,IAAI,CAFe,kBAAkB,SAAS,CAAC,CAAC,MAAM,SAAS,WAAW,IAAI,CAEhE,GAIZ;CAGF,oBAAoB;CAMpB,MAAM,6BAA6B,EAAE,GAAG,QAAQ,IAAI;CAKpD,2BACE,2BAA2B,sBAAsB,SAAS,GAAG,0BAA0B,CACzF;CAMA,MAAM,QAAQ,QAAW;EAAE,GAAG;EAA0B,KAAK;CAAU,CAAC;AAC1E"}

package/esm/utils/report-environment-overrides.mjs

@@ -0,0 +1,30 @@
+//#region ../core/src/utils/report-environment-overrides.ts
+/**
+* Key names shaped like a secret. Matched values are redacted in the printed
+* line even though the key itself is still named — knowing WHICH secret was
+* overridden is useful, the value never is.
+*/
+const SECRET_KEY_PATTERN = /(PASSWORD|SECRET|TOKEN|KEY|CREDENTIAL|DSN|CONNECTION_STRING)/i;
+const REDACTED_PLACEHOLDER = "<redacted>";
+/**
+* Tell the developer, one line per key, which `.env` values the ambient
+* process environment silently beat.
+*
+* Uses `console.warn` (stderr) rather than the `log` singleton on purpose:
+* this runs from `loadEnvironmentFiles()`, ahead of the logger connector in
+* the boot sequence, so any channel configured through `log.*` has nowhere to
+* deliver to yet. Same reasoning as `console.error` in
+* `src/http/boot-port-preflight.ts`.
+*/
+function reportEnvironmentOverrides(overrides) {
+	for (const override of overrides) {
+		const isSecretShaped = SECRET_KEY_PATTERN.test(override.key);
+		const effectiveValue = isSecretShaped ? REDACTED_PLACEHOLDER : override.effectiveValue;
+		const fileValue = isSecretShaped ? REDACTED_PLACEHOLDER : override.fileValue;
+		console.warn(`[env] ${override.key}=${effectiveValue} is in effect from the process environment, overriding .env's ${override.key}=${fileValue}`);
+	}
+}
+
+//#endregion
+export { reportEnvironmentOverrides };
+//# sourceMappingURL=report-environment-overrides.mjs.map

package/esm/utils/report-environment-overrides.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-environment-overrides.mjs","names":[],"sources":["../../../../../../../core/src/utils/report-environment-overrides.ts"],"sourcesContent":["import type { EnvironmentOverride } from \"./detect-environment-overrides\";\n\n/**\n * Key names shaped like a secret. Matched values are redacted in the printed\n * line even though the key itself is still named — knowing WHICH secret was\n * overridden is useful, the value never is.\n */\nconst SECRET_KEY_PATTERN = /(PASSWORD|SECRET|TOKEN|KEY|CREDENTIAL|DSN|CONNECTION_STRING)/i;\n\nconst REDACTED_PLACEHOLDER = \"<redacted>\";\n\n/**\n * Tell the developer, one line per key, which `.env` values the ambient\n * process environment silently beat.\n *\n * Uses `console.warn` (stderr) rather than the `log` singleton on purpose:\n * this runs from `loadEnvironmentFiles()`, ahead of the logger connector in\n * the boot sequence, so any channel configured through `log.*` has nowhere to\n * deliver to yet. Same reasoning as `console.error` in\n * `src/http/boot-port-preflight.ts`.\n */\nexport function reportEnvironmentOverrides(overrides: EnvironmentOverride[]): void {\n  for (const override of overrides) {\n    const isSecretShaped = SECRET_KEY_PATTERN.test(override.key);\n    const effectiveValue = isSecretShaped ? REDACTED_PLACEHOLDER : override.effectiveValue;\n    const fileValue = isSecretShaped ? REDACTED_PLACEHOLDER : override.fileValue;\n\n    console.warn(\n      `[env] ${override.key}=${effectiveValue} is in effect from the process environment, overriding .env's ${override.key}=${fileValue}`,\n    );\n  }\n}\n"],"mappings":";;;;;;AAOA,MAAM,qBAAqB;AAE3B,MAAM,uBAAuB;;;;;;;;;;;AAY7B,SAAgB,2BAA2B,WAAwC;CACjF,KAAK,MAAM,YAAY,WAAW;EAChC,MAAM,iBAAiB,mBAAmB,KAAK,SAAS,GAAG;EAC3D,MAAM,iBAAiB,iBAAiB,uBAAuB,SAAS;EACxE,MAAM,YAAY,iBAAiB,uBAAuB,SAAS;EAEnE,QAAQ,KACN,SAAS,SAAS,IAAI,GAAG,eAAe,gEAAgE,SAAS,IAAI,GAAG,WAC1H;CACF;AACF"}

package/esm/validation/types.d.mts

@@ -22,7 +22,10 @@ declare module "@warlock.js/seal" {
     file: (errorMessage?: string) => FileValidator & StandardSchemaV1<UploadedFile>;
     localized: <T extends BaseValidator = ScalarValidator & StandardSchemaV1<string | number | boolean>>(valueValidator?: T, errorMessage?: string) => ArrayValidator & {
       validator: LocalizedEntryValidator<T>;
-    };
+    } & StandardSchemaV1<Array<{
+      localeCode: string;
+      value: Infer<T>;
+    }>>;
   }
   interface ScalarValidator {
     /** Value must be unique in database except current user */

package/esm/validation/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/validation/types.ts"],"mappings":";;;;;;;;;;;;KAmCK,uBAAA,WAAkC,aAAA,IAAiB,eAAA;EACtD,UAAA,EAAY,eAAA,GAAkB,gBAAA;EAC9B,KAAA,EAAO,CAAA;AAAA,KAEP,gBAAA;EACE,UAAA;EACA,KAAA,EAAO,KAAA,CAAM,CAAA;AAAA;AAAA;EAAA,UAME,UAAA;IACf,IAAA,GAAO,YAAA,cAA0B,aAAA,GAAgB,gBAAA,CAAiB,YAAA;IAClE,SAAA,aACY,aAAA,GAAgB,eAAA,GAAkB,gBAAA,6BAE5C,cAAA,GAAiB,CAAA,EACjB,YAAA,cACG,cAAA;MACH,SAAA,EAAW,uBAAA,CAAwB,CAAA;IAAA;EAAA;EAAA,UAI7B,eAAA;IAlBR;IAoBA,uBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,kCAAA;MACpB,YAAA;IAAA;IAvBU;IA4Bd,qBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,gCAAA;MACpB,YAAA;IAAA;IAxB6B;IA6BjC,uBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,kCAAA;MACpB,YAAA;IAAA;IA9BwB;IAmC5B,qBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,gCAAA;MACpB,YAAA;IAAA;EAAA;EAAA,UAMI,eAAA;IACR,uBAAA,EAAyB,eAAA;IACzB,qBAAA,EAAuB,eAAA;IACvB,uBAAA,EAAyB,eAAA;IACzB,qBAAA,EAAuB,eAAA;EAAA;AAAA;AAAA,KAYf,uBAAA;EAhCY;;;;;;EAwCtB,gBAAA;EA/BkB;;;;;;EAsClB,cAAA;EA9EiB;;;;EAmFjB,cAAA;EAlFoE;;;;EAuFpE,aAAA,GAAgB,qBAAA;EArFgC;;;EAyFhD,kBAAA,GAAqB,0BAA0B;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/validation/types.ts"],"mappings":";;;;;;;;;;;;KAmCK,uBAAA,WAAkC,aAAA,IAAiB,eAAA;EACtD,UAAA,EAAY,eAAA,GAAkB,gBAAA;EAC9B,KAAA,EAAO,CAAA;AAAA,KAEP,gBAAA;EACE,UAAA;EACA,KAAA,EAAO,KAAA,CAAM,CAAA;AAAA;AAAA;EAAA,UAME,UAAA;IACf,IAAA,GAAO,YAAA,cAA0B,aAAA,GAAgB,gBAAA,CAAiB,YAAA;IAClE,SAAA,aACY,aAAA,GAAgB,eAAA,GAAkB,gBAAA,6BAE5C,cAAA,GAAiB,CAAA,EACjB,YAAA,cACG,cAAA;MACH,SAAA,EAAW,uBAAA,CAAwB,CAAA;IAAA,IACjC,gBAAA,CACA,KAAA;MACE,UAAA;MACA,KAAA,EAAO,KAAA,CAAM,CAAA;IAAA;EAAA;EAAA,UAKX,eAAA;IAvBM;IAyBd,uBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,kCAAA;MACpB,YAAA;IAAA;IA5BU;IAiCd,qBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,gCAAA;MACpB,YAAA;IAAA;IA3BQ;IAgCZ,uBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,kCAAA;MACpB,YAAA;IAAA;IA/BC;IAoCL,qBAAA,CACE,KAAA,EAAO,UAAA,CAAW,KAAA,YAClB,WAAA,GAAc,OAAA,CAAQ,gCAAA;MACpB,YAAA;IAAA;EAAA;EAAA,UAMI,eAAA;IACR,uBAAA,EAAyB,eAAA;IACzB,qBAAA,EAAuB,eAAA;IACvB,uBAAA,EAAyB,eAAA;IACzB,qBAAA,EAAuB,eAAA;EAAA;AAAA;AAAA,KAYf,uBAAA;EAvCQ;;;;;;EA+ClB,gBAAA;EA/B0B;;;;;;EAsC1B,cAAA;EA3BwC;;;;EAgCxC,cAAA;EAvFmD;;;;EA4FnD,aAAA,GAAgB,qBAAA;EA1Fc;;;EA8F9B,kBAAA,GAAqB,0BAA0B;AAAA"}

package/llms-full.txt

@@ -3586,7 +3586,7 @@ The third line is conditional on the parent having actually seen child output. W
 
 That distinction is the point of the change: an unhelpful "see above" printed above an empty terminal used to be the entire diagnostic.
 
-**Port already in use.** The HTTP connector preflights the port immediately before `listen()`, so a collision is named rather than surfacing as a raw `EADDRINUSE` from inside Fastify:
+**Port already in use.** The port is preflighted twice: once **before the early-phase connectors**, so a collision is reported without waiting for the database to connect, and again in the HTTP connector immediately before `listen()`, because a port can be taken in the seconds between the two. Either way the collision is named rather than surfacing as a raw `EADDRINUSE` from inside Fastify:
 
 ```
 EADDRINUSE: Port 3000 is already in use on 127.0.0.1. Stop the dev server (or whatever
@@ -3594,7 +3594,15 @@ else is listening on port 3000) and run again, or start on a free port — e.g.
 startHttpTestServer({ port: 3001 }).
 ```
 
-The connector logs it fatally and exits `1`; the supervisor forwards that text and then prints the failure summary above it. `EACCES` on the port is treated the same way as `EADDRINUSE` (a privileged port you may not bind is also "not available"); anything else the probe throws is rethrown untouched.
+**The process exits `78` (`EX_CONFIG`), and `warlock dev`'s supervisor treats that as terminal — it prints once and stops rather than restarting.** That code is the counterpart of `75`, which a worker uses to ask for a fresh process. The distinction is the point: a code error is worth restarting, and a *startup precondition* — a port held by something else, a port value that is not a port, a boot validator that rejected — cannot change because we tried again six seconds later. Retrying one only reprints the diagnostic and then scrolls it away.
+
+`EACCES` on the port is treated the same way as `EADDRINUSE` (a privileged port you may not bind is also "not available"); anything else the probe throws is rethrown untouched.
+
+**A configured port is normalised before anything binds.** `env()` coerces a `.env` value to a number only when it round-trips exactly, so `HTTP_PORT=03999`, `" 3999"`, `+3999` and `1e3` all arrive as strings. They are resolved to a canonical integer first — used for the preflight, for `listen()`, and for the port reported to a supervisor — and a value that cannot become a usable port fails naming it. When the raw value was not already canonical, one line says so:
+
+```
+Configured http.port "03999" normalised to 3999.
+```
 
 ### How readiness is reported
 

package/package.json

@@ -25,13 +25,13 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^2.1.4",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/auth": "5.3.1",
-    "@warlock.js/cache": "5.3.1",
-    "@warlock.js/cascade": "5.3.1",
-    "@warlock.js/context": "5.3.1",
-    "@warlock.js/logger": "5.3.1",
-    "@warlock.js/seal": "5.3.1",
-    "@warlock.js/fs": "5.3.1",
+    "@warlock.js/auth": "5.4.0",
+    "@warlock.js/cache": "5.4.0",
+    "@warlock.js/cascade": "5.4.0",
+    "@warlock.js/context": "5.4.0",
+    "@warlock.js/logger": "5.4.0",
+    "@warlock.js/seal": "5.4.0",
+    "@warlock.js/fs": "5.4.0",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
     "es-module-lexer": "^2.0.0",
@@ -57,10 +57,10 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/herald": "5.3.1",
-    "@warlock.js/ai": "5.3.1",
-    "@warlock.js/access": "5.3.1",
-    "@warlock.js/notifications": "5.3.1"
+    "@warlock.js/herald": "5.4.0",
+    "@warlock.js/ai": "5.4.0",
+    "@warlock.js/access": "5.4.0",
+    "@warlock.js/notifications": "5.4.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -123,7 +123,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/run-app/SKILL.md

@@ -309,7 +309,7 @@ The third line is conditional on the parent having actually seen child output. W
 
 That distinction is the point of the change: an unhelpful "see above" printed above an empty terminal used to be the entire diagnostic.
 
-**Port already in use.** The HTTP connector preflights the port immediately before `listen()`, so a collision is named rather than surfacing as a raw `EADDRINUSE` from inside Fastify:
+**Port already in use.** The port is preflighted twice: once **before the early-phase connectors**, so a collision is reported without waiting for the database to connect, and again in the HTTP connector immediately before `listen()`, because a port can be taken in the seconds between the two. Either way the collision is named rather than surfacing as a raw `EADDRINUSE` from inside Fastify:
 
 ```
 EADDRINUSE: Port 3000 is already in use on 127.0.0.1. Stop the dev server (or whatever
@@ -317,7 +317,15 @@ else is listening on port 3000) and run again, or start on a free port — e.g.
 startHttpTestServer({ port: 3001 }).
 ```
 
-The connector logs it fatally and exits `1`; the supervisor forwards that text and then prints the failure summary above it. `EACCES` on the port is treated the same way as `EADDRINUSE` (a privileged port you may not bind is also "not available"); anything else the probe throws is rethrown untouched.
+**The process exits `78` (`EX_CONFIG`), and `warlock dev`'s supervisor treats that as terminal — it prints once and stops rather than restarting.** That code is the counterpart of `75`, which a worker uses to ask for a fresh process. The distinction is the point: a code error is worth restarting, and a *startup precondition* — a port held by something else, a port value that is not a port, a boot validator that rejected — cannot change because we tried again six seconds later. Retrying one only reprints the diagnostic and then scrolls it away.
+
+`EACCES` on the port is treated the same way as `EADDRINUSE` (a privileged port you may not bind is also "not available"); anything else the probe throws is rethrown untouched.
+
+**A configured port is normalised before anything binds.** `env()` coerces a `.env` value to a number only when it round-trips exactly, so `HTTP_PORT=03999`, `" 3999"`, `+3999` and `1e3` all arrive as strings. They are resolved to a canonical integer first — used for the preflight, for `listen()`, and for the port reported to a supervisor — and a value that cannot become a usable port fails naming it. When the raw value was not already canonical, one line says so:
+
+```
+Configured http.port "03999" normalised to 3999.
+```
 
 ### How readiness is reported