@open-mercato/cli 0.6.3-develop.3894.1.352abf4240 → 0.6.3

package/src/mercato.ts

@@ -341,6 +341,122 @@ type DevServerRestartResult = {
 
 type DevServerExitResult = ManagedProcessExitResult | DevServerRestartResult
 
+function resolveDevRuntimeBaseUrl(environment: NodeJS.ProcessEnv = process.env): string {
+  const configured =
+    environment.APP_URL
+    ?? environment.NEXT_PUBLIC_APP_URL
+    ?? environment.NEXTAUTH_URL
+  if (configured?.trim()) {
+    return configured.trim().replace(/\/+$/, '')
+  }
+  return `http://localhost:${environment.PORT?.trim() || '3000'}`
+}
+
+function writeDevSplashChildState(state: Record<string, unknown>): void {
+  if (process.env.OM_DEV_SPLASH_RUNTIME_WRAPPER === '1') return
+  const stateFile = process.env.OM_DEV_SPLASH_CHILD_STATE_FILE
+  if (!stateFile?.trim()) return
+
+  try {
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true })
+    fs.writeFileSync(stateFile, `${JSON.stringify({
+      mode: process.env.OM_DEV_SPLASH_MODE || 'dev',
+      failed: false,
+      failureLines: [],
+      failureCommand: null,
+      ...state,
+    }, null, 2)}\n`)
+  } catch {
+    // Splash state is best-effort; terminal logs remain authoritative.
+  }
+}
+
+function writeDevSplashRuntimeStarting(detail = 'Starting Next.js dev server'): void {
+  writeDevSplashChildState({
+    phase: 'Preparing app runtime',
+    detail,
+    ready: false,
+    readyUrl: null,
+    loginUrl: null,
+    progressLabel: 'Launching app runtime',
+    activity: detail,
+  })
+}
+
+function resolveSplashProgressFallback(): { current: number; total: number } {
+  const current = Number.parseInt(process.env.OM_DEV_SPLASH_STAGE_CURRENT ?? '', 10)
+  const total = Number.parseInt(process.env.OM_DEV_SPLASH_STAGE_TOTAL ?? '', 10)
+  if (Number.isFinite(current) && Number.isFinite(total) && total > 0) {
+    return { current, total }
+  }
+  if (process.env.OM_DEV_SPLASH_MODE === 'greenfield' || process.env.OM_DEV_SPLASH_MODE === 'setup') {
+    return { current: 5, total: 5 }
+  }
+  return { current: 3, total: 3 }
+}
+
+function writeDevSplashRuntimeRestarting(reason: string): void {
+  const progress = resolveSplashProgressFallback()
+  writeDevSplashChildState({
+    phase: 'App runtime is restarting',
+    detail: `Reason: ${reason}`,
+    ready: false,
+    readyUrl: null,
+    loginUrl: null,
+    progressCurrent: progress.current,
+    progressTotal: progress.total,
+    progressLabel: 'Restarting app runtime',
+    activity: `App runtime restart: ${reason}`,
+  })
+}
+
+function writeDevSplashRuntimeReady(reason?: string): void {
+  const readyUrl = resolveDevRuntimeBaseUrl()
+  const progress = resolveSplashProgressFallback()
+  writeDevSplashChildState({
+    phase: 'App is ready',
+    detail: reason ? `Restart completed after ${reason}` : 'Next.js dev server is ready',
+    ready: true,
+    readyUrl,
+    loginUrl: `${readyUrl}/login`,
+    progressCurrent: progress.current,
+    progressTotal: progress.total,
+    progressPercent: 100,
+    progressLabel: 'App is ready',
+    activity: reason ? `Restart completed after ${reason}` : 'App runtime is ready',
+  })
+}
+
+function resolveDevWarmupReadyTimeoutMs(environment: NodeJS.ProcessEnv = process.env): number {
+  const parsed = Number.parseInt(environment.OM_DEV_WARMUP_READY_TIMEOUT_MS ?? '', 10)
+  if (Number.isFinite(parsed) && parsed >= 0) return parsed
+  return 300_000
+}
+
+async function waitForDevWarmupReadyFile(
+  filePath: string | undefined,
+  options: {
+    timeoutMs?: number
+    signal?: AbortSignal
+  } = {},
+): Promise<'ready' | 'timeout' | 'aborted'> {
+  const normalized = filePath?.trim()
+  if (!normalized) return 'ready'
+  const timeoutMs = options.timeoutMs ?? resolveDevWarmupReadyTimeoutMs()
+  const startedAt = Date.now()
+
+  while (true) {
+    if (options.signal?.aborted) return 'aborted'
+    try {
+      if (fs.existsSync(normalized)) return 'ready'
+    } catch {
+      // Keep polling; the runtime wrapper owns this best-effort marker.
+    }
+    if (timeoutMs >= 0 && Date.now() - startedAt >= timeoutMs) return 'timeout'
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+}
+
 type ModuleCommandLookupResult =
   | {
       status: 'ok'
@@ -601,18 +717,17 @@ async function runGeneratorSuite(quiet: boolean): Promise<void> {
 function createGenerateWatchChecksumFn(): () => Promise<string> {
   return async () => {
     const { createResolver } = await import('./lib/resolver')
-    const { calculateStructureChecksum } = await import('./lib/utils')
+    const { calculateGenerateWatchStructureChecksum } = await import('./lib/generate-watch-structure')
     const resolver = createResolver()
-    const tracked = new Set<string>([
-      path.join(resolver.getAppDir(), 'src', 'modules.ts'),
-      path.join(resolver.getAppDir(), 'src', 'modules'),
-    ])
+    const moduleRoots = []
     for (const entry of resolver.loadEnabledModules()) {
       const roots = resolver.getModulePaths(entry)
-      tracked.add(roots.appBase)
-      tracked.add(roots.pkgBase)
+      moduleRoots.push({ appBase: roots.appBase, pkgBase: roots.pkgBase })
     }
-    return calculateStructureChecksum(Array.from(tracked))
+    return calculateGenerateWatchStructureChecksum({
+      modulesFile: path.join(resolver.getAppDir(), 'src', 'modules.ts'),
+      moduleRoots,
+    })
   }
 }
 
@@ -1690,10 +1805,11 @@ export async function run(argv = process.argv) {
           let processes: ChildProcess[] = []
           let didRetryCorruptedTurbopackCache = false
           let stopping = false
-          let envChangePromiseResolve: ((result: DevServerRestartResult) => void) | null = null
+          let devRestartPromiseResolve: ((result: DevServerRestartResult) => void) | null = null
           let activeLazySupervisor: ReturnType<typeof startLazyWorkerSupervisor> | null = null
           let activeLazySchedulerSupervisor: ReturnType<typeof startLazySchedulerSupervisor> | null = null
           let activeGenerateWatcher: GenerateWatcherHandle | null = null
+          let lastRestartReason: string | null = null
           const generateWatcherMode: GenerateWatcherMode = resolveGenerateWatcherMode(process.env)
           const envReloader = createDevEnvReloader(appDir, process.env, initialProcessEnvironmentEntries)
 
@@ -1781,20 +1897,31 @@ export async function run(argv = process.argv) {
           const mercatoBin = resolveInstalledBinary(nodeModulesBases, '@open-mercato/cli/bin/mercato')
 
           const stopEnvWatcher = watchDevEnvFiles(appDir, (filePath) => {
-            envChangePromiseResolve?.({
+            devRestartPromiseResolve?.({
               label: 'Environment file change',
               restart: true,
               filePath,
             })
           })
-
-          const waitForEnvChange = (): Promise<DevServerRestartResult> =>
+          const waitForDevRestart = (): Promise<DevServerRestartResult> =>
             new Promise((resolve) => {
-              envChangePromiseResolve = resolve
+              devRestartPromiseResolve = resolve
             })
 
-          const startNextDev = (runtimeEnv: NodeJS.ProcessEnv): Promise<ManagedProcessExitResult> =>
-            new Promise((resolve) => {
+          const startNextDev = (runtimeEnv: NodeJS.ProcessEnv): {
+            exitPromise: Promise<ManagedProcessExitResult>
+            readyPromise: Promise<void>
+          } => {
+            let readyResolve: () => void = () => undefined
+            const readyPromise = new Promise<void>((resolve) => {
+              readyResolve = resolve
+            })
+            const exitPromise = new Promise<ManagedProcessExitResult>((resolve) => {
+              writeDevSplashRuntimeStarting(
+                lastRestartReason
+                  ? `Restarting Next.js dev server. Reason: ${lastRestartReason}`
+                  : 'Starting Next.js dev server',
+              )
               const nextProcess = spawn('node', [nextBin, 'dev', '--turbopack'], {
                 stdio: ['inherit', 'pipe', 'pipe'],
                 env: runtimeEnv,
@@ -1803,11 +1930,18 @@ export async function run(argv = process.argv) {
               processes.push(nextProcess)
 
               let combinedOutput = ''
+              let reportedReady = false
               const appendOutput = (chunk: string) => {
                 combinedOutput += chunk
                 if (combinedOutput.length > 32_768) {
                   combinedOutput = combinedOutput.slice(-32_768)
                 }
+                if (!reportedReady && /\bready in\b/i.test(chunk)) {
+                  reportedReady = true
+                  writeDevSplashRuntimeReady(lastRestartReason ?? undefined)
+                  lastRestartReason = null
+                  readyResolve()
+                }
               }
 
               nextProcess.stdout?.on('data', (chunk: Buffer | string) => {
@@ -1824,9 +1958,13 @@ export async function run(argv = process.argv) {
               nextProcess.on('exit', async (code, signal) => {
                 if (!didRetryCorruptedTurbopackCache && isTurbopackCacheCorruption(combinedOutput)) {
                   didRetryCorruptedTurbopackCache = true
+                  lastRestartReason = 'corrupted Turbopack dev cache'
+                  writeDevSplashRuntimeRestarting(lastRestartReason)
                   console.log('[server] Detected corrupted Turbopack dev cache. Clearing .mercato/next/dev and restarting Next.js once...')
                   removeTurbopackDevCache(appDir)
-                  return resolve(await startNextDev(runtimeEnv))
+                  const restarted = startNextDev(runtimeEnv)
+                  restarted.readyPromise.then(readyResolve)
+                  return resolve(await restarted.exitPromise)
                 }
                 resolve({
                   label: 'Next.js dev server',
@@ -1835,6 +1973,8 @@ export async function run(argv = process.argv) {
                 })
               })
             })
+            return { exitPromise, readyPromise }
+          }
 
           try {
             while (!stopping) {
@@ -1844,62 +1984,92 @@ export async function run(argv = process.argv) {
               const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
               const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
               const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
+              const nextRuntime = startNextDev(runtimeEnv)
+              const restartPromise = waitForDevRestart()
+              const backgroundStartAbort = new AbortController()
+              const cancelBackgroundStart = () => backgroundStartAbort.abort()
+              nextRuntime.exitPromise.finally(cancelBackgroundStart)
+              restartPromise.then(cancelBackgroundStart)
+              let backgroundExitResolve: (result: ManagedProcessExitResult) => void = () => undefined
+              const backgroundExitPromise = new Promise<ManagedProcessExitResult>((resolve) => {
+                backgroundExitResolve = resolve
+              })
               const managedExitPromises: Promise<DevServerExitResult>[] = [
-                startNextDev(runtimeEnv),
-                waitForEnvChange(),
+                nextRuntime.exitPromise,
+                restartPromise,
+                backgroundExitPromise,
               ]
 
-              // Start workers if enabled
-              if (autoSpawnWorkersMode !== 'off') {
-                const discoveredWorkers = getRegisteredCliWorkers()
-                const discoveredWorkerQueues = [...new Set(discoveredWorkers.map((worker) => worker.queue))]
-                if (discoveredWorkerQueues.length === 0) {
-                  console.error('[server] AUTO_SPAWN_WORKERS is enabled, but no queues were discovered from CLI modules. Run `yarn generate` and verify `.mercato/generated/modules.cli.generated.ts` contains worker entries. Continuing without auto-spawned workers.')
-                } else if (autoSpawnWorkersMode === 'lazy') {
-                  console.log(`[server] Lazy worker auto-spawn enabled — workers will start on first job (${discoveredWorkerQueues.length} queue(s) watched).`)
-                  activeLazySupervisor = startLazyWorkerSupervisor({
-                    mercatoBin,
-                    appDir,
-                    runtimeEnv,
-                    workers: discoveredWorkers,
-                    pollMs: resolveLazyPollMs(process.env),
-                    restartOnUnexpectedExit: resolveLazyRestart(process.env),
-                  })
-                } else {
-                  console.log('[server] Eager worker auto-spawn enabled - starting workers for all queues...')
-                  const workerProcess = spawn('node', [mercatoBin, 'queue', 'worker', '--all'], {
-                    stdio: 'inherit',
-                    env: runtimeEnv,
-                    cwd: appDir,
-                  })
-                  processes.push(workerProcess)
-                  managedExitPromises.push(waitForManagedProcessExit(workerProcess, formatQueueWorkerLabel(discoveredWorkerQueues)))
+              const startBackgroundServices = async () => {
+                if (stopping || backgroundStartAbort.signal.aborted) return
+
+                // Keep first-route compilation responsive: greenfield setup can
+                // leave vector/fulltext jobs ready. When the dev wrapper is
+                // active, wait for its /login + /backend warmup marker before
+                // workers and scheduler begin consuming CPU and database I/O.
+                const warmupReady = await waitForDevWarmupReadyFile(process.env.OM_DEV_WARMUP_READY_FILE, {
+                  timeoutMs: resolveDevWarmupReadyTimeoutMs(process.env),
+                  signal: backgroundStartAbort.signal,
+                })
+                if (warmupReady === 'aborted' || stopping || backgroundStartAbort.signal.aborted) return
+                if (warmupReady === 'timeout') {
+                  console.warn('[server] Timed out waiting for dev warmup marker; starting background services anyway.')
                 }
-              }
 
-              if (autoSpawnSchedulerMode !== 'off' && queueStrategy === 'local') {
-                if (schedulerCommand.status !== 'ok') {
-                  console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
-                } else if (autoSpawnSchedulerMode === 'lazy') {
-                  console.log('[server] Lazy scheduler auto-spawn enabled - scheduler will start when an enabled schedule exists.')
-                  activeLazySchedulerSupervisor = startLazySchedulerSupervisor({
-                    mercatoBin,
-                    appDir,
-                    runtimeEnv,
-                    pollMs: resolveLazySchedulerPollMs(process.env),
-                    restartOnUnexpectedExit: resolveLazySchedulerRestart(process.env),
-                  })
-                } else {
-                  console.log('[server] Eager scheduler auto-spawn enabled - starting scheduler polling engine...')
-                  const schedulerProcess = spawn('node', [mercatoBin, 'scheduler', 'start'], {
-                    stdio: 'inherit',
-                    env: runtimeEnv,
-                    cwd: appDir,
-                  })
-                  processes.push(schedulerProcess)
-                  managedExitPromises.push(waitForManagedProcessExit(schedulerProcess, 'Scheduler polling engine'))
+                if (autoSpawnWorkersMode !== 'off') {
+                  const discoveredWorkers = getRegisteredCliWorkers()
+                  const discoveredWorkerQueues = [...new Set(discoveredWorkers.map((worker) => worker.queue))]
+                  if (discoveredWorkerQueues.length === 0) {
+                    console.error('[server] AUTO_SPAWN_WORKERS is enabled, but no queues were discovered from CLI modules. Run `yarn generate` and verify `.mercato/generated/modules.cli.generated.ts` contains worker entries. Continuing without auto-spawned workers.')
+                  } else if (autoSpawnWorkersMode === 'lazy') {
+                    console.log(`[server] Lazy worker auto-spawn enabled — workers will start on first job (${discoveredWorkerQueues.length} queue(s) watched).`)
+                    activeLazySupervisor = startLazyWorkerSupervisor({
+                      mercatoBin,
+                      appDir,
+                      runtimeEnv,
+                      workers: discoveredWorkers,
+                      pollMs: resolveLazyPollMs(process.env),
+                      restartOnUnexpectedExit: resolveLazyRestart(process.env),
+                    })
+                  } else {
+                    console.log('[server] Eager worker auto-spawn enabled - starting workers for all queues...')
+                    const workerProcess = spawn('node', [mercatoBin, 'queue', 'worker', '--all'], {
+                      stdio: 'inherit',
+                      env: runtimeEnv,
+                      cwd: appDir,
+                    })
+                    processes.push(workerProcess)
+                    waitForManagedProcessExit(workerProcess, formatQueueWorkerLabel(discoveredWorkerQueues)).then(backgroundExitResolve)
+                  }
+                }
+
+                if (autoSpawnSchedulerMode !== 'off' && queueStrategy === 'local') {
+                  if (schedulerCommand.status !== 'ok') {
+                    console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
+                  } else if (autoSpawnSchedulerMode === 'lazy') {
+                    console.log('[server] Lazy scheduler auto-spawn enabled - scheduler will start when an enabled schedule exists.')
+                    activeLazySchedulerSupervisor = startLazySchedulerSupervisor({
+                      mercatoBin,
+                      appDir,
+                      runtimeEnv,
+                      pollMs: resolveLazySchedulerPollMs(process.env),
+                      restartOnUnexpectedExit: resolveLazySchedulerRestart(process.env),
+                    })
+                  } else {
+                    console.log('[server] Eager scheduler auto-spawn enabled - starting scheduler polling engine...')
+                    const schedulerProcess = spawn('node', [mercatoBin, 'scheduler', 'start'], {
+                      stdio: 'inherit',
+                      env: runtimeEnv,
+                      cwd: appDir,
+                    })
+                    processes.push(schedulerProcess)
+                    waitForManagedProcessExit(schedulerProcess, 'Scheduler polling engine').then(backgroundExitResolve)
+                  }
                 }
               }
+              nextRuntime.readyPromise.then(() => {
+                void startBackgroundServices()
+              })
 
               if (generateWatcherMode === 'in-process') {
                 // Run the structural regeneration watcher inside this process
@@ -1927,11 +2097,15 @@ export async function run(argv = process.argv) {
               }
 
               const firstExit = await Promise.race(managedExitPromises)
+              if (isDevServerRestartResult(firstExit)) {
+                lastRestartReason = `${firstExit.label.toLowerCase()} (${path.basename(firstExit.filePath)})`
+                writeDevSplashRuntimeRestarting(lastRestartReason)
+              }
               await cleanupAndWait()
-              envChangePromiseResolve = null
+              devRestartPromiseResolve = null
 
               if (isDevServerRestartResult(firstExit)) {
-                console.log(`[server] Detected environment file change (${path.basename(firstExit.filePath)}). Restarting app runtime...`)
+                console.log(`[server] Detected ${firstExit.label.toLowerCase()} (${path.basename(firstExit.filePath)}). Restarting app runtime...`)
                 continue
               }