@open-mercato/shared 0.6.7-develop.6828.1.ab1620a63e → 0.6.7-develop.6842.1.8cd8a8883c

package/src/lib/bootstrap/__tests__/dynamicLoader.generatedCacheRecovery.test.ts

@@ -0,0 +1,192 @@
+/**
+ * @jest-environment node
+ *
+ * Integration guard for #4526/#4693: compileAndImport must await its dynamic
+ * import so that an import-time rejection settles inside the try block.
+ * Returning the promise unawaited let the rejection escape the surrounding try,
+ * which made the MikroORM v7 generated-cache recovery in the catch dead code for
+ * exactly the failure it exists to repair. The one-line fix shipped in #4540;
+ * this file is the end-to-end coverage for it.
+ *
+ * Two sibling suites cover this area and neither subsumes the other:
+ *
+ * - dynamicLoader.cacheRecovery.test.ts mocks ../generatedCacheRecovery in full
+ *   and asserts how the loader *reacts* to a rejecting import (recovery is
+ *   invoked once, the retry is capped at one, the error propagates when no
+ *   recovery applies).
+ * - generatedCacheRecovery.test.ts exercises the recovery module directly,
+ *   without going through the loader.
+ * - This file runs the REAL recovery module from the loader's catch, so the
+ *   loader ↔ recovery seam is covered end to end: the on-disk marker, its
+ *   `runtime-import-error` reason and the deleted-file list are asserted against
+ *   what the production module actually writes. Nothing else in the repository
+ *   reaches that reason.
+ *
+ * The fixture reproduces the window the catch exists for: a stale compiled file
+ * that the startup scan (ensureMikroOrmV7GeneratedCacheCompatibility) cannot see
+ * because it appears only once loading is already under way. The staged .mjs
+ * therefore carries no decorator import at scan time — it writes a stale sibling
+ * and then rejects with the error Node raises for a v6 decorator import, which
+ * is what the import-time recovery is meant to repair.
+ *
+ * The assertions stop at the recovery boundary on purpose. Jest's module
+ * registry keeps serving a file it has already evaluated, so the guarded retry
+ * re-runs the rejecting module from memory no matter what recovery wrote to
+ * disk — the outcome of the retry is a property of the test runner, not of the
+ * loader. What #4526 broke, and what this guards, is that the catch runs at
+ * all: before the fix the rejection escaped the try, so no import-time recovery
+ * ever happened.
+ */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { loadBootstrapData } from '../dynamicLoader'
+
+const STALE_SIBLING_BASENAME = 'stale-entity.generated.mjs'
+
+/**
+ * The decorator import is assembled at runtime rather than written literally:
+ * a literal would make this fixture itself match the startup scan's staleness
+ * pattern, so the scan would delete the cache before the import ever runs and
+ * the import-time path under test would never be exercised.
+ */
+const REJECTING_COMPILED_SOURCE = [
+  "const nodeFs = require('node:fs')",
+  "const nodePath = require('node:path')",
+  "const quote = String.fromCharCode(39)",
+  "const staleImport = 'import { Entity, PrimaryKey } from ' + quote + '@mikro-orm/core' + quote",
+  `nodeFs.writeFileSync(nodePath.join(__dirname, ${JSON.stringify(STALE_SIBLING_BASENAME)}), staleImport + '\\nexport const stale = true\\n')`,
+  `throw new Error('The requested module ' + quote + '@mikro-orm/core' + quote + ' does not provide an export named ' + quote + 'Entity' + quote)`,
+].join('\n')
+
+/**
+ * Jest resolves the loader's dynamic import through its own CommonJS registry,
+ * so a staged .mjs has to be CommonJS to evaluate at all — esbuild's real ESM
+ * output fails under the runner with "Unexpected token 'export'". The .ts
+ * sources stay honest ESM: they are what the loader recompiles from once
+ * recovery has deleted the cache.
+ */
+const GENERATED_MODULES: Record<string, { ts: string; compiled: string }> = {
+  'entities.ids.generated': { ts: 'export const E = {}', compiled: 'module.exports = { E: {} }' },
+  'modules.cli.generated': { ts: 'export const modules = []', compiled: 'module.exports = { modules: [] }' },
+  'entities.generated': { ts: 'export const entities = []', compiled: 'module.exports = { entities: [] }' },
+  'di.generated': { ts: 'export const diRegistrars = []', compiled: 'module.exports = { diRegistrars: [] }' },
+}
+
+function contentHash(content: Buffer | string): string {
+  return crypto.createHash('sha256').update(content).digest('hex')
+}
+
+/**
+ * Replace a compiled cache entry with staged content the runner can evaluate,
+ * keeping the loader's own cache metadata authoritative.
+ *
+ * The loader validates a cache entry by hashing (#4724): it recompiles unless
+ * the sibling `.cache.json` matches both the source and the compiled output.
+ * Only `outputHash` is rewritten here — `version`, `inputHash` and
+ * `dependencies` stay exactly as the loader wrote them, so the fixture models a
+ * cache that is internally consistent and simply stale, and it cannot drift out
+ * of step with the cache format the way a hand-built metadata file would.
+ */
+function stageCompiledCache(generatedDir: string, baseName: string, compiled: string) {
+  const jsPath = path.join(generatedDir, `${baseName}.mjs`)
+  const metadataPath = `${jsPath}.cache.json`
+
+  fs.writeFileSync(jsPath, compiled)
+  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'))
+  metadata.outputHash = contentHash(fs.readFileSync(jsPath))
+  fs.writeFileSync(metadataPath, JSON.stringify(metadata))
+}
+
+function hasCacheMetadata(generatedDir: string, baseName: string): boolean {
+  return fs.existsSync(path.join(generatedDir, `${baseName}.mjs.cache.json`))
+}
+
+describe('compileAndImport — generated-cache recovery is reachable (#4526)', () => {
+  let appRoot: string
+  let generatedDir: string
+  let warnSpy: jest.SpyInstance
+
+  /**
+   * Let the loader compile the generated sources so it writes real cache
+   * metadata for each of them, replacing each compiled output with the
+   * runner-evaluable staged content as it appears.
+   *
+   * The loader writes a module's metadata before importing it, so an import
+   * failing here (esbuild's ESM output under Jest's CommonJS registry) is
+   * expected and irrelevant — the metadata is the only thing this step is
+   * after. That failure does abort the rest of the load, though, so one pass
+   * only reaches the modules the loader got to: entities.ids first and alone,
+   * then the remainder together. Repeating the pass lets each newly staged
+   * module unblock the next batch, and the loop ends on the first pass that
+   * loads cleanly, which is precisely when every module is staged.
+   *
+   * jest.resetModules() between passes is load-bearing. Jest keys its registry
+   * on the resolved path and ignores the loader's `?cache=` query, so without
+   * the reset a module would keep being served from its first (ESM, failing)
+   * evaluation and no later pass could make progress.
+   *
+   * None of these failures carries a decorator-export error, so no recovery
+   * runs and no marker is written during setup; both tests below would fail
+   * loudly if one were.
+   */
+  async function primeAndStageCompiledCaches() {
+    const baseNames = Object.keys(GENERATED_MODULES)
+    for (let pass = 0; pass <= baseNames.length; pass += 1) {
+      let loadedCleanly = true
+      await loadBootstrapData(appRoot).catch(() => { loadedCleanly = false })
+      jest.resetModules()
+      if (loadedCleanly) return
+      for (const baseName of baseNames) {
+        if (!hasCacheMetadata(generatedDir, baseName)) continue
+        stageCompiledCache(generatedDir, baseName, GENERATED_MODULES[baseName].compiled)
+      }
+    }
+    throw new Error('[internal] loader never reached a fully staged generated cache')
+  }
+
+  beforeEach(async () => {
+    appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'om-bootstrap-4526-'))
+    generatedDir = path.join(appRoot, '.mercato', 'generated')
+    fs.mkdirSync(generatedDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(appRoot, 'tsconfig.json'),
+      JSON.stringify({ compilerOptions: { target: 'ES2022', module: 'ESNext' } }),
+    )
+    for (const [baseName, source] of Object.entries(GENERATED_MODULES)) {
+      fs.writeFileSync(path.join(generatedDir, `${baseName}.ts`), source.ts)
+    }
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+
+    await primeAndStageCompiledCaches()
+  })
+
+  afterEach(() => {
+    warnSpy.mockRestore()
+    fs.rmSync(appRoot, { recursive: true, force: true })
+  })
+
+  it('runs cache recovery when the compiled cache rejects on import', async () => {
+    const rejectingPath = path.join(generatedDir, 'entities.ids.generated.mjs')
+    stageCompiledCache(generatedDir, 'entities.ids.generated', REJECTING_COMPILED_SOURCE)
+
+    await loadBootstrapData(appRoot).catch(() => undefined)
+
+    const markerPath = path.join(generatedDir, '.mikro-orm-v7-cache-recovery.json')
+    expect(fs.existsSync(markerPath)).toBe(true)
+
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'))
+    expect(marker.reason).toBe('runtime-import-error')
+    expect(marker.deletedFiles).toContain(rejectingPath)
+    expect(marker.deletedFiles).toContain(path.join(generatedDir, STALE_SIBLING_BASENAME))
+
+    expect(fs.readFileSync(rejectingPath, 'utf8')).not.toContain('does not provide an export named')
+  })
+
+  it('does not run recovery when the compiled cache imports cleanly', async () => {
+    await loadBootstrapData(appRoot)
+
+    expect(fs.existsSync(path.join(generatedDir, '.mikro-orm-v7-cache-recovery.json'))).toBe(false)
+  })
+})

package/src/lib/bootstrap/dynamicLoader.ts

@@ -1,4 +1,5 @@
 import type { BootstrapData } from './types'
+import type { AppDiRegistrar } from '../di/container'
 import { findAppRoot, type AppRoot } from './appResolver'
 import { registerEntityIds } from '../encryption/entityIds'
 import { createLogger } from '../logger'
@@ -41,22 +42,29 @@ class GeneratedFileNotFoundError extends Error {
  * list, which would silently reintroduce #4623.
  */
 export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugin[] {
-  // Plugin to resolve @/ alias to app root (works for @app modules)
+  // Plugin to resolve the @/ alias the way the app tsconfig maps it:
+  // `@/.mercato/*` to the app root, every other `@/*` to the app's src/ directory.
   const aliasPlugin: import('esbuild').Plugin = {
     name: 'alias-resolver',
     setup(build) {
-      // Resolve @/ alias to app root
       build.onResolve({ filter: /^@\// }, (args) => {
-        const resolved = path.join(appRoot, args.path.slice(2))
-        // Try with .ts extension if base path doesn't exist
-        if (!fs.existsSync(resolved) && fs.existsSync(resolved + '.ts')) {
-          return { path: resolved + '.ts' }
+        const rest = args.path.slice('@/'.length)
+        const bases = rest.startsWith('.mercato/')
+          ? [path.join(appRoot, rest)]
+          : [path.join(appRoot, 'src', rest), path.join(appRoot, rest)]
+        for (const base of bases) {
+          if (fs.existsSync(base) && fs.statSync(base).isFile()) {
+            return { path: base }
+          }
+          for (const suffix of ['.ts', '.tsx', '/index.ts', '/index.tsx']) {
+            if (fs.existsSync(base + suffix)) {
+              return { path: base + suffix }
+            }
+          }
         }
-        // Also check for /index.ts if it's a directory
-        if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory() && fs.existsSync(path.join(resolved, 'index.ts'))) {
-          return { path: path.join(resolved, 'index.ts') }
-        }
-        return { path: resolved }
+        // Nothing matched — hand esbuild the literal mapping so it reports the
+        // missing file against the path the app author actually wrote.
+        return { path: path.join(appRoot, rest) }
       })
     },
   }
@@ -296,14 +304,33 @@ function cacheIsValid(
     && dependenciesAreValid(appRoot, metadata.dependencies)
 }
 
+/**
+ * Options for `compileAndImport`.
+ *
+ * Both paths default to the generated-registry layout (`<appRoot>/.mercato/generated/<file>.ts`
+ * compiled to a `.mjs` sibling). Sources that live elsewhere in the app — `src/di.ts` — MUST pass
+ * both explicitly: the default app root is derived by walking three directories up from the source,
+ * which only holds inside `.mercato/generated`.
+ */
+type CompileAndImportOptions = {
+  appRoot?: string
+  outFile?: string
+  allowRecovery?: boolean
+}
+
 /**
  * Compile a TypeScript file to JavaScript using esbuild bundler.
  * This bundles the file and all its dependencies, handling JSON imports properly.
- * The compiled file is written next to the source file with a .mjs extension.
+ * The compiled file is written next to the source file with a .mjs extension unless
+ * `outFile` says otherwise.
  */
-async function compileAndImport(tsPath: string, allowRecovery: boolean = true): Promise<Record<string, unknown>> {
-  const jsPath = tsPath.replace(/\.ts$/, '.mjs')
-  const appRoot = path.dirname(path.dirname(path.dirname(tsPath)))
+async function compileAndImport(
+  tsPath: string,
+  options: CompileAndImportOptions = {},
+): Promise<Record<string, unknown>> {
+  const allowRecovery = options.allowRecovery ?? true
+  const jsPath = options.outFile ?? tsPath.replace(/\.ts$/, '.mjs')
+  const appRoot = options.appRoot ?? path.dirname(path.dirname(path.dirname(tsPath)))
   const appTsconfig = path.join(appRoot, 'tsconfig.json')
   const metadataPath = cacheMetadataPath(jsPath)
 
@@ -322,6 +349,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
   const needsCompile = !cacheIsValid(appRoot, jsPath, metadataPath, expectedInputHash)
 
   if (needsCompile) {
+    fs.mkdirSync(path.dirname(jsPath), { recursive: true })
     // Dynamically import esbuild only when needed
     const esbuild = await import('esbuild')
 
@@ -367,7 +395,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
       throw error
     }
 
-    return compileAndImport(tsPath, false)
+    return compileAndImport(tsPath, { ...options, allowRecovery: false })
   }
 }
 
@@ -405,20 +433,7 @@ async function loadOptionalGeneratedModule(
   }
 }
 
-/**
- * Dynamically load bootstrap data from a resolved app directory.
- *
- * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
- * Do NOT use this in Next.js bundled code - use static imports instead.
- *
- * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
- * CLI commands are discovered separately via the CLI module system.
- *
- * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
- * @returns The loaded bootstrap data
- * @throws Error if app root cannot be found or generated files are missing
- */
-export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+function resolveAppRootOrThrow(appRoot?: string): AppRoot {
   const resolved: AppRoot | null = appRoot
     ? {
         generatedDir: path.join(appRoot, '.mercato', 'generated'),
@@ -435,6 +450,68 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
     )
   }
 
+  return resolved
+}
+
+/**
+ * Load the app-level DI registrar (`src/di.ts`) for the dynamic bootstrap path.
+ *
+ * The Next.js runtime imports `@/di` statically from its own `src/bootstrap.ts` and hands the
+ * registrar to `createBootstrap`. Worker, scheduler and CLI processes bootstrap through
+ * `bootstrapFromAppRoot` instead, where the `@/` alias does not exist — so without this the app's
+ * DI registrations silently never ran there, and every request container paid a failed
+ * `import('@/di')` resolution (the compatibility fallback in `lib/di/container.ts`).
+ *
+ * An absent `src/di.ts` is the supported case and resolves to `null` quietly. A file that exists
+ * but cannot be compiled, imported, or does not export `register` is reported at error level and
+ * still resolves to `null`, so a broken app DI module degrades the same way a broken generated
+ * registry does (#4327, #4491) instead of taking the whole process down.
+ */
+async function loadAppDiRegistrar(appDir: string): Promise<AppDiRegistrar | null> {
+  const tsPath = path.join(appDir, 'src', 'di.ts')
+  if (!fs.existsSync(tsPath)) {
+    logger.debug('App-level DI module not present, skipping its registrations', { filePath: tsPath })
+    return null
+  }
+
+  try {
+    const appDiModule = await compileAndImport(tsPath, {
+      appRoot: appDir,
+      outFile: path.join(appDir, '.mercato', 'generated', 'app-di.compiled.mjs'),
+    })
+    const register = appDiModule.register
+    if (typeof register !== 'function') {
+      logger.error('App-level DI module exports no register(); its registrations are skipped', {
+        filePath: tsPath,
+      })
+      return null
+    }
+    return register as AppDiRegistrar
+  } catch (error) {
+    logger.error('Failed to load the app-level DI module; its registrations are skipped', {
+      filePath: tsPath,
+      err: error,
+    })
+    return null
+  }
+}
+
+/**
+ * Dynamically load bootstrap data from a resolved app directory.
+ *
+ * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
+ * Do NOT use this in Next.js bundled code - use static imports instead.
+ *
+ * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
+ * CLI commands are discovered separately via the CLI module system.
+ *
+ * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
+ * @returns The loaded bootstrap data
+ * @throws Error if app root cannot be found or generated files are missing
+ */
+export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+  const resolved = resolveAppRootOrThrow(appRoot)
+
   const { generatedDir } = resolved
 
   ensureMikroOrmV7GeneratedCacheCompatibility(resolved.appDir)
@@ -506,8 +583,10 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
  */
 export async function bootstrapFromAppRoot(appRoot?: string): Promise<BootstrapData> {
   const { createBootstrap, waitForAsyncRegistration } = await import('./factory.js')
-  const data = await loadBootstrapData(appRoot)
-  const bootstrap = createBootstrap(data)
+  const resolved = resolveAppRootOrThrow(appRoot)
+  const data = await loadBootstrapData(resolved.appDir)
+  const appDiRegistrar = await loadAppDiRegistrar(resolved.appDir)
+  const bootstrap = createBootstrap(data, appDiRegistrar ? { appDiRegistrar } : {})
   bootstrap()
   // In CLI context, wait for async registrations (UI widgets, search configs, etc.)
   await waitForAsyncRegistration()

package/src/lib/di/__tests__/container-app-di-absent.test.ts

@@ -84,9 +84,10 @@ jest.mock(
 )
 
 const mockWarn = jest.fn()
+const mockDebug = jest.fn()
 jest.mock('../../logger', () => ({
   createLogger: () => ({
-    debug: jest.fn(),
+    debug: (...args: unknown[]) => mockDebug(...args),
     info: jest.fn(),
     warn: (...args: unknown[]) => mockWarn(...args),
     error: jest.fn(),
@@ -107,6 +108,7 @@ describe('app-level DI override hook when @/di is absent', () => {
     registerAppDiRegistrar(null)
     registerDiRegistrars([])
     mockWarn.mockClear()
+    mockDebug.mockClear()
   })
 
   it('creates the container without warning', async () => {
@@ -117,6 +119,20 @@ describe('app-level DI override hook when @/di is absent', () => {
     expect(mockWarn).not.toHaveBeenCalled()
   })
 
+  // Worker and CLI processes create one request container per job against built package
+  // output, where the app's `@/` alias does not exist. Retrying the doomed import per
+  // container repeats a failed module resolution — and its log line — once per job.
+  it('stops retrying the unresolvable @/di import after the first container', async () => {
+    await createRequestContainer()
+    await createRequestContainer()
+    await createRequestContainer()
+
+    const unresolvableLogs = mockDebug.mock.calls.filter(
+      ([message]) => message === 'App-level DI override module (@/di) not resolvable; skipping',
+    )
+    expect(unresolvableLogs).toHaveLength(1)
+  })
+
   it('warns once when @/di fails because a nested app alias is missing', async () => {
     const nestedAliasError = Object.assign(new Error("Cannot find module '@/di/helpers'"), {
       code: 'MODULE_NOT_FOUND',

package/src/lib/di/container.ts

@@ -26,6 +26,11 @@ const GLOBAL_KEY = '__openMercatoDiRegistrars__'
 const APP_DI_REGISTRAR_KEY = '__openMercatoAppDiRegistrar__'
 const APP_DI_LOAD_WARNING_KEY = '__openMercatoAppDiLoadWarningEmitted__'
 const APP_DI_REGISTER_WARNING_KEY = '__openMercatoAppDiRegisterWarningEmitted__'
+// Set once the legacy `@/di` fallback proves the specifier is unresolvable in this process.
+// Worker/CLI processes run against built package output where the app's `@/` alias does not
+// exist, so retrying the import per request container only repeats a failed module resolution
+// (and its log line) once per job.
+const APP_DI_MODULE_UNRESOLVABLE_KEY = '__openMercatoAppDiModuleUnresolvable__'
 // Phase 5 — process-scoped bootstrap cache. The cache/event-bus/encryption
 // services bootstrap() creates are inherently process-scoped (they hold
 // state across requests). Caching them on globalThis after the first
@@ -120,6 +125,9 @@ export function registerDiRegistrars(registrars: DiRegistrar[]) {
   // Force re-bootstrap on HMR — module subscribers may have changed.
   ;(globalThis as any)[BOOTSTRAP_CACHE_KEY] = null
   ;(globalThis as any)[ENCRYPTION_ENABLED_KEY] = undefined
+  // An app that gains a src/di.ts mid-session reloads through here, so the negative
+  // resolution result must not outlive the reload.
+  ;(globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] = undefined
 }
 
 export function getDiRegistrars(): DiRegistrar[] {
@@ -145,6 +153,15 @@ export function resetBootstrapCache(): void {
   ;(globalThis as any)[ENCRYPTION_ENABLED_KEY] = undefined
   ;(globalThis as Record<string, unknown>)[APP_DI_LOAD_WARNING_KEY] = undefined
   ;(globalThis as Record<string, unknown>)[APP_DI_REGISTER_WARNING_KEY] = undefined
+  ;(globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] = undefined
+}
+
+function isAppDiModuleUnresolvable(): boolean {
+  return (globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] === true
+}
+
+function markAppDiModuleUnresolvable(): void {
+  ;(globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] = true
 }
 
 function isAppDiModuleNotFound(error: unknown): boolean {
@@ -267,7 +284,7 @@ export async function createRequestContainer(): Promise<AppContainer> {
     } catch (error) {
       logger.error('App-level DI registrar failed', { err: error })
     }
-  } else {
+  } else if (!isAppDiModuleUnresolvable()) {
     // Backward-compatible fallback for apps that have not adopted explicit wiring.
     try {
       // @ts-ignore - @/di only exists in app context, not in packages
@@ -286,6 +303,7 @@ export async function createRequestContainer(): Promise<AppContainer> {
       }
     } catch (err) {
       if (isAppDiModuleNotFound(err)) {
+        markAppDiModuleUnresolvable()
         logger.debug('App-level DI override module (@/di) not resolvable; skipping', { err })
       } else {
         warnAppDiFailureOnce(

package/src/lib/i18n/__tests__/config.test.ts

@@ -0,0 +1,8 @@
+import { defaultLocale, locales, type Locale } from '../config'
+
+describe('supported application locales', () => {
+  it('registers Korean without changing the default locale', () => {
+    expect(locales).toEqual<Locale[]>(['en', 'pl', 'es', 'de', 'ko'])
+    expect(defaultLocale).toBe('en')
+  })
+})

package/src/lib/i18n/__tests__/server-unbootstrapped.test.ts

@@ -0,0 +1,29 @@
+import { invalidateDictionaryCache, loadDictionary, registerModules, resolveTranslations } from '../server'
+import type { Module } from '../../../modules/registry'
+
+const REGISTRY_GLOBAL_KEY = '__openMercatoModulesRegistry__'
+
+describe('loadDictionary without a bootstrapped module registry', () => {
+  beforeEach(() => {
+    delete (globalThis as Record<string, unknown>)[REGISTRY_GLOBAL_KEY]
+    invalidateDictionaryCache()
+  })
+
+  it('resolves the app dictionary instead of throwing a bootstrap error', async () => {
+    await expect(loadDictionary('en')).resolves.toEqual(expect.any(Object))
+  })
+
+  it('lets a route handler translate its response before bootstrap runs', async () => {
+    const { translate } = await resolveTranslations()
+
+    expect(translate('storage_s3.upload.errors.unsupported', 'Unsupported file type')).toBe('Unsupported file type')
+  })
+
+  it('picks up module translations once bootstrap registers them', async () => {
+    await loadDictionary('en')
+
+    registerModules([{ id: 'demo', translations: { en: { 'demo.hello': 'Hello' } } }] satisfies Module[])
+
+    await expect(loadDictionary('en')).resolves.toMatchObject({ 'demo.hello': 'Hello' })
+  })
+})

package/src/lib/i18n/config.ts

@@ -1,4 +1,4 @@
-export type Locale = 'en' | 'pl' | 'es' | 'de'
+export type Locale = 'en' | 'pl' | 'es' | 'de' | 'ko'
 
-export const locales: Locale[] = ['en', 'pl', 'es', 'de']
+export const locales: Locale[] = ['en', 'pl', 'es', 'de', 'ko']
 export const defaultLocale: Locale = 'en'

package/src/lib/i18n/server.ts

@@ -2,7 +2,7 @@ import { defaultLocale, locales, type Locale } from './config'
 import type { Dict } from './context'
 import { resolveForcedLocale, resolveLocaleFromAcceptLanguage } from './locale'
 import { createFallbackTranslator, createTranslator } from './translate'
-import { getModules } from '../modules/registry'
+import { tryGetModules } from '../modules/registry'
 import { loadAppDictionary } from './app-dictionaries'
 import { getCachedDictionary, setCachedDictionary } from './dictionary-cache'
 
@@ -61,7 +61,11 @@ export async function loadDictionary(locale: Locale): Promise<Dict> {
   // Load from registry instead of @/ import (works in standalone packages)
   const baseRaw = await loadAppDictionary(locale)
   const merged: Dict = { ...flattenDictionary(baseRaw) }
-  const modules = getModules()
+  // Route handlers translate their responses, so they resolve a dictionary even
+  // when they are exercised in isolation without a bootstrapped registry. The
+  // app dictionary alone is the right degraded answer there — `registerModules`
+  // invalidates this cache, so a later bootstrap still gets the merged result.
+  const modules = tryGetModules() ?? []
   for (const m of modules) {
     const dict = m.translations?.[locale]
     if (dict) Object.assign(merged, flattenDictionary(dict))

package/src/lib/logger/__tests__/logger.test.ts

@@ -3,7 +3,9 @@ import {
   createLogger,
   getLogLevel,
   isLevelEnabled,
+  registerLoggerExtension,
   resetLogLevelCache,
+  resetLoggerExtension,
   resetLoggerRegistry,
 } from '../index'
 import { resolveLevel, type LogLevel } from '../level'
@@ -65,6 +67,7 @@ function resetLoggerState(): void {
   resetLoggerRegistry()
   resetServerLoggerCache()
   resetLogPrettyCache()
+  resetLoggerExtension()
 }
 
 function forcePinoTransport(): void {
@@ -241,6 +244,80 @@ describe('structured logging facade', () => {
     })
   })
 
+  describe('process-wide logger extension', () => {
+    beforeEach(() => {
+      forcePinoTransport()
+    })
+
+    it('keeps one local line and observes one correlated record with child bindings', () => {
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      const records: unknown[] = []
+      registerLoggerExtension({
+        enrich: () => ({ trace_id: 'trace-1', span_id: 'span-1' }),
+        emit: (record) => records.push(record),
+      })
+
+      createLogger('orders')
+        .child({ module: 'sales' })
+        .info('Order placed', { orderId: 'o-1' })
+
+      expect(fake.calls).toEqual([{
+        level: 'info',
+        args: [{
+          orderId: 'o-1',
+          trace_id: 'trace-1',
+          span_id: 'span-1',
+        }, 'Order placed'],
+      }])
+      expect(records).toHaveLength(1)
+      expect(records[0]).toMatchObject({
+        level: 'info',
+        namespace: 'orders',
+        message: 'Order placed',
+        fields: {
+          module: 'sales',
+          orderId: 'o-1',
+          trace_id: 'trace-1',
+          span_id: 'span-1',
+        },
+      })
+    })
+
+    it('applies the shared level gate to local and remote output', () => {
+      process.env.OM_LOG_LEVEL = 'warn'
+      resetLogLevelCache()
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      const emit = jest.fn()
+      registerLoggerExtension({ emit })
+      const logger = createLogger('gated-extension')
+
+      logger.info('quiet')
+      logger.warn('visible')
+
+      expect(fake.calls.map((call) => call.level)).toEqual(['warn'])
+      expect(emit).toHaveBeenCalledTimes(1)
+      expect(emit.mock.calls[0][0]).toMatchObject({ level: 'warn', message: 'visible' })
+    })
+
+    it('isolates extension failures from application logging', () => {
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      registerLoggerExtension({
+        enrich: () => {
+          throw new Error('context failed')
+        },
+        emit: () => {
+          throw new Error('sink failed')
+        },
+      })
+
+      expect(() => createLogger('resilient-extension').error('Still local')).not.toThrow()
+      expect(fake.calls).toEqual([{ level: 'error', args: [{}, 'Still local'] }])
+    })
+  })
+
   describe('isomorphism', () => {
     beforeEach(() => {
       forcePinoTransport()