@open-mercato/cli 0.6.1-develop.3291.1.6fad645fd0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.1-develop.3291.1.6fad645fd0",
+  "version": "0.6.1",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.0.15",
     "@mikro-orm/migrations": "^7.0.15",
     "@mikro-orm/postgresql": "^7.0.15",
-    "@open-mercato/queue": "0.6.1-develop.3291.1.6fad645fd0",
-    "@open-mercato/shared": "0.6.1-develop.3291.1.6fad645fd0",
+    "@open-mercato/queue": "0.6.1",
+    "@open-mercato/shared": "0.6.1",
     "cross-spawn": "^7.0.6",
     "pg": "8.20.0",
     "semver": "^7.8.0",
@@ -70,10 +70,10 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3291.1.6fad645fd0"
+    "@open-mercato/shared": "0.6.1"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3291.1.6fad645fd0",
+    "@open-mercato/shared": "0.6.1",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.9"
@@ -85,6 +85,5 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cli"
-  },
-  "stableVersion": "0.6.0"
+  }
 }

package/src/__tests__/mercato.test.ts

@@ -62,6 +62,16 @@ const eventsWorkerFixture: Pick<Module, 'id' | 'workers'> = {
   ],
 }
 
+const schedulerCliFixture: Pick<Module, 'id' | 'cli'> = {
+  id: 'scheduler',
+  cli: [
+    {
+      command: 'start',
+      run: jest.fn(),
+    },
+  ],
+}
+
 describe('mercato CLI module registration', () => {
   beforeEach(() => {
     // Reset module state by re-importing
@@ -620,6 +630,7 @@ describe('server dev managed process exits', () => {
   const originalAutoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER
   const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
   const originalLazy = process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+  const originalLazyScheduler = process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
 
   beforeEach(() => {
     jest.restoreAllMocks()
@@ -627,6 +638,7 @@ describe('server dev managed process exits', () => {
     process.env.AUTO_SPAWN_SCHEDULER = 'false'
     process.env.AUTO_SPAWN_WORKERS = 'true'
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+    delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
   })
 
   afterEach(() => {
@@ -636,8 +648,10 @@ describe('server dev managed process exits', () => {
     jest.dontMock('../lib/generators')
     jest.dontMock('../lib/resolver')
     jest.dontMock('../lib/queue-worker-supervisor')
+    jest.dontMock('../lib/scheduler-supervisor')
     jest.resetModules()
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+    delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
   })
 
   afterAll(() => {
@@ -645,6 +659,8 @@ describe('server dev managed process exits', () => {
     process.env.AUTO_SPAWN_WORKERS = originalAutoSpawnWorkers
     if (originalLazy === undefined) delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
     else process.env.OM_AUTO_SPAWN_WORKERS_LAZY = originalLazy
+    if (originalLazyScheduler === undefined) delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
+    else process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY = originalLazyScheduler
   })
 
   it('skips scheduler auto-start when the module is not enabled', async () => {
@@ -801,12 +817,79 @@ describe('server dev managed process exits', () => {
     consoleErrorSpy.mockRestore()
     consoleLogSpy.mockRestore()
   })
+
+  it('starts the lazy scheduler supervisor instead of the scheduler process when OM_AUTO_SPAWN_SCHEDULER_LAZY=true', 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'
+    process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY = 'true'
+
+    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: () => ({}),
+    }))
+
+    const schedulerClose = jest.fn().mockResolvedValue(undefined)
+    const startLazySchedulerSupervisor = jest.fn(() => ({
+      started: false,
+      getActiveChild: () => undefined,
+      close: schedulerClose,
+      done: Promise.resolve(),
+    }))
+    jest.doMock('../lib/scheduler-supervisor', () => ({
+      startLazySchedulerSupervisor,
+    }))
+
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        args[0]?.includes('next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const mercado = await import('../mercato')
+    mercado.registerCliModules([schedulerCliFixture as Module])
+
+    const exitCode = await mercado.run(['node', 'mercato', 'server', 'dev'])
+
+    expect(exitCode).toBe(0)
+    expect(startLazySchedulerSupervisor).toHaveBeenCalledTimes(1)
+    const supervisorCall = startLazySchedulerSupervisor.mock.calls[0][0]
+    expect(supervisorCall.pollMs).toBe(1000)
+    expect(supervisorCall.restartOnUnexpectedExit).toBe(true)
+    expect(schedulerClose).toHaveBeenCalled()
+
+    const { spawn } = await import('child_process')
+    const allSpawnCalls = (spawn as jest.Mock).mock.calls.map((call) => call[1] as string[])
+    const schedulerSpawn = allSpawnCalls.find((args) => args.slice(1).join(' ') === 'scheduler start')
+    expect(schedulerSpawn).toBeUndefined()
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
 })
 
 describe('server start managed process exits', () => {
   const originalAutoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER
   const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
   const originalLazy = process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+  const originalLazyScheduler = process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
 
   beforeEach(() => {
     jest.restoreAllMocks()
@@ -814,6 +897,7 @@ describe('server start managed process exits', () => {
     process.env.AUTO_SPAWN_SCHEDULER = 'false'
     process.env.AUTO_SPAWN_WORKERS = 'true'
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+    delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
   })
 
   afterEach(() => {
@@ -822,8 +906,10 @@ describe('server start managed process exits', () => {
     jest.dontMock('../lib/resolver')
     jest.dontMock('../lib/server-start-lock')
     jest.dontMock('../lib/queue-worker-supervisor')
+    jest.dontMock('../lib/scheduler-supervisor')
     jest.resetModules()
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+    delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
   })
 
   afterAll(() => {
@@ -831,6 +917,8 @@ describe('server start managed process exits', () => {
     process.env.AUTO_SPAWN_WORKERS = originalAutoSpawnWorkers
     if (originalLazy === undefined) delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
     else process.env.OM_AUTO_SPAWN_WORKERS_LAZY = originalLazy
+    if (originalLazyScheduler === undefined) delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
+    else process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY = originalLazyScheduler
   })
 
   it('skips scheduler auto-start when the module is not enabled', async () => {

package/src/lib/__tests__/auto-spawn-scheduler.test.ts

@@ -0,0 +1,63 @@
+import {
+  resolveAutoSpawnSchedulerEnabled,
+  resolveAutoSpawnSchedulerLazy,
+  resolveAutoSpawnSchedulerMode,
+  resolveLazySchedulerPollMs,
+  resolveLazySchedulerRestart,
+} from '../auto-spawn-scheduler'
+
+describe('auto scheduler spawn env resolution', () => {
+  it('defaults to eager scheduler auto-spawn', () => {
+    expect(resolveAutoSpawnSchedulerMode({})).toBe('eager')
+    expect(resolveAutoSpawnSchedulerEnabled({})).toBe(true)
+    expect(resolveAutoSpawnSchedulerLazy({})).toBe(false)
+  })
+
+  it('returns off when AUTO_SPAWN_SCHEDULER=false', () => {
+    expect(resolveAutoSpawnSchedulerMode({ AUTO_SPAWN_SCHEDULER: 'false' })).toBe('off')
+  })
+
+  it('returns off when OM_AUTO_SPAWN_SCHEDULER=false and legacy unset', () => {
+    expect(resolveAutoSpawnSchedulerMode({ OM_AUTO_SPAWN_SCHEDULER: 'false' })).toBe('off')
+  })
+
+  it('legacy AUTO_SPAWN_SCHEDULER=true wins over OM_AUTO_SPAWN_SCHEDULER=false', () => {
+    expect(resolveAutoSpawnSchedulerMode({
+      AUTO_SPAWN_SCHEDULER: 'true',
+      OM_AUTO_SPAWN_SCHEDULER: 'false',
+    })).toBe('eager')
+  })
+
+  it('returns lazy when scheduler is enabled and OM_AUTO_SPAWN_SCHEDULER_LAZY=true', () => {
+    expect(resolveAutoSpawnSchedulerMode({
+      AUTO_SPAWN_SCHEDULER: 'true',
+      OM_AUTO_SPAWN_SCHEDULER_LAZY: 'true',
+    })).toBe('lazy')
+  })
+
+  it('lazy is ignored when AUTO_SPAWN_SCHEDULER=false', () => {
+    expect(resolveAutoSpawnSchedulerMode({
+      AUTO_SPAWN_SCHEDULER: 'false',
+      OM_AUTO_SPAWN_SCHEDULER_LAZY: 'true',
+    })).toBe('off')
+  })
+
+  it('treats invalid AUTO_SPAWN_SCHEDULER values as default', () => {
+    expect(resolveAutoSpawnSchedulerMode({ AUTO_SPAWN_SCHEDULER: 'maybe' })).toBe('eager')
+  })
+
+  it('resolves and clamps the lazy scheduler poll interval', () => {
+    expect(resolveLazySchedulerPollMs({})).toBe(1000)
+    expect(resolveLazySchedulerPollMs({ OM_AUTO_SPAWN_SCHEDULER_LAZY_POLL_MS: '500' })).toBe(500)
+    expect(resolveLazySchedulerPollMs({ OM_AUTO_SPAWN_SCHEDULER_LAZY_POLL_MS: '50' })).toBe(250)
+    expect(resolveLazySchedulerPollMs({ OM_AUTO_SPAWN_SCHEDULER_LAZY_POLL_MS: 'abc' })).toBe(1000)
+    expect(resolveLazySchedulerPollMs({ OM_AUTO_SPAWN_SCHEDULER_LAZY_POLL_MS: '0' })).toBe(1000)
+  })
+
+  it('defaults lazy scheduler restart to enabled', () => {
+    expect(resolveLazySchedulerRestart({})).toBe(true)
+    expect(resolveLazySchedulerRestart({ OM_AUTO_SPAWN_SCHEDULER_LAZY_RESTART: 'false' })).toBe(false)
+    expect(resolveLazySchedulerRestart({ OM_AUTO_SPAWN_SCHEDULER_LAZY_RESTART: 'true' })).toBe(true)
+    expect(resolveLazySchedulerRestart({ OM_AUTO_SPAWN_SCHEDULER_LAZY_RESTART: 'maybe' })).toBe(true)
+  })
+})

package/src/lib/__tests__/scheduler-supervisor.test.ts

@@ -0,0 +1,199 @@
+import { EventEmitter } from 'node:events'
+import type { ChildProcess } from 'node:child_process'
+import {
+  startLazySchedulerSupervisor,
+  type LazySchedulerSupervisorProbeFn,
+  type LazySchedulerSupervisorSpawnFn,
+} from '../scheduler-supervisor'
+
+type FakeChild = ChildProcess & {
+  triggerExit: (code: number | null, signal?: NodeJS.Signals | null) => void
+}
+
+function createFakeChild(): FakeChild {
+  const child = new EventEmitter() as unknown as FakeChild
+  ;(child as any).stdout = null
+  ;(child as any).stderr = null
+  ;(child as any).pid = Math.floor(Math.random() * 100000) + 1
+  ;(child as any).killed = false
+  ;(child as any).exitCode = null
+  ;(child as any).signalCode = null
+  ;(child as any).kill = jest.fn((signal: NodeJS.Signals = 'SIGTERM') => {
+    if ((child as any).killed) return true
+    ;(child as any).killed = true
+    ;(child as any).signalCode = signal
+    process.nextTick(() => child.emit('exit', null, signal))
+    return true
+  })
+  child.triggerExit = (code, signal = null) => {
+    ;(child as any).exitCode = code
+    ;(child as any).signalCode = signal
+    child.emit('exit', code, signal)
+  }
+  return child
+}
+
+const silentLogger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() }
+
+async function flushAsync(times = 5): Promise<void> {
+  for (let i = 0; i < times; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve()
+  }
+}
+
+describe('startLazySchedulerSupervisor', () => {
+  it('does not spawn the scheduler while no enabled schedules exist', async () => {
+    const spawnFn = jest.fn() as unknown as jest.MockedFunction<LazySchedulerSupervisorSpawnFn>
+    const probeFn = jest.fn(async () => ({
+      enabledSchedules: 0,
+      dueSchedules: 0,
+      error: false,
+    })) as jest.MockedFunction<LazySchedulerSupervisorProbeFn>
+
+    const handle = startLazySchedulerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(probeFn).toHaveBeenCalled()
+    expect(spawnFn).not.toHaveBeenCalled()
+    expect(handle.started).toBe(false)
+
+    await handle.close()
+  })
+
+  it('spawns the existing scheduler command after an enabled schedule appears', async () => {
+    const child = createFakeChild()
+    const spawnFn = jest.fn(() => child) as unknown as jest.MockedFunction<LazySchedulerSupervisorSpawnFn>
+    const probeFn = jest.fn(async () => ({
+      enabledSchedules: 1,
+      dueSchedules: 0,
+      error: false,
+    })) as jest.MockedFunction<LazySchedulerSupervisorProbeFn>
+
+    const handle = startLazySchedulerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      pollMs: 250,
+      restartOnUnexpectedExit: false,
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+    const [command, args] = spawnFn.mock.calls[0]
+    expect(command).toBe('node')
+    expect(args).toEqual(['/tmp/mercato', 'scheduler', 'start'])
+    expect(handle.started).toBe(true)
+
+    await flushAsync(20)
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    await handle.close()
+  })
+
+  it('does not spawn when the probe reports an error', async () => {
+    const spawnFn = jest.fn() as unknown as jest.MockedFunction<LazySchedulerSupervisorSpawnFn>
+    const probeFn = jest.fn(async () => ({
+      enabledSchedules: 0,
+      dueSchedules: 0,
+      error: true,
+      errorMessage: 'database unavailable',
+    })) as jest.MockedFunction<LazySchedulerSupervisorProbeFn>
+
+    const handle = startLazySchedulerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(spawnFn).not.toHaveBeenCalled()
+
+    await handle.close()
+  })
+
+  it('terminates the scheduler child on close()', async () => {
+    const child = createFakeChild()
+    const spawnFn = jest.fn(() => child) as unknown as jest.MockedFunction<LazySchedulerSupervisorSpawnFn>
+    const probeFn = jest.fn(async () => ({
+      enabledSchedules: 1,
+      dueSchedules: 1,
+      error: false,
+    })) as jest.MockedFunction<LazySchedulerSupervisorProbeFn>
+
+    const handle = startLazySchedulerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    await handle.close()
+
+    expect((child as any).kill).toHaveBeenCalledWith('SIGTERM')
+  })
+
+  it('restarts an unexpectedly exited scheduler only while schedules still exist', async () => {
+    const firstChild = createFakeChild()
+    const secondChild = createFakeChild()
+    const spawnFn = jest
+      .fn()
+      .mockImplementationOnce(() => firstChild)
+      .mockImplementationOnce(() => secondChild) as unknown as jest.MockedFunction<LazySchedulerSupervisorSpawnFn>
+
+    let enabledSchedules = 1
+    const probeFn = jest.fn(async () => ({
+      enabledSchedules,
+      dueSchedules: enabledSchedules,
+      error: false,
+    })) as jest.MockedFunction<LazySchedulerSupervisorProbeFn>
+
+    const handle = startLazySchedulerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    firstChild.triggerExit(1, null)
+    await flushAsync(40)
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+
+    enabledSchedules = 0
+    secondChild.triggerExit(1, null)
+    await flushAsync(40)
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+
+    await handle.close()
+  })
+})

package/src/lib/auto-spawn-scheduler.ts

@@ -0,0 +1,39 @@
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+
+export type AutoSpawnSchedulerMode = 'off' | 'eager' | 'lazy'
+
+export type AutoSpawnSchedulerEnvSource = Pick<NodeJS.ProcessEnv, string> | Record<string, string | undefined>
+
+const DEFAULT_LAZY_SCHEDULER_POLL_MS = 1000
+const MIN_LAZY_SCHEDULER_POLL_MS = 250
+
+export function resolveAutoSpawnSchedulerEnabled(env: AutoSpawnSchedulerEnvSource = process.env): boolean {
+  const legacy = parseBooleanToken(env.AUTO_SPAWN_SCHEDULER)
+  if (legacy !== null) return legacy
+  const aliased = parseBooleanToken(env.OM_AUTO_SPAWN_SCHEDULER)
+  if (aliased !== null) return aliased
+  return true
+}
+
+export function resolveAutoSpawnSchedulerLazy(env: AutoSpawnSchedulerEnvSource = process.env): boolean {
+  return parseBooleanToken(env.OM_AUTO_SPAWN_SCHEDULER_LAZY) === true
+}
+
+export function resolveAutoSpawnSchedulerMode(env: AutoSpawnSchedulerEnvSource = process.env): AutoSpawnSchedulerMode {
+  if (!resolveAutoSpawnSchedulerEnabled(env)) return 'off'
+  if (resolveAutoSpawnSchedulerLazy(env)) return 'lazy'
+  return 'eager'
+}
+
+export function resolveLazySchedulerPollMs(env: AutoSpawnSchedulerEnvSource = process.env): number {
+  const raw = env.OM_AUTO_SPAWN_SCHEDULER_LAZY_POLL_MS
+  if (typeof raw !== 'string' || raw.trim() === '') return DEFAULT_LAZY_SCHEDULER_POLL_MS
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_LAZY_SCHEDULER_POLL_MS
+  return Math.max(MIN_LAZY_SCHEDULER_POLL_MS, Math.floor(parsed))
+}
+
+export function resolveLazySchedulerRestart(env: AutoSpawnSchedulerEnvSource = process.env): boolean {
+  const parsed = parseBooleanToken(env.OM_AUTO_SPAWN_SCHEDULER_LAZY_RESTART)
+  return parsed === null ? true : parsed
+}