@warlock.js/core 4.10.0 → 4.12.0

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  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, warlockPath } from \"../utils\";\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: Bundle with esbuild\r\n    await this.bundle();\r\n\r\n    // // Step 5: 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   * 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    const imports: string[] = [\r\n      'import config from \"@mongez/config\";',\r\n      'import { 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(`config.set(\"${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":"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"}
+{"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":"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"}

package/esm/production/production-supervisor.mjs

@@ -0,0 +1,108 @@
+import { BOOT_SIGNAL_ENV_KEY, isBootSignal } from "../application/boot-signal.mjs";
+import { displayMissingReadinessNotice, displayProductionReadyBanner, displayProductionStartFailure } from "../cli/cli-commands.utils.mjs";
+import { spawn } from "child_process";
+
+//#region ../core/src/production/production-supervisor.ts
+/**
+* How long a still-running child may stay silent before we say so.
+*
+* Only reached by a bundle built before readiness reporting existed; a current
+* bundle signals as soon as its late-phase connectors are up.
+*/
+const DEFAULT_READINESS_NOTICE_DELAY_MS = 1e4;
+/**
+* Run the production bundle in a child process and report honestly on it.
+*
+* The supervisor exists because a parent with `stdio: "inherit"` cannot see
+* whether its child ever booted — it only sees the process exit. It therefore
+* opens an IPC channel and treats the child's `warlock:ready` signal, emitted
+* by `Application.markBooted`, as the single source of truth for "started":
+*
+* 1. The success banner is printed only on that signal.
+* 2. A child that dies before signalling is reported as a failed start and
+*    forced to a non-zero exit, even if it exited 0.
+* 3. A child still running without having signalled draws a note on stderr —
+*    never stdout, which would be the false-green this whole channel prevents.
+*
+* Resolves rather than exiting so the outcome stays assertable in a test; the
+* `start` command turns the result into the process exit code.
+*/
+function superviseProductionProcess({ nodeArgs, cwd = process.cwd(), env = process.env, readinessNoticeDelayMs = DEFAULT_READINESS_NOTICE_DELAY_MS }) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, nodeArgs, {
+			stdio: [
+				"inherit",
+				"inherit",
+				"inherit",
+				"ipc"
+			],
+			cwd,
+			env: {
+				...env,
+				[BOOT_SIGNAL_ENV_KEY]: "1"
+			},
+			detached: false
+		});
+		const startedAt = Date.now();
+		let isReady = false;
+		let isShuttingDown = false;
+		let isSettled = false;
+		const readinessNoticeTimer = setTimeout(() => {
+			if (isReady) return;
+			displayMissingReadinessNotice(Date.now() - startedAt);
+		}, readinessNoticeDelayMs);
+		readinessNoticeTimer.unref?.();
+		const settle = (result) => {
+			if (isSettled) return;
+			isSettled = true;
+			clearTimeout(readinessNoticeTimer);
+			process.off("SIGTERM", onSigterm);
+			process.off("SIGINT", onSigint);
+			resolve(result);
+		};
+		child.on("message", (message) => {
+			if (isReady || !isBootSignal(message)) return;
+			isReady = true;
+			clearTimeout(readinessNoticeTimer);
+			displayProductionReadyBanner({ bootDurationMs: message.bootDurationMs }).catch((error) => {
+				console.error(error);
+			});
+		});
+		child.on("error", (error) => {
+			displayProductionStartFailure(1);
+			console.error(error);
+			settle({
+				exitCode: 1,
+				ready: false
+			});
+		});
+		const onSigterm = () => {
+			if (isShuttingDown) return;
+			isShuttingDown = true;
+			child.kill("SIGTERM");
+		};
+		const onSigint = () => {
+			isShuttingDown = true;
+		};
+		process.on("SIGTERM", onSigterm);
+		process.on("SIGINT", onSigint);
+		child.on("exit", (code) => {
+			if (!isReady && !isShuttingDown) {
+				const exitCode = code === 0 || code === null ? 1 : code;
+				displayProductionStartFailure(exitCode);
+				return settle({
+					exitCode,
+					ready: false
+				});
+			}
+			settle({
+				exitCode: code ?? 0,
+				ready: isReady
+			});
+		});
+	});
+}
+
+//#endregion
+export { superviseProductionProcess };
+//# sourceMappingURL=production-supervisor.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"production-supervisor.mjs","names":[],"sources":["../../../../../../../core/src/production/production-supervisor.ts"],"sourcesContent":["import { spawn } from \"child_process\";\nimport { BOOT_SIGNAL_ENV_KEY, isBootSignal } from \"../application/boot-signal\";\nimport {\n  displayMissingReadinessNotice,\n  displayProductionReadyBanner,\n  displayProductionStartFailure,\n} from \"../cli/cli-commands.utils\";\n\n/**\n * How long a still-running child may stay silent before we say so.\n *\n * Only reached by a bundle built before readiness reporting existed; a current\n * bundle signals as soon as its late-phase connectors are up.\n */\nexport const DEFAULT_READINESS_NOTICE_DELAY_MS = 10_000;\n\nexport type ProductionSupervisorOptions = {\n  /** Arguments handed to the node binary, entry file included. */\n  nodeArgs: string[];\n  cwd?: string;\n  env?: NodeJS.ProcessEnv;\n  readinessNoticeDelayMs?: number;\n};\n\nexport type ProductionSupervisorResult = {\n  /** What the CLI should exit with — never 0 for a boot that never completed. */\n  exitCode: number;\n  /** Whether the child ever reported a finished boot. */\n  ready: boolean;\n};\n\n/**\n * Run the production bundle in a child process and report honestly on it.\n *\n * The supervisor exists because a parent with `stdio: \"inherit\"` cannot see\n * whether its child ever booted — it only sees the process exit. It therefore\n * opens an IPC channel and treats the child's `warlock:ready` signal, emitted\n * by `Application.markBooted`, as the single source of truth for \"started\":\n *\n * 1. The success banner is printed only on that signal.\n * 2. A child that dies before signalling is reported as a failed start and\n *    forced to a non-zero exit, even if it exited 0.\n * 3. A child still running without having signalled draws a note on stderr —\n *    never stdout, which would be the false-green this whole channel prevents.\n *\n * Resolves rather than exiting so the outcome stays assertable in a test; the\n * `start` command turns the result into the process exit code.\n */\nexport function superviseProductionProcess({\n  nodeArgs,\n  cwd = process.cwd(),\n  env = process.env,\n  readinessNoticeDelayMs = DEFAULT_READINESS_NOTICE_DELAY_MS,\n}: ProductionSupervisorOptions): Promise<ProductionSupervisorResult> {\n  return new Promise<ProductionSupervisorResult>((resolve) => {\n    // On Windows, we need to be careful with signals - the console sends Ctrl+C\n    // to all processes in the group, so we just need to not interfere.\n    // `process.execPath`, not \"node\": the bare name needs `node` on PATH, which\n    // a systemd unit, a cron job, or a slim container may not provide — and a\n    // PATH `node` that *is* present can be a different version than the one\n    // running this CLI. execPath is the binary already executing us.\n    //\n    // The fourth stdio slot opens the IPC channel the child reports readiness\n    // on. Without it `process.send` is undefined in the child and we would be\n    // back to guessing whether the boot succeeded.\n    const child = spawn(process.execPath, nodeArgs, {\n      stdio: [\"inherit\", \"inherit\", \"inherit\", \"ipc\"],\n      cwd,\n      // The flag identifies us as a parent that speaks the boot protocol. The\n      // child stays silent without it, so an app running under pm2 or any other\n      // supervisor never writes to a channel that belongs to someone else.\n      env: { ...env, [BOOT_SIGNAL_ENV_KEY]: \"1\" },\n      // Important: keep child in same process group for proper signal handling\n      detached: false,\n    });\n\n    const startedAt = Date.now();\n    let isReady = false;\n    let isShuttingDown = false;\n    let isSettled = false;\n\n    const readinessNoticeTimer = setTimeout(() => {\n      if (isReady) {\n        return;\n      }\n\n      displayMissingReadinessNotice(Date.now() - startedAt);\n    }, readinessNoticeDelayMs);\n\n    // A diagnostic timer must never be the reason the CLI stays alive.\n    readinessNoticeTimer.unref?.();\n\n    const settle = (result: ProductionSupervisorResult) => {\n      if (isSettled) {\n        return;\n      }\n\n      isSettled = true;\n      clearTimeout(readinessNoticeTimer);\n      process.off(\"SIGTERM\", onSigterm);\n      process.off(\"SIGINT\", onSigint);\n\n      resolve(result);\n    };\n\n    child.on(\"message\", (message: unknown) => {\n      if (isReady || !isBootSignal(message)) {\n        return;\n      }\n\n      isReady = true;\n      clearTimeout(readinessNoticeTimer);\n\n      displayProductionReadyBanner({ bootDurationMs: message.bootDurationMs }).catch((error) => {\n        // The server is up either way — a banner that fails to render must not\n        // be reported as, or turn into, a boot failure.\n        console.error(error);\n      });\n    });\n\n    // A spawn that never starts (missing binary, EACCES) emits `error` and no\n    // `exit`, so without this the command would hang silently on a failure.\n    child.on(\"error\", (error) => {\n      displayProductionStartFailure(1);\n      console.error(error);\n\n      settle({ exitCode: 1, ready: false });\n    });\n\n    // SIGTERM doesn't auto-propagate like SIGINT does on Windows.\n    const onSigterm = () => {\n      if (isShuttingDown) {\n        return;\n      }\n\n      isShuttingDown = true;\n      child.kill(\"SIGTERM\");\n    };\n\n    // On Windows Ctrl+C reaches both processes, so the child already has it —\n    // we only record that this exit was asked for.\n    const onSigint = () => {\n      isShuttingDown = true;\n    };\n\n    process.on(\"SIGTERM\", onSigterm);\n    process.on(\"SIGINT\", onSigint);\n\n    child.on(\"exit\", (code) => {\n      // A child that dies before reporting readiness never served a request.\n      // Exiting 0 there — which a clean `process.exit(0)` in failing app code\n      // would do — reports a boot failure as a successful run, so the exit code\n      // is forced non-zero to match what actually happened.\n      //\n      // An operator who interrupts the boot is not a failed boot, so a signalled\n      // shutdown keeps the child's own exit code.\n      if (!isReady && !isShuttingDown) {\n        const exitCode = code === 0 || code === null ? 1 : code;\n\n        displayProductionStartFailure(exitCode);\n\n        return settle({ exitCode, ready: false });\n      }\n\n      settle({ exitCode: code ?? 0, ready: isReady });\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;AAcA,MAAa,oCAAoC;;;;;;;;;;;;;;;;;;AAkCjD,SAAgB,2BAA2B,EACzC,UACA,MAAM,QAAQ,IAAI,GAClB,MAAM,QAAQ,KACd,yBAAyB,qCAC0C;CACnE,OAAO,IAAI,SAAqC,YAAY;EAW1D,MAAM,QAAQ,MAAM,QAAQ,UAAU,UAAU;GAC9C,OAAO;IAAC;IAAW;IAAW;IAAW;GAAK;GAC9C;GAIA,KAAK;IAAE,GAAG;KAAM,sBAAsB;GAAI;GAE1C,UAAU;EACZ,CAAC;EAED,MAAM,YAAY,KAAK,IAAI;EAC3B,IAAI,UAAU;EACd,IAAI,iBAAiB;EACrB,IAAI,YAAY;EAEhB,MAAM,uBAAuB,iBAAiB;GAC5C,IAAI,SACF;GAGF,8BAA8B,KAAK,IAAI,IAAI,SAAS;EACtD,GAAG,sBAAsB;EAGzB,qBAAqB,QAAQ;EAE7B,MAAM,UAAU,WAAuC;GACrD,IAAI,WACF;GAGF,YAAY;GACZ,aAAa,oBAAoB;GACjC,QAAQ,IAAI,WAAW,SAAS;GAChC,QAAQ,IAAI,UAAU,QAAQ;GAE9B,QAAQ,MAAM;EAChB;EAEA,MAAM,GAAG,YAAY,YAAqB;GACxC,IAAI,WAAW,CAAC,aAAa,OAAO,GAClC;GAGF,UAAU;GACV,aAAa,oBAAoB;GAEjC,6BAA6B,EAAE,gBAAgB,QAAQ,eAAe,CAAC,CAAC,CAAC,OAAO,UAAU;IAGxF,QAAQ,MAAM,KAAK;GACrB,CAAC;EACH,CAAC;EAID,MAAM,GAAG,UAAU,UAAU;GAC3B,8BAA8B,CAAC;GAC/B,QAAQ,MAAM,KAAK;GAEnB,OAAO;IAAE,UAAU;IAAG,OAAO;GAAM,CAAC;EACtC,CAAC;EAGD,MAAM,kBAAkB;GACtB,IAAI,gBACF;GAGF,iBAAiB;GACjB,MAAM,KAAK,SAAS;EACtB;EAIA,MAAM,iBAAiB;GACrB,iBAAiB;EACnB;EAEA,QAAQ,GAAG,WAAW,SAAS;EAC/B,QAAQ,GAAG,UAAU,QAAQ;EAE7B,MAAM,GAAG,SAAS,SAAS;GAQzB,IAAI,CAAC,WAAW,CAAC,gBAAgB;IAC/B,MAAM,WAAW,SAAS,KAAK,SAAS,OAAO,IAAI;IAEnD,8BAA8B,QAAQ;IAEtC,OAAO,OAAO;KAAE;KAAU,OAAO;IAAM,CAAC;GAC1C;GAEA,OAAO;IAAE,UAAU,QAAQ;IAAG,OAAO;GAAQ,CAAC;EAChD,CAAC;CACH,CAAC;AACH"}

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/storage/storage.d.mts

@@ -97,6 +97,22 @@ declare class Storage extends ScopedStorage implements StorageManagerContract {
    * @internal
    */
   protected loadDriversFromConfig(): void;
+  /**
+   * Register the built-in `local` driver, rooted at `uploadsPath()`.
+   *
+   * The storage connector starts unconditionally — unlike database, cache and
+   * herald, it does not early-return when `config.get("storage")` is absent —
+   * on the stated grounds that `init()` falls back to a built-in local driver so
+   * file storage works out of the box. That fallback did not exist: `init()`
+   * resolved the default driver *name* and then found no config registered
+   * under it, so **any app without `src/config/storage.ts` failed to boot**
+   * with `Storage driver "local" is not configured`. Only scaffolded apps, which
+   * always ship that file, hid it.
+   *
+   * Registered before the configured drivers so an app that defines its own
+   * `local` entry overrides this one rather than fighting it.
+   */
+  protected registerBuiltInLocalDriver(): void;
   /**
    * Get a scoped storage for a specific driver
    *

package/esm/storage/storage.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.mts","names":[],"sources":["../../../../../../../core/src/storage/storage.ts"],"mappings":";;;;;;;;;;;AAgFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA,SAAgB,aAAA,YAAyB,sBAAA;EAkUjD;;;;EAAA,UA7TO,OAAA,EAAO,GAAA,SAAA,qBAAA;EA0ZL;;;;EAAA,UApZF,OAAA,EAAO,GAAA,SAAA,mBAAA;EAucd;;;;EAAA,UAjcO,iBAAA,EAAoB,iBAAA;EAsfqB;;;;EAAA,QAhf3C,WAAA;EAiiBwC;;;;;;EAgDoB;;;;;EAhkBvD,IAAA,IAAQ,OAAA;EA4nByB;;;EAxmBvC,KAAA;EA0rBK;;;;;;;;EAAA,IA1qBQ,YAAA,IAAgB,qBAAA;EA2xBsC;;;;EAAA,UA1wBhE,qBAAA;EAm0BqB;;;;;;;;;;;;;;;;;;;;;;EAryBxB,GAAA,CAAI,IAAA,EAAM,iBAAA,GAAoB,qBAAA;EAnFhB;;;;;;;;;;;;;;;;;EAwGd,SAAA,CAAU,IAAA,EAAM,iBAAA,GAAoB,qBAAA;EA0BD;;;EAnBnC,IAAA,CAAK,YAAA;EAoDqC;;;;;;;;;;;;;EAjC1C,QAAA,CAAS,IAAA,EAAM,iBAAA,GAAoB,0BAAA;EAoGtB;;;;;;;;;;;;;;;;;;;;;;;EAnEb,QAAA,CAAS,IAAA,EAAM,iBAAA,EAAmB,MAAA,EAAQ,mBAAA;EAqH/C;;;;;;;;;;;;EAnGK,UAAA,CAAW,IAAA,EAAM,iBAAA;EA+LX;;;;;EApLA,OAAA,IAAW,OAAA;EAwLb;;;;EAAA,UAhLD,aAAA,CAAc,MAAA,EAAQ,qBAAA,GAAwB,MAAA,IAAU,0BAAA;EAiOhE;;;;;;;;;;;;;;;;;;;;;;EAnMK,EAAA,WAAa,mBAAA,GAAsB,mBAAA,EACxC,KAAA,EAAO,gBAAA,EACP,OAAA,EAAS,mBAAA,CAAoB,CAAA,IAC5B,iBAAA;EAuS0B;;;;;;;;;;;EAxRtB,GAAA,CAAI,KAAA,EAAO,gBAAA;EAwUkD;;;;EAAA,UA/TpD,IAAA,WAAe,mBAAA,EAC7B,KAAA,EAAO,gBAAA,EACP,OAAA,EAAS,CAAA,GACR,OAAA;EA+VD;;;;;;;;;;EA7UoB,GAAA,CACpB,IAAA,EAAM,YAAA,GAAe,MAAA,YAAkB,QAAA,EACvC,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,WAAA;EAmXO;;;;;;;;;;EA9UI,SAAA,CACpB,MAAA,EAAQ,QAAA,WACR,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,WAAA;EA4YR;;;;;;;;;;;;;;;;;;;;;;;;EA3VU,UAAA,CACX,GAAA,UACA,QAAA,UACA,OAAA,GAAU,iBAAA,GACT,OAAA,CAAQ,WAAA;EAseiD;;;;;;;;;;;;;;;;;;AAmJK;AAwBnE;;;EAnmBe,aAAA,CACX,MAAA,UACA,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,WAAA;EA+lBuB;;;;;;;;EAvkBZ,GAAA,CAAI,QAAA,WAAmB,OAAA,CAAQ,MAAA;;;;;;;;;;;;;;;EAkBxC,OAAA,CAAQ,QAAA,WAAmB,OAAA;;;;;;;EAWlB,SAAA,CAAU,QAAA,WAAmB,OAAA,CAAQ,QAAA;;;;;;;;;EAYrC,MAAA,CAAO,QAAA,WAAmB,WAAA,GAAc,OAAA;;;;;;;EA2BxC,UAAA,CAAW,SAAA,aAAsB,OAAA,CAAQ,gBAAA;;;;;;;EAUzC,MAAA,CAAO,QAAA,WAAmB,OAAA;;;;;;;;;;EAa1B,IAAA,CAAK,IAAA,WAAe,WAAA,EAAa,EAAA,WAAa,OAAA,CAAQ,WAAA;;;;;;;;;;EAmCtD,IAAA,CAAK,IAAA,WAAe,WAAA,EAAa,EAAA,WAAa,OAAA,CAAQ,WAAA;;;;;;;;EAiCtD,IAAA,CACpB,SAAA,WACA,OAAA,GAAU,WAAA,GACT,OAAA,CAAQ,eAAA;;;;;;;EAcW,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,eAAA;;;;;;;EAUpC,IAAA,CAAK,QAAA,WAAmB,OAAA;;;;;;;;;;EAiBjC,IAAA,CAAK,QAAA,WAAmB,OAAA;;;;;;;;;;;;;;;;;;EA+BxB,eAAA,CAAgB,QAAA,UAAkB,OAAA,GAAU,gBAAA,GAAmB,OAAA;;;;;;;;;;;;;;;;;;;;;;;EAgC/D,qBAAA,CACX,QAAA,UACA,OAAA,GAAU,sBAAA,GACT,OAAA;;;;;;;;;EAkBU,SAAA,IAAa,OAAA;;;;;;;;;EAkBb,SAAA,IAAa,OAAA;;;;;;;;;;EAmBb,eAAA,CAAgB,QAAA,UAAkB,YAAA,WAAuB,OAAA;;;;;;;;;;EAmBzD,aAAA,CAAc,QAAA,UAAkB,UAAA,EAAY,cAAA,GAAiB,OAAA;;;;;;;;;;EAmB7D,aAAA,CAAc,QAAA,WAAmB,OAAA,CAAQ,cAAA;;;;;;;;;;EAmBhC,YAAA,CAAa,QAAA,UAAkB,SAAA,YAAqB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+B7D,sBAAA,CAAuB,KAAA,WAAgB,OAAA,CAAQ,wBAAA;;;;;YAwBlD,YAAA,CACR,MAAA,EAAQ,mBAAA,GACP,yBAAA,GAA4B,yBAAA,GAA4B,sBAAA;;;;;YA8DjD,mBAAA,CAAoB,MAAA,EAAQ,mBAAA,EAAqB,UAAA;;;;;YAkBjD,aAAA,CAAc,IAAA,WAAe,qBAAA;;;;;YAyCvB,oBAAA,IAAwB,OAAA,CAAQ,iBAAA;AAAA;;;;;;;;;;;;;cAwBrC,OAAA,EAAO,OAAgB"}
+{"version":3,"file":"storage.d.mts","names":[],"sources":["../../../../../../../core/src/storage/storage.ts"],"mappings":"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"}

package/esm/storage/storage.mjs

@@ -1,4 +1,5 @@
-import { storageConfig } from "./config.mjs";
+import { uploadsPath } from "../utils/paths.mjs";
+import { storageConfig, storageConfigurations } from "./config.mjs";
 import { StorageFile } from "./storage-file.mjs";
 import { safeFetchToBuffer } from "./utils/safe-fetch.mjs";
 import { ScopedStorage } from "./scoped-storage.mjs";
@@ -105,10 +106,32 @@ var Storage = class extends ScopedStorage {
 	* @internal
 	*/
 	loadDriversFromConfig() {
+		this.registerBuiltInLocalDriver();
 		const drivers = storageConfig("drivers", {});
 		for (const [name, config] of Object.entries(drivers)) this.configs.set(name, config);
 	}
 	/**
+	* Register the built-in `local` driver, rooted at `uploadsPath()`.
+	*
+	* The storage connector starts unconditionally — unlike database, cache and
+	* herald, it does not early-return when `config.get("storage")` is absent —
+	* on the stated grounds that `init()` falls back to a built-in local driver so
+	* file storage works out of the box. That fallback did not exist: `init()`
+	* resolved the default driver *name* and then found no config registered
+	* under it, so **any app without `src/config/storage.ts` failed to boot**
+	* with `Storage driver "local" is not configured`. Only scaffolded apps, which
+	* always ship that file, hid it.
+	*
+	* Registered before the configured drivers so an app that defines its own
+	* `local` entry overrides this one rather than fighting it.
+	*/
+	registerBuiltInLocalDriver() {
+		this.configs.set("local", storageConfigurations.local({
+			root: uploadsPath(),
+			urlPrefix: "/uploads"
+		}));
+	}
+	/**
 	* Get a scoped storage for a specific driver
 	*
 	* Returns a `ScopedStorage` instance that wraps the specified driver.