@warlock.js/core 4.10.0 → 4.11.0

package/esm/tests/start-http-development-server.d.mts

@@ -1,9 +1,22 @@
 //#region ../core/src/tests/start-http-development-server.d.ts
+type StartHttpTestServerOptions = {
+  /**
+   * Port the test server binds to, overriding `http.port`.
+   *
+   * Needed because the server cannot be moved from outside: this function
+   * bootstraps the app itself, and that bootstrap re-reads `.env`.
+   */
+  port?: number;
+};
 /**
  * Start the HTTP test server (minimal - no file watching)
  * Call this in Vitest's globalSetup
+ *
+ * @example
+ * // run this suite on its own port, whatever `.env` says
+ * await startHttpTestServer({ port: 3999 });
  */
-declare function startHttpTestServer(): Promise<void>;
+declare function startHttpTestServer(options?: StartHttpTestServerOptions): Promise<void>;
 /**
  * Stop the HTTP test server
  * Call this in Vitest's globalTeardown
@@ -14,5 +27,5 @@ declare function stopHttpTestServer(): Promise<void>;
  */
 declare function isTestServerRunning(): boolean;
 //#endregion
-export { isTestServerRunning, startHttpTestServer, stopHttpTestServer };
+export { StartHttpTestServerOptions, isTestServerRunning, startHttpTestServer, stopHttpTestServer };
 //# sourceMappingURL=start-http-development-server.d.mts.map

package/esm/tests/start-http-development-server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"start-http-development-server.d.mts","names":[],"sources":["../../../../../../../core/src/tests/start-http-development-server.ts"],"mappings":";;AAyBA;;;iBAAsB,mBAAA,IAAuB,OAAO;AAAA;AAgDpD;;;AAhDoD,iBAgD9B,kBAAA,IAAsB,OAAO;AAAA;AAmBnD;;AAnBmD,iBAmBnC,mBAAA"}
+{"version":3,"file":"start-http-development-server.d.mts","names":[],"sources":["../../../../../../../core/src/tests/start-http-development-server.ts"],"mappings":";KAwBY,0BAAA;EAAA;;;;AAON;AAuDN;EAvDE,IAAI;AAAA;;;;;;AAyDI;AA8CV;;iBAhDsB,mBAAA,CACpB,OAAA,GAAS,0BAAA,GACR,OAAO;;AA8CyC;AAoBnD;;iBApBsB,kBAAA,IAAsB,OAAO;;AAoBhB;;iBAAnB,mBAAA"}

package/esm/tests/start-http-development-server.mjs

@@ -1,11 +1,14 @@
 import { Application } from "../application/application.mjs";
 import "../application/index.mjs";
+import { assertPortIsAvailable } from "../http/port-preflight.mjs";
 import { bootstrap } from "../bootstrap.mjs";
 import { ConnectorLifecyclePhase } from "../connectors/types.mjs";
 import { connectorsManager } from "../connectors/connectors-manager.mjs";
 import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
 import { filesOrchestrator } from "../dev-server/files-orchestrator.mjs";
 import { loadConfigFiles } from "../config/load-config-files.mjs";
+import { publishTestServerPort, withdrawTestServerPort } from "./test-server-port-channel.mjs";
+import config from "@mongez/config";
 
 //#region ../core/src/tests/start-http-development-server.ts
 /**
@@ -21,30 +24,53 @@ import { loadConfigFiles } from "../config/load-config-files.mjs";
 */
 let isServerRunning = false;
 /**
+* Apply the caller's port and preflight the bind.
+*
+* Called at the last moment before the HTTP connector binds, and that timing is
+* the fix: `bootstrap()` re-reads `.env` through `loadEnv()` (dotenv overrides
+* by default), and `src/config/http.ts` then resolves its port from that store,
+* so anything the caller set earlier is gone by the time the port is read.
+* Writing into `config` here is also the only channel that works — assigning
+* `process.env.HTTP_PORT` has no effect, since `env()` reads dotenv's own store
+* and never falls back to `process.env`.
+*/
+async function applyTestServerPort(port) {
+	if (!config.get("http")) {
+		if (port !== void 0) throw new Error(`startHttpTestServer({ port: ${port} }) was given a port, but this app has no \`http\` config, so no HTTP server is started. Add \`src/config/http.ts\` first.`);
+		return;
+	}
+	if (port !== void 0) config.set("http.port", port);
+	const resolvedPort = config.get("http.port");
+	if (typeof resolvedPort !== "number" || resolvedPort <= 0) return;
+	await assertPortIsAvailable(resolvedPort, config.get("http.host") || "localhost");
+	publishTestServerPort(resolvedPort);
+}
+/**
 * Start the HTTP test server (minimal - no file watching)
 * Call this in Vitest's globalSetup
+*
+* @example
+* // run this suite on its own port, whatever `.env` says
+* await startHttpTestServer({ port: 3999 });
 */
-async function startHttpTestServer() {
+async function startHttpTestServer(options = {}) {
 	if (isServerRunning) {
 		console.log("[test-server] Server already running, skipping start");
 		return;
 	}
 	console.log("[test-server] Starting HTTP test server...");
-	try {
-		Application.setRuntimeStrategy("development");
-		Application.setEnvironment("test");
-		await warlockConfigManager.load();
-		await bootstrap();
-		await filesOrchestrator.init();
-		await filesOrchestrator.initializeAll();
-		await loadConfigFiles(true);
-		await connectorsManager.startPhase("early");
-		await filesOrchestrator.moduleLoader.loadAll();
-		await connectorsManager.startPhase("late");
-		isServerRunning = true;
-	} catch (error) {
-		throw error;
-	}
+	Application.setRuntimeStrategy("development");
+	Application.setEnvironment("test");
+	await warlockConfigManager.load();
+	await bootstrap();
+	await filesOrchestrator.init();
+	await filesOrchestrator.initializeAll();
+	await loadConfigFiles(true);
+	await connectorsManager.startPhase("early");
+	await filesOrchestrator.moduleLoader.loadAll();
+	await applyTestServerPort(options.port);
+	await connectorsManager.startPhase("late");
+	isServerRunning = true;
 }
 /**
 * Stop the HTTP test server
@@ -57,6 +83,7 @@ async function stopHttpTestServer() {
 	}
 	try {
 		await connectorsManager.shutdown();
+		withdrawTestServerPort();
 		isServerRunning = false;
 		console.log("[test-server] HTTP test server stopped");
 	} catch (error) {

package/esm/tests/start-http-development-server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"start-http-development-server.mjs","names":[],"sources":["../../../../../../../core/src/tests/start-http-development-server.ts"],"sourcesContent":["/**\r\n * HTTP Test Server\r\n *\r\n * Starts a minimal HTTP server for testing.\r\n * Unlike the full DevelopmentServer, this:\r\n * - Does NOT watch files\r\n * - Does NOT do HMR\r\n * - Only starts connectors needed for HTTP requests\r\n *\r\n * Used in Vitest's globalSetup to start server once for all test workers.\r\n */\r\nimport { Application } from \"../application\";\r\nimport { bootstrap } from \"../bootstrap\";\r\nimport { loadConfigFiles } from \"../config/load-config-files\";\r\nimport { connectorsManager } from \"../connectors/connectors-manager\";\r\nimport { ConnectorLifecyclePhase } from \"../connectors/types\";\r\nimport { filesOrchestrator } from \"../dev-server/files-orchestrator\";\r\nimport { warlockConfigManager } from \"../warlock-config/warlock-config.manager\";\r\n\r\nlet isServerRunning = false;\r\n\r\n/**\r\n * Start the HTTP test server (minimal - no file watching)\r\n * Call this in Vitest's globalSetup\r\n */\r\nexport async function startHttpTestServer(): Promise<void> {\r\n  if (isServerRunning) {\r\n    console.log(\"[test-server] Server already running, skipping start\");\r\n    return;\r\n  }\r\n\r\n  console.log(\"[test-server] Starting HTTP test server...\");\r\n\r\n  try {\r\n    // Set environment\r\n    Application.setRuntimeStrategy(\"development\");\r\n    Application.setEnvironment(\"test\");\r\n\r\n    // Bootstrap (env, etc.)\r\n    await warlockConfigManager.load();\r\n    await bootstrap();\r\n\r\n    // Initialize file orchestrator (but don't watch)\r\n    await filesOrchestrator.init();\r\n    await filesOrchestrator.initializeAll();\r\n\r\n    // Load config files\r\n    await loadConfigFiles(true);\r\n\r\n    // Early-phase connectors (database, cache, logger, storage, mailer,\r\n    // herald) must start BEFORE app modules load: a module's `main.ts` boot\r\n    // side-effect can query the DB at import time, so the data source has to\r\n    // be registered first. This mirrors the dev/prod boot order (see\r\n    // `cli-commands.manager`, `production-builder`, and `DevelopmentServer`).\r\n    await connectorsManager.startPhase(ConnectorLifecyclePhase.Early);\r\n\r\n    // Load application modules (their boot side-effects now see a live DB).\r\n    await filesOrchestrator.moduleLoader.loadAll();\r\n\r\n    // Late-phase connectors (http, socket) bind after app code has\r\n    // registered its routes and listeners.\r\n    await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);\r\n\r\n    isServerRunning = true;\r\n  } catch (error) {\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * Stop the HTTP test server\r\n * Call this in Vitest's globalTeardown\r\n */\r\nexport async function stopHttpTestServer(): Promise<void> {\r\n  if (!isServerRunning) {\r\n    console.log(\"[test-server] No server to stop\");\r\n    return;\r\n  }\r\n\r\n  try {\r\n    await connectorsManager.shutdown();\r\n    isServerRunning = false;\r\n    console.log(\"[test-server] HTTP test server stopped\");\r\n  } catch (error) {\r\n    console.error(\"[test-server] Error stopping HTTP server:\", error);\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * Check if test server is running\r\n */\r\nexport function isTestServerRunning(): boolean {\r\n  return isServerRunning;\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAmBA,IAAI,kBAAkB;;;;;AAMtB,eAAsB,sBAAqC;CACzD,IAAI,iBAAiB;EACnB,QAAQ,IAAI,sDAAsD;EAClE;CACF;CAEA,QAAQ,IAAI,4CAA4C;CAExD,IAAI;EAEF,YAAY,mBAAmB,aAAa;EAC5C,YAAY,eAAe,MAAM;EAGjC,MAAM,qBAAqB,KAAK;EAChC,MAAM,UAAU;EAGhB,MAAM,kBAAkB,KAAK;EAC7B,MAAM,kBAAkB,cAAc;EAGtC,MAAM,gBAAgB,IAAI;EAO1B,MAAM,kBAAkB,kBAAwC;EAGhE,MAAM,kBAAkB,aAAa,QAAQ;EAI7C,MAAM,kBAAkB,iBAAuC;EAE/D,kBAAkB;CACpB,SAAS,OAAO;EACd,MAAM;CACR;AACF;;;;;AAMA,eAAsB,qBAAoC;CACxD,IAAI,CAAC,iBAAiB;EACpB,QAAQ,IAAI,iCAAiC;EAC7C;CACF;CAEA,IAAI;EACF,MAAM,kBAAkB,SAAS;EACjC,kBAAkB;EAClB,QAAQ,IAAI,wCAAwC;CACtD,SAAS,OAAO;EACd,QAAQ,MAAM,6CAA6C,KAAK;EAChE,MAAM;CACR;AACF;;;;AAKA,SAAgB,sBAA+B;CAC7C,OAAO;AACT"}
+{"version":3,"file":"start-http-development-server.mjs","names":[],"sources":["../../../../../../../core/src/tests/start-http-development-server.ts"],"sourcesContent":["/**\r\n * HTTP Test Server\r\n *\r\n * Starts a minimal HTTP server for testing.\r\n * Unlike the full DevelopmentServer, this:\r\n * - Does NOT watch files\r\n * - Does NOT do HMR\r\n * - Only starts connectors needed for HTTP requests\r\n *\r\n * Used in Vitest's globalSetup to start server once for all test workers.\r\n */\r\nimport config from \"@mongez/config\";\r\nimport { Application } from \"../application\";\r\nimport { bootstrap } from \"../bootstrap\";\r\nimport { loadConfigFiles } from \"../config/load-config-files\";\r\nimport { connectorsManager } from \"../connectors/connectors-manager\";\r\nimport { ConnectorLifecyclePhase } from \"../connectors/types\";\r\nimport { filesOrchestrator } from \"../dev-server/files-orchestrator\";\r\nimport { assertPortIsAvailable } from \"../http/port-preflight\";\r\nimport { warlockConfigManager } from \"../warlock-config/warlock-config.manager\";\r\nimport { publishTestServerPort, withdrawTestServerPort } from \"./test-server-port-channel\";\r\n\r\nlet isServerRunning = false;\r\n\r\nexport type StartHttpTestServerOptions = {\r\n  /**\r\n   * Port the test server binds to, overriding `http.port`.\r\n   *\r\n   * Needed because the server cannot be moved from outside: this function\r\n   * bootstraps the app itself, and that bootstrap re-reads `.env`.\r\n   */\r\n  port?: number;\r\n};\r\n\r\n/**\r\n * Apply the caller's port and preflight the bind.\r\n *\r\n * Called at the last moment before the HTTP connector binds, and that timing is\r\n * the fix: `bootstrap()` re-reads `.env` through `loadEnv()` (dotenv overrides\r\n * by default), and `src/config/http.ts` then resolves its port from that store,\r\n * so anything the caller set earlier is gone by the time the port is read.\r\n * Writing into `config` here is also the only channel that works — assigning\r\n * `process.env.HTTP_PORT` has no effect, since `env()` reads dotenv's own store\r\n * and never falls back to `process.env`.\r\n */\r\nasync function applyTestServerPort(port?: number): Promise<void> {\r\n  const httpConfig = config.get(\"http\");\r\n\r\n  if (!httpConfig) {\r\n    if (port !== undefined) {\r\n      throw new Error(\r\n        `startHttpTestServer({ port: ${port} }) was given a port, but this app has no \\`http\\` config, so no HTTP server is started. Add \\`src/config/http.ts\\` first.`,\r\n      );\r\n    }\r\n\r\n    return;\r\n  }\r\n\r\n  if (port !== undefined) {\r\n    config.set(\"http.port\", port);\r\n  }\r\n\r\n  const resolvedPort = config.get(\"http.port\");\r\n\r\n  // No configured port — or an explicit `0`, which is the OS's \"pick a free one\r\n  // for me\" idiom — means Fastify chooses the port, so there is nothing to\r\n  // preflight and nothing to publish: preflighting 0 would bind some unrelated\r\n  // ephemeral port and pass without proving anything, and publishing 0 would\r\n  // point every worker request at `http://host:0`.\r\n  if (typeof resolvedPort !== \"number\" || resolvedPort <= 0) {\r\n    return;\r\n  }\r\n\r\n  await assertPortIsAvailable(resolvedPort, config.get(\"http.host\") || \"localhost\");\r\n\r\n  publishTestServerPort(resolvedPort);\r\n}\r\n\r\n/**\r\n * Start the HTTP test server (minimal - no file watching)\r\n * Call this in Vitest's globalSetup\r\n *\r\n * @example\r\n * // run this suite on its own port, whatever `.env` says\r\n * await startHttpTestServer({ port: 3999 });\r\n */\r\nexport async function startHttpTestServer(\r\n  options: StartHttpTestServerOptions = {},\r\n): Promise<void> {\r\n  if (isServerRunning) {\r\n    console.log(\"[test-server] Server already running, skipping start\");\r\n    return;\r\n  }\r\n\r\n  console.log(\"[test-server] Starting HTTP test server...\");\r\n\r\n  // Set environment\r\n  Application.setRuntimeStrategy(\"development\");\r\n  Application.setEnvironment(\"test\");\r\n\r\n  // Bootstrap (env, etc.)\r\n  await warlockConfigManager.load();\r\n  await bootstrap();\r\n\r\n  // Initialize file orchestrator (but don't watch)\r\n  await filesOrchestrator.init();\r\n  await filesOrchestrator.initializeAll();\r\n\r\n  // Load config files\r\n  await loadConfigFiles(true);\r\n\r\n  // Early-phase connectors (database, cache, logger, storage, mailer,\r\n  // herald) must start BEFORE app modules load: a module's `main.ts` boot\r\n  // side-effect can query the DB at import time, so the data source has to\r\n  // be registered first. This mirrors the dev/prod boot order (see\r\n  // `cli-commands.manager`, `production-builder`, and `DevelopmentServer`).\r\n  await connectorsManager.startPhase(ConnectorLifecyclePhase.Early);\r\n\r\n  // Load application modules (their boot side-effects now see a live DB).\r\n  await filesOrchestrator.moduleLoader.loadAll();\r\n\r\n  await applyTestServerPort(options.port);\r\n\r\n  // Late-phase connectors (http, socket) bind after app code has\r\n  // registered its routes and listeners.\r\n  await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);\r\n\r\n  isServerRunning = true;\r\n}\r\n\r\n/**\r\n * Stop the HTTP test server\r\n * Call this in Vitest's globalTeardown\r\n */\r\nexport async function stopHttpTestServer(): Promise<void> {\r\n  if (!isServerRunning) {\r\n    console.log(\"[test-server] No server to stop\");\r\n    return;\r\n  }\r\n\r\n  try {\r\n    await connectorsManager.shutdown();\r\n    withdrawTestServerPort();\r\n    isServerRunning = false;\r\n    console.log(\"[test-server] HTTP test server stopped\");\r\n  } catch (error) {\r\n    console.error(\"[test-server] Error stopping HTTP server:\", error);\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * Check if test server is running\r\n */\r\nexport function isTestServerRunning(): boolean {\r\n  return isServerRunning;\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAsBA,IAAI,kBAAkB;;;;;;;;;;;;AAuBtB,eAAe,oBAAoB,MAA8B;CAG/D,IAAI,CAFe,OAAO,IAAI,MAEhB,GAAG;EACf,IAAI,SAAS,QACX,MAAM,IAAI,MACR,+BAA+B,KAAK,2HACtC;EAGF;CACF;CAEA,IAAI,SAAS,QACX,OAAO,IAAI,aAAa,IAAI;CAG9B,MAAM,eAAe,OAAO,IAAI,WAAW;CAO3C,IAAI,OAAO,iBAAiB,YAAY,gBAAgB,GACtD;CAGF,MAAM,sBAAsB,cAAc,OAAO,IAAI,WAAW,KAAK,WAAW;CAEhF,sBAAsB,YAAY;AACpC;;;;;;;;;AAUA,eAAsB,oBACpB,UAAsC,CAAC,GACxB;CACf,IAAI,iBAAiB;EACnB,QAAQ,IAAI,sDAAsD;EAClE;CACF;CAEA,QAAQ,IAAI,4CAA4C;CAGxD,YAAY,mBAAmB,aAAa;CAC5C,YAAY,eAAe,MAAM;CAGjC,MAAM,qBAAqB,KAAK;CAChC,MAAM,UAAU;CAGhB,MAAM,kBAAkB,KAAK;CAC7B,MAAM,kBAAkB,cAAc;CAGtC,MAAM,gBAAgB,IAAI;CAO1B,MAAM,kBAAkB,kBAAwC;CAGhE,MAAM,kBAAkB,aAAa,QAAQ;CAE7C,MAAM,oBAAoB,QAAQ,IAAI;CAItC,MAAM,kBAAkB,iBAAuC;CAE/D,kBAAkB;AACpB;;;;;AAMA,eAAsB,qBAAoC;CACxD,IAAI,CAAC,iBAAiB;EACpB,QAAQ,IAAI,iCAAiC;EAC7C;CACF;CAEA,IAAI;EACF,MAAM,kBAAkB,SAAS;EACjC,uBAAuB;EACvB,kBAAkB;EAClB,QAAQ,IAAI,wCAAwC;CACtD,SAAS,OAAO;EACd,QAAQ,MAAM,6CAA6C,KAAK;EAChE,MAAM;CACR;AACF;;;;AAKA,SAAgB,sBAA+B;CAC7C,OAAO;AACT"}

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":";;AAWA;;;;AAAgC;AAUhC;;AAVgC,iBAAhB,gBAAA;;;;;iBAUM,WAAA,CAAY,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAgB9D,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;AAhBY;iBAuBtE,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;;;;iBAWW,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;;AAhD6E;AAOxF;iBAoDsB,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":";;AAYA;;;;AAAgC;AAehC;;AAfgC,iBAAhB,gBAAA;;;;;iBAeM,WAAA,CAAY,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;;iBAgB9D,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAS,WAAA,GAAmB,OAAA,CAAQ,QAAA;;;AAhBY;iBAuBtE,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;;;;iBAWW,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;;AAhD6E;AAOxF;iBAoDsB,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 { TEST_SERVER_PORT_ENV_KEY } from "./test-server-port-channel.mjs";
 
 //#region ../core/src/tests/test-helpers.ts
 /**
@@ -11,7 +12,7 @@ import "../config/index.mjs";
 * Get the test server base URL
 */
 function getTestServerUrl() {
-	const port = config.key("http.port", 2031);
+	const port = process.env["WARLOCK_TEST_SERVER_PORT"] || 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\";\n\n/**\n * Get the test server base URL\n */\nexport function getTestServerUrl(): string {\n  const port = 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  const baseUrl = getTestServerUrl();\n  const url = path.startsWith(\"/\") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;\n\n  return fetch(url, {\n    ...options,\n    headers: {\n      \"Content-Type\": \"application/json\",\n      ...options.headers,\n    },\n  });\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 testRequest(path, {\n    ...options,\n    method: \"POST\",\n    body: body ? JSON.stringify(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 testRequest(path, {\n    ...options,\n    method: \"PUT\",\n    body: body ? JSON.stringify(body) : undefined,\n  });\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 testRequest(path, {\n    ...options,\n    method: \"PATCH\",\n    body: body ? JSON.stringify(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":";;;;;;;;;;;;AAWA,SAAgB,mBAA2B;CACzC,MAAM,OAAO,OAAO,IAAI,aAAa,IAAI;CAEzC,OAAO,UADM,OAAO,IAAI,aAAa,WACjB,EAAE,GAAG;AAC3B;;;;;AAMA,eAAsB,YAAY,MAAc,UAAuB,CAAC,GAAsB;CAC5F,MAAM,UAAU,iBAAiB;CACjC,MAAM,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,SAAS,GAAG,QAAQ,GAAG;CAEvE,OAAO,MAAM,KAAK;EAChB,GAAG;EACH,SAAS;GACP,gBAAgB;GAChB,GAAG,QAAQ;EACb;CACF,CAAC;AACH;;;;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;EACvB,GAAG;EACH,QAAQ;EACR,MAAM,OAAO,KAAK,UAAU,IAAI,IAAI;CACtC,CAAC;AACH;;;;AAKA,eAAsB,QACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EACvB,GAAG;EACH,QAAQ;EACR,MAAM,OAAO,KAAK,UAAU,IAAI,IAAI;CACtC,CAAC;AACH;;;;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;EACvB,GAAG;EACH,QAAQ;EACR,MAAM,OAAO,KAAK,UAAU,IAAI,IAAI;CACtC,CAAC;AACH;;;;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 { 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  const baseUrl = getTestServerUrl();\n  const url = path.startsWith(\"/\") ? `${baseUrl}${path}` : `${baseUrl}/${path}`;\n\n  return fetch(url, {\n    ...options,\n    headers: {\n      \"Content-Type\": \"application/json\",\n      ...options.headers,\n    },\n  });\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 testRequest(path, {\n    ...options,\n    method: \"POST\",\n    body: body ? JSON.stringify(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 testRequest(path, {\n    ...options,\n    method: \"PUT\",\n    body: body ? JSON.stringify(body) : undefined,\n  });\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 testRequest(path, {\n    ...options,\n    method: \"PATCH\",\n    body: body ? JSON.stringify(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":";;;;;;;;;;;;;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,MAAM,UAAU,iBAAiB;CACjC,MAAM,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,SAAS,GAAG,QAAQ,GAAG;CAEvE,OAAO,MAAM,KAAK;EAChB,GAAG;EACH,SAAS;GACP,gBAAgB;GAChB,GAAG,QAAQ;EACb;CACF,CAAC;AACH;;;;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;EACvB,GAAG;EACH,QAAQ;EACR,MAAM,OAAO,KAAK,UAAU,IAAI,IAAI;CACtC,CAAC;AACH;;;;AAKA,eAAsB,QACpB,MACA,MACA,UAAuB,CAAC,GACL;CACnB,OAAO,YAAY,MAAM;EACvB,GAAG;EACH,QAAQ;EACR,MAAM,OAAO,KAAK,UAAU,IAAI,IAAI;CACtC,CAAC;AACH;;;;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;EACvB,GAAG;EACH,QAAQ;EACR,MAAM,OAAO,KAAK,UAAU,IAAI,IAAI;CACtC,CAAC;AACH;;;;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/tests/test-server-port-channel.d.mts

@@ -0,0 +1,27 @@
+//#region ../core/src/tests/test-server-port-channel.d.ts
+/**
+ * The channel `startHttpTestServer` uses to tell test workers which port it
+ * bound.
+ *
+ * Vitest runs `globalSetup` in the main process and each test file in its own
+ * worker, so the workers do not share the main process's resolved config — they
+ * re-resolve `http.port` from `.env`. An environment variable is the one thing a
+ * worker inherits from the process that spawned it, which makes it the only
+ * channel an explicit port can travel through.
+ *
+ * This is process plumbing between two of our own processes, not application
+ * configuration — app code still reads its port through `config`.
+ */
+declare const TEST_SERVER_PORT_ENV_KEY = "WARLOCK_TEST_SERVER_PORT";
+/**
+ * Publish the port the test server bound, for the workers to read.
+ */
+declare function publishTestServerPort(port: number): void;
+/**
+ * Withdraw the published port on shutdown, so a later run in the same process
+ * can't inherit a stale one.
+ */
+declare function withdrawTestServerPort(): void;
+//#endregion
+export { TEST_SERVER_PORT_ENV_KEY, publishTestServerPort, withdrawTestServerPort };
+//# sourceMappingURL=test-server-port-channel.d.mts.map

package/esm/tests/test-server-port-channel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server-port-channel.d.mts","names":[],"sources":["../../../../../../../core/src/tests/test-server-port-channel.ts"],"mappings":";;AAaA;;;;AAAqC;AAKrC;;;;AAAkD;AAQlD;;cAba,wBAAA;;AAayB;;iBARtB,qBAAA,CAAsB,IAAY;;;;;iBAQlC,sBAAA"}

package/esm/tests/test-server-port-channel.mjs

@@ -0,0 +1,32 @@
+//#region ../core/src/tests/test-server-port-channel.ts
+/**
+* The channel `startHttpTestServer` uses to tell test workers which port it
+* bound.
+*
+* Vitest runs `globalSetup` in the main process and each test file in its own
+* worker, so the workers do not share the main process's resolved config — they
+* re-resolve `http.port` from `.env`. An environment variable is the one thing a
+* worker inherits from the process that spawned it, which makes it the only
+* channel an explicit port can travel through.
+*
+* This is process plumbing between two of our own processes, not application
+* configuration — app code still reads its port through `config`.
+*/
+const TEST_SERVER_PORT_ENV_KEY = "WARLOCK_TEST_SERVER_PORT";
+/**
+* Publish the port the test server bound, for the workers to read.
+*/
+function publishTestServerPort(port) {
+	process.env[TEST_SERVER_PORT_ENV_KEY] = String(port);
+}
+/**
+* Withdraw the published port on shutdown, so a later run in the same process
+* can't inherit a stale one.
+*/
+function withdrawTestServerPort() {
+	delete process.env[TEST_SERVER_PORT_ENV_KEY];
+}
+
+//#endregion
+export { TEST_SERVER_PORT_ENV_KEY, publishTestServerPort, withdrawTestServerPort };
+//# sourceMappingURL=test-server-port-channel.mjs.map

package/esm/tests/test-server-port-channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server-port-channel.mjs","names":[],"sources":["../../../../../../../core/src/tests/test-server-port-channel.ts"],"sourcesContent":["/**\n * The channel `startHttpTestServer` uses to tell test workers which port it\n * bound.\n *\n * Vitest runs `globalSetup` in the main process and each test file in its own\n * worker, so the workers do not share the main process's resolved config — they\n * re-resolve `http.port` from `.env`. An environment variable is the one thing a\n * worker inherits from the process that spawned it, which makes it the only\n * channel an explicit port can travel through.\n *\n * This is process plumbing between two of our own processes, not application\n * configuration — app code still reads its port through `config`.\n */\nexport const TEST_SERVER_PORT_ENV_KEY = \"WARLOCK_TEST_SERVER_PORT\";\n\n/**\n * Publish the port the test server bound, for the workers to read.\n */\nexport function publishTestServerPort(port: number): void {\n  process.env[TEST_SERVER_PORT_ENV_KEY] = String(port);\n}\n\n/**\n * Withdraw the published port on shutdown, so a later run in the same process\n * can't inherit a stale one.\n */\nexport function withdrawTestServerPort(): void {\n  delete process.env[TEST_SERVER_PORT_ENV_KEY];\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAa,2BAA2B;;;;AAKxC,SAAgB,sBAAsB,MAAoB;CACxD,QAAQ,IAAI,4BAA4B,OAAO,IAAI;AACrD;;;;;AAMA,SAAgB,yBAA+B;CAC7C,OAAO,QAAQ,IAAI;AACrB"}

package/esm/utils/load-environment.mjs

@@ -0,0 +1,59 @@
+import { loadEnv } from "@mongez/dotenv";
+import path from "node:path";
+import { existsSync } from "node:fs";
+
+//#region ../core/src/utils/load-environment.ts
+/**
+* The files `loadEnv()` will look for, in the order it considers them.
+*
+* Mirrors `@mongez/dotenv`'s own resolution — `.env.shared` first, then
+* `.env.<NODE_ENV>` if it exists, else plain `.env` — because the presence
+* check has to ask the same question the loader is about to ask.
+*/
+function candidateEnvFiles(directory) {
+	const files = [path.join(directory, ".env"), path.join(directory, ".env.shared")];
+	if (process.env.NODE_ENV) files.push(path.join(directory, `.env.${process.env.NODE_ENV}`));
+	return files;
+}
+/**
+* Whether this process has already loaded its env files.
+*
+* Two callers reach here on a bootstrapping command — the CLI preload phase and
+* `bootstrap()` — and `loadEnv()` defaults to `override: true`, so a second pass
+* re-parses the same files and re-writes `process.env`. Anything set in between
+* (a `warlock.config.ts` module body, a config file, an orchestrator) would be
+* silently clobbered by the later load. Same shape as the defect where a
+* caller's test-server port was overwritten by a re-read of `.env`.
+*
+* A deliberate reload is still possible and still used: the dev server calls
+* `loadEnv()` directly when an `.env` file changes on disk, which is a reload
+* the user asked for rather than an accidental second pass.
+*/
+let environmentLoaded = false;
+/**
+* Load `.env` files when there are any, and do nothing when there are not.
+*
+* Loads at most **once per process** — see {@link environmentLoaded}.
+*
+* `@mongez/dotenv`'s `loadEnvFile` **throws** when the file is absent. That was
+* survivable while only `dev` loaded env; now that every command loads it —
+* because `warlock.config.ts` calls `env()` in its module body and had been
+* evaluated against an empty store under every command — an unguarded call
+* would turn "this project has no .env" from a non-event into a hard failure
+* of `warlock build`. A project without a `.env` is legitimate: config files
+* carry defaults, and containers inject their own variables.
+*
+* The guard lives here rather than waiting on a fix in `@mongez/dotenv`: core
+* decides its own env policy and must not depend on another package's release
+* schedule to avoid crashing a working build.
+*/
+async function loadEnvironmentFiles(directory = process.cwd()) {
+	if (environmentLoaded) return;
+	if (!candidateEnvFiles(directory).some((file) => existsSync(file))) return;
+	environmentLoaded = true;
+	await loadEnv();
+}
+
+//#endregion
+export { loadEnvironmentFiles };
+//# sourceMappingURL=load-environment.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load-environment.mjs","names":[],"sources":["../../../../../../../core/src/utils/load-environment.ts"],"sourcesContent":["import { loadEnv } from \"@mongez/dotenv\";\nimport { existsSync } from \"node:fs\";\nimport path from \"node:path\";\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  await loadEnv();\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":";;;;;;;;;;;;AAWA,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;CAEpB,MAAM,QAAQ;AAChB"}

package/esm/utils/paths.mjs

@@ -1,4 +1,4 @@
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import path from "path";
 
 //#region ../core/src/utils/paths.ts
@@ -28,7 +28,7 @@ function storagePath(relativePath = "") {
 * If no path is given, it will return the absolute path to the uploads folder
 */
 function uploadsPath(relativePath = "") {
-	const configPath = baseConfig.get("uploads.root");
+	const configPath = config.get("uploads.root");
 	if (!configPath) return rootPath("storage", "uploads", relativePath);
 	return typeof configPath === "function" ? configPath(relativePath) : path.resolve(configPath, relativePath);
 }

package/esm/utils/paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","names":["config"],"sources":["../../../../../../../core/src/utils/paths.ts"],"sourcesContent":["import config from \"@mongez/config\";\r\nimport path from \"path\";\r\n\r\n/**\r\n * Get root path or join the given paths to the root path\r\n */\r\nexport function rootPath(...paths: string[]) {\r\n  return path.resolve(process.cwd(), ...paths);\r\n}\r\n\r\n/**\r\n * Get src directory path or join the given paths to the src directory path\r\n */\r\nexport function srcPath(...paths: string[]) {\r\n  return rootPath(\"src\", ...paths);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the storage folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the storage folder\r\n */\r\nexport function storagePath(relativePath = \"\") {\r\n  return rootPath(\"storage\", relativePath);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the uploads folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the uploads folder\r\n */\r\nexport function uploadsPath(relativePath = \"\") {\r\n  const configPath = config.get(\"uploads.root\");\r\n  if (!configPath) {\r\n    return rootPath(\"storage\", \"uploads\", relativePath);\r\n  }\r\n\r\n  return typeof configPath === \"function\"\r\n    ? configPath(relativePath)\r\n    : path.resolve(configPath, relativePath);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the public folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the public folder\r\n */\r\nexport function publicPath(relativePath = \"\") {\r\n  return rootPath(\"public\", relativePath);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the cache folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the cache folder\r\n */\r\nexport function cachePath(relativePath = \"\") {\r\n  return rootPath(\"storage\", \"cache\", relativePath);\r\n}\r\n\r\n/**\r\n * App path\r\n */\r\nexport function appPath(relativePath = \"\") {\r\n  return rootPath(\"src/app\", relativePath);\r\n}\r\n\r\n/**\r\n * Get logs directory path\r\n */\r\nexport function logsPath(relativePath = \"\") {\r\n  return rootPath(\"storage/logs\", relativePath);\r\n}\r\n\r\n/**\r\n * Get a temp path\r\n */\r\nexport function tempPath(relativePath = \"\") {\r\n  return rootPath(\"storage/tmp\", relativePath);\r\n}\r\n\r\n/**\r\n * Remove any invalid characters from the file path using regex\r\n * It should accept any language character, numbers, and the following characters: _ - .\r\n */\r\nconst invalidCharsRegex = /[<>:\"/\\\\|?*]/g; // Regex to match invalid characters\r\nexport function sanitizePath(filePath: string) {\r\n  return filePath.replace(invalidCharsRegex, \"\"); // Replace invalid characters with an empty string\r\n}\r\n\r\n/**\r\n * Warlock path\r\n * PLEASE DO NOT add any files in this directory as it may be deleted\r\n */\r\nexport function warlockPath(...path: string[]) {\r\n  return rootPath(\".warlock\", ...path);\r\n}\r\n\r\n/**\r\n * Get config directory path\r\n */\r\nexport function configPath(...path: string[]) {\r\n  return rootPath(\"src/config\", ...path);\r\n}\r\n\r\nexport const paths = {\r\n  root: rootPath,\r\n  src: srcPath,\r\n  storage: storagePath,\r\n  logs: logsPath,\r\n  uploads: uploadsPath,\r\n  public: publicPath,\r\n  cache: cachePath,\r\n  app: appPath,\r\n  temp: tempPath,\r\n  warlock: warlockPath,\r\n  config: configPath,\r\n  sanitize: sanitizePath,\r\n};\r\n"],"mappings":";;;;;;;AAMA,SAAgB,SAAS,GAAG,OAAiB;CAC3C,OAAO,KAAK,QAAQ,QAAQ,IAAI,GAAG,GAAG,KAAK;AAC7C;;;;AAKA,SAAgB,QAAQ,GAAG,OAAiB;CAC1C,OAAO,SAAS,OAAO,GAAG,KAAK;AACjC;;;;;;AAOA,SAAgB,YAAY,eAAe,IAAI;CAC7C,OAAO,SAAS,WAAW,YAAY;AACzC;;;;;;AAOA,SAAgB,YAAY,eAAe,IAAI;CAC7C,MAAM,aAAaA,WAAO,IAAI,cAAc;CAC5C,IAAI,CAAC,YACH,OAAO,SAAS,WAAW,WAAW,YAAY;CAGpD,OAAO,OAAO,eAAe,aACzB,WAAW,YAAY,IACvB,KAAK,QAAQ,YAAY,YAAY;AAC3C;;;;;;AAOA,SAAgB,WAAW,eAAe,IAAI;CAC5C,OAAO,SAAS,UAAU,YAAY;AACxC;;;;;;AAOA,SAAgB,UAAU,eAAe,IAAI;CAC3C,OAAO,SAAS,WAAW,SAAS,YAAY;AAClD;;;;AAKA,SAAgB,QAAQ,eAAe,IAAI;CACzC,OAAO,SAAS,WAAW,YAAY;AACzC;;;;AAKA,SAAgB,SAAS,eAAe,IAAI;CAC1C,OAAO,SAAS,gBAAgB,YAAY;AAC9C;;;;AAKA,SAAgB,SAAS,eAAe,IAAI;CAC1C,OAAO,SAAS,eAAe,YAAY;AAC7C;;;;;AAMA,MAAM,oBAAoB;AAC1B,SAAgB,aAAa,UAAkB;CAC7C,OAAO,SAAS,QAAQ,mBAAmB,EAAE;AAC/C;;;;;AAMA,SAAgB,YAAY,GAAG,MAAgB;CAC7C,OAAO,SAAS,YAAY,GAAG,IAAI;AACrC;;;;AAKA,SAAgB,WAAW,GAAG,MAAgB;CAC5C,OAAO,SAAS,cAAc,GAAG,IAAI;AACvC;AAEA,MAAa,QAAQ;CACnB,MAAM;CACN,KAAK;CACL,SAAS;CACT,MAAM;CACN,SAAS;CACT,QAAQ;CACR,OAAO;CACP,KAAK;CACL,MAAM;CACN,SAAS;CACT,QAAQ;CACR,UAAU;AACZ"}
+{"version":3,"file":"paths.mjs","names":[],"sources":["../../../../../../../core/src/utils/paths.ts"],"sourcesContent":["import config from \"@mongez/config\";\r\nimport path from \"path\";\r\n\r\n/**\r\n * Get root path or join the given paths to the root path\r\n */\r\nexport function rootPath(...paths: string[]) {\r\n  return path.resolve(process.cwd(), ...paths);\r\n}\r\n\r\n/**\r\n * Get src directory path or join the given paths to the src directory path\r\n */\r\nexport function srcPath(...paths: string[]) {\r\n  return rootPath(\"src\", ...paths);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the storage folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the storage folder\r\n */\r\nexport function storagePath(relativePath = \"\") {\r\n  return rootPath(\"storage\", relativePath);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the uploads folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the uploads folder\r\n */\r\nexport function uploadsPath(relativePath = \"\") {\r\n  const configPath = config.get(\"uploads.root\");\r\n  if (!configPath) {\r\n    return rootPath(\"storage\", \"uploads\", relativePath);\r\n  }\r\n\r\n  return typeof configPath === \"function\"\r\n    ? configPath(relativePath)\r\n    : path.resolve(configPath, relativePath);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the public folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the public folder\r\n */\r\nexport function publicPath(relativePath = \"\") {\r\n  return rootPath(\"public\", relativePath);\r\n}\r\n\r\n/**\r\n * Get the absolute path to the cache folder to the given path\r\n *\r\n * If no path is given, it will return the absolute path to the cache folder\r\n */\r\nexport function cachePath(relativePath = \"\") {\r\n  return rootPath(\"storage\", \"cache\", relativePath);\r\n}\r\n\r\n/**\r\n * App path\r\n */\r\nexport function appPath(relativePath = \"\") {\r\n  return rootPath(\"src/app\", relativePath);\r\n}\r\n\r\n/**\r\n * Get logs directory path\r\n */\r\nexport function logsPath(relativePath = \"\") {\r\n  return rootPath(\"storage/logs\", relativePath);\r\n}\r\n\r\n/**\r\n * Get a temp path\r\n */\r\nexport function tempPath(relativePath = \"\") {\r\n  return rootPath(\"storage/tmp\", relativePath);\r\n}\r\n\r\n/**\r\n * Remove any invalid characters from the file path using regex\r\n * It should accept any language character, numbers, and the following characters: _ - .\r\n */\r\nconst invalidCharsRegex = /[<>:\"/\\\\|?*]/g; // Regex to match invalid characters\r\nexport function sanitizePath(filePath: string) {\r\n  return filePath.replace(invalidCharsRegex, \"\"); // Replace invalid characters with an empty string\r\n}\r\n\r\n/**\r\n * Warlock path\r\n * PLEASE DO NOT add any files in this directory as it may be deleted\r\n */\r\nexport function warlockPath(...path: string[]) {\r\n  return rootPath(\".warlock\", ...path);\r\n}\r\n\r\n/**\r\n * Get config directory path\r\n */\r\nexport function configPath(...path: string[]) {\r\n  return rootPath(\"src/config\", ...path);\r\n}\r\n\r\nexport const paths = {\r\n  root: rootPath,\r\n  src: srcPath,\r\n  storage: storagePath,\r\n  logs: logsPath,\r\n  uploads: uploadsPath,\r\n  public: publicPath,\r\n  cache: cachePath,\r\n  app: appPath,\r\n  temp: tempPath,\r\n  warlock: warlockPath,\r\n  config: configPath,\r\n  sanitize: sanitizePath,\r\n};\r\n"],"mappings":";;;;;;;AAMA,SAAgB,SAAS,GAAG,OAAiB;CAC3C,OAAO,KAAK,QAAQ,QAAQ,IAAI,GAAG,GAAG,KAAK;AAC7C;;;;AAKA,SAAgB,QAAQ,GAAG,OAAiB;CAC1C,OAAO,SAAS,OAAO,GAAG,KAAK;AACjC;;;;;;AAOA,SAAgB,YAAY,eAAe,IAAI;CAC7C,OAAO,SAAS,WAAW,YAAY;AACzC;;;;;;AAOA,SAAgB,YAAY,eAAe,IAAI;CAC7C,MAAM,aAAa,OAAO,IAAI,cAAc;CAC5C,IAAI,CAAC,YACH,OAAO,SAAS,WAAW,WAAW,YAAY;CAGpD,OAAO,OAAO,eAAe,aACzB,WAAW,YAAY,IACvB,KAAK,QAAQ,YAAY,YAAY;AAC3C;;;;;;AAOA,SAAgB,WAAW,eAAe,IAAI;CAC5C,OAAO,SAAS,UAAU,YAAY;AACxC;;;;;;AAOA,SAAgB,UAAU,eAAe,IAAI;CAC3C,OAAO,SAAS,WAAW,SAAS,YAAY;AAClD;;;;AAKA,SAAgB,QAAQ,eAAe,IAAI;CACzC,OAAO,SAAS,WAAW,YAAY;AACzC;;;;AAKA,SAAgB,SAAS,eAAe,IAAI;CAC1C,OAAO,SAAS,gBAAgB,YAAY;AAC9C;;;;AAKA,SAAgB,SAAS,eAAe,IAAI;CAC1C,OAAO,SAAS,eAAe,YAAY;AAC7C;;;;;AAMA,MAAM,oBAAoB;AAC1B,SAAgB,aAAa,UAAkB;CAC7C,OAAO,SAAS,QAAQ,mBAAmB,EAAE;AAC/C;;;;;AAMA,SAAgB,YAAY,GAAG,MAAgB;CAC7C,OAAO,SAAS,YAAY,GAAG,IAAI;AACrC;;;;AAKA,SAAgB,WAAW,GAAG,MAAgB;CAC5C,OAAO,SAAS,cAAc,GAAG,IAAI;AACvC;AAEA,MAAa,QAAQ;CACnB,MAAM;CACN,KAAK;CACL,SAAS;CACT,MAAM;CACN,SAAS;CACT,QAAQ;CACR,OAAO;CACP,KAAK;CACL,MAAM;CACN,SAAS;CACT,QAAQ;CACR,UAAU;AACZ"}

package/esm/validation/validateAll.mjs

@@ -1,5 +1,5 @@
 import { v } from "@warlock.js/seal";
-import baseConfig from "@mongez/config";
+import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import { merge } from "@mongez/reinforcements";
 
@@ -40,7 +40,7 @@ async function validateAll(validation, request, response) {
 	if (validation.validate) {
 		const result = await validation.validate(request, response);
 		if (result) {
-			if (!response.statusCode) response.setStatusCode(baseConfig.get("validation.responseStatus", 400));
+			if (!response.statusCode) response.setStatusCode(config.get("validation.responseStatus", 400));
 			log.info("validation", "failed", "Validation failed");
 			return result;
 		}

package/esm/validation/validateAll.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"validateAll.mjs","names":["config"],"sources":["../../../../../../../core/src/validation/validateAll.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { merge } from \"@mongez/reinforcements\";\nimport { log } from \"@warlock.js/logger\";\nimport { v } from \"@warlock.js/seal\";\nimport type { Request, Response } from \"../http\";\nimport type { RequestHandlerValidation, Route } from \"../router\";\n\nfunction resolveDataToParse(validating: RequestHandlerValidation[\"validating\"], request: Request) {\n  if (!validating || validating.length === 0) return request.allExceptParams();\n\n  let data: any = {};\n\n  for (const validatingType of validating) {\n    if (validatingType === \"body\") {\n      data = merge(data, request.body);\n    }\n\n    if (validatingType === \"query\") {\n      data = merge(data, request.query);\n    }\n\n    if (validatingType === \"params\") {\n      data = merge(data, request.params);\n    }\n\n    if (validatingType === \"headers\") {\n      data = merge(data, request.headers);\n    }\n  }\n\n  return data;\n}\n\n/**\n * Validate the request route\n */\nexport async function validateAll(\n  validation: Route[\"handler\"][\"validation\"],\n  request: Request,\n  response: Response,\n) {\n  if (!validation) return;\n\n  log.info(\"validation\", \"started\", \"Start validating the request\");\n\n  if (validation.schema) {\n    log.info(\"validation\", \"schema\", \"Validating request schema\");\n    try {\n      const data = resolveDataToParse(validation.validating, request);\n      const result = await v.validate(validation.schema, data);\n\n      if (result.data && result.isValid) {\n        request.setValidatedData(result.data);\n      }\n\n      if (!result.isValid) {\n        log.warn(\"validation\", \"schema\", \"Schema Validation failed\");\n        return response.failedSchema(result);\n      }\n\n      log.success(\"validation\", \"schema\", \"Schema Validation passed\");\n    } catch (error) {\n      log.warn(\"app.validation\", \"error\", error);\n      throw error;\n    }\n  }\n\n  if (validation.validate) {\n    const result = await validation.validate(request, response);\n\n    // if there is a result, it means it failed\n    if (result) {\n      // check if there is no response status code, then set it to config value or 400 as default\n      if (!response.statusCode) {\n        response.setStatusCode(config.get(\"validation.responseStatus\", 400));\n      }\n\n      log.info(\"validation\", \"failed\", \"Validation failed\");\n\n      return result;\n    }\n\n    log.info(\"validation\", \"passed\", \"Validation passed\");\n  }\n}\n"],"mappings":";;;;;;AAOA,SAAS,mBAAmB,YAAoD,SAAkB;CAChG,IAAI,CAAC,cAAc,WAAW,WAAW,GAAG,OAAO,QAAQ,gBAAgB;CAE3E,IAAI,OAAY,CAAC;CAEjB,KAAK,MAAM,kBAAkB,YAAY;EACvC,IAAI,mBAAmB,QACrB,OAAO,MAAM,MAAM,QAAQ,IAAI;EAGjC,IAAI,mBAAmB,SACrB,OAAO,MAAM,MAAM,QAAQ,KAAK;EAGlC,IAAI,mBAAmB,UACrB,OAAO,MAAM,MAAM,QAAQ,MAAM;EAGnC,IAAI,mBAAmB,WACrB,OAAO,MAAM,MAAM,QAAQ,OAAO;CAEtC;CAEA,OAAO;AACT;;;;AAKA,eAAsB,YACpB,YACA,SACA,UACA;CACA,IAAI,CAAC,YAAY;CAEjB,IAAI,KAAK,cAAc,WAAW,8BAA8B;CAEhE,IAAI,WAAW,QAAQ;EACrB,IAAI,KAAK,cAAc,UAAU,2BAA2B;EAC5D,IAAI;GACF,MAAM,OAAO,mBAAmB,WAAW,YAAY,OAAO;GAC9D,MAAM,SAAS,MAAM,EAAE,SAAS,WAAW,QAAQ,IAAI;GAEvD,IAAI,OAAO,QAAQ,OAAO,SACxB,QAAQ,iBAAiB,OAAO,IAAI;GAGtC,IAAI,CAAC,OAAO,SAAS;IACnB,IAAI,KAAK,cAAc,UAAU,0BAA0B;IAC3D,OAAO,SAAS,aAAa,MAAM;GACrC;GAEA,IAAI,QAAQ,cAAc,UAAU,0BAA0B;EAChE,SAAS,OAAO;GACd,IAAI,KAAK,kBAAkB,SAAS,KAAK;GACzC,MAAM;EACR;CACF;CAEA,IAAI,WAAW,UAAU;EACvB,MAAM,SAAS,MAAM,WAAW,SAAS,SAAS,QAAQ;EAG1D,IAAI,QAAQ;GAEV,IAAI,CAAC,SAAS,YACZ,SAAS,cAAcA,WAAO,IAAI,6BAA6B,GAAG,CAAC;GAGrE,IAAI,KAAK,cAAc,UAAU,mBAAmB;GAEpD,OAAO;EACT;EAEA,IAAI,KAAK,cAAc,UAAU,mBAAmB;CACtD;AACF"}
+{"version":3,"file":"validateAll.mjs","names":[],"sources":["../../../../../../../core/src/validation/validateAll.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { merge } from \"@mongez/reinforcements\";\nimport { log } from \"@warlock.js/logger\";\nimport { v } from \"@warlock.js/seal\";\nimport type { Request, Response } from \"../http\";\nimport type { RequestHandlerValidation, Route } from \"../router\";\n\nfunction resolveDataToParse(validating: RequestHandlerValidation[\"validating\"], request: Request) {\n  if (!validating || validating.length === 0) return request.allExceptParams();\n\n  let data: any = {};\n\n  for (const validatingType of validating) {\n    if (validatingType === \"body\") {\n      data = merge(data, request.body);\n    }\n\n    if (validatingType === \"query\") {\n      data = merge(data, request.query);\n    }\n\n    if (validatingType === \"params\") {\n      data = merge(data, request.params);\n    }\n\n    if (validatingType === \"headers\") {\n      data = merge(data, request.headers);\n    }\n  }\n\n  return data;\n}\n\n/**\n * Validate the request route\n */\nexport async function validateAll(\n  validation: Route[\"handler\"][\"validation\"],\n  request: Request,\n  response: Response,\n) {\n  if (!validation) return;\n\n  log.info(\"validation\", \"started\", \"Start validating the request\");\n\n  if (validation.schema) {\n    log.info(\"validation\", \"schema\", \"Validating request schema\");\n    try {\n      const data = resolveDataToParse(validation.validating, request);\n      const result = await v.validate(validation.schema, data);\n\n      if (result.data && result.isValid) {\n        request.setValidatedData(result.data);\n      }\n\n      if (!result.isValid) {\n        log.warn(\"validation\", \"schema\", \"Schema Validation failed\");\n        return response.failedSchema(result);\n      }\n\n      log.success(\"validation\", \"schema\", \"Schema Validation passed\");\n    } catch (error) {\n      log.warn(\"app.validation\", \"error\", error);\n      throw error;\n    }\n  }\n\n  if (validation.validate) {\n    const result = await validation.validate(request, response);\n\n    // if there is a result, it means it failed\n    if (result) {\n      // check if there is no response status code, then set it to config value or 400 as default\n      if (!response.statusCode) {\n        response.setStatusCode(config.get(\"validation.responseStatus\", 400));\n      }\n\n      log.info(\"validation\", \"failed\", \"Validation failed\");\n\n      return result;\n    }\n\n    log.info(\"validation\", \"passed\", \"Validation passed\");\n  }\n}\n"],"mappings":";;;;;;AAOA,SAAS,mBAAmB,YAAoD,SAAkB;CAChG,IAAI,CAAC,cAAc,WAAW,WAAW,GAAG,OAAO,QAAQ,gBAAgB;CAE3E,IAAI,OAAY,CAAC;CAEjB,KAAK,MAAM,kBAAkB,YAAY;EACvC,IAAI,mBAAmB,QACrB,OAAO,MAAM,MAAM,QAAQ,IAAI;EAGjC,IAAI,mBAAmB,SACrB,OAAO,MAAM,MAAM,QAAQ,KAAK;EAGlC,IAAI,mBAAmB,UACrB,OAAO,MAAM,MAAM,QAAQ,MAAM;EAGnC,IAAI,mBAAmB,WACrB,OAAO,MAAM,MAAM,QAAQ,OAAO;CAEtC;CAEA,OAAO;AACT;;;;AAKA,eAAsB,YACpB,YACA,SACA,UACA;CACA,IAAI,CAAC,YAAY;CAEjB,IAAI,KAAK,cAAc,WAAW,8BAA8B;CAEhE,IAAI,WAAW,QAAQ;EACrB,IAAI,KAAK,cAAc,UAAU,2BAA2B;EAC5D,IAAI;GACF,MAAM,OAAO,mBAAmB,WAAW,YAAY,OAAO;GAC9D,MAAM,SAAS,MAAM,EAAE,SAAS,WAAW,QAAQ,IAAI;GAEvD,IAAI,OAAO,QAAQ,OAAO,SACxB,QAAQ,iBAAiB,OAAO,IAAI;GAGtC,IAAI,CAAC,OAAO,SAAS;IACnB,IAAI,KAAK,cAAc,UAAU,0BAA0B;IAC3D,OAAO,SAAS,aAAa,MAAM;GACrC;GAEA,IAAI,QAAQ,cAAc,UAAU,0BAA0B;EAChE,SAAS,OAAO;GACd,IAAI,KAAK,kBAAkB,SAAS,KAAK;GACzC,MAAM;EACR;CACF;CAEA,IAAI,WAAW,UAAU;EACvB,MAAM,SAAS,MAAM,WAAW,SAAS,SAAS,QAAQ;EAG1D,IAAI,QAAQ;GAEV,IAAI,CAAC,SAAS,YACZ,SAAS,cAAc,OAAO,IAAI,6BAA6B,GAAG,CAAC;GAGrE,IAAI,KAAK,cAAc,UAAU,mBAAmB;GAEpD,OAAO;EACT;EAEA,IAAI,KAAK,cAAc,UAAU,mBAAmB;CACtD;AACF"}

package/llms-full.txt

@@ -3339,6 +3339,57 @@ Just `warlockConfig: true` — same as `build`. The actual app bootstrap happens
 
 Means `docker stop` / `kubectl delete pod` works as expected: SIGTERM reaches the bundle, your graceful-shutdown hooks fire, then the parent exits.
 
+### pnpm needs esbuild's install script allowed
+
+pnpm 10+ will not run a dependency's install script unless the app names it. esbuild's script links its platform-native binary, and `warlock build` shells out to that binary — so the app installs cleanly and then cannot build:
+
+```
+[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.27.7
+```
+
+Fix it once in the app's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  esbuild: true
+```
+
+Note pnpm reads this from `pnpm-workspace.yaml`, **not** from `package.json`'s `pnpm` field — pnpm 11 warns that the field is ignored and then carries on, so settings left there fail silently.
+
+Nothing else is needed for pnpm. Warlock never requires an app to declare a package it does not import: generated code is checked at build time against the app's own `dependencies`, so `warlock build` failing over an unfamiliar package name is a framework bug, not a missing dependency.
+
+### Output streams — what a supervisor may trust
+
+**A success line on stdout means the app is serving requests.** That is a contract, not a convention, and you can build a CI gate or a health probe on it.
+
+| Stream     | Carries                                                        |
+| ---------- | -------------------------------------------------------------- |
+| **stdout** | the started banner, and start failures. Nothing else.           |
+| **stderr** | progress (`🚀 Starting production server...`), diagnostics, the application's own logs |
+
+The started banner prints **only** when the running application reports a completed boot — not when the command starts, not when the child is spawned. A child that dies before reporting is a failed start: the failure is written to **both** streams (stderr for humans and log collectors, stdout so a supervisor greping for the banner finds a failure rather than silence), and `warlock start` exits non-zero **even when the child itself exited `0`**.
+
+```bash
+# a CI gate can be this blunt, and it is now correct
+yarn warlock start | grep -q "production server started"
+```
+
+### How readiness is reported
+
+`warlock start` spawns the bundle with an IPC channel and sets `WARLOCK_BOOT_SIGNAL=1` on it. `Application.markBooted()` — which the production entry calls after the late-phase connectors (http, socket) are up — sends one versioned message and closes the channel:
+
+```ts
+{ type: "warlock:ready", version: 1, pid, at, environment, runtimeStrategy, bootDurationMs?, port? }
+```
+
+Three consequences worth knowing:
+
+1. **A queue worker with no http connector still reports.** Readiness hangs on a completed boot, not on a bound port. `port` is simply absent.
+2. **Running the bundle any other way changes nothing.** `node dist/app.js`, a Docker `CMD`, or pm2 — the signal is a strict no-op without both the IPC channel and the handshake flag, so Warlock never writes into a channel that belongs to another supervisor.
+3. **A bundle built before 4.11.0 has no signal.** It starts and runs normally, and after ten seconds prints a note on **stderr only** telling you to re-run `warlock build`. An absent signal is never an error, never fails the run, and never kills a slow boot.
+
+If you need the same fact inside the app, use `Application.onceBooted()` / `Application.whenBooted()` — the signal and your listeners fire from the same latch.
+
 ## Picking which mode you're in
 
 `Application.environment` and `Application.runtimeStrategy` are separate axes:
@@ -3406,6 +3457,18 @@ export default defineConfig({
 
 CI sets `BUILD_OUT=build/<sha>` per pipeline. `warlock start` reads the same config and finds the bundle without any hardcoded paths.
 
+**This recipe only started working in 4.11.0.** Before that, `warlock.config.ts` was evaluated *before* any `.env` file was read, so every `env()` call in it returned its default — silently, under every command. If you copied this recipe earlier and concluded that `BUILD_OUT` was ignored, it was.
+
+**Which file the value comes from is decided by `NODE_ENV`, and no Warlock command sets it.** `env()` reads `.env.<NODE_ENV>` when that file exists and falls back to plain `.env`. So:
+
+```bash
+warlock build                       # NODE_ENV unset → reads .env
+NODE_ENV=production warlock build   # → reads .env.production
+NODE_ENV=staging warlock build      # → reads .env.staging
+```
+
+That is deliberate: `build` and `start` do **not** force `production`. Forcing it would silently change which file an existing `NODE_ENV=staging` pipeline reads, and would have the framework overriding an operator's explicit choice at the moment of deployment. Set `NODE_ENV` in your Dockerfile, CI job, or process manager — the same place you already set it for `Application.environment`.
+
 ### Skip type-gen on machines without write access
 
 ```bash
@@ -4493,7 +4556,7 @@ Client `PUT`s the bytes straight to R2 — your server never sees them.
 
 ---
 name: test-http
-description: 'Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.'
+description: 'Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `startHttpTestServer({ port })`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`, `PortInUseError`, `assertPortIsAvailable`, `isPortAvailable`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape", "test server port already in use", "EADDRINUSE while running tests", "run tests while the dev server is up"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.'
 ---
 
 # Warlock — HTTP integration tests
@@ -4549,6 +4612,30 @@ Unlike the dev server, it doesn't watch files, doesn't do HMR, doesn't run healt
 
 Both are idempotent. A second `start` returns early; `stop` on a non-running server logs and returns.
 
+### Choosing the port — `startHttpTestServer({ port })`
+
+```ts
+await startHttpTestServer({ port: 3999 });
+```
+
+The explicit port wins over `http.port` — including over `HTTP_PORT` in `.env`. Use it to run a suite while the dev server holds the configured port, or to run two suites side by side.
+
+**Nothing else can move the server.** `startHttpTestServer()` bootstraps the app itself, and that bootstrap re-reads `.env` (dotenv overrides by default), so any value you set before calling it is gone before the port is read. Assigning `process.env.HTTP_PORT` does not work either: `env()` reads dotenv's own store and never falls back to `process.env`. The option is applied after the bootstrap, immediately before the connector binds — that is why it is the only channel that survives.
+
+The request helpers follow with no extra wiring: the bound port is published as `WARLOCK_TEST_SERVER_PORT`, which the workers inherit, and `getTestServerUrl()` prefers it over their own `.env`-resolved `http.port`. `stopHttpTestServer()` withdraws it.
+
+### The port is preflighted
+
+Before binding, the test server checks the resolved port is free and fails with an instruction if it isn't:
+
+```
+Port 2031 is already in use on localhost. Stop the dev server (or whatever else is
+listening on port 2031) and run again, or start on a free port — e.g.
+startHttpTestServer({ port: 2032 }).
+```
+
+This runs whether or not you passed a port, so a collision never reaches you as a bare `EADDRINUSE` from inside Fastify. The failure is a `PortInUseError` carrying `port` and `host`. The same check is available on its own — `assertPortIsAvailable(port, host)` throws it, `isPortAvailable(port, host)` returns a boolean.
+
 ## Project wiring — `src/test-global-setup.ts` + `vite.config.ts`
 
 ```ts title="src/test-global-setup.ts"
@@ -4598,7 +4685,7 @@ import { getTestServerUrl } from "@warlock.js/core";
 const url = getTestServerUrl();  // → "http://localhost:2031" (defaults)
 ```
 
-Reads `http.host` (default `"localhost"`) and `http.port` (default `2031`) from config. If you change the HTTP config, helpers follow automatically.
+Reads `http.host` (default `"localhost"`) and `http.port` (default `2031`) from config — unless `startHttpTestServer` published a port, which wins, since a worker's own config never sees the `{ port }` option passed in `globalSetup`. If you change the HTTP config, helpers follow automatically.
 
 ### Verb helpers
 
@@ -4767,7 +4854,7 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 ## Gotchas
 
 - **`globalSetup` must export `setup` and `teardown`.** Vitest reads them by name. A typo in the export gets you a confusing "server not running" error on the first `testGet` call.
-- **Port conflicts.** If `http.port` matches your running dev server, `startHttpTestServer()` fails to bind. Either stop the dev server or set a test-only port: `http: { port: 3999 }` in a test-config branch.
+- **Port conflicts.** If `http.port` matches your running dev server, the preflight fails with a `PortInUseError` naming the port. Either stop the dev server or pass a free one: `startHttpTestServer({ port: 3999 })`.
 - **Auth tokens need a real user.** Generating a JWT with a non-existent `user_id` works — but the auth middleware's user-loading step will reject the request with 401 because it can't find the user in the DB.
 - **`expectJson` parses the body once.** If you call it twice on the same response, the second call gets an already-consumed stream error. Capture the result.
 - **The HTTP server's connection is NOT torn down between test files.** Data persists across files within a single `vitest` run. Either truncate in `afterEach` / `afterAll`, or design your tests to be order-independent.

package/llms.txt

@@ -26,7 +26,7 @@
 - [send-mail](@warlock.js/core/send-mail/SKILL.md): Send transactional email — `Mail` fluent builder, `sendMail()` direct call, React Email components. Test mode auto-captures into an in-memory mailbox; dev mode logs. Triggers: `Mail.to`, `sendMail`, `setMailMode`, `mailEvents`, `assertMailSent`, `getTestMailbox`, `wasMailSentTo`, `closeAllMailers`; "send a transactional email", "build a React Email template", "configure SMTP or SES", "assert an email was sent in tests"; typical import `import { Mail, sendMail } from "@warlock.js/core"`. Skip: per-config wiring — `@warlock.js/core/configure-app/SKILL.md`; layered service patterns — `@warlock.js/core/warlock-conventions/SKILL.md`; competing libs `nodemailer` direct, `@sendgrid/mail`, `resend`, `mailgun.js`.
 - [send-response](@warlock.js/core/send-response/SKILL.md): Send HTTP responses via @warlock.js/core's Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `ResourceNotFoundError`, `ForbiddenError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — `@warlock.js/core/create-controller/SKILL.md`; route registration — `@warlock.js/core/register-route/SKILL.md`; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.
 - [store-file](@warlock.js/core/store-file/SKILL.md): Read/write/delete files via the `storage` singleton — disks, drivers (local/S3/R2/DO Spaces), `storage.use(name)`, `StorageFile` handles, presigned URLs. Triggers: `storage.put`, `storage.get`, `storage.use`, `StorageFile`, `storageConfigurations`, `getPresignedUrl`, `getPresignedUploadUrl`; "save an uploaded file", "switch between local and S3", "generate a presigned URL", "read file metadata"; typical import `import { storage } from "@warlock.js/core"`. Skip: multipart parsing + image chain — `@warlock.js/core/upload-file/SKILL.md`; image transforms — `@warlock.js/core/process-image/SKILL.md`; storage config shape — `@warlock.js/core/configure-app/SKILL.md`; competing libs `@aws-sdk/client-s3`, `multer`, `formidable`.
-- [test-http](@warlock.js/core/test-http/SKILL.md): Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.
+- [test-http](@warlock.js/core/test-http/SKILL.md): Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `startHttpTestServer({ port })`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`, `PortInUseError`, `assertPortIsAvailable`, `isPortAvailable`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape", "test server port already in use", "EADDRINUSE while running tests", "run tests while the dev server is up"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.
 - [test-service](@warlock.js/core/test-service/SKILL.md): Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.
 - [update-packages](@warlock.js/core/update-packages/SKILL.md): Keep a project current with `warlock update` — bump every `@warlock.js/*` dependency in package.json to its latest published version (range operator preserved), then run the lockfile-detected package manager install. Also covers the `warlock dev` update notice, its `u` update-and-restart keyboard shortcut, and the `devServer.checkForUpdates` toggle. Triggers: `warlock update`, `--no-install`, `--dry-run`, `--check`, `checkForUpdates`, `fetchLatestVersion`, `isNewerVersion`; "update warlock packages", "upgrade the framework", "is there a new warlock version", "update notice in the dev server", "press u to update", "dev server keyboard shortcut", "update check offline", "bump @warlock.js/* to latest"; typical CLI `warlock update`. Skip: dev/build/start runtime — `@warlock.js/core/run-app/SKILL.md`; writing a custom command — `@warlock.js/core/write-cli-command/SKILL.md`; installing a NEW feature package (auth, mail, storage) — that is `warlock add`; releasing/publishing the framework — workspace release tooling, not this command.
 - [upload-file](@warlock.js/core/upload-file/SKILL.md): Handle multipart file uploads — read via `request.file()` or `request.validated()`, validate with `v.file()`, save via `UploadedFile.save()` or the storage layer, transform images inline. Triggers: `UploadedFile`, `request.file`, `v.file`, `.save`, `.saveAs`, `.resize`, `.format`, `.quality`, `.image`, `.mimeType`, `.maxSize`; "accept a file upload", "validate file size and mime", "save to S3 or local disk", "resize an uploaded image on save"; typical import `import type { UploadedFile, RequestHandler } from "@warlock.js/core"`. Skip: storage drivers + presigned URLs — `@warlock.js/core/store-file/SKILL.md`; image-only transforms — `@warlock.js/core/process-image/SKILL.md`; schema rules — `@warlock.js/core/validate-input/SKILL.md`; competing libs `multer`, `formidable`, `busboy`.