@open-mercato/cli 0.7.1-develop.7185.1.0f280ef1f1 → 0.7.1-develop.7191.1.3c9346566b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.7.1-develop.7185.1.0f280ef1f1",
+  "version": "0.7.1-develop.7191.1.3c9346566b",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,9 @@
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/migrations": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/queue": "0.7.1-develop.7185.1.0f280ef1f1",
-    "@open-mercato/shared": "0.7.1-develop.7185.1.0f280ef1f1",
-    "@open-mercato/telemetry": "0.7.1-develop.7185.1.0f280ef1f1",
+    "@open-mercato/queue": "0.7.1-develop.7191.1.3c9346566b",
+    "@open-mercato/shared": "0.7.1-develop.7191.1.3c9346566b",
+    "@open-mercato/telemetry": "0.7.1-develop.7191.1.3c9346566b",
     "cross-spawn": "^7.0.6",
     "pg": "8.23.0",
     "semver": "^7.8.5",
@@ -73,10 +73,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.7.1-develop.7185.1.0f280ef1f1"
+    "@open-mercato/shared": "0.7.1-develop.7191.1.3c9346566b"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.7.1-develop.7185.1.0f280ef1f1",
+    "@open-mercato/shared": "0.7.1-develop.7191.1.3c9346566b",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"

package/src/__tests__/module-runtimes.test.ts

@@ -0,0 +1,267 @@
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { ModuleRuntime } from '@open-mercato/shared/modules/runtime'
+import {
+  isProductionBuildPhase,
+  startModuleRuntimes,
+  type ModuleRuntimeCarrier,
+} from '../lib/module-runtimes'
+
+const container = {} as AppContainer
+const silent = () => {}
+
+function moduleWith(id: string, runtime: ModuleRuntime): ModuleRuntimeCarrier {
+  return { id, runtime }
+}
+
+describe('startModuleRuntimes', () => {
+  it('starts only the modules that declare a runtime', async () => {
+    const start = jest.fn().mockResolvedValue(undefined)
+    const started = await startModuleRuntimes({
+      modules: [{ id: 'no_runtime' }, moduleWith('has_runtime', { start })],
+      container,
+      role: 'worker',
+      log: silent,
+    })
+
+    expect(start).toHaveBeenCalledTimes(1)
+    expect(started.started).toEqual(['has_runtime'])
+  })
+
+  it('starts in module id order, so a failure is reproducible', async () => {
+    const order: string[] = []
+    const record = (id: string): ModuleRuntime => ({ start: async () => { order.push(id) } })
+
+    await startModuleRuntimes({
+      modules: [moduleWith('zulu', record('zulu')), moduleWith('alpha', record('alpha')), moduleWith('mike', record('mike'))],
+      container,
+      role: 'worker',
+      log: silent,
+    })
+
+    expect(order).toEqual(['alpha', 'mike', 'zulu'])
+  })
+
+  it('defaults to the worker role — the only one wired — and honours a declared role set', async () => {
+    const byDefault = jest.fn().mockResolvedValue(undefined)
+    const serverOnly = jest.fn().mockResolvedValue(undefined)
+    const modules = [
+      moduleWith('default_roles', { start: byDefault }),
+      moduleWith('server_only', { roles: ['server'], start: serverOnly }),
+    ]
+
+    await startModuleRuntimes({ modules, container, role: 'worker', log: silent })
+    expect(byDefault).toHaveBeenCalledTimes(1)
+    expect(serverOnly).not.toHaveBeenCalled()
+
+    await startModuleRuntimes({ modules, container, role: 'scheduler', log: silent })
+    // Neither applies: 'scheduler' is in neither the default set nor the declared one.
+    expect(byDefault).toHaveBeenCalledTimes(1)
+    expect(serverOnly).not.toHaveBeenCalled()
+
+    // A role a module names explicitly still applies, so widening the default later is additive.
+    await startModuleRuntimes({ modules, container, role: 'server', log: silent })
+    expect(byDefault).toHaveBeenCalledTimes(1)
+    expect(serverOnly).toHaveBeenCalledTimes(1)
+  })
+
+  it('fails startup when a runtime throws, and stops the ones already started', async () => {
+    const stop = jest.fn().mockResolvedValue(undefined)
+    const modules = [
+      moduleWith('a_ok', { start: async () => ({ stop }) }),
+      moduleWith('b_broken', { start: async () => { throw new Error('no broker') } }),
+    ]
+
+    await expect(startModuleRuntimes({ modules, container, role: 'worker', log: silent }))
+      .rejects.toThrow('no broker')
+
+    // The whole point: a half-started process must not be left running. A module that came up
+    // before the failure holds a lease or a subscription, and nothing else will release it.
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('fails startup when a runtime throws synchronously, and stops the ones already started', async () => {
+    const stop = jest.fn().mockResolvedValue(undefined)
+    const modules = [
+      moduleWith('a_ok', { start: async () => ({ stop }) }),
+      moduleWith('b_broken', { start: (() => { throw new Error('bad config') }) as ModuleRuntime['start'] }),
+    ]
+
+    await expect(startModuleRuntimes({ modules, container, role: 'worker', log: silent }))
+      .rejects.toThrow('bad config')
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('fails startup when a runtime does not start within the timeout', async () => {
+    const modules = [moduleWith('slow', { start: () => new Promise<never>(() => {}) })]
+
+    await expect(startModuleRuntimes({ modules, container, role: 'worker', log: silent, startTimeoutMs: 10 }))
+      .rejects.toThrow(/did not start within 10ms/)
+  })
+
+  // A start timeout is fatal, so an operator whose runtime legitimately needs longer than the
+  // default needs a supported way to say so rather than a worker that exits non-zero every boot.
+  it('takes both timeouts from the environment', async () => {
+    const modules = [moduleWith('slow', { start: () => new Promise<never>(() => {}) })]
+
+    await expect(startModuleRuntimes({
+      modules,
+      container,
+      role: 'worker',
+      log: silent,
+      env: { OM_MODULE_RUNTIME_START_TIMEOUT_MS: '7' },
+    })).rejects.toThrow(/did not start within 7ms/)
+
+    const stopped = jest.fn().mockResolvedValue(undefined)
+    const started = await startModuleRuntimes({
+      modules: [
+        moduleWith('a_first', { start: async () => ({ stop: stopped }) }),
+        moduleWith('b_hangs', { start: async () => ({ stop: () => new Promise<never>(() => {}) }) }),
+      ],
+      container,
+      role: 'worker',
+      log: silent,
+      env: { OM_MODULE_RUNTIME_STOP_TIMEOUT_MS: '10' },
+    })
+
+    await expect(started.stop()).resolves.toBeUndefined()
+    expect(stopped).toHaveBeenCalledTimes(1)
+  })
+
+  it('prefers an explicit timeout over the environment', async () => {
+    const modules = [moduleWith('slow', { start: () => new Promise<never>(() => {}) })]
+
+    await expect(startModuleRuntimes({
+      modules,
+      container,
+      role: 'worker',
+      log: silent,
+      startTimeoutMs: 5,
+      env: { OM_MODULE_RUNTIME_START_TIMEOUT_MS: '600000' },
+    })).rejects.toThrow(/did not start within 5ms/)
+  })
+
+  // Refusing to boot over a typo in a tuning knob would be worse than the default it replaces.
+  it('falls back to the default timeout, loudly, when the environment value is unusable', async () => {
+    const lines: string[] = []
+    const modules = [moduleWith('ok', { start: async () => undefined })]
+
+    await startModuleRuntimes({
+      modules,
+      container,
+      role: 'worker',
+      log: (message) => lines.push(message),
+      env: { OM_MODULE_RUNTIME_START_TIMEOUT_MS: 'soon', OM_MODULE_RUNTIME_STOP_TIMEOUT_MS: '-1' },
+    })
+
+    expect(lines).toEqual(expect.arrayContaining([
+      expect.stringContaining('ignoring OM_MODULE_RUNTIME_START_TIMEOUT_MS="soon"'),
+      expect.stringContaining('ignoring OM_MODULE_RUNTIME_STOP_TIMEOUT_MS="-1"'),
+    ]))
+  })
+
+  // The handle from a timed-out start never reaches `started`, so shutdown cannot reach it either.
+  // Without trailing the promise, a runtime that ignores `signal` keeps whatever it acquired.
+  it('releases the handle of a start that resolves after its timeout', async () => {
+    const stop = jest.fn().mockResolvedValue(undefined)
+    let resolveStart: (handle: { stop: () => Promise<void> }) => void = () => {}
+    const modules = [moduleWith('late', {
+      start: () => new Promise((resolve) => { resolveStart = resolve }),
+    })]
+
+    await expect(startModuleRuntimes({ modules, container, role: 'worker', log: silent, startTimeoutMs: 10 }))
+      .rejects.toThrow(/did not start within 10ms/)
+
+    resolveStart({ stop })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops runtimes in reverse start order', async () => {
+    const order: string[] = []
+    const runtime = (id: string): ModuleRuntime => ({
+      start: async () => ({ stop: async () => { order.push(id) } }),
+    })
+
+    const started = await startModuleRuntimes({
+      modules: [moduleWith('alpha', runtime('alpha')), moduleWith('bravo', runtime('bravo'))],
+      container,
+      role: 'worker',
+      log: silent,
+    })
+    await started.stop()
+
+    expect(order).toEqual(['bravo', 'alpha'])
+  })
+
+  it('aborts the shared signal before stopping, so a runtime can wind down at its own boundary', async () => {
+    let abortedDuringStop: boolean | null = null
+    const started = await startModuleRuntimes({
+      modules: [moduleWith('watcher', {
+        start: async ({ signal }) => ({ stop: async () => { abortedDuringStop = signal.aborted } }),
+      })],
+      container,
+      role: 'worker',
+      log: silent,
+    })
+
+    await started.stop()
+    expect(abortedDuringStop).toBe(true)
+  })
+
+  it('keeps going when one runtime fails to stop, and does not hang on one that never does', async () => {
+    const lastStopped = jest.fn().mockResolvedValue(undefined)
+    const started = await startModuleRuntimes({
+      modules: [
+        moduleWith('a_first', { start: async () => ({ stop: lastStopped }) }),
+        moduleWith('b_throws', { start: async () => ({ stop: async () => { throw new Error('rude') } }) }),
+        moduleWith('c_hangs', { start: async () => ({ stop: () => new Promise<never>(() => {}) }) }),
+      ],
+      container,
+      role: 'worker',
+      log: silent,
+      stopTimeoutMs: 10,
+    })
+
+    // Resolves rather than rejecting or hanging: shutdown is best-effort by design, because a
+    // shutdown that cannot finish would otherwise become one that never finishes.
+    await expect(started.stop()).resolves.toBeUndefined()
+    expect(lastStopped).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops only once however many times stop is called', async () => {
+    const stop = jest.fn().mockResolvedValue(undefined)
+    const started = await startModuleRuntimes({
+      modules: [moduleWith('once', { start: async () => ({ stop }) })],
+      container,
+      role: 'worker',
+      log: silent,
+    })
+
+    await Promise.all([started.stop(), started.stop(), started.stop()])
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('tolerates a runtime that returns no handle', async () => {
+    const started = await startModuleRuntimes({
+      modules: [moduleWith('fire_and_forget', { start: async () => undefined })],
+      container,
+      role: 'worker',
+      log: silent,
+    })
+
+    await expect(started.stop()).resolves.toBeUndefined()
+  })
+})
+
+describe('isProductionBuildPhase', () => {
+  it('detects a Next production build', () => {
+    expect(isProductionBuildPhase({ NEXT_PHASE: 'phase-production-build' } as NodeJS.ProcessEnv)).toBe(true)
+  })
+
+  it('is false for a server, a worker and an unset environment', () => {
+    expect(isProductionBuildPhase({ NEXT_PHASE: 'phase-production-server' } as NodeJS.ProcessEnv)).toBe(false)
+    expect(isProductionBuildPhase({} as NodeJS.ProcessEnv)).toBe(false)
+  })
+})

package/src/lib/__tests__/generate-watch-structure.test.ts

@@ -78,6 +78,24 @@ describe('calculateGenerateWatchStructureChecksum', () => {
     expect(currentChecksum()).not.toBe(before)
   })
 
+  // A runtime.ts the watcher cannot see is the failure SPEC-072 exists to remove, reappearing in
+  // the dev loop: the registry is not regenerated, `Module.runtime` stays undefined, and the
+  // runtime never starts — with no error and no warning.
+  it('changes when a module runtime is added, edited and removed', () => {
+    const before = currentChecksum()
+    const runtimePath = path.join(pkgModule, 'runtime.ts')
+
+    write(runtimePath, 'export const runtime = { start: async () => {} }\n')
+    const afterAdd = currentChecksum()
+    expect(afterAdd).not.toBe(before)
+
+    write(runtimePath, 'export const runtime = { roles: ["worker"], start: async () => {} }\n')
+    expect(currentChecksum()).not.toBe(afterAdd)
+
+    fs.rmSync(runtimePath)
+    expect(currentChecksum()).toBe(before)
+  })
+
   it('changes when a discovered worker is added and removed', () => {
     const before = currentChecksum()
     const workerPath = path.join(pkgModule, 'workers', 'sync-customers.ts')

package/src/lib/generate-watch-structure.ts

@@ -15,6 +15,7 @@ const STRUCTURAL_CONVENTION_FILES = [
   'di.ts',
   'acl.ts',
   'setup.ts',
+  'runtime.ts',
   'encryption.ts',
   'ce.ts',
   'search.ts',

package/src/lib/generators/__tests__/registry-variant-parity.test.ts

@@ -17,7 +17,7 @@ import path from 'node:path'
 import os from 'node:os'
 import ts from 'typescript-js'
 import type { PackageResolver, ModuleEntry } from '../../resolver'
-import { generateModuleRegistry, generateModuleRegistryApp } from '../module-registry'
+import { generateModuleRegistry, generateModuleRegistryApp, generateModuleRegistryCli } from '../module-registry'
 
 /** Properties both registry variants must agree on, per module. */
 const SHARED_PROPERTIES = [
@@ -33,6 +33,7 @@ const SHARED_PROPERTIES = [
   'features',
   'customEntities',
   'setup',
+  'runtime',
   'defaultEncryptionMaps',
   'integrations',
   'bundles',
@@ -102,6 +103,10 @@ function scaffoldFixture(): ModuleEntry[] {
   )
   touchFile(pkgModulePath('orders', 'acl.ts'), "export const features = ['orders.view', 'orders.create']\n")
   touchFile(pkgModulePath('orders', 'setup.ts'), "export const setup = { defaultRoleFeatures: ['orders.view'] }\n")
+  touchFile(
+    pkgModulePath('orders', 'runtime.ts'),
+    "export const runtime = { roles: ['worker'], start: async () => ({ stop: async () => {} }) }\n",
+  )
   touchFile(
     pkgModulePath('orders', 'encryption.ts'),
     "export const defaultEncryptionMaps = [{ entityId: 'orders:sales_order', fields: [{ field: 'customer_email' }] }]\nexport default defaultEncryptionMaps\n",
@@ -190,8 +195,10 @@ describe('module registry variant parity', () => {
     const resolver = createMockResolver(scaffoldFixture())
     const mainResult = await generateModuleRegistry({ resolver, quiet: true })
     const appResult = await generateModuleRegistryApp({ resolver, quiet: true })
+    const cliResult = await generateModuleRegistryCli({ resolver, quiet: true })
     expect(mainResult.errors).toEqual([])
     expect(appResult.errors).toEqual([])
+    expect(cliResult.errors).toEqual([])
 
     mainVariant = parseModulePropertiesById(readGenerated('modules.generated.ts'), 'modules.generated.ts')
     runtimeVariant = parseModulePropertiesById(
@@ -236,6 +243,26 @@ describe('module registry variant parity', () => {
     expect(restrictTo(mainVariant.get('bare')!, SHARED_PROPERTIES)).toEqual(['customFieldSets', 'id', 'info'])
   })
 
+  // The worker wiring reads `getCliModules()` — modules.cli.generated.ts — while the web tier
+  // reads the app and bootstrap registries. A convention file that reaches only some of them is a
+  // runtime that starts in some processes and not others, with nothing to say so.
+  it('emits the module runtime in every registry a process can read', () => {
+    const registryFiles = [
+      'modules.generated.ts',
+      'modules.runtime.generated.ts',
+      'modules.app.generated.ts',
+      'modules.bootstrap.generated.ts',
+      'modules.cli.generated.ts',
+    ]
+
+    const carriesRuntime = registryFiles.map((fileName) => {
+      const byId = parseModulePropertiesById(readGenerated(fileName), fileName)
+      return [fileName, byId.get('orders')?.has('runtime'), byId.get('bare')?.has('runtime')]
+    })
+
+    expect(carriesRuntime).toEqual(registryFiles.map((fileName) => [fileName, true, false]))
+  })
+
   describe('known, intentional divergences', () => {
     it('only the main variant carries eager api handlers and the cli entry point', () => {
       expect(mainVariant.get('orders')!.has('apis')).toBe(true)

package/src/lib/generators/module-registry.ts

@@ -2705,6 +2705,13 @@ function buildLegacyModuleSetupValue(importName: string): WriterFunction {
   ])
 }
 
+function buildLegacyModuleRuntimeValue(importName: string): WriterFunction {
+  return logicalOr([
+    legacyNamespaceMemberFallback(importName, ['default', 'runtime']),
+    identifier('undefined'),
+  ])
+}
+
 function buildLegacyIntegrationListValue(
   importName: string,
   pluralMember: string,
@@ -3637,6 +3644,7 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     let customFieldSetsExpr: string = '[]'
     const dashboardWidgets: string[] = []
     let setupImportName: string | null = null
+    let moduleRuntimeImportName: string | null = null
     let encryptionImportName: string | null = null
     let integrationImportName: string | null = null
 
@@ -3772,6 +3780,12 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
       }
     }
 
+    // 11c. Module runtime: runtime.ts (SPEC-072)
+    {
+      const moduleRuntime = resolveConventionFile(discovered.resolve('runtime.ts'), 'RUNTIME', modId, importIdRef, imports, runtimeImports)
+      if (moduleRuntime) moduleRuntimeImportName = moduleRuntime.importName
+    }
+
     // 12. Custom fields: data/fields.ts
     {
       const fields = resolveConventionFile(discovered.resolve('data/fields.ts'), 'F', modId, importIdRef, imports, runtimeImports)
@@ -3931,6 +3945,9 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     if (setupImportName) {
       setupAndBeyondEntries.push({ name: 'setup', value: buildLegacyModuleSetupValue(setupImportName) })
     }
+    if (moduleRuntimeImportName) {
+      setupAndBeyondEntries.push({ name: 'runtime', value: buildLegacyModuleRuntimeValue(moduleRuntimeImportName) })
+    }
     if (encryptionImportName) {
       setupAndBeyondEntries.push({
         name: 'defaultEncryptionMaps',
@@ -4328,6 +4345,7 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
     let customEntitiesImportName: string | null = null
     let dashboardWidgetsValue: WriterFunction = emptyArray()
     let setupImportName: string | null = null
+    let moduleRuntimeImportName: string | null = null
     let encryptionImportName: string | null = null
     let integrationImportName: string | null = null
 
@@ -4352,6 +4370,13 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
       if (setup) setupImportName = setup.importName
     }
 
+    // Module runtime: runtime.ts (SPEC-072)
+    {
+      const moduleRuntime = resolveConventionFile(discovered.resolve('runtime.ts'), 'RUNTIME', modId, importIdRef, imports)
+      if (moduleRuntime) bootstrapImports.push(buildImportStatement(`* as ${moduleRuntime.importName}`, moduleRuntime.importPath))
+      if (moduleRuntime) moduleRuntimeImportName = moduleRuntime.importName
+    }
+
     {
       const encryption = resolveConventionFile(discovered.resolve('encryption.ts'), 'ENCRYPTION', modId, importIdRef, imports)
       if (encryption) bootstrapImports.push(buildImportStatement(`* as ${encryption.importName}`, encryption.importPath))
@@ -4543,6 +4568,16 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
         }),
       })
     }
+    if (moduleRuntimeImportName) {
+      moduleEntries.push({
+        name: 'runtime',
+        value: namespaceFallback({
+          importName: moduleRuntimeImportName,
+          members: ['default', 'runtime'],
+          fallback: identifier('undefined'),
+        }),
+      })
+    }
     if (encryptionImportName) {
       moduleEntries.push({
         name: 'defaultEncryptionMaps',
@@ -4744,6 +4779,7 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
     let vectorImportName: string | null = null
     let dashboardWidgetsValue: WriterFunction = emptyArray()
     let setupImportName: string | null = null
+    let moduleRuntimeImportName: string | null = null
     let encryptionImportName: string | null = null
     let integrationImportName: string | null = null
 
@@ -4768,6 +4804,12 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
       if (setup) setupImportName = setup.importName
     }
 
+    // Module runtime: runtime.ts (SPEC-072)
+    {
+      const moduleRuntime = resolveConventionFile(discovered.resolve('runtime.ts'), 'RUNTIME', modId, importIdRef, imports)
+      if (moduleRuntime) moduleRuntimeImportName = moduleRuntime.importName
+    }
+
     // Module encryption defaults: encryption.ts
     {
       const encryption = resolveConventionFile(discovered.resolve('encryption.ts'), 'ENCRYPTION', modId, importIdRef, imports)
@@ -4937,6 +4979,16 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
         }),
       })
     }
+    if (moduleRuntimeImportName) {
+      moduleEntries.push({
+        name: 'runtime',
+        value: namespaceFallback({
+          importName: moduleRuntimeImportName,
+          members: ['default', 'runtime'],
+          fallback: identifier('undefined'),
+        }),
+      })
+    }
     if (encryptionImportName) {
       moduleEntries.push({
         name: 'defaultEncryptionMaps',