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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.3-develop.3876.1.d40fe4ec2d",
+  "version": "0.6.3-develop.3894.1.352abf4240",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.1.1",
     "@mikro-orm/migrations": "^7.1.1",
     "@mikro-orm/postgresql": "^7.1.1",
-    "@open-mercato/queue": "0.6.3-develop.3876.1.d40fe4ec2d",
-    "@open-mercato/shared": "0.6.3-develop.3876.1.d40fe4ec2d",
+    "@open-mercato/queue": "0.6.3-develop.3894.1.352abf4240",
+    "@open-mercato/shared": "0.6.3-develop.3894.1.352abf4240",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.1",
@@ -70,10 +70,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.3-develop.3876.1.d40fe4ec2d"
+    "@open-mercato/shared": "0.6.3-develop.3894.1.352abf4240"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.3-develop.3876.1.d40fe4ec2d",
+    "@open-mercato/shared": "0.6.3-develop.3894.1.352abf4240",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/__tests__/mercato.test.ts

@@ -632,6 +632,7 @@ describe('server dev managed process exits', () => {
   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
+  const originalGenerateWatchMode = process.env.OM_DEV_GENERATE_WATCH_MODE
 
   beforeEach(() => {
     jest.restoreAllMocks()
@@ -640,6 +641,12 @@ describe('server dev managed process exits', () => {
     process.env.AUTO_SPAWN_WORKERS = 'true'
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
     delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
+    // These tests stub the resolver to an empty object; the in-process
+    // generate watcher's default checksum function would error on the
+    // missing methods. Force the legacy out-of-process mode so the
+    // managed-exit assertions only exercise the worker/scheduler/Next
+    // spawn surface.
+    process.env.OM_DEV_GENERATE_WATCH_MODE = 'legacy'
   })
 
   afterEach(() => {
@@ -651,6 +658,8 @@ describe('server dev managed process exits', () => {
     jest.dontMock('../lib/queue-worker-supervisor')
     jest.dontMock('../lib/scheduler-supervisor')
     jest.resetModules()
+    if (originalGenerateWatchMode === undefined) delete process.env.OM_DEV_GENERATE_WATCH_MODE
+    else process.env.OM_DEV_GENERATE_WATCH_MODE = originalGenerateWatchMode
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
     delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
   })

package/src/lib/__tests__/in-process-generate-watcher-mode.test.ts

@@ -0,0 +1,20 @@
+import { resolveGenerateWatcherMode } from '../in-process-generate-watcher-mode'
+
+describe('resolveGenerateWatcherMode', () => {
+  it('defaults to in-process when the env var is unset', () => {
+    expect(resolveGenerateWatcherMode({})).toBe('in-process')
+  })
+
+  it('defaults to in-process for empty / whitespace / unknown values', () => {
+    expect(resolveGenerateWatcherMode({ OM_DEV_GENERATE_WATCH_MODE: '' })).toBe('in-process')
+    expect(resolveGenerateWatcherMode({ OM_DEV_GENERATE_WATCH_MODE: '   ' })).toBe('in-process')
+    expect(resolveGenerateWatcherMode({ OM_DEV_GENERATE_WATCH_MODE: 'maybe' })).toBe('in-process')
+  })
+
+  it.each(['legacy', 'LEGACY', 'sidecar', 'out-of-process', '  legacy  '])(
+    'returns legacy for opt-out alias %p',
+    (value) => {
+      expect(resolveGenerateWatcherMode({ OM_DEV_GENERATE_WATCH_MODE: value })).toBe('legacy')
+    },
+  )
+})

package/src/lib/__tests__/in-process-generate-watcher.test.ts

@@ -0,0 +1,191 @@
+import { startInProcessGenerateWatcher } from '../in-process-generate-watcher'
+
+const silentLogger = { log: 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('startInProcessGenerateWatcher', () => {
+  beforeEach(() => {
+    jest.useFakeTimers()
+    silentLogger.log.mockReset()
+    silentLogger.error.mockReset()
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  it('runs the generator once on startup when skipInitial is false', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => 'checksum-a')
+
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: false,
+      quiet: true,
+      logger: silentLogger,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+    expect(runGenerators.mock.calls[0][0]).toBe('initial')
+
+    await handle.close()
+    await handle.done
+  })
+
+  it('skips the initial run when skipInitial is true', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => 'checksum-b')
+
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+
+    expect(runGenerators).not.toHaveBeenCalled()
+    expect(computeStructureChecksum).toHaveBeenCalled()
+
+    await handle.close()
+    await handle.done
+  })
+
+  it('re-runs the generator when the checksum changes', async () => {
+    let currentChecksum = 'stable'
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => currentChecksum)
+
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    expect(runGenerators).not.toHaveBeenCalled()
+
+    // First tick: same checksum, no regeneration.
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    expect(runGenerators).not.toHaveBeenCalled()
+
+    // Second tick: checksum changed, generator must run with 'structure change'.
+    currentChecksum = 'changed'
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+    expect(runGenerators.mock.calls[0][0]).toBe('structure change')
+
+    await handle.close()
+    await handle.done
+  })
+
+  it('does not start a new poll while a regeneration is in flight', async () => {
+    let release: (() => void) | null = null
+    const runGenerators = jest.fn(async (_reason: string) => {
+      await new Promise<void>((resolve) => {
+        release = resolve
+      })
+    })
+    let currentChecksum = 'a'
+    const computeStructureChecksum = jest.fn(async () => currentChecksum)
+
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    // Establish baseline checksum, no run yet.
+    expect(runGenerators).not.toHaveBeenCalled()
+
+    // Tick #1: change checksum so a run starts and blocks.
+    currentChecksum = 'b'
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+
+    // Tick #2 and #3 must NOT spawn parallel runs while #1 is in flight —
+    // the helper serializes via the running/pending pair plus the
+    // single-shot finally-scheduled poll cycle.
+    currentChecksum = 'c'
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+
+    release?.()
+    await flushAsync(20)
+
+    await handle.close()
+    await handle.done
+  })
+
+  it('logs but does not crash when the generator throws', async () => {
+    const runGenerators = jest.fn(async () => {
+      throw new Error('boom')
+    })
+    const computeStructureChecksum = jest.fn(async () => 'k')
+
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: false,
+      quiet: true,
+      logger: silentLogger,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+    expect(silentLogger.error).toHaveBeenCalled()
+    const message = String(silentLogger.error.mock.calls[0][0] ?? '')
+    expect(message).toMatch(/Generation failed/)
+    expect(message).toMatch(/boom/)
+
+    await handle.close()
+    await handle.done
+  })
+
+  it('close() is idempotent and resolves done exactly once', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => 'k')
+
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    await handle.close()
+    await handle.close()
+    await handle.done
+    expect(true).toBe(true)
+  })
+})

package/src/lib/in-process-generate-watcher-mode.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolves the watcher-mode env flag that governs whether the dev runtime
+ * runs the generate watcher in-process (default) or as a legacy out-of-process
+ * `mercato generate watch --skip-initial` sidecar.
+ *
+ * `OM_DEV_GENERATE_WATCH_MODE=legacy` opts back into the pre-consolidation
+ * behavior (one extra long-running Node process). Any other value, missing
+ * value, or unparseable value resolves to `in-process`.
+ */
+
+export type GenerateWatcherMode = 'in-process' | 'legacy'
+
+export function resolveGenerateWatcherMode(env: NodeJS.ProcessEnv): GenerateWatcherMode {
+  const raw = env.OM_DEV_GENERATE_WATCH_MODE
+  if (typeof raw !== 'string') return 'in-process'
+  const normalized = raw.trim().toLowerCase()
+  if (normalized === 'legacy' || normalized === 'sidecar' || normalized === 'out-of-process') {
+    return 'legacy'
+  }
+  return 'in-process'
+}

package/src/lib/in-process-generate-watcher.ts

@@ -0,0 +1,175 @@
+/**
+ * In-process generate watcher.
+ *
+ * Polls a structural-fingerprint function on a configurable interval and
+ * invokes the supplied generator callback whenever the fingerprint changes.
+ * The polling loop is identical to the legacy standalone watcher; the only
+ * difference is that it now runs inside whatever process calls it
+ * (typically `mercato server dev`), so the dev runtime no longer needs a
+ * sidecar `mercato generate watch` Node process.
+ *
+ * Contract preserved 1:1 with the prior standalone watcher:
+ *   - Default poll interval 1000 ms (minimum 250 ms).
+ *   - One initial generator run unless `skipInitial` is true.
+ *   - Concurrent regeneration requests are coalesced (running + pending).
+ *   - Generator errors are logged but never crash the watcher.
+ *   - The polling timer uses `.unref()` so it never blocks process exit.
+ */
+
+export type GenerateWatcherLogger = Pick<Console, 'log' | 'error'>
+
+export type GenerateWatcherOptions = {
+  /**
+   * Function that returns the current structural fingerprint of the module
+   * tree. The watcher re-runs `runGenerators` whenever this value changes.
+   */
+  computeStructureChecksum: () => Promise<string> | string
+  /**
+   * Function that performs the actual regeneration work. Called once on
+   * startup (unless `skipInitial`) and again whenever the checksum changes.
+   * The `reason` argument is suitable for logging (`'initial'`,
+   * `'structure change'`, `'queued change'`).
+   */
+  runGenerators: (reason: string) => Promise<void>
+  /** Poll interval in milliseconds. Defaults to 1000. Clamped to >= 250. */
+  pollMs?: number
+  /** Skip the initial regeneration on startup. Defaults to false. */
+  skipInitial?: boolean
+  /** Suppress informational logs. Errors are always logged. */
+  quiet?: boolean
+  /** Logger override. Defaults to `console`. */
+  logger?: GenerateWatcherLogger
+}
+
+export type GenerateWatcherHandle = {
+  /** Resolves when the watcher loop has stopped (after `close()`). */
+  readonly done: Promise<void>
+  /** Stop the polling loop and resolve `done`. Idempotent. */
+  close(): Promise<void>
+}
+
+const MIN_POLL_MS = 250
+const DEFAULT_POLL_MS = 1000
+
+function resolvePollMs(value: number | undefined): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_POLL_MS
+  const numeric = Math.floor(value)
+  return numeric >= MIN_POLL_MS ? numeric : DEFAULT_POLL_MS
+}
+
+/**
+ * Start an in-process generate watcher. The returned handle exposes a
+ * `close()` to stop polling and a `done` promise that resolves once the
+ * watcher loop has finished.
+ */
+export function startInProcessGenerateWatcher(
+  options: GenerateWatcherOptions,
+): GenerateWatcherHandle {
+  const logger = options.logger ?? console
+  const quiet = options.quiet === true
+  const pollMs = resolvePollMs(options.pollMs)
+  const skipInitial = options.skipInitial === true
+  const { computeStructureChecksum, runGenerators } = options
+
+  let stopping = false
+  let pollTimer: ReturnType<typeof setTimeout> | null = null
+  let running = false
+  let pendingReason: string | null = null
+  let previousChecksum = ''
+  let doneResolve: (() => void) | null = null
+  const done = new Promise<void>((resolve) => {
+    doneResolve = resolve
+  })
+
+  async function runOnce(reason: string): Promise<void> {
+    if (running) {
+      pendingReason = reason
+      return
+    }
+    running = true
+    try {
+      if (!quiet) {
+        logger.log(`[generate:watch] Regenerating (${reason})...`)
+      }
+      await runGenerators(reason)
+      if (!quiet) {
+        logger.log('[generate:watch] Generators completed.')
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      logger.error(`[generate:watch] Generation failed: ${message}`)
+    } finally {
+      running = false
+      if (pendingReason && !stopping) {
+        const queued = pendingReason
+        pendingReason = null
+        await runOnce(queued)
+      }
+    }
+  }
+
+  function scheduleNext(): void {
+    if (stopping) return
+    pollTimer = setTimeout(() => {
+      void (async () => {
+        if (stopping) return
+        try {
+          const nextChecksum = await computeStructureChecksum()
+          if (nextChecksum !== previousChecksum) {
+            previousChecksum = nextChecksum
+            await runOnce('structure change')
+          }
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          logger.error(`[generate:watch] Poll cycle failed: ${message}`)
+        } finally {
+          if (!stopping) scheduleNext()
+        }
+      })()
+    }, pollMs)
+    pollTimer.unref?.()
+  }
+
+  void (async () => {
+    try {
+      if (!skipInitial) {
+        await runOnce('initial')
+      }
+      previousChecksum = await computeStructureChecksum()
+      if (!quiet) {
+        if (skipInitial) {
+          logger.log('[generate:watch] Skipping initial regeneration and watching the current generated state.')
+        }
+        logger.log(`[generate:watch] Watching structural module files every ${pollMs}ms (in-process).`)
+      }
+      scheduleNext()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      logger.error(`[generate:watch] Initial setup failed: ${message}`)
+      // Even if the initial bootstrap fails, schedule polling so a later
+      // checksum recovery still picks up the next change on disk.
+      scheduleNext()
+    }
+  })()
+
+  async function close(): Promise<void> {
+    if (stopping) {
+      await done
+      return
+    }
+    stopping = true
+    if (pollTimer) {
+      clearTimeout(pollTimer)
+      pollTimer = null
+    }
+    if (doneResolve) {
+      doneResolve()
+      doneResolve = null
+    }
+  }
+
+  return {
+    done,
+    close,
+  }
+}

package/src/lib/testing/integration.ts

@@ -1649,6 +1649,10 @@ function buildReusableEnvironment(
     OM_ENABLE_ENTERPRISE_MODULES_SECURITY: process.env.OM_ENABLE_ENTERPRISE_MODULES_SECURITY ?? enterpriseModulesFlag,
     OM_TEST_MODE: '1',
     OM_TEST_AUTH_RATE_LIMIT_MODE: 'opt-in',
+    // Tests assert on access_logs immediately after CRUD reads; keep the
+    // blocking write path on inside the integration runtime so tests do
+    // not have to call flushPendingCrudAccessLogs() explicitly.
+    OM_CRUD_ACCESS_LOG_BLOCKING: process.env.OM_CRUD_ACCESS_LOG_BLOCKING ?? '1',
     OM_WEBHOOKS_ALLOW_PRIVATE_URLS: process.env.OM_WEBHOOKS_ALLOW_PRIVATE_URLS ?? '1',
     ENABLE_CRUD_API_CACHE: 'true',
     MOCK_GATEWAY_WEBHOOK_SECRET: 'open-mercato-mock-dev-webhook-secret',
@@ -2936,7 +2940,7 @@ export async function startEphemeralEnvironment(options: EphemeralRuntimeOptions
       NEXT_PUBLIC_UMES_DEVTOOLS: 'true',
       CI: 'true',
       TENANT_DATA_ENCRYPTION_FALLBACK_KEY: process.env.TENANT_DATA_ENCRYPTION_FALLBACK_KEY ?? 'om-ephemeral-integration-fallback-key',
-      AUTO_SPAWN_WORKERS: 'false',
+      AUTO_SPAWN_WORKERS: process.env.AUTO_SPAWN_WORKERS ?? 'true',
       AUTO_SPAWN_SCHEDULER: 'false',
       OM_CLI_QUIET: '1',
       MERCATO_QUIET: '1',