@warlock.js/core 4.11.0 → 4.13.0

package/esm/production/production-builder.mjs

@@ -13,6 +13,44 @@ import esbuild from "esbuild";
 
 //#region ../core/src/production/production-builder.ts
 /**
+* Recreates `require`, `__filename` and `__dirname` at the top of an ESM bundle.
+*
+* Bundled CommonJS dependencies call `require("node:assert")` and read
+* `__dirname` to locate their own assets. Neither exists in an ES module, so
+* esbuild substitutes a stub that throws — **after the build has reported
+* success**. `Dynamic require of "node:assert" is not supported` is that stub
+* firing, and it is the defect this shim removes.
+*
+* `__dirname` matters as much as `require`: without it a dependency resolving
+* an asset path silently gets `undefined` and fails later, further from the
+* cause.
+*
+* Written as one line because esbuild inserts a banner verbatim above the
+* bundle and a multi-line string here would shift every mapped line.
+*/
+const ESM_INTEROP_SHIM = "import{createRequire as __wlCreateRequire}from'node:module';import{fileURLToPath as __wlFileURLToPath}from'node:url';import{dirname as __wlDirname}from'node:path';const require=__wlCreateRequire(import.meta.url);const __filename=__wlFileURLToPath(import.meta.url);const __dirname=__wlDirname(__filename);";
+/**
+* Combine the framework's banner with the user's, keeping both.
+*
+* esbuild's `banner` is an object keyed by output type, and every merge in the
+* path to it — the config merge and the options spread — REPLACES that object
+* rather than merging it. So whichever is applied second silently deletes the
+* other. This is the only place the two can coexist.
+*
+* The shim goes first: it defines `require`, which a user banner may use.
+*
+* @param userBanner banner from `warlock.config.ts`, if any
+* @param shim the interop shim, or undefined when it does not apply
+*/
+function mergeBanner(userBanner, shim) {
+	if (!shim) return userBanner;
+	const userJs = userBanner?.js;
+	return {
+		...userBanner,
+		js: userJs ? `${shim}${userJs}` : shim
+	};
+}
+/**
 * Production Builder
 * Generates production-ready files and bundles them for deployment
 * Build options are loaded from warlock.config.ts
@@ -244,17 +282,26 @@ bootstrap();
 		const outDir = this.options.outdir;
 		const outFileName = this.options.outFile;
 		const entryName = path.basename(outFileName, path.extname(outFileName));
+		const singleBundle = this.options.singleBundle === true;
+		const esmShim = this.options.esmShim !== false;
+		const userBanner = this.options.banner;
 		delete this.options.outFile;
 		delete this.options.entryPath;
+		delete this.options.singleBundle;
+		delete this.options.esmShim;
+		delete this.options.banner;
 		await ensureDirectoryAsync(outDir);
 		const alias = this.buildAliasMapFromTsconfig();
+		const isEsm = (this.options.format ?? "esm") === "esm";
+		const banner = mergeBanner(userBanner, esmShim && isEsm ? ESM_INTEROP_SHIM : void 0);
+		if (singleBundle) console.log(colors.magenta("   Single-bundle mode — one JS file" + (esmShim && isEsm ? " with the ESM interop shim" : "") + ". Native .node addons are still emitted alongside it."));
 		try {
 			await esbuild.build({
 				platform: "node",
 				entryPoints: [entryPoint],
 				bundle: true,
-				splitting: true,
-				packages: "external",
+				splitting: !singleBundle,
+				packages: singleBundle ? "bundle" : "external",
 				minify: this.options.minify,
 				sourcemap: this.options.sourcemap === true ? "linked" : this.options.sourcemap,
 				format: "esm",
@@ -263,7 +310,8 @@ bootstrap();
 				entryNames: entryName,
 				alias,
 				plugins: [nativeNodeModulesPlugin],
-				...this.options
+				...this.options,
+				...banner ? { banner } : {}
 			});
 		} catch (e) {
 			console.log(e);

package/esm/production/production-builder.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"production-builder.mjs","names":[],"sources":["../../../../../../../core/src/production/production-builder.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\r\nimport {\r\n  ensureDirectoryAsync,\r\n  fileExistsAsync,\r\n  getFileAsync,\r\n  getJsonFileAsync,\r\n  putFileAsync,\r\n  removeDirectoryAsync,\r\n} from \"@warlock.js/fs\";\r\nimport esbuild from \"esbuild\";\r\nimport glob from \"fast-glob\";\r\nimport path from \"path\";\r\nimport { tsconfigManager } from \"../dev-server/tsconfig-manager\";\r\nimport { appPath, rootPath, warlockPath } from \"../utils\";\r\nimport { assertGeneratedImportsAreDeclared } from \"./assert-generated-imports\";\r\nimport { nativeNodeModulesPlugin } from \"./esbuild-plugins\";\r\nimport { resolveBuildConfig, type ResolvedBuildConfig } from \"./resolve-build-config\";\r\nimport { toCamelCase, toKebabCase } from \"@mongez/reinforcements\";\r\n\r\n/**\r\n * Production Builder\r\n * Generates production-ready files and bundles them for deployment\r\n * Build options are loaded from warlock.config.ts\r\n */\r\nexport class ProductionBuilder {\r\n  private options!: ResolvedBuildConfig;\r\n  private readonly productionDir = warlockPath(\"production\");\r\n\r\n  /**\r\n   * Main build entry point\r\n   */\r\n  public async build(): Promise<void> {\r\n    console.log(colors.cyan(\"Building for production...\\n\"));\r\n\r\n    // Step 1: Initialize options from config\r\n    await this.initializeOptions();\r\n\r\n    // Step 2: Generate combined files\r\n    await this.generateCombinedFiles();\r\n\r\n    // Step 3: Generate entry point\r\n    await this.generateEntryPoint();\r\n\r\n    // Step 4: Refuse to bundle code the app could not resolve at runtime\r\n    await this.assertGeneratedImports();\r\n\r\n    // Step 5: Bundle with esbuild\r\n    await this.bundle();\r\n\r\n    // Step 6: Remove production folder\r\n    await removeDirectoryAsync(this.productionDir);\r\n\r\n    console.log(colors.green(\"Build complete!\"));\r\n    console.log(`Start production server by running ${colors.cyan(\"warlock start\")}`);\r\n  }\r\n\r\n  /**\r\n   * Initialize options from warlock.config.ts\r\n   */\r\n  private async initializeOptions(): Promise<void> {\r\n    this.options = resolveBuildConfig();\r\n\r\n    // Ensure production directory exists\r\n    await ensureDirectoryAsync(this.productionDir);\r\n  }\r\n\r\n  /**\r\n   * Track which special files were generated\r\n   */\r\n  private generatedFiles = {\r\n    locales: false,\r\n    events: false,\r\n    main: false,\r\n    routes: false,\r\n  };\r\n\r\n  /**\r\n   * Generate all combined files\r\n   */\r\n  private async generateCombinedFiles(): Promise<void> {\r\n    console.log(colors.yellow(\"   Generating production files...\"));\r\n\r\n    // Generate bootstrap.ts file\r\n    await this.generateBootstrap();\r\n\r\n    // Generate config loader\r\n    await this.generateConfigLoader();\r\n\r\n    // Generate special files and track which ones have content\r\n    const [locales, events, main, routes] = await Promise.all([\r\n      this.generateLocales(),\r\n      this.generateEvents(),\r\n      this.generateMain(),\r\n      this.generateRoutes(),\r\n    ]);\r\n\r\n    this.generatedFiles = { locales, events, main, routes };\r\n  }\r\n\r\n  /**\r\n   * Generate bootstrap.ts - ensures bootstrap() runs first and sets production environment\r\n   */\r\n  private async generateBootstrap(): Promise<void> {\r\n    let content = `import { bootstrap, Application } from \"@warlock.js/core\";\r\n\r\n// Set production environment\r\nApplication.setRuntimeStrategy(\"production\");\r\nApplication.setEnvironment(\"production\");\r\n\r\n// Bootstrap the application\r\nbootstrap();\r\n`;\r\n    if (await fileExistsAsync(appPath(\"bootstrap.ts\"))) {\r\n      content += \"import './../../src/app/bootstrap';\\n\";\r\n    }\r\n\r\n    await putFileAsync(path.join(this.productionDir, \"bootstrap.ts\"), content);\r\n  }\r\n\r\n  /**\r\n   * Fail the build when generated code imports a package the app does not\r\n   * declare.\r\n   *\r\n   * The bundler is configured `packages: \"external\"`, so every bare specifier\r\n   * written above survives verbatim into an artifact that resolves against the\r\n   * **consuming app's** node_modules. A framework-internal dependency imported\r\n   * there resolves by accident under npm/yarn hoisting and dies under pnpm —\r\n   * which is how a production app shipped that could not boot. Rewriting the\r\n   * offending import fixes today's bundle; this check is what stops the next\r\n   * change to the generator from quietly reintroducing it.\r\n   */\r\n  private async assertGeneratedImports(): Promise<void> {\r\n    const generatedPaths = await glob(\"**/*.{ts,tsx,js,mjs}\", {\r\n      cwd: this.productionDir,\r\n      absolute: false,\r\n    });\r\n\r\n    const [files, appPackage] = await Promise.all([\r\n      Promise.all(\r\n        generatedPaths.map(async (file) => ({\r\n          file,\r\n          content: await getFileAsync(path.join(this.productionDir, file)),\r\n        })),\r\n      ),\r\n      getJsonFileAsync<{ dependencies?: Record<string, string> }>(rootPath(\"package.json\")),\r\n    ]);\r\n\r\n    assertGeneratedImportsAreDeclared(files, Object.keys(appPackage.dependencies ?? {}));\r\n  }\r\n\r\n  /**\r\n   * Glob for module files matching a pattern\r\n   * Returns relative paths from .warlock/production/ to src/app/\r\n   */\r\n  private async globModule(fileName: string): Promise<string[]> {\r\n    const pattern = `**/${fileName}.{ts,tsx}`;\r\n    const appDirectory = appPath();\r\n\r\n    const files = await glob(pattern, {\r\n      cwd: appDirectory,\r\n      absolute: false,\r\n    });\r\n\r\n    // Convert to relative paths from .warlock/production/ to src/app/\r\n    // e.g., \"users/main\" -> \"../../src/app/users/main\"\r\n    return files.map((file) => \"../../src/app/\" + file.replace(/\\.(ts|tsx)$/, \"\"));\r\n  }\r\n\r\n  /**\r\n   * Glob for files in a specific directory pattern\r\n   * Returns relative paths from .warlock/production/ to src/app/\r\n   */\r\n  private async globModuleDirectory(directory: string): Promise<string[]> {\r\n    const pattern = `**/${directory}/*.{ts,tsx}`;\r\n    const appDirectory = appPath();\r\n\r\n    const files = await glob(pattern, {\r\n      cwd: appDirectory,\r\n      absolute: false,\r\n    });\r\n\r\n    return files.map((file) => \"../../src/app/\" + file.replace(/\\.(ts|tsx)$/, \"\"));\r\n  }\r\n\r\n  /**\r\n   * Generate config-loader.ts\r\n   */\r\n  private async generateConfigLoader(): Promise<void> {\r\n    const configDirectory = path.join(process.cwd(), \"src/config\");\r\n\r\n    const files = await glob(\"*.{ts,tsx}\", {\r\n      cwd: configDirectory,\r\n      absolute: false,\r\n    });\r\n\r\n    const configNames = files.map((f) => f.replace(/\\.(ts|tsx)$/, \"\"));\r\n\r\n    // Only `@warlock.js/core` — the one package the app itself declares. See\r\n    // `assertGeneratedImportsAreDeclared`: `@mongez/config` is core's own\r\n    // dependency, so a bare import of it resolved by luck under npm/yarn\r\n    // hoisting and died under pnpm's strict layout.\r\n    const imports: string[] = [\r\n      'import { setConfig, configSpecialHandlers } from \"@warlock.js/core\";',\r\n    ];\r\n    const configImports: string[] = [];\r\n    const configSetCalls: string[] = [];\r\n    const executors: string[] = [];\r\n\r\n    for (const configName of configNames) {\r\n      const properConfigName = toCamelCase(configName);\r\n      const varName = `${properConfigName}Config`;\r\n      configImports.push(`import ${varName} from \"../../src/config/${configName}\";`);\r\n      configSetCalls.push(`setConfig(\"${properConfigName}\", ${varName});`);\r\n      executors.push(`await configSpecialHandlers.execute(\"${properConfigName}\", ${varName});`);\r\n    }\r\n\r\n    let content = [\r\n      ...imports,\r\n      \"\",\r\n      \"// Config imports\",\r\n      ...configImports,\r\n      \"\",\r\n      \"// Register configs\",\r\n      ...configSetCalls,\r\n      \"\",\r\n      \"// Special handlers\",\r\n      ...executors,\r\n      \"\",\r\n    ].join(\"\\n\");\r\n\r\n    if (await fileExistsAsync(appPath(\"prestart.ts\"))) {\r\n      content += \"import './../../src/app/prestart';\\n\";\r\n    }\r\n\r\n    await putFileAsync(path.join(this.productionDir, \"config-loader.ts\"), content);\r\n  }\r\n\r\n  /**\r\n   * Generate locales.ts (only if there are locale files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateLocales(): Promise<boolean> {\r\n    const files = await this.globModule(\"utils/locales\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"locales.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate events.ts (only if there are event files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateEvents(): Promise<boolean> {\r\n    const files = await this.globModuleDirectory(\"events\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"events.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate main.ts (only if there are main files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateMain(): Promise<boolean> {\r\n    const files = await this.globModule(\"main\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"main.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate routes.ts (only if there are route files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateRoutes(): Promise<boolean> {\r\n    const files = await this.globModule(\"routes\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"routes.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate a file with imports from all given files\r\n   */\r\n  private async generateImportsFile(importPaths: string[], outputFile: string): Promise<void> {\r\n    const imports = importPaths.map((importPath) => `import \"${importPath}\";`);\r\n    const content = imports.join(\"\\n\") + \"\\n\";\r\n    await putFileAsync(path.join(this.productionDir, outputFile), content);\r\n  }\r\n\r\n  /**\r\n   * Generate the main entry point (app.ts)\r\n   */\r\n  private async generateEntryPoint(): Promise<void> {\r\n    console.log(colors.yellow(\"   Generating entry point...\"));\r\n\r\n    // Build imports based on which files were generated\r\n    const imports: string[] = [\r\n      \"// 1. Bootstrap (loads .env, initializes framework)\",\r\n      'import \"./bootstrap\";',\r\n      \"\",\r\n      \"// 2. Load configs\",\r\n      'import \"./config-loader\";',\r\n      \"\",\r\n      \"// 3. Start early-phase connectors (database, cache, logger, ...)\",\r\n      \"//    so data sources, cache, etc. are ready before app code runs\",\r\n      'import { Application, connectorsManager, ConnectorLifecyclePhase } from \"@warlock.js/core\";',\r\n      \"await connectorsManager.startPhase(ConnectorLifecyclePhase.Early);\",\r\n    ];\r\n\r\n    // App code uses dynamic `await import(...)` so each module's side\r\n    // effects fire at THIS point in execution. Static imports would be\r\n    // hoisted to module-instantiation time (before the early-phase await\r\n    // resolves), which is exactly the bug this split is meant to fix.\r\n    // Requires `splitting: true` in esbuild (set below in bundle()).\r\n    imports.push(\"\", \"// 4. Load app code (events, locales, main, routes)\");\r\n\r\n    if (this.generatedFiles.events) {\r\n      imports.push('await import(\"./events\");');\r\n    }\r\n    if (this.generatedFiles.locales) {\r\n      imports.push('await import(\"./locales\");');\r\n    }\r\n    if (this.generatedFiles.main) {\r\n      imports.push('await import(\"./main\");');\r\n    }\r\n    if (this.generatedFiles.routes) {\r\n      imports.push('await import(\"./routes\");');\r\n    }\r\n\r\n    // Start late-phase connectors after app code registers routes/listeners\r\n    imports.push(\r\n      \"\",\r\n      \"// 5. Start late-phase connectors (http, socket) — routes and\",\r\n      \"//    listeners registered by app code are now ready to bind\",\r\n      \"await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);\",\r\n      \"\",\r\n      \"// 6. Signal a complete boot so `Application.onceBooted(...)` listeners fire\",\r\n      \"Application.markBooted({ environment: Application.environment, runtimeStrategy: Application.runtimeStrategy });\",\r\n      \"connectorsManager.shutdownOnProcessKill();\",\r\n    );\r\n\r\n    const content = imports.join(\"\\n\") + \"\\n\";\r\n    await putFileAsync(path.join(this.productionDir, \"app.ts\"), content);\r\n  }\r\n\r\n  /**\r\n   * Bundle with esbuild\r\n   */\r\n  private async bundle(): Promise<void> {\r\n    console.log(colors.magenta(\"   Bundling with esbuild...\"));\r\n\r\n    const entryPoint = path.join(this.productionDir, \"app.ts\");\r\n    const outDir = this.options.outdir!;\r\n    const outFileName = this.options.outFile!;\r\n    // Strip extension so entryNames produces \"<base>.js\" via esbuild\r\n    const entryName = path.basename(outFileName, path.extname(outFileName));\r\n\r\n    delete this.options.outFile;\r\n    delete this.options.entryPath;\r\n\r\n    await ensureDirectoryAsync(outDir);\r\n\r\n    const alias = this.buildAliasMapFromTsconfig();\r\n\r\n\r\n    try {\r\n      \r\n    await esbuild.build({\r\n      platform: \"node\",\r\n      entryPoints: [entryPoint],\r\n      bundle: true,\r\n      // Required so dynamic `await import(\"./main\")` in the generated\r\n      // app.ts produces separate chunks loaded at the runtime call site,\r\n      // instead of inlining the modules at instantiation time (which\r\n      // would defeat the early/late phase split).\r\n      splitting: true,\r\n      packages: \"external\",\r\n      minify: this.options!.minify,\r\n      sourcemap: this.options!.sourcemap === true ? \"linked\" : this.options!.sourcemap,\r\n      format: \"esm\",\r\n      // Targeting a concrete Node version (not \"esnext\") so esbuild\r\n      // transpiles TC39 stage 3 decorators into helpers — Node does not\r\n      // implement them natively yet.\r\n      target: [\"node22\"],\r\n      outdir: outDir,\r\n      entryNames: entryName,\r\n      alias,\r\n      plugins: [nativeNodeModulesPlugin],\r\n      ...(this.options as any),\r\n    });\r\n    } catch (e) {\r\n      console.log(e);\r\n      throw e;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Build an alias map from tsconfig `paths` so esbuild resolves local\r\n   * source aliases (e.g. `@warlock.js/cascade`) to their on-disk source\r\n   * folders during bundling. Without this, `packages: \"external\"` would\r\n   * leave those bare specifiers as raw imports and Node would fail to\r\n   * resolve them at runtime (they aren't installed in node_modules).\r\n   *\r\n   * Only exact (non-wildcard) aliases are included — esbuild's `alias`\r\n   * option doesn't support glob-style mappings.\r\n   */\r\n  private buildAliasMapFromTsconfig(): Record<string, string> {\r\n    tsconfigManager.init();\r\n\r\n    const alias: Record<string, string> = {};\r\n    const baseUrl = path.resolve(process.cwd(), tsconfigManager.baseUrl);\r\n\r\n    for (const [from, to] of Object.entries(tsconfigManager.aliases)) {\r\n      if (from.endsWith(\"/*\") || !Array.isArray(to) || to.length === 0) {\r\n        continue;\r\n      }\r\n\r\n      alias[from] = path.resolve(baseUrl, to[0]);\r\n    }\r\n\r\n    return alias;\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAwBA,IAAa,oBAAb,MAA+B;;uBAEI,YAAY,YAAY;wBA2ChC;GACvB,SAAS;GACT,QAAQ;GACR,MAAM;GACN,QAAQ;EACV;;;;;CA3CA,MAAa,QAAuB;EAClC,QAAQ,IAAI,OAAO,KAAK,8BAA8B,CAAC;EAGvD,MAAM,KAAK,kBAAkB;EAG7B,MAAM,KAAK,sBAAsB;EAGjC,MAAM,KAAK,mBAAmB;EAG9B,MAAM,KAAK,uBAAuB;EAGlC,MAAM,KAAK,OAAO;EAGlB,MAAM,qBAAqB,KAAK,aAAa;EAE7C,QAAQ,IAAI,OAAO,MAAM,iBAAiB,CAAC;EAC3C,QAAQ,IAAI,sCAAsC,OAAO,KAAK,eAAe,GAAG;CAClF;;;;CAKA,MAAc,oBAAmC;EAC/C,KAAK,UAAU,mBAAmB;EAGlC,MAAM,qBAAqB,KAAK,aAAa;CAC/C;;;;CAeA,MAAc,wBAAuC;EACnD,QAAQ,IAAI,OAAO,OAAO,mCAAmC,CAAC;EAG9D,MAAM,KAAK,kBAAkB;EAG7B,MAAM,KAAK,qBAAqB;EAGhC,MAAM,CAAC,SAAS,QAAQ,MAAM,UAAU,MAAM,QAAQ,IAAI;GACxD,KAAK,gBAAgB;GACrB,KAAK,eAAe;GACpB,KAAK,aAAa;GAClB,KAAK,eAAe;EACtB,CAAC;EAED,KAAK,iBAAiB;GAAE;GAAS;GAAQ;GAAM;EAAO;CACxD;;;;CAKA,MAAc,oBAAmC;EAC/C,IAAI,UAAU;;;;;;;;;EASd,IAAI,MAAM,gBAAgB,QAAQ,cAAc,CAAC,GAC/C,WAAW;EAGb,MAAM,aAAa,KAAK,KAAK,KAAK,eAAe,cAAc,GAAG,OAAO;CAC3E;;;;;;;;;;;;;CAcA,MAAc,yBAAwC;EACpD,MAAM,iBAAiB,MAAM,KAAK,wBAAwB;GACxD,KAAK,KAAK;GACV,UAAU;EACZ,CAAC;EAED,MAAM,CAAC,OAAO,cAAc,MAAM,QAAQ,IAAI,CAC5C,QAAQ,IACN,eAAe,IAAI,OAAO,UAAU;GAClC;GACA,SAAS,MAAM,aAAa,KAAK,KAAK,KAAK,eAAe,IAAI,CAAC;EACjE,EAAE,CACJ,GACA,iBAA4D,SAAS,cAAc,CAAC,CACtF,CAAC;EAED,kCAAkC,OAAO,OAAO,KAAK,WAAW,gBAAgB,CAAC,CAAC,CAAC;CACrF;;;;;CAMA,MAAc,WAAW,UAAqC;EAW5D,QAAO,MAPa,KAAK,MAHH,SAAS,YAGG;GAChC,KAHmB,QAGH;GAChB,UAAU;EACZ,CAAC,EAIW,CAAC,KAAK,SAAS,mBAAmB,KAAK,QAAQ,eAAe,EAAE,CAAC;CAC/E;;;;;CAMA,MAAc,oBAAoB,WAAsC;EAStE,QAAO,MALa,KAAK,MAHH,UAAU,cAGE;GAChC,KAHmB,QAGH;GAChB,UAAU;EACZ,CAAC,EAEW,CAAC,KAAK,SAAS,mBAAmB,KAAK,QAAQ,eAAe,EAAE,CAAC;CAC/E;;;;CAKA,MAAc,uBAAsC;EAQlD,MAAM,eAAc,MALA,KAAK,cAAc;GACrC,KAHsB,KAAK,KAAK,QAAQ,IAAI,GAAG,YAG5B;GACnB,UAAU;EACZ,CAAC,EAEwB,CAAC,KAAK,MAAM,EAAE,QAAQ,eAAe,EAAE,CAAC;EAMjE,MAAM,UAAoB,CACxB,wEACF;EACA,MAAM,gBAA0B,CAAC;EACjC,MAAM,iBAA2B,CAAC;EAClC,MAAM,YAAsB,CAAC;EAE7B,KAAK,MAAM,cAAc,aAAa;GACpC,MAAM,mBAAmB,YAAY,UAAU;GAC/C,MAAM,UAAU,GAAG,iBAAiB;GACpC,cAAc,KAAK,UAAU,QAAQ,0BAA0B,WAAW,GAAG;GAC7E,eAAe,KAAK,cAAc,iBAAiB,KAAK,QAAQ,GAAG;GACnE,UAAU,KAAK,wCAAwC,iBAAiB,KAAK,QAAQ,GAAG;EAC1F;EAEA,IAAI,UAAU;GACZ,GAAG;GACH;GACA;GACA,GAAG;GACH;GACA;GACA,GAAG;GACH;GACA;GACA,GAAG;GACH;EACF,CAAC,CAAC,KAAK,IAAI;EAEX,IAAI,MAAM,gBAAgB,QAAQ,aAAa,CAAC,GAC9C,WAAW;EAGb,MAAM,aAAa,KAAK,KAAK,KAAK,eAAe,kBAAkB,GAAG,OAAO;CAC/E;;;;;CAMA,MAAc,kBAAoC;EAChD,MAAM,QAAQ,MAAM,KAAK,WAAW,eAAe;EACnD,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,MAAM,KAAK,oBAAoB,OAAO,YAAY;EAClD,OAAO;CACT;;;;;CAMA,MAAc,iBAAmC;EAC/C,MAAM,QAAQ,MAAM,KAAK,oBAAoB,QAAQ;EACrD,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,MAAM,KAAK,oBAAoB,OAAO,WAAW;EACjD,OAAO;CACT;;;;;CAMA,MAAc,eAAiC;EAC7C,MAAM,QAAQ,MAAM,KAAK,WAAW,MAAM;EAC1C,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,MAAM,KAAK,oBAAoB,OAAO,SAAS;EAC/C,OAAO;CACT;;;;;CAMA,MAAc,iBAAmC;EAC/C,MAAM,QAAQ,MAAM,KAAK,WAAW,QAAQ;EAC5C,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,MAAM,KAAK,oBAAoB,OAAO,WAAW;EACjD,OAAO;CACT;;;;CAKA,MAAc,oBAAoB,aAAuB,YAAmC;EAE1F,MAAM,UADU,YAAY,KAAK,eAAe,WAAW,WAAW,GAChD,CAAC,CAAC,KAAK,IAAI,IAAI;EACrC,MAAM,aAAa,KAAK,KAAK,KAAK,eAAe,UAAU,GAAG,OAAO;CACvE;;;;CAKA,MAAc,qBAAoC;EAChD,QAAQ,IAAI,OAAO,OAAO,8BAA8B,CAAC;EAGzD,MAAM,UAAoB;GACxB;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EACF;EAOA,QAAQ,KAAK,IAAI,qDAAqD;EAEtE,IAAI,KAAK,eAAe,QACtB,QAAQ,KAAK,6BAA2B;EAE1C,IAAI,KAAK,eAAe,SACtB,QAAQ,KAAK,8BAA4B;EAE3C,IAAI,KAAK,eAAe,MACtB,QAAQ,KAAK,2BAAyB;EAExC,IAAI,KAAK,eAAe,QACtB,QAAQ,KAAK,6BAA2B;EAI1C,QAAQ,KACN,IACA,mEACA,gEACA,qEACA,IACA,gFACA,mHACA,4CACF;EAEA,MAAM,UAAU,QAAQ,KAAK,IAAI,IAAI;EACrC,MAAM,aAAa,KAAK,KAAK,KAAK,eAAe,QAAQ,GAAG,OAAO;CACrE;;;;CAKA,MAAc,SAAwB;EACpC,QAAQ,IAAI,OAAO,QAAQ,6BAA6B,CAAC;EAEzD,MAAM,aAAa,KAAK,KAAK,KAAK,eAAe,QAAQ;EACzD,MAAM,SAAS,KAAK,QAAQ;EAC5B,MAAM,cAAc,KAAK,QAAQ;EAEjC,MAAM,YAAY,KAAK,SAAS,aAAa,KAAK,QAAQ,WAAW,CAAC;EAEtE,OAAO,KAAK,QAAQ;EACpB,OAAO,KAAK,QAAQ;EAEpB,MAAM,qBAAqB,MAAM;EAEjC,MAAM,QAAQ,KAAK,0BAA0B;EAG7C,IAAI;GAEJ,MAAM,QAAQ,MAAM;IAClB,UAAU;IACV,aAAa,CAAC,UAAU;IACxB,QAAQ;IAKR,WAAW;IACX,UAAU;IACV,QAAQ,KAAK,QAAS;IACtB,WAAW,KAAK,QAAS,cAAc,OAAO,WAAW,KAAK,QAAS;IACvE,QAAQ;IAIR,QAAQ,CAAC,QAAQ;IACjB,QAAQ;IACR,YAAY;IACZ;IACA,SAAS,CAAC,uBAAuB;IACjC,GAAI,KAAK;GACX,CAAC;EACD,SAAS,GAAG;GACV,QAAQ,IAAI,CAAC;GACb,MAAM;EACR;CACF;;;;;;;;;;;CAYA,AAAQ,4BAAoD;EAC1D,gBAAgB,KAAK;EAErB,MAAM,QAAgC,CAAC;EACvC,MAAM,UAAU,KAAK,QAAQ,QAAQ,IAAI,GAAG,gBAAgB,OAAO;EAEnE,KAAK,MAAM,CAAC,MAAM,OAAO,OAAO,QAAQ,gBAAgB,OAAO,GAAG;GAChE,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,QAAQ,EAAE,KAAK,GAAG,WAAW,GAC7D;GAGF,MAAM,QAAQ,KAAK,QAAQ,SAAS,GAAG,EAAE;EAC3C;EAEA,OAAO;CACT;AACF"}
+{"version":3,"file":"production-builder.mjs","names":[],"sources":["../../../../../../../core/src/production/production-builder.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\r\nimport {\r\n  ensureDirectoryAsync,\r\n  fileExistsAsync,\r\n  getFileAsync,\r\n  getJsonFileAsync,\r\n  putFileAsync,\r\n  removeDirectoryAsync,\r\n} from \"@warlock.js/fs\";\r\nimport esbuild from \"esbuild\";\r\nimport glob from \"fast-glob\";\r\nimport path from \"path\";\r\nimport { tsconfigManager } from \"../dev-server/tsconfig-manager\";\r\nimport { appPath, rootPath, warlockPath } from \"../utils\";\r\nimport { assertGeneratedImportsAreDeclared } from \"./assert-generated-imports\";\r\nimport { nativeNodeModulesPlugin } from \"./esbuild-plugins\";\r\nimport { resolveBuildConfig, type ResolvedBuildConfig } from \"./resolve-build-config\";\r\nimport { toCamelCase, toKebabCase } from \"@mongez/reinforcements\";\r\n\r\n/**\r\n * Recreates `require`, `__filename` and `__dirname` at the top of an ESM bundle.\r\n *\r\n * Bundled CommonJS dependencies call `require(\"node:assert\")` and read\r\n * `__dirname` to locate their own assets. Neither exists in an ES module, so\r\n * esbuild substitutes a stub that throws — **after the build has reported\r\n * success**. `Dynamic require of \"node:assert\" is not supported` is that stub\r\n * firing, and it is the defect this shim removes.\r\n *\r\n * `__dirname` matters as much as `require`: without it a dependency resolving\r\n * an asset path silently gets `undefined` and fails later, further from the\r\n * cause.\r\n *\r\n * Written as one line because esbuild inserts a banner verbatim above the\r\n * bundle and a multi-line string here would shift every mapped line.\r\n */\r\nconst ESM_INTEROP_SHIM =\r\n  \"import{createRequire as __wlCreateRequire}from'node:module';\" +\r\n  \"import{fileURLToPath as __wlFileURLToPath}from'node:url';\" +\r\n  \"import{dirname as __wlDirname}from'node:path';\" +\r\n  \"const require=__wlCreateRequire(import.meta.url);\" +\r\n  \"const __filename=__wlFileURLToPath(import.meta.url);\" +\r\n  \"const __dirname=__wlDirname(__filename);\";\r\n\r\n/**\r\n * Combine the framework's banner with the user's, keeping both.\r\n *\r\n * esbuild's `banner` is an object keyed by output type, and every merge in the\r\n * path to it — the config merge and the options spread — REPLACES that object\r\n * rather than merging it. So whichever is applied second silently deletes the\r\n * other. This is the only place the two can coexist.\r\n *\r\n * The shim goes first: it defines `require`, which a user banner may use.\r\n *\r\n * @param userBanner banner from `warlock.config.ts`, if any\r\n * @param shim the interop shim, or undefined when it does not apply\r\n */\r\nfunction mergeBanner(\r\n  userBanner: Record<string, string> | undefined,\r\n  shim: string | undefined,\r\n): Record<string, string> | undefined {\r\n  if (!shim) return userBanner;\r\n\r\n  const userJs = userBanner?.js;\r\n\r\n  return {\r\n    ...userBanner,\r\n    js: userJs ? `${shim}${userJs}` : shim,\r\n  };\r\n}\r\n\r\n/**\r\n * Production Builder\r\n * Generates production-ready files and bundles them for deployment\r\n * Build options are loaded from warlock.config.ts\r\n */\r\nexport class ProductionBuilder {\r\n  private options!: ResolvedBuildConfig;\r\n  private readonly productionDir = warlockPath(\"production\");\r\n\r\n  /**\r\n   * Main build entry point\r\n   */\r\n  public async build(): Promise<void> {\r\n    console.log(colors.cyan(\"Building for production...\\n\"));\r\n\r\n    // Step 1: Initialize options from config\r\n    await this.initializeOptions();\r\n\r\n    // Step 2: Generate combined files\r\n    await this.generateCombinedFiles();\r\n\r\n    // Step 3: Generate entry point\r\n    await this.generateEntryPoint();\r\n\r\n    // Step 4: Refuse to bundle code the app could not resolve at runtime\r\n    await this.assertGeneratedImports();\r\n\r\n    // Step 5: Bundle with esbuild\r\n    await this.bundle();\r\n\r\n    // Step 6: Remove production folder\r\n    await removeDirectoryAsync(this.productionDir);\r\n\r\n    console.log(colors.green(\"Build complete!\"));\r\n    console.log(`Start production server by running ${colors.cyan(\"warlock start\")}`);\r\n  }\r\n\r\n  /**\r\n   * Initialize options from warlock.config.ts\r\n   */\r\n  private async initializeOptions(): Promise<void> {\r\n    this.options = resolveBuildConfig();\r\n\r\n    // Ensure production directory exists\r\n    await ensureDirectoryAsync(this.productionDir);\r\n  }\r\n\r\n  /**\r\n   * Track which special files were generated\r\n   */\r\n  private generatedFiles = {\r\n    locales: false,\r\n    events: false,\r\n    main: false,\r\n    routes: false,\r\n  };\r\n\r\n  /**\r\n   * Generate all combined files\r\n   */\r\n  private async generateCombinedFiles(): Promise<void> {\r\n    console.log(colors.yellow(\"   Generating production files...\"));\r\n\r\n    // Generate bootstrap.ts file\r\n    await this.generateBootstrap();\r\n\r\n    // Generate config loader\r\n    await this.generateConfigLoader();\r\n\r\n    // Generate special files and track which ones have content\r\n    const [locales, events, main, routes] = await Promise.all([\r\n      this.generateLocales(),\r\n      this.generateEvents(),\r\n      this.generateMain(),\r\n      this.generateRoutes(),\r\n    ]);\r\n\r\n    this.generatedFiles = { locales, events, main, routes };\r\n  }\r\n\r\n  /**\r\n   * Generate bootstrap.ts - ensures bootstrap() runs first and sets production environment\r\n   */\r\n  private async generateBootstrap(): Promise<void> {\r\n    let content = `import { bootstrap, Application } from \"@warlock.js/core\";\r\n\r\n// Set production environment\r\nApplication.setRuntimeStrategy(\"production\");\r\nApplication.setEnvironment(\"production\");\r\n\r\n// Bootstrap the application\r\nbootstrap();\r\n`;\r\n    if (await fileExistsAsync(appPath(\"bootstrap.ts\"))) {\r\n      content += \"import './../../src/app/bootstrap';\\n\";\r\n    }\r\n\r\n    await putFileAsync(path.join(this.productionDir, \"bootstrap.ts\"), content);\r\n  }\r\n\r\n  /**\r\n   * Fail the build when generated code imports a package the app does not\r\n   * declare.\r\n   *\r\n   * The bundler is configured `packages: \"external\"`, so every bare specifier\r\n   * written above survives verbatim into an artifact that resolves against the\r\n   * **consuming app's** node_modules. A framework-internal dependency imported\r\n   * there resolves by accident under npm/yarn hoisting and dies under pnpm —\r\n   * which is how a production app shipped that could not boot. Rewriting the\r\n   * offending import fixes today's bundle; this check is what stops the next\r\n   * change to the generator from quietly reintroducing it.\r\n   */\r\n  private async assertGeneratedImports(): Promise<void> {\r\n    const generatedPaths = await glob(\"**/*.{ts,tsx,js,mjs}\", {\r\n      cwd: this.productionDir,\r\n      absolute: false,\r\n    });\r\n\r\n    const [files, appPackage] = await Promise.all([\r\n      Promise.all(\r\n        generatedPaths.map(async (file) => ({\r\n          file,\r\n          content: await getFileAsync(path.join(this.productionDir, file)),\r\n        })),\r\n      ),\r\n      getJsonFileAsync<{ dependencies?: Record<string, string> }>(rootPath(\"package.json\")),\r\n    ]);\r\n\r\n    assertGeneratedImportsAreDeclared(files, Object.keys(appPackage.dependencies ?? {}));\r\n  }\r\n\r\n  /**\r\n   * Glob for module files matching a pattern\r\n   * Returns relative paths from .warlock/production/ to src/app/\r\n   */\r\n  private async globModule(fileName: string): Promise<string[]> {\r\n    const pattern = `**/${fileName}.{ts,tsx}`;\r\n    const appDirectory = appPath();\r\n\r\n    const files = await glob(pattern, {\r\n      cwd: appDirectory,\r\n      absolute: false,\r\n    });\r\n\r\n    // Convert to relative paths from .warlock/production/ to src/app/\r\n    // e.g., \"users/main\" -> \"../../src/app/users/main\"\r\n    return files.map((file) => \"../../src/app/\" + file.replace(/\\.(ts|tsx)$/, \"\"));\r\n  }\r\n\r\n  /**\r\n   * Glob for files in a specific directory pattern\r\n   * Returns relative paths from .warlock/production/ to src/app/\r\n   */\r\n  private async globModuleDirectory(directory: string): Promise<string[]> {\r\n    const pattern = `**/${directory}/*.{ts,tsx}`;\r\n    const appDirectory = appPath();\r\n\r\n    const files = await glob(pattern, {\r\n      cwd: appDirectory,\r\n      absolute: false,\r\n    });\r\n\r\n    return files.map((file) => \"../../src/app/\" + file.replace(/\\.(ts|tsx)$/, \"\"));\r\n  }\r\n\r\n  /**\r\n   * Generate config-loader.ts\r\n   */\r\n  private async generateConfigLoader(): Promise<void> {\r\n    const configDirectory = path.join(process.cwd(), \"src/config\");\r\n\r\n    const files = await glob(\"*.{ts,tsx}\", {\r\n      cwd: configDirectory,\r\n      absolute: false,\r\n    });\r\n\r\n    const configNames = files.map((f) => f.replace(/\\.(ts|tsx)$/, \"\"));\r\n\r\n    // Only `@warlock.js/core` — the one package the app itself declares. See\r\n    // `assertGeneratedImportsAreDeclared`: `@mongez/config` is core's own\r\n    // dependency, so a bare import of it resolved by luck under npm/yarn\r\n    // hoisting and died under pnpm's strict layout.\r\n    const imports: string[] = [\r\n      'import { setConfig, configSpecialHandlers } from \"@warlock.js/core\";',\r\n    ];\r\n    const configImports: string[] = [];\r\n    const configSetCalls: string[] = [];\r\n    const executors: string[] = [];\r\n\r\n    for (const configName of configNames) {\r\n      const properConfigName = toCamelCase(configName);\r\n      const varName = `${properConfigName}Config`;\r\n      configImports.push(`import ${varName} from \"../../src/config/${configName}\";`);\r\n      configSetCalls.push(`setConfig(\"${properConfigName}\", ${varName});`);\r\n      executors.push(`await configSpecialHandlers.execute(\"${properConfigName}\", ${varName});`);\r\n    }\r\n\r\n    let content = [\r\n      ...imports,\r\n      \"\",\r\n      \"// Config imports\",\r\n      ...configImports,\r\n      \"\",\r\n      \"// Register configs\",\r\n      ...configSetCalls,\r\n      \"\",\r\n      \"// Special handlers\",\r\n      ...executors,\r\n      \"\",\r\n    ].join(\"\\n\");\r\n\r\n    if (await fileExistsAsync(appPath(\"prestart.ts\"))) {\r\n      content += \"import './../../src/app/prestart';\\n\";\r\n    }\r\n\r\n    await putFileAsync(path.join(this.productionDir, \"config-loader.ts\"), content);\r\n  }\r\n\r\n  /**\r\n   * Generate locales.ts (only if there are locale files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateLocales(): Promise<boolean> {\r\n    const files = await this.globModule(\"utils/locales\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"locales.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate events.ts (only if there are event files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateEvents(): Promise<boolean> {\r\n    const files = await this.globModuleDirectory(\"events\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"events.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate main.ts (only if there are main files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateMain(): Promise<boolean> {\r\n    const files = await this.globModule(\"main\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"main.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate routes.ts (only if there are route files)\r\n   * @returns true if file was generated with content\r\n   */\r\n  private async generateRoutes(): Promise<boolean> {\r\n    const files = await this.globModule(\"routes\");\r\n    if (files.length === 0) return false;\r\n    await this.generateImportsFile(files, \"routes.ts\");\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Generate a file with imports from all given files\r\n   */\r\n  private async generateImportsFile(importPaths: string[], outputFile: string): Promise<void> {\r\n    const imports = importPaths.map((importPath) => `import \"${importPath}\";`);\r\n    const content = imports.join(\"\\n\") + \"\\n\";\r\n    await putFileAsync(path.join(this.productionDir, outputFile), content);\r\n  }\r\n\r\n  /**\r\n   * Generate the main entry point (app.ts)\r\n   */\r\n  private async generateEntryPoint(): Promise<void> {\r\n    console.log(colors.yellow(\"   Generating entry point...\"));\r\n\r\n    // Build imports based on which files were generated\r\n    const imports: string[] = [\r\n      \"// 1. Bootstrap (loads .env, initializes framework)\",\r\n      'import \"./bootstrap\";',\r\n      \"\",\r\n      \"// 2. Load configs\",\r\n      'import \"./config-loader\";',\r\n      \"\",\r\n      \"// 3. Start early-phase connectors (database, cache, logger, ...)\",\r\n      \"//    so data sources, cache, etc. are ready before app code runs\",\r\n      'import { Application, connectorsManager, ConnectorLifecyclePhase } from \"@warlock.js/core\";',\r\n      \"await connectorsManager.startPhase(ConnectorLifecyclePhase.Early);\",\r\n    ];\r\n\r\n    // App code uses dynamic `await import(...)` so each module's side\r\n    // effects fire at THIS point in execution. Static imports would be\r\n    // hoisted to module-instantiation time (before the early-phase await\r\n    // resolves), which is exactly the bug this split is meant to fix.\r\n    //\r\n    // The guarantee comes from the imports being DYNAMIC — esbuild wraps a\r\n    // dynamically-imported module in its `__esm(() => {…})` helper and runs\r\n    // it at the await, not at instantiation. It does NOT come from\r\n    // `splitting: true`, which only decides one-file-vs-chunks. This\r\n    // previously said splitting was required; it is not, and `singleBundle`\r\n    // (splitting: false) preserves the ordering.\r\n    imports.push(\"\", \"// 4. Load app code (events, locales, main, routes)\");\r\n\r\n    if (this.generatedFiles.events) {\r\n      imports.push('await import(\"./events\");');\r\n    }\r\n    if (this.generatedFiles.locales) {\r\n      imports.push('await import(\"./locales\");');\r\n    }\r\n    if (this.generatedFiles.main) {\r\n      imports.push('await import(\"./main\");');\r\n    }\r\n    if (this.generatedFiles.routes) {\r\n      imports.push('await import(\"./routes\");');\r\n    }\r\n\r\n    // Start late-phase connectors after app code registers routes/listeners\r\n    imports.push(\r\n      \"\",\r\n      \"// 5. Start late-phase connectors (http, socket) — routes and\",\r\n      \"//    listeners registered by app code are now ready to bind\",\r\n      \"await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);\",\r\n      \"\",\r\n      \"// 6. Signal a complete boot so `Application.onceBooted(...)` listeners fire\",\r\n      \"Application.markBooted({ environment: Application.environment, runtimeStrategy: Application.runtimeStrategy });\",\r\n      \"connectorsManager.shutdownOnProcessKill();\",\r\n    );\r\n\r\n    const content = imports.join(\"\\n\") + \"\\n\";\r\n    await putFileAsync(path.join(this.productionDir, \"app.ts\"), content);\r\n  }\r\n\r\n  /**\r\n   * Bundle with esbuild\r\n   */\r\n  private async bundle(): Promise<void> {\r\n    console.log(colors.magenta(\"   Bundling with esbuild...\"));\r\n\r\n    const entryPoint = path.join(this.productionDir, \"app.ts\");\r\n    const outDir = this.options.outdir!;\r\n    const outFileName = this.options.outFile!;\r\n    // Strip extension so entryNames produces \"<base>.js\" via esbuild\r\n    const entryName = path.basename(outFileName, path.extname(outFileName));\r\n\r\n    // `singleBundle` and `esmShim` are ours, not esbuild's — it throws on\r\n    // unknown keys, and the user options are spread into its call verbatim.\r\n    const singleBundle = this.options.singleBundle === true;\r\n    const esmShim = this.options.esmShim !== false;\r\n    // Read before deleting: the merged banner is applied AFTER the user\r\n    // spread, so a user banner must not be lost to it or clobber the shim.\r\n    const userBanner = this.options.banner;\r\n\r\n    delete this.options.outFile;\r\n    delete this.options.entryPath;\r\n    delete this.options.singleBundle;\r\n    delete this.options.esmShim;\r\n    delete this.options.banner;\r\n\r\n    await ensureDirectoryAsync(outDir);\r\n\r\n    const alias = this.buildAliasMapFromTsconfig();\r\n\r\n    // The user can override `format`, so gate the shim on the EFFECTIVE\r\n    // format rather than on the default below. A CJS build already has\r\n    // `require` and friends; injecting them there would be a redefinition.\r\n    const isEsm = (this.options.format ?? \"esm\") === \"esm\";\r\n    const banner = mergeBanner(userBanner, esmShim && isEsm ? ESM_INTEROP_SHIM : undefined);\r\n\r\n    if (singleBundle) {\r\n      console.log(\r\n        colors.magenta(\r\n          \"   Single-bundle mode — one JS file\" +\r\n            (esmShim && isEsm ? \" with the ESM interop shim\" : \"\") +\r\n            \". Native .node addons are still emitted alongside it.\",\r\n        ),\r\n      );\r\n    }\r\n\r\n\r\n    try {\r\n      \r\n    await esbuild.build({\r\n      platform: \"node\",\r\n      entryPoints: [entryPoint],\r\n      bundle: true,\r\n      // Both are DEFAULTS the user can override — they sit before the\r\n      // `...this.options` spread deliberately. `singleBundle` moves them,\r\n      // an explicit `splitting`/`packages` in warlock.config.ts beats both.\r\n      //\r\n      // Phase ordering does not depend on `splitting`: it comes from the\r\n      // generated app.ts using dynamic `await import(...)` (see\r\n      // generateAppEntry above), which esbuild defers to the call site in\r\n      // either mode. Splitting only decides one file vs chunks.\r\n      splitting: !singleBundle,\r\n      packages: singleBundle ? \"bundle\" : \"external\",\r\n      minify: this.options!.minify,\r\n      sourcemap: this.options!.sourcemap === true ? \"linked\" : this.options!.sourcemap,\r\n      format: \"esm\",\r\n      // Targeting a concrete Node version (not \"esnext\") so esbuild\r\n      // transpiles TC39 stage 3 decorators into helpers — Node does not\r\n      // implement them natively yet.\r\n      target: [\"node22\"],\r\n      outdir: outDir,\r\n      entryNames: entryName,\r\n      alias,\r\n      plugins: [nativeNodeModulesPlugin],\r\n      ...(this.options as any),\r\n      // AFTER the spread, and intentionally so: `banner` is an object, and\r\n      // both the config merge and this spread REPLACE it wholesale rather\r\n      // than merging. Left as a default above, any user banner would delete\r\n      // the shim; left to the spread, the shim would delete theirs. The\r\n      // merge is the only form that keeps both.\r\n      ...(banner ? { banner } : {}),\r\n    });\r\n    } catch (e) {\r\n      console.log(e);\r\n      throw e;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Build an alias map from tsconfig `paths` so esbuild resolves local\r\n   * source aliases (e.g. `@warlock.js/cascade`) to their on-disk source\r\n   * folders during bundling. Without this, `packages: \"external\"` would\r\n   * leave those bare specifiers as raw imports and Node would fail to\r\n   * resolve them at runtime (they aren't installed in node_modules).\r\n   *\r\n   * Only exact (non-wildcard) aliases are included — esbuild's `alias`\r\n   * option doesn't support glob-style mappings.\r\n   */\r\n  private buildAliasMapFromTsconfig(): Record<string, string> {\r\n    tsconfigManager.init();\r\n\r\n    const alias: Record<string, string> = {};\r\n    const baseUrl = path.resolve(process.cwd(), tsconfigManager.baseUrl);\r\n\r\n    for (const [from, to] of Object.entries(tsconfigManager.aliases)) {\r\n      if (from.endsWith(\"/*\") || !Array.isArray(to) || to.length === 0) {\r\n        continue;\r\n      }\r\n\r\n      alias[from] = path.resolve(baseUrl, to[0]);\r\n    }\r\n\r\n    return alias;\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/production/resolve-build-config.mjs

@@ -1,6 +1,6 @@
-import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
 import { defaultWarlockConfigurations } from "../warlock-config/default-configurations.mjs";
 import { normalizeBuildConfig } from "../warlock-config/normalize-build-config.mjs";
+import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
 import path from "path";
 
 //#region ../core/src/production/resolve-build-config.ts

package/esm/production/resolve-build-config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-build-config.mjs","names":[],"sources":["../../../../../../../core/src/production/resolve-build-config.ts"],"sourcesContent":["import path from \"path\";\nimport { defaultWarlockConfigurations } from \"../warlock-config/default-configurations\";\nimport { normalizeBuildConfig } from \"../warlock-config/normalize-build-config\";\nimport type { WarlockConfig } from \"../warlock-config/types\";\nimport { warlockConfigManager } from \"../warlock-config/warlock-config.manager\";\n\nexport type ResolvedBuildConfig = Required<\n  Omit<NonNullable<WarlockConfig[\"build\"]>, \"outDirectory\">\n> & {\n  /** Absolute path to the bundled entry file (`{outdir}/{outFile}`) */\n  entryPath: string;\n};\n\n/**\n * Resolve the build config with framework defaults applied.\n *\n * Both the production builder and `warlock start` call this so they\n * agree on where the bundle lives — previously each had its own local\n * fallbacks and they drifted (`.warlock/production` vs `dist`),\n * letting `build` and `start` look at different paths.\n */\nexport function resolveBuildConfig(): ResolvedBuildConfig {\n  // Normalised here rather than only in `defineConfig` because a project may\n  // export a plain config object that never went through it.\n  const userBuild = normalizeBuildConfig(warlockConfigManager.get(\"build\") ?? {});\n  const defaults = defaultWarlockConfigurations.build!;\n  const merged = { ...defaults, ...userBuild } as ResolvedBuildConfig;\n\n  return {\n    ...merged,\n    entryPath: path.resolve(merged.outdir, merged.outFile),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAqBA,SAAgB,qBAA0C;CAGxD,MAAM,YAAY,qBAAqB,qBAAqB,IAAI,OAAO,KAAK,CAAC,CAAC;CAE9E,MAAM,SAAS;EAAE,GADA,6BAA6B;EAChB,GAAG;CAAU;CAE3C,OAAO;EACL,GAAG;EACH,WAAW,KAAK,QAAQ,OAAO,QAAQ,OAAO,OAAO;CACvD;AACF"}
+{"version":3,"file":"resolve-build-config.mjs","names":[],"sources":["../../../../../../../core/src/production/resolve-build-config.ts"],"sourcesContent":["import path from \"path\";\nimport { defaultWarlockConfigurations } from \"../warlock-config/default-configurations\";\nimport { normalizeBuildConfig } from \"../warlock-config/normalize-build-config\";\nimport type { WarlockConfig } from \"../warlock-config/types\";\nimport { warlockConfigManager } from \"../warlock-config/warlock-config.manager\";\n\n/**\n * Keys the builder deletes before handing the options to esbuild — ours\n * (`singleBundle`, `esmShim`), which esbuild would reject as unknown, and\n * `banner`, which is re-merged and re-applied after the user spread.\n *\n * They are optional here for a concrete reason: `Required<…>` makes `delete`\n * a type error (TS2790). Naming exactly these three says which keys are\n * removable, rather than casting at each `delete` — a cast there would also\n * hide a genuine mistake.\n *\n * `outFile` and `entryPath` stay REQUIRED even though the builder deletes\n * them too. They are always present after resolution and callers depend on\n * that; widening them to `string | undefined` pushed the lie downstream into\n * `start-production.command.ts`, which then could not trust its own config.\n */\ntype BuilderStrippedKeys = \"singleBundle\" | \"esmShim\" | \"banner\";\n\nexport type ResolvedBuildConfig = Required<\n  Omit<NonNullable<WarlockConfig[\"build\"]>, \"outDirectory\" | BuilderStrippedKeys>\n> &\n  Partial<Pick<NonNullable<WarlockConfig[\"build\"]>, BuilderStrippedKeys>> & {\n    /** Absolute path to the bundled entry file (`{outdir}/{outFile}`) */\n    entryPath: string;\n  };\n\n/**\n * Resolve the build config with framework defaults applied.\n *\n * Both the production builder and `warlock start` call this so they\n * agree on where the bundle lives — previously each had its own local\n * fallbacks and they drifted (`.warlock/production` vs `dist`),\n * letting `build` and `start` look at different paths.\n */\nexport function resolveBuildConfig(): ResolvedBuildConfig {\n  // Normalised here rather than only in `defineConfig` because a project may\n  // export a plain config object that never went through it.\n  const userBuild = normalizeBuildConfig(warlockConfigManager.get(\"build\") ?? {});\n  const defaults = defaultWarlockConfigurations.build!;\n  const merged = { ...defaults, ...userBuild } as ResolvedBuildConfig;\n\n  return {\n    ...merged,\n    entryPath: path.resolve(merged.outdir, merged.outFile),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAuCA,SAAgB,qBAA0C;CAGxD,MAAM,YAAY,qBAAqB,qBAAqB,IAAI,OAAO,KAAK,CAAC,CAAC;CAE9E,MAAM,SAAS;EAAE,GADA,6BAA6B;EAChB,GAAG;CAAU;CAE3C,OAAO;EACL,GAAG;EACH,WAAW,KAAK,QAAQ,OAAO,QAAQ,OAAO,OAAO;CACvD;AACF"}

package/esm/react/index.d.mts

@@ -7,6 +7,10 @@ import { ComponentType, ReactElement, ReactNode } from "react";
  * **Important:** This function requires React packages to be installed.
  * Install them with: `warlock add react` or `yarn add react react-dom`
  *
+ * React is resolved synchronously on the first call that needs it, so this
+ * function stays synchronous and missing packages throw here rather than
+ * surfacing later as a read off an undefined module.
+ *
  * @example
  * ```typescript
  * const html = renderReact(<WelcomeEmail name="John" />);

package/esm/react/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../core/src/react/index.ts"],"mappings":";;;;;AAgEA;;;;;;;;;iBAAgB,WAAA,CAAY,YAAA,EAAc,YAAA,GAAe,aAAA,GAAgB,SAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../core/src/react/index.ts"],"mappings":";;;;;AAqKA;;;;;;;;;;;;;iBAAgB,WAAA,CAAY,YAAA,EAAc,YAAA,GAAe,aAAA,GAAgB,SAAA"}

package/esm/react/index.mjs

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+
 //#region ../core/src/react/index.ts
 /**
 * Installation instructions for React
@@ -15,40 +17,112 @@ Or manually:
   yarn add react react-dom
 `.trim();
 /**
-* Module availability flag
+* Cached React modules, populated by the first `resolveReactModules()` call
 */
-let moduleExists = null;
+let react = null;
+let reactDomServer = null;
 /**
-* Cached React modules (loaded at import time)
+* Whether the resolution attempt already ran (success or failure)
 */
-let react;
-let reactDomServer;
+let reactResolved = false;
 /**
-* Eagerly load React modules at import time
+* Why the resolution failed, when it failed.
+*
+* Cached and re-thrown on every later call: the resolution attempt runs exactly
+* once, so without this the second `renderReact()` would skip the attempt and
+* fall through to the "not installed" branch, reporting a different, wrong
+* cause one call after the accurate one.
+*/
+let reactLoadError = null;
+const ErrorWithCause = Error;
+/**
+* Whether `error` says `specifier` itself is absent, as opposed to present but
+* broken.
+*
+* Both halves are load-bearing. `MODULE_NOT_FOUND` alone is not enough: a
+* dependency missing *inside* react raises the very same code (`Cannot find
+* module 'scheduler'`), and treating that as absence would tell the operator to
+* install a package they already have. So the message has to name the specifier
+* exactly — quoted, which is also what stops `'react-dom'` from matching a
+* check for `'react'`.
+*/
+function isModuleMissing(error, specifier) {
+	if (!(error instanceof Error)) return false;
+	return error.code === "MODULE_NOT_FOUND" && error.message.includes(`Cannot find module '${specifier}'`);
+}
+/**
+* Require one module, translating its failure into a message that names the
+* specifier that actually failed.
+*
+* The two specifiers are resolved separately and reported separately: a broken
+* `react-dom/server` must never be announced as "react is not installed", since
+* that sends the operator to fix a package that is already fine.
 */
-async function loadReactModules() {
+function requireModule(require, specifier) {
 	try {
-		react = await import("react");
-		reactDomServer = await import("react-dom/server");
-		moduleExists = true;
-	} catch {
-		moduleExists = false;
+		const module = require(specifier);
+		return module.default ?? module;
+	} catch (error) {
+		if (isModuleMissing(error, specifier)) throw new Error(`${specifier} is not installed.\n\n${REACT_INSTALL_INSTRUCTIONS}`);
+		throw new ErrorWithCause(`Failed to load "${specifier}": ${error.message}`, { cause: error });
 	}
 }
-loadReactModules();
+/**
+* Resolve the React modules synchronously, on first use.
+*
+* Resolution is deliberately *lazy* and *synchronous*:
+*
+* - Lazy, because a top-level require would drag react and react-dom into every
+*   `import "@warlock.js/core"`, including apps that never render a component.
+* - Synchronous, because `renderReact()` is synchronous. An async import kicked
+*   off at module load leaves a window in which the modules are neither loaded
+*   nor known to be missing, and a render running inside that window has no
+*   correct answer to give — it used to read `createElement` off `undefined`.
+*
+* `createRequire` gives an ESM-safe `require`, and the outcome — modules,
+* absence or load failure — is cached, so resolution runs exactly once per
+* process. The failure *reason* is cached too, not just the fact of it: every
+* call after a failed load has to report the same cause as the first one.
+*
+* @throws when react or react-dom is not installed, or cannot be loaded
+*/
+function resolveReactModules() {
+	if (!reactResolved) {
+		reactResolved = true;
+		try {
+			const require = createRequire(import.meta.url);
+			react = requireModule(require, "react");
+			reactDomServer = requireModule(require, "react-dom/server");
+		} catch (error) {
+			react = null;
+			reactDomServer = null;
+			reactLoadError = error;
+		}
+	}
+	if (reactLoadError) throw reactLoadError;
+	if (!react || !reactDomServer) throw new Error(`react is not installed.\n\n${REACT_INSTALL_INSTRUCTIONS}`);
+	return {
+		react,
+		reactDomServer
+	};
+}
 /**
 * Render a React element/component to HTML string
 *
 * **Important:** This function requires React packages to be installed.
 * Install them with: `warlock add react` or `yarn add react react-dom`
 *
+* React is resolved synchronously on the first call that needs it, so this
+* function stays synchronous and missing packages throw here rather than
+* surfacing later as a read off an undefined module.
+*
 * @example
 * ```typescript
 * const html = renderReact(<WelcomeEmail name="John" />);
 * ```
 */
 function renderReact(reactElement) {
-	if (moduleExists === false) throw new Error(`react is not installed.\n\n${REACT_INSTALL_INSTRUCTIONS}`);
+	const { react, reactDomServer } = resolveReactModules();
 	if (typeof reactElement === "function") reactElement = react.createElement(reactElement);
 	return reactDomServer.renderToString(reactElement);
 }

package/esm/react/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../core/src/react/index.ts"],"sourcesContent":["import type { ComponentType, ReactElement, ReactNode } from \"react\";\n\n// ============================================================\n// Eager-loaded React Modules\n// ============================================================\n\n/**\n * Installation instructions for React\n */\nconst REACT_INSTALL_INSTRUCTIONS = `\nReact SSR functionality requires React packages.\nInstall them with:\n\n  warlock add react\n\nOr manually:\n\n  npm install react react-dom\n  pnpm add react react-dom\n  yarn add react react-dom\n`.trim();\n\n/**\n * Module availability flag\n */\nlet moduleExists: boolean | null = null;\n\n/**\n * Cached React modules (loaded at import time)\n */\nlet react: typeof import(\"react\");\nlet reactDomServer: typeof import(\"react-dom/server\");\n\n/**\n * Eagerly load React modules at import time\n */\nasync function loadReactModules() {\n  try {\n    react = await import(\"react\");\n    reactDomServer = await import(\"react-dom/server\");\n    moduleExists = true;\n  } catch {\n    moduleExists = false;\n  }\n}\n\n// Kick off eager loading immediately\nloadReactModules();\n\n// ============================================================\n// Render Function\n// ============================================================\n\n/**\n * Render a React element/component to HTML string\n *\n * **Important:** This function requires React packages to be installed.\n * Install them with: `warlock add react` or `yarn add react react-dom`\n *\n * @example\n * ```typescript\n * const html = renderReact(<WelcomeEmail name=\"John\" />);\n * ```\n */\nexport function renderReact(reactElement: ReactElement | ComponentType | ReactNode): string {\n  if (moduleExists === false) {\n    throw new Error(`react is not installed.\\n\\n${REACT_INSTALL_INSTRUCTIONS}`);\n  }\n\n  if (typeof reactElement === \"function\") {\n    reactElement = react.createElement(reactElement);\n  }\n\n  return reactDomServer.renderToString(reactElement);\n}\n"],"mappings":";;;;AASA,MAAM,6BAA6B;;;;;;;;;;;EAWjC,KAAK;;;;AAKP,IAAI,eAA+B;;;;AAKnC,IAAI;AACJ,IAAI;;;;AAKJ,eAAe,mBAAmB;CAChC,IAAI;EACF,QAAQ,MAAM,OAAO;EACrB,iBAAiB,MAAM,OAAO;EAC9B,eAAe;CACjB,QAAQ;EACN,eAAe;CACjB;AACF;AAGA,iBAAiB;;;;;;;;;;;;AAiBjB,SAAgB,YAAY,cAAgE;CAC1F,IAAI,iBAAiB,OACnB,MAAM,IAAI,MAAM,8BAA8B,4BAA4B;CAG5E,IAAI,OAAO,iBAAiB,YAC1B,eAAe,MAAM,cAAc,YAAY;CAGjD,OAAO,eAAe,eAAe,YAAY;AACnD"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../core/src/react/index.ts"],"sourcesContent":["import { createRequire } from \"node:module\";\nimport type { ComponentType, ReactElement, ReactNode } from \"react\";\n\n// ============================================================\n// Lazily Resolved React Modules\n// ============================================================\n\n/**\n * Installation instructions for React\n */\nconst REACT_INSTALL_INSTRUCTIONS = `\nReact SSR functionality requires React packages.\nInstall them with:\n\n  warlock add react\n\nOr manually:\n\n  npm install react react-dom\n  pnpm add react react-dom\n  yarn add react react-dom\n`.trim();\n\n/**\n * Cached React modules, populated by the first `resolveReactModules()` call\n */\nlet react: typeof import(\"react\") | null = null;\nlet reactDomServer: typeof import(\"react-dom/server\") | null = null;\n\n/**\n * Whether the resolution attempt already ran (success or failure)\n */\nlet reactResolved = false;\n\n/**\n * Why the resolution failed, when it failed.\n *\n * Cached and re-thrown on every later call: the resolution attempt runs exactly\n * once, so without this the second `renderReact()` would skip the attempt and\n * fall through to the \"not installed\" branch, reporting a different, wrong\n * cause one call after the accurate one.\n */\nlet reactLoadError: Error | null = null;\n\n/**\n * `new Error(message, { cause })` is ES2022, and this package still compiles\n * against the ES2020 lib (see #16), where `Error` is typed as taking a message\n * only. Node has supported the option since v16, so this is the type layer\n * catching up with the runtime, not a change in what the code does.\n */\ntype ErrorWithCauseConstructor = new (message: string, options: { cause: unknown }) => Error;\n\nconst ErrorWithCause = Error as ErrorWithCauseConstructor;\n\n/**\n * Whether `error` says `specifier` itself is absent, as opposed to present but\n * broken.\n *\n * Both halves are load-bearing. `MODULE_NOT_FOUND` alone is not enough: a\n * dependency missing *inside* react raises the very same code (`Cannot find\n * module 'scheduler'`), and treating that as absence would tell the operator to\n * install a package they already have. So the message has to name the specifier\n * exactly — quoted, which is also what stops `'react-dom'` from matching a\n * check for `'react'`.\n */\nfunction isModuleMissing(error: unknown, specifier: string): boolean {\n  if (!(error instanceof Error)) return false;\n\n  return (\n    (error as NodeJS.ErrnoException).code === \"MODULE_NOT_FOUND\" &&\n    error.message.includes(`Cannot find module '${specifier}'`)\n  );\n}\n\n/**\n * Require one module, translating its failure into a message that names the\n * specifier that actually failed.\n *\n * The two specifiers are resolved separately and reported separately: a broken\n * `react-dom/server` must never be announced as \"react is not installed\", since\n * that sends the operator to fix a package that is already fine.\n */\nfunction requireModule<T>(require: NodeRequire, specifier: string): T {\n  try {\n    const module = require(specifier);\n\n    return (module.default ?? module) as T;\n  } catch (error) {\n    if (isModuleMissing(error, specifier)) {\n      throw new Error(`${specifier} is not installed.\\n\\n${REACT_INSTALL_INSTRUCTIONS}`);\n    }\n\n    // The package is there, it just would not load. Its own error names the\n    // real cause, so it is inlined *and* chained: a terminal that never prints\n    // `cause` must still show the text that actually helps.\n    throw new ErrorWithCause(`Failed to load \"${specifier}\": ${(error as Error).message}`, {\n      cause: error,\n    });\n  }\n}\n\n/**\n * Resolve the React modules synchronously, on first use.\n *\n * Resolution is deliberately *lazy* and *synchronous*:\n *\n * - Lazy, because a top-level require would drag react and react-dom into every\n *   `import \"@warlock.js/core\"`, including apps that never render a component.\n * - Synchronous, because `renderReact()` is synchronous. An async import kicked\n *   off at module load leaves a window in which the modules are neither loaded\n *   nor known to be missing, and a render running inside that window has no\n *   correct answer to give — it used to read `createElement` off `undefined`.\n *\n * `createRequire` gives an ESM-safe `require`, and the outcome — modules,\n * absence or load failure — is cached, so resolution runs exactly once per\n * process. The failure *reason* is cached too, not just the fact of it: every\n * call after a failed load has to report the same cause as the first one.\n *\n * @throws when react or react-dom is not installed, or cannot be loaded\n */\nfunction resolveReactModules() {\n  if (!reactResolved) {\n    reactResolved = true;\n\n    try {\n      const require = createRequire(import.meta.url);\n      react = requireModule<typeof import(\"react\")>(require, \"react\");\n      reactDomServer = requireModule<typeof import(\"react-dom/server\")>(require, \"react-dom/server\");\n    } catch (error) {\n      react = null;\n      reactDomServer = null;\n      reactLoadError = error as Error;\n    }\n  }\n\n  if (reactLoadError) {\n    throw reactLoadError;\n  }\n\n  if (!react || !reactDomServer) {\n    throw new Error(`react is not installed.\\n\\n${REACT_INSTALL_INSTRUCTIONS}`);\n  }\n\n  return { react, reactDomServer };\n}\n\n// ============================================================\n// Render Function\n// ============================================================\n\n/**\n * Render a React element/component to HTML string\n *\n * **Important:** This function requires React packages to be installed.\n * Install them with: `warlock add react` or `yarn add react react-dom`\n *\n * React is resolved synchronously on the first call that needs it, so this\n * function stays synchronous and missing packages throw here rather than\n * surfacing later as a read off an undefined module.\n *\n * @example\n * ```typescript\n * const html = renderReact(<WelcomeEmail name=\"John\" />);\n * ```\n */\nexport function renderReact(reactElement: ReactElement | ComponentType | ReactNode): string {\n  const { react, reactDomServer } = resolveReactModules();\n\n  if (typeof reactElement === \"function\") {\n    reactElement = react.createElement(reactElement);\n  }\n\n  return reactDomServer.renderToString(reactElement);\n}\n"],"mappings":";;;;;;AAUA,MAAM,6BAA6B;;;;;;;;;;;EAWjC,KAAK;;;;AAKP,IAAI,QAAuC;AAC3C,IAAI,iBAA2D;;;;AAK/D,IAAI,gBAAgB;;;;;;;;;AAUpB,IAAI,iBAA+B;AAUnC,MAAM,iBAAiB;;;;;;;;;;;;AAavB,SAAS,gBAAgB,OAAgB,WAA4B;CACnE,IAAI,EAAE,iBAAiB,QAAQ,OAAO;CAEtC,OACG,MAAgC,SAAS,sBAC1C,MAAM,QAAQ,SAAS,uBAAuB,UAAU,EAAE;AAE9D;;;;;;;;;AAUA,SAAS,cAAiB,SAAsB,WAAsB;CACpE,IAAI;EACF,MAAM,SAAS,QAAQ,SAAS;EAEhC,OAAQ,OAAO,WAAW;CAC5B,SAAS,OAAO;EACd,IAAI,gBAAgB,OAAO,SAAS,GAClC,MAAM,IAAI,MAAM,GAAG,UAAU,wBAAwB,4BAA4B;EAMnF,MAAM,IAAI,eAAe,mBAAmB,UAAU,KAAM,MAAgB,WAAW,EACrF,OAAO,MACT,CAAC;CACH;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,SAAS,sBAAsB;CAC7B,IAAI,CAAC,eAAe;EAClB,gBAAgB;EAEhB,IAAI;GACF,MAAM,UAAU,cAAc,OAAO,KAAK,GAAG;GAC7C,QAAQ,cAAsC,SAAS,OAAO;GAC9D,iBAAiB,cAAiD,SAAS,kBAAkB;EAC/F,SAAS,OAAO;GACd,QAAQ;GACR,iBAAiB;GACjB,iBAAiB;EACnB;CACF;CAEA,IAAI,gBACF,MAAM;CAGR,IAAI,CAAC,SAAS,CAAC,gBACb,MAAM,IAAI,MAAM,8BAA8B,4BAA4B;CAG5E,OAAO;EAAE;EAAO;CAAe;AACjC;;;;;;;;;;;;;;;;AAqBA,SAAgB,YAAY,cAAgE;CAC1F,MAAM,EAAE,OAAO,mBAAmB,oBAAoB;CAEtD,IAAI,OAAO,iBAAiB,YAC1B,eAAe,MAAM,cAAc,YAAY;CAGjD,OAAO,eAAe,eAAe,YAAY;AACnD"}

package/esm/router/router.d.mts

@@ -10,6 +10,15 @@ declare class Router {
    * Routes list
    */
   private routes;
+  /**
+   * Bumped on every mutation of {@link routes}.
+   *
+   * The dev dispatcher caches a route registry and needs to know when it is
+   * stale. Comparing `routes.length` would miss an HMR reload that replaces a
+   * route without changing the count — the registry would then keep matching
+   * paths that no longer exist. A version counter cannot miss that.
+   */
+  private routesVersion;
   /**
    * Router Instance
    */

package/esm/router/router.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.mts","names":[],"sources":["../../../../../../../core/src/router/router.ts"],"mappings":"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"}
+{"version":3,"file":"router.d.mts","names":[],"sources":["../../../../../../../core/src/router/router.ts"],"mappings":"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"}

package/esm/router/router.mjs

@@ -11,6 +11,35 @@ import fastifyStatic from "@fastify/static";
 import concatRoute from "@mongez/concat-route";
 
 //#region ../core/src/router/router.ts
+/**
+* The pre-handler phases the dev server forwards from a route's `serverOptions`.
+*
+* These are the admission-control phases and they share the `(request, reply)`
+* signature. `preParsing` is deliberately absent — it must return the payload
+* stream, so forwarding it generically would corrupt the body rather than
+* guard it. `bodyLimit` cannot be forwarded at all; Fastify reads it at
+* registration time and no hook can bound a body already being parsed.
+*/
+const FORWARDED_ROUTE_PHASES = [
+	"onRequest",
+	"preValidation",
+	"preHandler"
+];
+function toHookList(hook) {
+	if (!hook) return [];
+	return Array.isArray(hook) ? hook : [hook];
+}
+/**
+* Run a matched route's hooks for one phase.
+*
+* Returning the reply is how an async Fastify hook signals that it has answered
+* the request; the chain must stop there, so the value is propagated rather
+* than discarded.
+*/
+async function runRouteHooks(route, phase, request, reply) {
+	const hooks = toHookList(route.serverOptions?.[phase]);
+	for (const hook of hooks) if (await hook(request, reply) === reply) return reply;
+}
 var Router = class Router {
 	/**
 	* Get router instance
@@ -21,6 +50,7 @@ var Router = class Router {
 	}
 	constructor() {
 		this.routes = [];
+		this.routesVersion = 0;
 		this.staticDirectories = [];
 		this.eventListeners = {};
 		this.stacks = {
@@ -145,6 +175,7 @@ var Router = class Router {
 			else routeData.name += `.${routeData.method.toLowerCase()}`;
 		}
 		this.routes.push(routeData);
+		this.routesVersion++;
 		return this;
 	}
 	/**
@@ -351,6 +382,7 @@ var Router = class Router {
 	*/
 	removeRoutesBySourceFile(sourceFile) {
 		this.routes = this.routes.filter((route) => route.sourceFile !== sourceFile);
+		this.routesVersion++;
 	}
 	/**
 	* Manage validation system for the given resource
@@ -438,21 +470,42 @@ var Router = class Router {
 	*/
 	scanDevServer(server) {
 		this.eventListeners.beforeScan?.forEach((callback) => callback(this, server));
-		const wildcardHandler = async (fastifyRequest, fastifyReply) => {
-			const routeRegistry = new RouteRegistry();
+		let routeRegistry;
+		let registryVersion = -1;
+		const resolveRouteRegistry = () => {
+			if (routeRegistry && registryVersion === this.routesVersion) return routeRegistry;
+			routeRegistry = new RouteRegistry();
 			routeRegistry.register(this.routes);
-			const match = routeRegistry.find(fastifyRequest.method, fastifyRequest.url);
+			registryVersion = this.routesVersion;
+			return routeRegistry;
+		};
+		server.addHook("onRequest", async (fastifyRequest, fastifyReply) => {
+			const match = resolveRouteRegistry().find(fastifyRequest.method, fastifyRequest.url);
+			if (!match) return;
+			fastifyRequest.matchedDevRoute = match;
+			fastifyRequest.params = match.params;
+			return runRouteHooks(match.route, "onRequest", fastifyRequest, fastifyReply);
+		});
+		for (const phase of FORWARDED_ROUTE_PHASES.filter((name) => name !== "onRequest")) server.addHook(phase, async (fastifyRequest, fastifyReply) => {
+			const match = fastifyRequest.matchedDevRoute;
+			if (!match) return;
+			return runRouteHooks(match.route, phase, fastifyRequest, fastifyReply);
+		});
+		const wildcardHandler = async (fastifyRequest, fastifyReply) => {
+			const match = fastifyRequest.matchedDevRoute;
 			if (!match) return fastifyReply.code(404).send({
 				error: "Route not found",
 				path: fastifyRequest.url,
 				method: fastifyRequest.method
 			});
-			fastifyRequest.params = match.params;
 			try {
 				const { output, response } = await this.handleRoute(match.route)(fastifyRequest, fastifyReply);
 				return output || response.baseResponse;
 			} catch (error) {
-				console.log(error);
+				log.error("router", "dev-dispatch", error, {
+					method: fastifyRequest.method,
+					url: fastifyRequest.url
+				});
 				throw error;
 			}
 		};