create-mercato-app 0.6.3-develop.3901.1.ddad60693a → 0.6.3

package/agentic/shared/AGENTS.md.template

@@ -201,6 +201,7 @@ When the user asks to **create a new application** or a **new module**, do not i
 - Entity classes belong in `src/modules/<module>/data/entities.ts` and use decorators from `@mikro-orm/decorators/legacy`
 - Standalone apps expose `yarn mercato configs cache ...` because the template enables the `configs` module from `@open-mercato/core`
 - `yarn generate` automatically runs a best-effort structural cache purge (`yarn mercato configs cache structural --all-tenants`) after successful generation; if the cache command is unavailable, generation still succeeds
+- Use `yarn dev:reset` only as the stale-Turbopack escape hatch; it clears `.mercato/next/dev` plus legacy `.next` caches.
 - Detail/read-model APIs that expose `customFields` MUST return bare field keys via `normalizeCustomFieldResponse()` (for example `{ priority: 3 }`). Keep `cf_` / `cf:` prefixes for request payloads, filters, and form field IDs only.
 - Sidebar icons MUST use `lucide-react` components — never inline SVG via `React.createElement`
 - `page.meta.ts` MUST include `pageGroup`, `pageGroupKey`, and `pageOrder` for sidebar grouping

package/dist/agentic/shared/AGENTS.md.template

@@ -201,6 +201,7 @@ When the user asks to **create a new application** or a **new module**, do not i
 - Entity classes belong in `src/modules/<module>/data/entities.ts` and use decorators from `@mikro-orm/decorators/legacy`
 - Standalone apps expose `yarn mercato configs cache ...` because the template enables the `configs` module from `@open-mercato/core`
 - `yarn generate` automatically runs a best-effort structural cache purge (`yarn mercato configs cache structural --all-tenants`) after successful generation; if the cache command is unavailable, generation still succeeds
+- Use `yarn dev:reset` only as the stale-Turbopack escape hatch; it clears `.mercato/next/dev` plus legacy `.next` caches.
 - Detail/read-model APIs that expose `customFields` MUST return bare field keys via `normalizeCustomFieldResponse()` (for example `{ priority: 3 }`). Keep `cf_` / `cf:` prefixes for request payloads, filters, and form field IDs only.
 - Sidebar icons MUST use `lucide-react` components — never inline SVG via `React.createElement`
 - `page.meta.ts` MUST include `pageGroup`, `pageGroupKey`, and `pageOrder` for sidebar grouping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.3-develop.3901.1.ddad60693a",
+  "version": "0.6.3",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",
@@ -41,6 +41,5 @@
     "scaffolding",
     "cli"
   ],
-  "license": "MIT",
-  "stableVersion": "0.6.2"
+  "license": "MIT"
 }

package/template/AGENTS.md

@@ -99,7 +99,7 @@ yarn generate
 # Manually purge structural caches when needed (Redis nav:* + Turbopack barrel mtimes)
 yarn mercato configs cache structural --all-tenants
 
-# Escape hatch: clear .next/cache/turbopack when Turbopack still serves a stale chunk
+# Escape hatch: clear .mercato/next/dev and legacy .next caches when Turbopack still serves a stale chunk
 yarn dev:reset
 
 # Database operations
@@ -650,7 +650,7 @@ Notes:
 
 The standalone template enables the `configs` module from `@open-mercato/core`, so `yarn mercato configs cache ...` is available here after installation. After structural changes such as enabling or disabling modules, adding or removing backend/frontend pages, or changing sidebar/navigation injections, run `yarn generate`. The generator now performs a best-effort structural cache purge automatically after successful generation; if the cache command is unavailable, generation still succeeds.
 
-The structural cache purge invalidates two layers: Redis `nav:*` cache keys and Turbopack's module-graph fingerprints (it bumps mtimes on every file in `.mercato/generated/` without changing content). When Turbopack still serves a stale compiled chunk after a structural change — typically because its own internal cache pinned a previous compile error — run `yarn dev:reset` to clear `.next/cache/turbopack` and restart `yarn dev`.
+The structural cache purge invalidates two layers: Redis `nav:*` cache keys and Turbopack's module-graph fingerprints (it bumps mtimes on every file in `.mercato/generated/` without changing content). When Turbopack still serves a stale compiled chunk after a structural change — typically because its own internal cache pinned a previous compile error — run `yarn dev:reset` to clear `.mercato/next/dev` plus legacy `.next` caches and restart `yarn dev`.
 
 Detail/read-model APIs that expose `customFields` must return bare field keys via `normalizeCustomFieldResponse()` (for example `{ priority: 3 }`). Keep `cf_` / `cf:` prefixes for request payloads, filters, and form field IDs only.
 

package/template/scripts/dev-cache-purge.mjs

@@ -1,11 +1,20 @@
 import fs from 'node:fs'
 import path from 'node:path'
 
-// Greenfield must not inherit the prior run's compiler state. Wiping the
-// configured Next.js distDir (`.mercato/next`) plus the legacy `.next` location guarantees Turbopack rebuilds the route table
-// and middleware manifest from scratch on the next launch.
+// Greenfield must not inherit stale route manifests, but wiping the whole
+// configured Next.js distDir also discards Turbopack's reusable compiler cache
+// and makes first /login warmup much slower. Remove manifests/locks that encode
+// route shape while preserving `.mercato/next/dev/cache/turbopack`.
 export const GREENFIELD_PURGE_TARGETS = Object.freeze([
-  Object.freeze(['.mercato', 'next']),
+  Object.freeze(['.mercato', 'next', 'dev', 'lock']),
+  Object.freeze(['.mercato', 'next', 'dev', 'build-manifest.json']),
+  Object.freeze(['.mercato', 'next', 'dev', 'fallback-build-manifest.json']),
+  Object.freeze(['.mercato', 'next', 'dev', 'prerender-manifest.json']),
+  Object.freeze(['.mercato', 'next', 'dev', 'routes-manifest.json']),
+  Object.freeze(['.mercato', 'next', 'dev', 'server', 'app-paths-manifest.json']),
+  Object.freeze(['.mercato', 'next', 'dev', 'server', 'middleware-build-manifest.js']),
+  Object.freeze(['.mercato', 'next', 'dev', 'server', 'middleware-manifest.json']),
+  Object.freeze(['.mercato', 'next', 'dev', 'server', 'pages-manifest.json']),
   Object.freeze(['.next']),
 ])
 
@@ -23,7 +32,7 @@ export function purgeAppBuildCaches({
     removed.push(segments.join('/'))
   }
   if (removed.length === 0) {
-    logger.log('🧹 [dev:greenfield] no stale Next/Turbopack build directories to purge')
+    logger.log('🧹 [dev:greenfield] no stale Next/Turbopack manifest files to purge')
   } else {
     for (const relPath of removed) {
       logger.log(`🧹 [dev:greenfield] removed ${relPath}`)

package/template/scripts/dev-reset.mjs

@@ -6,6 +6,7 @@ import fs from 'node:fs'
 const here = path.dirname(fileURLToPath(import.meta.url))
 const appDir = path.resolve(here, '..')
 const targets = [
+  path.join(appDir, '.mercato', 'next', 'dev'),
   path.join(appDir, '.next', 'cache', 'turbopack'),
   path.join(appDir, '.next', 'cache', 'webpack'),
 ]
@@ -19,9 +20,9 @@ for (const target of targets) {
 }
 
 if (removed === 0) {
-  console.log('🧹 [dev:reset] nothing to clean — .next/cache subdirectories already absent')
+  console.log('🧹 [dev:reset] nothing to clean — dev build caches already absent')
 }
 
 console.log('')
-console.log('✅ Turbopack/webpack cache cleared.')
-console.log('   Stop any running `yarn dev` and start it again to pick up fresh module output.')
+console.log('✅ Next.js dev cache cleared.')
+console.log('   Start `yarn dev` again to pick up fresh module output.')

package/template/scripts/dev-runtime.mjs

@@ -50,6 +50,12 @@ function parseEnvBooleanToken(value) {
   return null
 }
 
+function parsePositiveIntegerEnv(value) {
+  if (typeof value !== 'string') return null
+  const parsed = Number.parseInt(value.trim(), 10)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null
+}
+
 function resolveAutoSpawnEnabled(env, legacyName, aliasedName) {
   const legacy = parseEnvBooleanToken(env[legacyName])
   if (legacy !== null) return legacy
@@ -84,12 +90,20 @@ const verbose = !classic && (process.argv.includes('--verbose') || process.env.M
 const rawPassthrough = classic || verbose
 const interactiveLogToggle = !rawPassthrough && process.stdin.isTTY && process.stdout.isTTY && process.env.CI !== 'true'
 const splashChildStateFile = process.env.OM_DEV_SPLASH_CHILD_STATE_FILE?.trim() || null
+const warmupReadyFile = process.env.OM_DEV_WARMUP_READY_FILE?.trim()
+  || (splashChildStateFile ? `${splashChildStateFile}.warmup-ready` : null)
 const splashMode = process.env.OM_DEV_SPLASH_MODE?.trim() || 'dev'
 const setupSplashMode = splashMode === 'setup'
 const startupSplashPhase = setupSplashMode ? 'Project setup is in progress...' : 'Installation and first compilation is in progress...'
-const runtimeProgressTotal = setupSplashMode ? 5 : 4
-const runtimeProgressCurrent = setupSplashMode ? 4 : 0
-const runtimeReadyProgressCurrent = setupSplashMode ? 5 : 4
+const configuredRuntimeProgressTotal = parsePositiveIntegerEnv(process.env.OM_DEV_SPLASH_STAGE_TOTAL)
+const configuredRuntimeProgressCurrent = parsePositiveIntegerEnv(process.env.OM_DEV_SPLASH_STAGE_CURRENT)
+const runtimeProgressTotal = configuredRuntimeProgressTotal ?? (setupSplashMode ? 5 : 4)
+const runtimeProgressCurrent = configuredRuntimeProgressCurrent ?? (setupSplashMode ? 4 : 0)
+const runtimeReadyProgressCurrent = Math.max(runtimeProgressCurrent, runtimeProgressTotal)
+const runtimeWarmupProgressCurrent = Math.max(
+  runtimeProgressCurrent,
+  Math.min(runtimeReadyProgressCurrent, Math.max(0, runtimeProgressTotal - 1)),
+)
 const children = new Set()
 let shuttingDown = false
 let logsVisible = false
@@ -108,6 +122,7 @@ const backgroundServiceModes = {
   workers: resolveAutoSpawnMode(process.env, 'AUTO_SPAWN_WORKERS', 'OM_AUTO_SPAWN_WORKERS', 'OM_AUTO_SPAWN_WORKERS_LAZY'),
   scheduler: resolveAutoSpawnMode(process.env, 'AUTO_SPAWN_SCHEDULER', 'OM_AUTO_SPAWN_SCHEDULER', 'OM_AUTO_SPAWN_SCHEDULER_LAZY'),
 }
+const shutdownNoticeOwnedByParent = process.env.OM_DEV_SHUTDOWN_NOTICE_OWNER === 'parent'
 const splashState = {
   mode: splashMode,
   phase: startupSplashPhase,
@@ -161,11 +176,38 @@ const runtimeWarmupState = {
   failed: false,
   promise: null,
   retryTimer: null,
+  abortController: null,
+  generation: 0,
   retryAttempts: 0,
   tenantId: readNonEmptyEnvValue('OM_DEV_WARMUP_TENANT_ID') ?? null,
   tenantLookupAttempted: false,
 }
 
+function clearWarmupReadyFile() {
+  if (!warmupReadyFile) return
+  try {
+    fs.rmSync(warmupReadyFile, { force: true })
+  } catch {
+    // Warmup readiness is best-effort; terminal status remains authoritative.
+  }
+}
+
+function writeWarmupReadyFile(reason) {
+  if (!warmupReadyFile) return
+  try {
+    fs.mkdirSync(path.dirname(warmupReadyFile), { recursive: true })
+    fs.writeFileSync(warmupReadyFile, `${JSON.stringify({
+      ready: true,
+      reason,
+      at: new Date().toISOString(),
+    }, null, 2)}\n`)
+  } catch {
+    // Warmup readiness is best-effort; background services can still run without it.
+  }
+}
+
+clearWarmupReadyFile()
+
 function printCompactSummary(icon, title, lines) {
   if (!Array.isArray(lines) || lines.length === 0) return
   console.log(`${icon} ${title}`)
@@ -489,6 +531,8 @@ function spawnMercato(args) {
       ...process.env,
       OM_CLI_QUIET: rawPassthrough ? process.env.OM_CLI_QUIET : '1',
       DOTENV_CONFIG_QUIET: rawPassthrough ? process.env.DOTENV_CONFIG_QUIET : 'true',
+      ...(!rawPassthrough ? { OM_DEV_SPLASH_RUNTIME_WRAPPER: '1' } : {}),
+      ...(!rawPassthrough && warmupReadyFile ? { OM_DEV_WARMUP_READY_FILE: warmupReadyFile } : {}),
     },
     ...resolvedSpawn.spawnOptions,
   })
@@ -649,10 +693,18 @@ async function resolveWarmupTenantIdFromDatabase(email) {
   }
 }
 
-async function fetchWithTimeout(url, init = {}, timeoutMs = 45000) {
+async function fetchWithTimeout(url, init = {}, timeoutMs = 45000, externalSignal = null) {
+  if (externalSignal?.aborted) {
+    throw externalSignal.reason ?? new Error('warmup request aborted')
+  }
+
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), timeoutMs)
   timer.unref?.()
+  const abortFromExternalSignal = () => {
+    controller.abort(externalSignal.reason ?? new Error('warmup request aborted'))
+  }
+  externalSignal?.addEventListener?.('abort', abortFromExternalSignal, { once: true })
 
   try {
     return await fetch(url, {
@@ -661,6 +713,7 @@ async function fetchWithTimeout(url, init = {}, timeoutMs = 45000) {
     })
   } finally {
     clearTimeout(timer)
+    externalSignal?.removeEventListener?.('abort', abortFromExternalSignal)
   }
 }
 
@@ -674,14 +727,14 @@ function isAbortLikeError(error) {
   return /aborted/i.test(String(error))
 }
 
-async function fetchWarmupWithRetry(url, init, detailLabel, progressLabel) {
+async function fetchWarmupWithRetry(url, init, detailLabel, progressLabel, signal = null) {
   let lastError = null
 
   for (let index = 0; index < warmupRequestTimeoutsMs.length; index += 1) {
     const timeoutMs = warmupRequestTimeoutsMs[index]
 
     try {
-      return await fetchWithTimeout(url, init, timeoutMs)
+      return await fetchWithTimeout(url, init, timeoutMs, signal)
     } catch (error) {
       lastError = error
 
@@ -766,6 +819,20 @@ function clearWarmupRetryTimer() {
   runtimeWarmupState.retryTimer = null
 }
 
+function resetWarmupForRuntimeRestart(reason) {
+  clearWarmupRetryTimer()
+  runtimeWarmupState.generation += 1
+  runtimeWarmupState.readySignalSeen = false
+  runtimeWarmupState.started = false
+  runtimeWarmupState.completed = false
+  runtimeWarmupState.failed = false
+  runtimeWarmupState.promise = null
+  runtimeWarmupState.retryAttempts = 0
+  runtimeWarmupState.abortController?.abort(new Error(`warmup aborted because ${reason}`))
+  runtimeWarmupState.abortController = null
+  clearWarmupReadyFile()
+}
+
 function scheduleWarmupRetry(delayMs = 2000) {
   clearWarmupRetryTimer()
   runtimeWarmupState.retryTimer = setTimeout(() => {
@@ -782,6 +849,9 @@ async function runTargetedRouteWarmup() {
 
   clearWarmupRetryTimer()
   runtimeWarmupState.started = true
+  const generation = runtimeWarmupState.generation
+  const abortController = new AbortController()
+  runtimeWarmupState.abortController = abortController
   const startedAt = Date.now()
   const progressLabel = 'Precompiling login and backend'
   const introMessage = '🔥 Precompiling /login, login POST, and /backend'
@@ -796,7 +866,9 @@ async function runTargetedRouteWarmup() {
       { method: 'GET', redirect: 'manual' },
       '/login',
       progressLabel,
+      abortController.signal,
     )
+    if (generation !== runtimeWarmupState.generation) return
     if (shouldRetryWarmupStatus(loginPageResponse.status)) {
       throw createWarmupTransientError(`/login returned HTTP ${loginPageResponse.status}`)
     }
@@ -825,7 +897,9 @@ async function runTargetedRouteWarmup() {
       },
       'POST /api/auth/login',
       progressLabel,
+      abortController.signal,
     )
+    if (generation !== runtimeWarmupState.generation) return
     const loginPayload = await readResponsePayload(loginResponse)
     if (!loginResponse.ok || !loginPayload || typeof loginPayload !== 'object' || loginPayload.ok !== true) {
       const failure = extractWarmupErrorMessage(loginPayload, `HTTP ${loginResponse.status}`)
@@ -864,7 +938,9 @@ async function runTargetedRouteWarmup() {
       },
       '/backend',
       progressLabel,
+      abortController.signal,
     )
+    if (generation !== runtimeWarmupState.generation) return
     if (backendResponse.status >= 300 && backendResponse.status < 400) {
       const location = backendResponse.headers.get('location') || 'redirect'
       if (isWarmupRetryableRedirect(location)) {
@@ -888,6 +964,7 @@ async function runTargetedRouteWarmup() {
     runtimeWarmupState.completed = true
     runtimeWarmupState.failed = false
     runtimeWarmupState.promise = null
+    runtimeWarmupState.abortController = null
     const completedMessage = `🚪 Login flow and backend warmed in ${formatDuration(Date.now() - startedAt)}`
     updateSplashState({
       phase: 'App is ready',
@@ -902,9 +979,15 @@ async function runTargetedRouteWarmup() {
       progressLabel: 'App is ready',
       activity: completedMessage,
     })
+    writeWarmupReadyFile('warmup-complete')
     console.log(formatStatusOutput(completedMessage, runtimeReadyProgressCurrent, 'App is ready'))
   } catch (error) {
+    if (generation !== runtimeWarmupState.generation) {
+      return
+    }
+
     runtimeWarmupState.promise = null
+    runtimeWarmupState.abortController = null
 
     if (isAbortLikeError(error) || isWarmupTransientError(error)) {
       runtimeWarmupState.started = false
@@ -978,12 +1061,14 @@ async function runTargetedRouteWarmup() {
       activity: warmupWarning,
     })
     if (isCredentialsFailure) {
+      writeWarmupReadyFile('warmup-credentials-failed')
       console.log(formatStatusOutput(
         '⚠️ Warmup login returned 401 — credentials invalid. Set OM_INIT_SUPERADMIN_EMAIL/PASSWORD in .env or run: yarn initialize',
         runtimeReadyProgressCurrent,
         'App is ready',
       ))
     } else {
+      writeWarmupReadyFile('warmup-incomplete')
       console.log(formatStatusOutput(warmupWarning, runtimeReadyProgressCurrent, 'App is ready'))
     }
   }
@@ -1138,6 +1223,18 @@ function shutdown(exitCode = 0) {
     rawModeEnabled = false
   }
 
+  if (!shutdownNoticeOwnedByParent) {
+    const message = 'Shutting down services...'
+    updateSplashState({
+      phase: message,
+      detail: 'Stopping app runtime, workers, and scheduler',
+      ready: false,
+      progressLabel: message,
+      activity: message,
+    })
+    console.log(message)
+  }
+
   const alive = Array.from(children).filter((child) => !child.killed)
   if (alive.length === 0) {
     process.exit(exitCode)
@@ -1582,6 +1679,37 @@ function classifyServerLine(line) {
     }
   }
 
+  const runtimeRestartMatch = line.match(/^\[server\] Detected (.+?)\. Restarting app runtime\.\.\.$/)
+  if (runtimeRestartMatch) {
+    const reason = runtimeRestartMatch[1]
+    resetWarmupForRuntimeRestart(reason)
+    return {
+      type: 'status',
+      message: `🔄 Restarting app runtime: ${reason}`,
+      splashPhase: 'App runtime is restarting',
+      splashDetail: `Reason: ${reason}`,
+      ready: false,
+      activity: `App runtime restart: ${reason}`,
+      progressCurrent: runtimeProgressCurrent,
+      progressLabel: 'Restarting app runtime',
+    }
+  }
+
+  if (line === '[server] Detected corrupted Turbopack dev cache. Clearing .mercato/next/dev and restarting Next.js once...') {
+    const reason = 'corrupted Turbopack dev cache'
+    resetWarmupForRuntimeRestart(reason)
+    return {
+      type: 'status',
+      message: `🔄 Restarting Next.js dev server: ${reason}`,
+      splashPhase: 'App runtime is restarting',
+      splashDetail: `Reason: ${reason}`,
+      ready: false,
+      activity: `Next.js restart: ${reason}`,
+      progressCurrent: runtimeProgressCurrent,
+      progressLabel: 'Restarting app runtime',
+    }
+  }
+
   const localMatch = line.match(/^- Local:\s*(.+)$/)
   if (localMatch) {
     return {
@@ -1592,7 +1720,7 @@ function classifyServerLine(line) {
       readyUrl: localMatch[1],
       loginUrl: `${localMatch[1].replace(/\/$/, '')}/login`,
       activity: `App runtime at ${localMatch[1]}`,
-      progressCurrent: 4,
+      progressCurrent: runtimeWarmupProgressCurrent,
       progressLabel: 'Precompiling login page',
     }
   }
@@ -1607,7 +1735,7 @@ function classifyServerLine(line) {
       ready: false,
       runtimeReady: true,
       activity: timing,
-      progressCurrent: 4,
+      progressCurrent: runtimeWarmupProgressCurrent,
       progressLabel: 'Precompiling login page',
     }
   }
@@ -1616,7 +1744,7 @@ function classifyServerLine(line) {
     const target = compiledMatch[1]?.trim()
     const detail = target ? ` ${target}` : ''
     const timing = `⚡ Compiled${detail} in ${parseDurationToken(compiledMatch[2])}`
-    const progressCurrent = splashState.ready ? runtimeReadyProgressCurrent : 3
+    const progressCurrent = splashState.ready ? runtimeReadyProgressCurrent : runtimeWarmupProgressCurrent
     return {
       type: 'status',
       message: timing,
@@ -1721,9 +1849,10 @@ async function runClassicRuntime() {
     shutdown(initialGenerateExitCode)
   }
 
-  // Default ('in-process'): `mercato server dev` runs the structural
-  // regeneration watcher in-process. Set OM_DEV_GENERATE_WATCH_MODE=legacy
-  // to fall back to spawning the dedicated sidecar Node process.
+  // Default ('in-process'): `mercato server dev` owns the structural
+  // regeneration watcher in-process, so we no longer spawn the dedicated
+  // sidecar. Saves ~190 MB of resident RSS by collapsing one Node process.
+  // Opt back into the sidecar with OM_DEV_GENERATE_WATCH_MODE=legacy.
   const watchers = []
   if (generateWatchMode === 'legacy') {
     watchers.push(['Generator watch (legacy sidecar)', spawnMercato(['generate', 'watch', '--skip-initial'])])
@@ -1751,6 +1880,11 @@ installLogToggle()
 initializeRuntimeSummary()
 printRuntimePackagesSummary()
 
+// Default ('in-process'): `mercato server dev` runs the structural
+// regeneration watcher in-process — see packages/cli/src/lib/in-process-generate-watcher.ts
+// — so the orchestrator no longer spawns a dedicated `mercato generate watch`
+// sidecar. Saves ~190 MB of resident RSS by eliminating one Node process.
+// Set OM_DEV_GENERATE_WATCH_MODE=legacy to opt back into the sidecar.
 const sidecarWatch = generateWatchMode === 'legacy'
   ? startFilteredChild(['generate', 'watch', '--skip-initial'], 'Generator watch (legacy sidecar)', classifyWatchLine)
   : null

package/template/scripts/dev.mjs

@@ -202,6 +202,10 @@ const splashEnabled = !classic && !appOnly && splashPortConfig.enabled
 const autoOpenSplash = splashEnabled && process.stdout.isTTY && process.env.CI !== 'true' && process.env.OM_DEV_AUTO_OPEN !== '0'
 const splashBindHost = isContainerRuntime() ? '0.0.0.0' : '127.0.0.1'
 const standaloneRuntimeScript = path.join(process.cwd(), 'scripts', 'dev-runtime.mjs')
+const warmupReadyFilePath = path.join(
+  process.cwd(),
+  isMonorepo ? 'apps/mercato/.mercato/dev-warmup-ready.json' : '.mercato/dev-warmup-ready.json',
+)
 const devLogTeeDisabled = process.env.OM_DEV_LOG_TEE === '0' || process.env.OM_DEV_LOG_TEE === 'false'
 
 let devLogSessionInstance = null
@@ -492,7 +496,7 @@ function resolveSplashLocaleConfig() {
   return splashLocaleConfig
 }
 
-function buildSplashChildEnv() {
+function buildSplashChildEnv(options = {}) {
   const childEnv = devLogTeeDisabled
     ? {}
     : {
@@ -501,18 +505,31 @@ function buildSplashChildEnv() {
       }
 
   if (!splashChildStateFile) {
-    return Object.keys(childEnv).length > 0 ? childEnv : undefined
+    const env = {
+      ...childEnv,
+      OM_DEV_SHUTDOWN_NOTICE_OWNER: 'parent',
+    }
+    return Object.keys(env).length > 0 ? env : undefined
   }
 
   return {
     ...childEnv,
     OM_DEV_SPLASH_CHILD_STATE_FILE: splashChildStateFile,
+    OM_DEV_WARMUP_READY_FILE: warmupReadyFilePath,
     OM_DEV_SPLASH_MODE: splashMode,
+    OM_DEV_SHUTDOWN_NOTICE_OWNER: 'parent',
+    ...(Number.isFinite(options.stageCurrent) ? { OM_DEV_SPLASH_STAGE_CURRENT: String(options.stageCurrent) } : {}),
+    ...(Number.isFinite(options.stageTotal) ? { OM_DEV_SPLASH_STAGE_TOTAL: String(options.stageTotal) } : {}),
   }
 }
 
 function applyLocalDevBackgroundServiceDefaults(childEnv) {
-  const env = childEnv ?? {}
+  const env = {
+    ...(childEnv ?? {}),
+    OM_DEV_WARMUP_READY_FILE: (childEnv && 'OM_DEV_WARMUP_READY_FILE' in childEnv)
+      ? childEnv.OM_DEV_WARMUP_READY_FILE
+      : warmupReadyFilePath,
+  }
   if (
     typeof process.env.OM_AUTO_SPAWN_WORKERS_LAZY !== 'string'
     || process.env.OM_AUTO_SPAWN_WORKERS_LAZY.trim() === ''
@@ -528,8 +545,8 @@ function applyLocalDevBackgroundServiceDefaults(childEnv) {
   return env
 }
 
-function buildAppDevEnv() {
-  return applyLocalDevBackgroundServiceDefaults(buildSplashChildEnv() ?? {})
+function buildAppDevEnv(options = {}) {
+  return applyLocalDevBackgroundServiceDefaults(buildSplashChildEnv(options) ?? {})
 }
 
 function launchStandaloneDev(options = {}) {
@@ -566,7 +583,7 @@ function launchStandaloneDev(options = {}) {
 
   const app = spawnCommand(process.execPath, runtimeArgs, {
     stdio: 'inherit',
-    env: buildAppDevEnv(),
+    env: buildAppDevEnv({ stageCurrent, stageTotal }),
   })
 
   app.on('close', (code) => {
@@ -996,6 +1013,18 @@ function closeSplashServer() {
   writeSplashChildStateFileClear()
 }
 
+function announceShutdown() {
+  const message = 'Shutting down services...'
+  updateSplashState({
+    phase: message,
+    detail: 'Stopping app runtime, watchers, workers, and scheduler',
+    ready: false,
+    progressLabel: message,
+    activity: message,
+  })
+  console.log(message)
+}
+
 function openBrowser(url) {
   try {
     let child
@@ -1014,10 +1043,11 @@ function openBrowser(url) {
 function shutdown(exitCode = 0) {
   if (shuttingDown) return
   shuttingDown = true
-  closeSplashServer()
+  announceShutdown()
 
   const alive = Array.from(children).filter((child) => !child.killed)
   if (alive.length === 0) {
+    closeSplashServer()
     closeDevLogSession()
     process.exit(exitCode)
     return
@@ -1033,6 +1063,7 @@ function shutdown(exitCode = 0) {
         killProcessTree(child, 'SIGKILL')
       }
     }
+    closeSplashServer()
     closeDevLogSession()
     process.exit(exitCode)
   }, 3000)
@@ -1615,7 +1646,7 @@ function launchMonorepoAppDev() {
   })
   const app = spawnCommand(yarnCommand, appArgs, {
     stdio: 'inherit',
-    env: buildAppDevEnv(),
+    env: buildAppDevEnv({ stageCurrent, stageTotal }),
   })
 
   app.on('close', (code, signal) => {

package/template/src/app/globals.css

@@ -1,7 +1,6 @@
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "react-big-calendar/lib/css/react-big-calendar.css";
-@import "@xyflow/react/dist/style.css";
 @import "../../.mercato/generated/module-package-sources.css";
 
 /*

package/template/src/components/ClientBootstrap.tsx

@@ -1,51 +1,77 @@
 "use client"
 
 import * as React from 'react'
-import { injectionWidgetEntries } from '@/.mercato/generated/injection-widgets.generated'
-// Side-effect: registers translatable fields for client-side TranslationManager
+// Side-effect imports: these register types/components on import, so they
+// MUST stay top-level to be available during the first paint.
 import '@/.mercato/generated/translations-fields.generated'
-import { injectionTables } from '@/.mercato/generated/injection-tables.generated'
-import { enabledModuleIds } from '@/.mercato/generated/enabled-module-ids.generated'
+import '@/.mercato/generated/messages.client.generated'
+import '@/.mercato/generated/payments.client.generated'
+
 import { registerCoreInjectionWidgets, registerCoreInjectionTables, registerEnabledModuleIds } from '@open-mercato/core/modules/widgets/lib/injection'
 import { registerInjectionWidgets } from '@open-mercato/ui/backend/injection/widgetRegistry'
-import { dashboardWidgetEntries } from '@/.mercato/generated/dashboard-widgets.generated'
 import { registerDashboardWidgets } from '@open-mercato/ui/backend/dashboard/widgetRegistry'
-import { notificationHandlerEntries } from '@/.mercato/generated/notification-handlers.generated'
 import { registerNotificationHandlers } from '@open-mercato/shared/lib/notifications/handler-registry'
-// Side-effect: registers translatable fields for client-side TranslationManager
-import '@/.mercato/generated/translations-fields.generated'
-// Side-effect: configures message UI component and object type registries on the client.
-import '@/.mercato/generated/messages.client.generated'
-// Side-effect: registers provider-owned payment renderer widgets on the client.
-import '@/.mercato/generated/payments.client.generated'
 
 let _clientBootstrapped = false
+let _bootstrapPromise: Promise<void> | null = null
 
-function clientBootstrap() {
+async function clientBootstrap(): Promise<void> {
   if (_clientBootstrapped) return
-  _clientBootstrapped = true
+  if (_bootstrapPromise) return _bootstrapPromise
+
+  _bootstrapPromise = (async () => {
+    try {
+      // Defer generated registry barrels to a dynamic import so each barrel
+      // becomes its own lazy chunk in Turbopack. Routes that mount this
+      // provider but never use injection/dashboard/notification registries
+      // still get the chunks compiled, but no longer during initial page
+      // parse — the first paint is no longer blocked on registering every
+      // module's client widgets.
+      const [
+        injectionWidgets,
+        injectionTables,
+        enabledModuleIds,
+        dashboardWidgets,
+        notificationHandlers,
+      ] = await Promise.all([
+        import('@/.mercato/generated/injection-widgets.generated'),
+        import('@/.mercato/generated/injection-tables.generated'),
+        import('@/.mercato/generated/enabled-module-ids.generated'),
+        import('@/.mercato/generated/dashboard-widgets.generated'),
+        import('@/.mercato/generated/notification-handlers.generated'),
+      ])
 
-  // Register injection widgets
-  registerInjectionWidgets(injectionWidgetEntries)
-  registerCoreInjectionWidgets(injectionWidgetEntries)
-  registerCoreInjectionTables(injectionTables)
-  registerEnabledModuleIds(enabledModuleIds)
+      registerInjectionWidgets(injectionWidgets.injectionWidgetEntries)
+      registerCoreInjectionWidgets(injectionWidgets.injectionWidgetEntries)
+      registerCoreInjectionTables(injectionTables.injectionTables)
+      registerEnabledModuleIds(enabledModuleIds.enabledModuleIds)
+      registerDashboardWidgets(dashboardWidgets.dashboardWidgetEntries)
+      registerNotificationHandlers(notificationHandlers.notificationHandlerEntries)
 
-  // Register dashboard widgets
-  registerDashboardWidgets(dashboardWidgetEntries)
+      _clientBootstrapped = true
+    } catch (err) {
+      // A lazy registry chunk failed to load (e.g. a stale chunk after a
+      // deploy). Clear the cached promise so the next render retries instead
+      // of leaving every client registry empty forever — otherwise dashboard
+      // widget cards would wait on registration indefinitely with no error.
+      _bootstrapPromise = null
+      console.error('[ClientBootstrap] Failed to register client registries; will retry on next render', err)
+    }
+  })()
 
-  // Register notification handlers for client-side reactive effects
-  registerNotificationHandlers(notificationHandlerEntries)
+  return _bootstrapPromise
 }
 
 export function ClientBootstrapProvider({ children }: { children: React.ReactNode }) {
   React.useEffect(() => {
-    clientBootstrap()
+    void clientBootstrap()
   }, [])
 
-  // Also bootstrap synchronously on first render for SSR hydration
+  // Fire-and-forget on the very first client render so any consumer that
+  // reads registries during the same paint as this provider mounts still
+  // sees them populated by microtask flush. The promise is cached.
   if (typeof window !== 'undefined' && !_clientBootstrapped) {
-    clientBootstrap()
+    void clientBootstrap()
   }
 
   return <>{children}</>

package/template/src/i18n/de.json

@@ -107,6 +107,7 @@
   "common.delete": "Löschen",
   "common.edit": "Bearbeiten",
   "common.email": "E-Mail",
+  "common.error": "Etwas ist schiefgelaufen.",
   "common.expand": "Ausklappen",
   "common.export": "Exportieren",
   "common.inactive": "Inaktiv",

package/template/src/i18n/en.json

@@ -107,6 +107,7 @@
   "common.delete": "Delete",
   "common.edit": "Edit",
   "common.email": "Email",
+  "common.error": "Something went wrong.",
   "common.expand": "Expand",
   "common.export": "Export",
   "common.inactive": "Inactive",

package/template/src/i18n/es.json

@@ -107,6 +107,7 @@
   "common.delete": "Eliminar",
   "common.edit": "Editar",
   "common.email": "Correo electrónico",
+  "common.error": "Algo salió mal.",
   "common.expand": "Expandir",
   "common.export": "Exportar",
   "common.inactive": "Inactivo",

package/template/src/i18n/pl.json

@@ -107,6 +107,7 @@
   "common.delete": "Usuń",
   "common.edit": "Edytuj",
   "common.email": "E-mail",
+  "common.error": "Coś poszło nie tak.",
   "common.expand": "Rozwiń",
   "common.export": "Eksportuj",
   "common.inactive": "Nieaktywny",

package/template/src/modules/example_customers_sync/lib/runtime.ts

@@ -1,3 +1,5 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { DefaultDataEngine, type DataEngine } from '@open-mercato/shared/lib/data/engine'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 
 export type ExampleCustomersSyncScope = {
@@ -8,6 +10,31 @@ export type ExampleCustomersSyncScope = {
 export const EXAMPLE_CUSTOMERS_SYNC_OUTBOUND_ORIGIN = 'example_customers_sync:outbound'
 export const EXAMPLE_CUSTOMERS_SYNC_INBOUND_ORIGIN = 'example_customers_sync:inbound'
 
+type AnyContainer = { resolve: <T = unknown>(name: string) => T }
+
+// Each sync invocation gets its own forked EM + fresh DataEngine so that
+// concurrent or sequential jobs cannot pollute the shared identity map.
+// Without this, two outbound jobs targeting the same interaction.id would
+// both add an INSERT for the same Todo into the shared UoW, and the second
+// flush (inside setRecordCustomFields) would fail with todos_pkey duplicate.
+export function createScopedSyncContainer(container: AnyContainer): AnyContainer {
+  const baseEm = container.resolve('em') as EntityManager
+  const scopedEm = baseEm.fork({ clear: true })
+  let scopedDataEngine: DataEngine | null = null
+  return {
+    resolve<T = unknown>(name: string): T {
+      if (name === 'em') return scopedEm as unknown as T
+      if (name === 'dataEngine') {
+        if (!scopedDataEngine) {
+          scopedDataEngine = new DefaultDataEngine(scopedEm, container as never)
+        }
+        return scopedDataEngine as unknown as T
+      }
+      return container.resolve<T>(name)
+    },
+  }
+}
+
 export function buildExampleCustomersSyncCommandContext(
   container: { resolve: <T = unknown>(name: string) => T },
   scope: ExampleCustomersSyncScope,

package/template/src/modules/example_customers_sync/lib/sync.ts

@@ -30,6 +30,7 @@ import {
 } from './mappings'
 import {
   buildExampleCustomersSyncCommandContext,
+  createScopedSyncContainer,
   EXAMPLE_CUSTOMERS_SYNC_INBOUND_ORIGIN,
   EXAMPLE_CUSTOMERS_SYNC_OUTBOUND_ORIGIN,
   type ExampleCustomersSyncScope,
@@ -461,14 +462,24 @@ async function ensureLegacyExampleMapping(
 }
 
 export async function syncCustomerInteractionToExampleTodo(
-  container: ContainerLike,
+  rawContainer: ContainerLike,
   payload: ExampleCustomersSyncOutboundJobPayload,
 ): Promise<void> {
   const scope = { tenantId: payload.tenantId, organizationId: payload.organizationId }
-  const flags = await resolveExampleCustomersSyncFlags(container, scope.tenantId)
+  const flags = await resolveExampleCustomersSyncFlags(rawContainer, scope.tenantId)
   if (!flags.enabled) return
 
-  const em = (container.resolve('em') as EntityManager).fork()
+  // Worker's own fork — used for reads (findMappingByInteractionId,
+  // loadExampleTodoSnapshot, ensureLegacyExampleMapping) and for the
+  // error-path mapping write (markMappingError). This preserves the
+  // pre-fix behavior of the local em so the catch path keeps working.
+  const em = (rawContainer.resolve('em') as EntityManager).fork()
+  // Separate scoped container — used ONLY for command-bus calls so each
+  // sync invocation gets its own DataEngine.em. This isolates the
+  // identity-map pollution that surfaced as a todos_pkey duplicate inside
+  // setRecordCustomFields when multiple jobs touched the same interaction.id
+  // through the shared request-container DataEngine.
+  const container = createScopedSyncContainer(rawContainer)
   let mapping = await findMappingByInteractionId(em, scope, payload.interactionId)
 
   try {
@@ -600,6 +611,10 @@ export async function syncExampleTodoToCanonicalInteraction(
   const flags = await resolveExampleCustomersSyncFlags(container, scope.tenantId)
   if (!flags.enabled || !flags.bidirectional) return
 
+  // Inbound sync never hit the outbound duplicate-key bug (it creates/updates
+  // canonical interactions, not same-id Todos), so it keeps the original
+  // shared-container behavior — scoping it was speculative and regressed the
+  // inbound field-clear propagation in TC-CRM-028.
   const em = (container.resolve('em') as EntityManager).fork()
   let mapping = await findMappingByTodoId(em, scope, payload.todoId)
   let todo: ExampleTodoSnapshot | null = null
@@ -900,8 +915,8 @@ export async function reconcileLegacyExampleTodoLinks(
 ): Promise<ExampleCustomersSyncReconcileResult> {
   const scope = { tenantId: input.tenantId, organizationId: input.organizationId }
   const limit = Math.min(Math.max(input.limit ?? 100, 1), 500)
-  const { rows, nextCursor } = await loadLegacyExampleTodoLinks(container, scope, limit, input.cursor)
   const em = (container.resolve('em') as EntityManager).fork()
+  const { rows, nextCursor } = await loadLegacyExampleTodoLinks(container, scope, limit, input.cursor)
   const items: ExampleCustomersSyncReconcileItem[] = []
   let mapped = 0
   let createdInteractions = 0