create-mercato-app 0.6.4-develop.3944.1.4100aa7fbe → 0.6.4-develop.3962.1.70f30e284c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.4-develop.3944.1.4100aa7fbe",
+  "version": "0.6.4-develop.3962.1.70f30e284c",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

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-runtime.mjs

@@ -90,6 +90,8 @@ 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...'
@@ -98,6 +100,10 @@ const configuredRuntimeProgressCurrent = parsePositiveIntegerEnv(process.env.OM_
 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
@@ -116,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,
@@ -169,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}`)
@@ -498,6 +532,7 @@ function spawnMercato(args) {
       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,
   })
@@ -658,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, {
@@ -670,6 +713,7 @@ async function fetchWithTimeout(url, init = {}, timeoutMs = 45000) {
     })
   } finally {
     clearTimeout(timer)
+    externalSignal?.removeEventListener?.('abort', abortFromExternalSignal)
   }
 }
 
@@ -683,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
 
@@ -775,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(() => {
@@ -791,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'
@@ -805,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}`)
     }
@@ -834,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}`)
@@ -873,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)) {
@@ -897,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',
@@ -911,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
@@ -987,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'))
     }
   }
@@ -1147,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)
@@ -1594,6 +1682,7 @@ 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}`,
@@ -1608,6 +1697,7 @@ function classifyServerLine(line) {
 
   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}`,
@@ -1630,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',
     }
   }
@@ -1645,7 +1735,7 @@ function classifyServerLine(line) {
       ready: false,
       runtimeReady: true,
       activity: timing,
-      progressCurrent: 4,
+      progressCurrent: runtimeWarmupProgressCurrent,
       progressLabel: 'Precompiling login page',
     }
   }
@@ -1654,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,

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
@@ -501,20 +505,31 @@ function buildSplashChildEnv(options = {}) {
       }
 
   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() === ''
@@ -998,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
@@ -1016,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
@@ -1035,6 +1063,7 @@ function shutdown(exitCode = 0) {
         killProcessTree(child, 'SIGKILL')
       }
     }
+    closeSplashServer()
     closeDevLogSession()
     process.exit(exitCode)
   }, 3000)

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}</>