@open-mercato/cli 0.5.1-develop.3032.01699048cb → 0.5.1-develop.3036.f02c281f23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.5.1-develop.3032.01699048cb",
+  "version": "0.5.1-develop.3036.f02c281f23",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.0.13",
     "@mikro-orm/migrations": "^7.0.13",
     "@mikro-orm/postgresql": "^7.0.13",
-    "@open-mercato/queue": "0.5.1-develop.3032.01699048cb",
-    "@open-mercato/shared": "0.5.1-develop.3032.01699048cb",
+    "@open-mercato/queue": "0.5.1-develop.3036.f02c281f23",
+    "@open-mercato/shared": "0.5.1-develop.3036.f02c281f23",
     "cross-spawn": "^7.0.6",
     "pg": "8.20.0",
     "semver": "^7.7.4",
@@ -70,10 +70,10 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.3032.01699048cb"
+    "@open-mercato/shared": "0.5.1-develop.3036.f02c281f23"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.3032.01699048cb",
+    "@open-mercato/shared": "0.5.1-develop.3036.f02c281f23",
     "@types/jest": "^30.0.0",
     "jest": "^30.3.0",
     "ts-jest": "^29.4.9"

package/src/__tests__/mercato.test.ts

@@ -1,3 +1,4 @@
+import type { Module } from '@open-mercato/shared/modules/registry'
 import {
   registerCliModules,
   getCliModules,
@@ -6,6 +7,61 @@ import {
   run,
 } from '../mercato'
 
+type MockChildAutoExit = { code: number | null; signal?: NodeJS.Signals | null } | undefined
+type MockChildSpawnRouter = (args: string[]) => MockChildAutoExit
+
+function buildMockChildProcessModule(routeAutoExit: MockChildSpawnRouter) {
+  const { EventEmitter } = jest.requireActual('node:events')
+
+  const createChild = (spawnargs: string[], autoExit?: MockChildAutoExit) => {
+    const child = new EventEmitter() as any
+    child.stdout = new EventEmitter()
+    child.stderr = new EventEmitter()
+    child.spawnargs = spawnargs
+    child.killed = false
+    child.exitCode = null
+    child.signalCode = null
+    child.kill = jest.fn((signal: NodeJS.Signals = 'SIGTERM') => {
+      child.killed = true
+      if (child.exitCode !== null || child.signalCode !== null) {
+        return true
+      }
+      child.signalCode = signal
+      queueMicrotask(() => {
+        child.emit('exit', null, signal)
+      })
+      return true
+    })
+
+    if (autoExit) {
+      queueMicrotask(() => {
+        if (child.exitCode !== null || child.signalCode !== null) return
+        child.exitCode = autoExit.code
+        child.signalCode = autoExit.signal ?? null
+        child.emit('exit', child.exitCode, child.signalCode)
+      })
+    }
+
+    return child
+  }
+
+  return {
+    spawn: jest.fn((_command: string, args: string[]) => createChild(['node', ...args], routeAutoExit(args))),
+  }
+}
+
+const eventsWorkerFixture: Pick<Module, 'id' | 'workers'> = {
+  id: 'events',
+  workers: [
+    {
+      id: 'events.test-worker',
+      queue: 'events',
+      concurrency: 1,
+      handler: jest.fn(),
+    },
+  ],
+}
+
 describe('mercato CLI module registration', () => {
   beforeEach(() => {
     // Reset module state by re-importing
@@ -562,11 +618,13 @@ describe('generate post-step structural cache purge', () => {
 
 describe('server dev managed process exits', () => {
   const originalAutoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER
+  const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
 
   beforeEach(() => {
     jest.restoreAllMocks()
     jest.resetModules()
     process.env.AUTO_SPAWN_SCHEDULER = 'false'
+    process.env.AUTO_SPAWN_WORKERS = 'true'
   })
 
   afterEach(() => {
@@ -579,6 +637,50 @@ describe('server dev managed process exits', () => {
 
   afterAll(() => {
     process.env.AUTO_SPAWN_SCHEDULER = originalAutoSpawnScheduler
+    process.env.AUTO_SPAWN_WORKERS = originalAutoSpawnWorkers
+  })
+
+  it('skips scheduler auto-start when the module is not enabled', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    process.env.AUTO_SPAWN_SCHEDULER = 'true'
+    process.env.AUTO_SPAWN_WORKERS = 'false'
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
+      return {
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          candidate.includes('next/dist/bin/next') || candidate.includes('@open-mercato/cli/bin/mercato'),
+        ),
+        unlinkSync: jest.fn(),
+      }
+    })
+    jest.doMock('../lib/generators', () => ({
+      generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
+    }))
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+      createResolver: () => ({}),
+    }))
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        args[0]?.includes('next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const mercato = await import('../mercato')
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'dev'])
+
+    expect(exitCode).toBe(0)
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+    expect(consoleLogSpy).toHaveBeenCalledWith('[server] Skipping scheduler auto-start — module not enabled')
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
   })
 
   it('fails loudly when a managed child exits cleanly but unexpectedly', async () => {
@@ -605,76 +707,138 @@ describe('server dev managed process exits', () => {
       }),
       createResolver: () => ({}),
     }))
-    jest.doMock('child_process', () => {
-      const { EventEmitter } = jest.requireActual('node:events')
-
-      const createChild = (
-        spawnargs: string[],
-        autoExit?: { code: number | null; signal?: NodeJS.Signals | null },
-      ) => {
-        const child = new EventEmitter() as any
-        child.stdout = new EventEmitter()
-        child.stderr = new EventEmitter()
-        child.spawnargs = spawnargs
-        child.killed = false
-        child.exitCode = null
-        child.signalCode = null
-        child.kill = jest.fn((signal: NodeJS.Signals = 'SIGTERM') => {
-          child.killed = true
-          if (child.exitCode !== null || child.signalCode !== null) {
-            return true
-          }
-          child.signalCode = signal
-          queueMicrotask(() => {
-            child.emit('exit', null, signal)
-          })
-          return true
-        })
-
-        if (autoExit) {
-          queueMicrotask(() => {
-            if (child.exitCode !== null || child.signalCode !== null) return
-            child.exitCode = autoExit.code
-            child.signalCode = autoExit.signal ?? null
-            child.emit('exit', child.exitCode, child.signalCode)
-          })
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) => {
+        if (args.slice(1).join(' ') === 'queue worker --all') {
+          return { code: 0 }
         }
+        return undefined
+      }),
+    )
+
+    const mercato = await import('../mercato')
+    mercato.registerCliModules([eventsWorkerFixture as Module])
+
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'dev'])
+
+    expect(exitCode).toBe(1)
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '💥 Failed: [server] Queue worker (events) exited unexpectedly with exit code 0.',
+    )
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
+})
+
+describe('server start managed process exits', () => {
+  const originalAutoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER
+  const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
 
-        return child
+  beforeEach(() => {
+    jest.restoreAllMocks()
+    jest.resetModules()
+    process.env.AUTO_SPAWN_SCHEDULER = 'false'
+    process.env.AUTO_SPAWN_WORKERS = 'true'
+  })
+
+  afterEach(() => {
+    jest.dontMock('child_process')
+    jest.dontMock('node:fs')
+    jest.dontMock('../lib/resolver')
+    jest.dontMock('../lib/server-start-lock')
+    jest.resetModules()
+  })
+
+  afterAll(() => {
+    process.env.AUTO_SPAWN_SCHEDULER = originalAutoSpawnScheduler
+    process.env.AUTO_SPAWN_WORKERS = originalAutoSpawnWorkers
+  })
+
+  it('skips scheduler auto-start when the module is not enabled', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    process.env.AUTO_SPAWN_SCHEDULER = 'true'
+    process.env.AUTO_SPAWN_WORKERS = 'false'
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
+      return {
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          candidate.includes('next/dist/bin/next') || candidate.includes('@open-mercato/cli/bin/mercato'),
+        ),
       }
+    })
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+    }))
+    jest.doMock('../lib/server-start-lock', () => ({
+      acquireServerStartLock: jest.fn(() => ({
+        release: jest.fn(),
+      })),
+    }))
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        args[0]?.includes('next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const mercato = await import('../mercato')
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'start'])
+
+    expect(exitCode).toBe(0)
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+    expect(consoleLogSpy).toHaveBeenCalledWith('[server] Skipping scheduler auto-start — module not enabled')
 
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
+
+  it('fails loudly when a managed child exits cleanly but unexpectedly', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
       return {
-        spawn: jest.fn((_command: string, args: string[]) => {
-          if (args[0]?.includes('next/dist/bin/next')) {
-            return createChild(['node', ...args])
-          }
-          if (args.slice(1).join(' ') === 'queue worker --all') {
-            return createChild(['node', ...args], { code: 0 })
-          }
-          return createChild(['node', ...args])
-        }),
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          candidate.includes('next/dist/bin/next') || candidate.includes('@open-mercato/cli/bin/mercato'),
+        ),
       }
     })
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+    }))
+    jest.doMock('../lib/server-start-lock', () => ({
+      acquireServerStartLock: jest.fn(() => ({
+        release: jest.fn(),
+      })),
+    }))
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) => {
+        if (args.slice(1).join(' ') === 'queue worker --all') {
+          return { code: 0 }
+        }
+        return undefined
+      }),
+    )
 
     const mercato = await import('../mercato')
-    mercato.registerCliModules([
-      {
-        id: 'events',
-        workers: [
-          {
-            queue: 'events',
-            concurrency: 1,
-            handler: jest.fn(),
-          },
-        ],
-      } as any,
-    ])
+    mercato.registerCliModules([eventsWorkerFixture as Module])
 
-    const exitCode = await mercato.run(['node', 'mercato', 'server', 'dev'])
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'start'])
 
     expect(exitCode).toBe(1)
     expect(consoleErrorSpy).toHaveBeenCalledWith(
-      '💥 Failed: [server] Queue worker exited unexpectedly with exit code 0.',
+      '💥 Failed: [server] Queue worker (events) exited unexpectedly with exit code 0.',
     )
 
     consoleErrorSpy.mockRestore()

package/src/mercato.ts

@@ -311,6 +311,16 @@ type ManagedProcessExitResult = {
   signal: NodeJS.Signals | null
 }
 
+type ModuleCommandLookupResult =
+  | {
+      status: 'ok'
+      module: Module
+      command: NonNullable<Module['cli']>[number]
+    }
+  | {
+      status: 'missing-module' | 'missing-cli' | 'missing-command'
+    }
+
 function waitForManagedProcessExit(proc: ChildProcess, label: string): Promise<ManagedProcessExitResult> {
   return new Promise((resolve) => {
     proc.on('exit', (code, signal) => {
@@ -337,6 +347,50 @@ function createManagedProcessExitError(result: ManagedProcessExitResult): Error
   return new Error(`[server] ${result.label} exited unexpectedly with ${formatManagedProcessExitStatus(result)}.`)
 }
 
+function formatQueueWorkerLabel(queueNames: string[]): string {
+  if (queueNames.length === 0) return 'Queue worker'
+  const sorted = [...queueNames].sort((a, b) => a.localeCompare(b))
+  const preview = sorted.length > 4 ? `${sorted.slice(0, 4).join(', ')}, +${sorted.length - 4} more` : sorted.join(', ')
+  return `Queue worker (${preview})`
+}
+
+function lookupModuleCommand(
+  allModules: Module[],
+  moduleName: string,
+  commandName: string,
+): ModuleCommandLookupResult {
+  const mod = allModules.find((entry) => entry.id === moduleName)
+  if (!mod) {
+    return { status: 'missing-module' }
+  }
+
+  if (!mod.cli || mod.cli.length === 0) {
+    return { status: 'missing-cli' }
+  }
+
+  const command = mod.cli.find((entry) => entry.command === commandName)
+  if (!command) {
+    return { status: 'missing-command' }
+  }
+
+  return {
+    status: 'ok',
+    module: mod,
+    command,
+  }
+}
+
+function describeMissingModuleCommand(result: Exclude<ModuleCommandLookupResult, { status: 'ok' }>): string {
+  switch (result.status) {
+    case 'missing-module':
+      return 'module not enabled'
+    case 'missing-cli':
+      return 'module has no CLI commands'
+    case 'missing-command':
+      return 'command not found'
+  }
+}
+
 function ensureNextBuildIdInConfiguredDistDir(appDir: string): void {
   const configuredDistDir = path.join(appDir, '.mercato', 'next')
   const configuredBuildIdPath = path.join(configuredDistDir, 'BUILD_ID')
@@ -404,36 +458,25 @@ async function runModuleCommand(
   args: string[] = [],
   options: { optional?: boolean; silentOptional?: boolean } = {},
 ): Promise<boolean> {
-  const mod = allModules.find((m) => m.id === moduleName)
-  if (!mod) {
-    if (options.optional) {
-      if (!options.silentOptional) {
-        console.log(`⏭️  Skipping "${moduleName}:${commandName}" — module not enabled`)
-      }
-      return false
-    }
-    throw new Error(`Module not found: "${moduleName}"`)
-  }
-  if (!mod.cli || mod.cli.length === 0) {
+  const resolved = lookupModuleCommand(allModules, moduleName, commandName)
+  if (resolved.status !== 'ok') {
     if (options.optional) {
       if (!options.silentOptional) {
-        console.log(`⏭️  Skipping "${moduleName}:${commandName}" — module has no CLI commands`)
+        console.log(`⏭️  Skipping "${moduleName}:${commandName}" — ${describeMissingModuleCommand(resolved)}`)
       }
       return false
     }
-    throw new Error(`Module "${moduleName}" has no CLI commands`)
-  }
-  const cmd = mod.cli.find((c) => c.command === commandName)
-  if (!cmd) {
-    if (options.optional) {
-      if (!options.silentOptional) {
-        console.log(`⏭️  Skipping "${moduleName}:${commandName}" — command not found`)
-      }
-      return false
+    switch (resolved.status) {
+      case 'missing-module':
+        throw new Error(`Module not found: "${moduleName}"`)
+      case 'missing-cli':
+        throw new Error(`Module "${moduleName}" has no CLI commands`)
+      case 'missing-command':
+        throw new Error(`Command "${commandName}" not found in module "${moduleName}"`)
     }
-    throw new Error(`Command "${commandName}" not found in module "${moduleName}"`)
   }
-  await cmd.run(args)
+
+  await resolved.command.run(args)
   return true
 }
 
@@ -1603,8 +1646,8 @@ export async function run(argv = process.argv) {
           const autoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS !== 'false'
           const autoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER !== 'false'
           const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
-          const runtimeEnv = buildServerProcessEnvironment(process.env)
           let didRetryCorruptedTurbopackCache = false
+          const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
 
           function cleanup() {
             console.log('[server] Shutting down...')
@@ -1622,7 +1665,7 @@ export async function run(argv = process.argv) {
               processes.map(
                 (proc) =>
                   new Promise<void>((resolve) => {
-                    if (proc.exitCode !== null) return resolve()
+                    if (proc.exitCode !== null || proc.signalCode !== null) return resolve()
                     proc.on('exit', () => resolve())
                   })
               )
@@ -1653,7 +1696,7 @@ export async function run(argv = process.argv) {
             new Promise((resolve) => {
               const nextProcess = spawn('node', [nextBin, 'dev', '--turbopack'], {
                 stdio: ['inherit', 'pipe', 'pipe'],
-                env: runtimeEnv,
+                env: process.env,
                 cwd: appDir,
               })
               processes.push(nextProcess)
@@ -1704,23 +1747,27 @@ export async function run(argv = process.argv) {
               console.log('[server] Starting workers for all queues...')
               const workerProcess = spawn('node', [mercatoBin, 'queue', 'worker', '--all'], {
                 stdio: 'inherit',
-                env: runtimeEnv,
+                env: process.env,
                 cwd: appDir,
               })
               processes.push(workerProcess)
-              managedExitPromises.push(waitForManagedProcessExit(workerProcess, 'Queue worker'))
+              managedExitPromises.push(waitForManagedProcessExit(workerProcess, formatQueueWorkerLabel(discoveredWorkerQueues)))
             }
           }
 
           if (autoSpawnScheduler && queueStrategy === 'local') {
-            console.log('[server] 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 (schedulerCommand.status !== 'ok') {
+              console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
+            } else {
+              console.log('[server] Starting scheduler polling engine...')
+              const schedulerProcess = spawn('node', [mercatoBin, 'scheduler', 'start'], {
+                stdio: 'inherit',
+                env: process.env,
+                cwd: appDir,
+              })
+              processes.push(schedulerProcess)
+              managedExitPromises.push(waitForManagedProcessExit(schedulerProcess, 'Scheduler polling engine'))
+            }
           }
 
           const firstExit = await Promise.race(managedExitPromises)
@@ -1746,6 +1793,7 @@ export async function run(argv = process.argv) {
           const autoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER !== 'false'
           const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
           const runtimeEnv = buildServerProcessEnvironment(process.env)
+          const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
           const serverStartLock = acquireServerStartLock(appDir, {
             port: runtimeEnv.PORT ?? process.env.PORT ?? null,
           })
@@ -1753,7 +1801,7 @@ export async function run(argv = process.argv) {
           function cleanup() {
             console.log('[server] Shutting down...')
             for (const proc of processes) {
-              if (!proc.killed) {
+              if (!proc.killed && proc.exitCode === null && proc.signalCode === null) {
                 proc.kill('SIGTERM')
               }
             }
@@ -1765,7 +1813,7 @@ export async function run(argv = process.argv) {
               processes.map(
                 (proc) =>
                   new Promise<void>((resolve) => {
-                    if (proc.exitCode !== null) return resolve()
+                    if (proc.exitCode !== null || proc.signalCode !== null) return resolve()
                     proc.on('exit', () => resolve())
                   })
               )
@@ -1789,6 +1837,9 @@ export async function run(argv = process.argv) {
               cwd: appDir,
             })
             processes.push(nextProcess)
+            const managedExitPromises: Promise<ManagedProcessExitResult>[] = [
+              waitForManagedProcessExit(nextProcess, 'Next.js production server'),
+            ]
 
             // Start workers if enabled
             if (autoSpawnWorkers) {
@@ -1803,30 +1854,32 @@ export async function run(argv = process.argv) {
                   cwd: appDir,
                 })
                 processes.push(workerProcess)
+                managedExitPromises.push(waitForManagedProcessExit(workerProcess, formatQueueWorkerLabel(discoveredWorkerQueues)))
               }
             }
 
             if (autoSpawnScheduler && queueStrategy === 'local') {
-              console.log('[server] Starting scheduler polling engine...')
-              const schedulerProcess = spawn('node', [mercatoBin, 'scheduler', 'start'], {
-                stdio: 'inherit',
-                env: runtimeEnv,
-                cwd: appDir,
-              })
-              processes.push(schedulerProcess)
+              if (schedulerCommand.status !== 'ok') {
+                console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
+              } else {
+                console.log('[server] 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'))
+              }
             }
 
-            // Wait for any process to exit
-            await Promise.race(
-              processes.map(
-                (proc) =>
-                  new Promise<void>((resolve) => {
-                    proc.on('exit', () => resolve())
-                  })
-              )
-            )
+            const firstExit = await Promise.race(managedExitPromises)
 
             await cleanupAndWait()
+
+            if (!isExpectedManagedExitSignal(firstExit.signal)) {
+              throw createManagedProcessExitError(firstExit)
+            }
           } finally {
             serverStartLock.release()
           }