@open-mercato/cli 0.6.1-develop.3167.1.7aedd7b2ba → 0.6.1-develop.3174.1.c3822bcdf0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
-[build:cli] found 66 entry points
+[build:cli] found 68 entry points
 Copied create-app/agentic/ → dist/agentic/
 Discovered 16 standalone guides → dist/agentic/guides/
 [build:cli] built successfully

package/dist/lib/auto-spawn-workers.js

@@ -0,0 +1,37 @@
+import { parseBooleanToken } from "@open-mercato/shared/lib/boolean";
+const DEFAULT_LAZY_POLL_MS = 1e3;
+const MIN_LAZY_POLL_MS = 250;
+function resolveAutoSpawnWorkersEnabled(env = process.env) {
+  const legacy = parseBooleanToken(env.AUTO_SPAWN_WORKERS);
+  if (legacy !== null) return legacy;
+  const aliased = parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS);
+  if (aliased !== null) return aliased;
+  return true;
+}
+function resolveAutoSpawnWorkersLazy(env = process.env) {
+  return parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS_LAZY) === true;
+}
+function resolveAutoSpawnWorkersMode(env = process.env) {
+  if (!resolveAutoSpawnWorkersEnabled(env)) return "off";
+  if (resolveAutoSpawnWorkersLazy(env)) return "lazy";
+  return "eager";
+}
+function resolveLazyPollMs(env = process.env) {
+  const raw = env.OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS;
+  if (typeof raw !== "string" || raw.trim() === "") return DEFAULT_LAZY_POLL_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_LAZY_POLL_MS;
+  return Math.max(MIN_LAZY_POLL_MS, Math.floor(parsed));
+}
+function resolveLazyRestart(env = process.env) {
+  const parsed = parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS_LAZY_RESTART);
+  return parsed === null ? true : parsed;
+}
+export {
+  resolveAutoSpawnWorkersEnabled,
+  resolveAutoSpawnWorkersLazy,
+  resolveAutoSpawnWorkersMode,
+  resolveLazyPollMs,
+  resolveLazyRestart
+};
+//# sourceMappingURL=auto-spawn-workers.js.map

package/dist/lib/auto-spawn-workers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/auto-spawn-workers.ts"],
+  "sourcesContent": ["import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'\n\nexport type AutoSpawnWorkersMode = 'off' | 'eager' | 'lazy'\n\nexport type AutoSpawnEnvSource = Pick<NodeJS.ProcessEnv, string> | Record<string, string | undefined>\n\nconst DEFAULT_LAZY_POLL_MS = 1000\nconst MIN_LAZY_POLL_MS = 250\n\nexport function resolveAutoSpawnWorkersEnabled(env: AutoSpawnEnvSource = process.env): boolean {\n  const legacy = parseBooleanToken(env.AUTO_SPAWN_WORKERS)\n  if (legacy !== null) return legacy\n  const aliased = parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS)\n  if (aliased !== null) return aliased\n  return true\n}\n\nexport function resolveAutoSpawnWorkersLazy(env: AutoSpawnEnvSource = process.env): boolean {\n  return parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS_LAZY) === true\n}\n\nexport function resolveAutoSpawnWorkersMode(env: AutoSpawnEnvSource = process.env): AutoSpawnWorkersMode {\n  if (!resolveAutoSpawnWorkersEnabled(env)) return 'off'\n  if (resolveAutoSpawnWorkersLazy(env)) return 'lazy'\n  return 'eager'\n}\n\nexport function resolveLazyPollMs(env: AutoSpawnEnvSource = process.env): number {\n  const raw = env.OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS\n  if (typeof raw !== 'string' || raw.trim() === '') return DEFAULT_LAZY_POLL_MS\n  const parsed = Number(raw)\n  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_LAZY_POLL_MS\n  return Math.max(MIN_LAZY_POLL_MS, Math.floor(parsed))\n}\n\nexport function resolveLazyRestart(env: AutoSpawnEnvSource = process.env): boolean {\n  const parsed = parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS_LAZY_RESTART)\n  return parsed === null ? true : parsed\n}\n"],
+  "mappings": "AAAA,SAAS,yBAAyB;AAMlC,MAAM,uBAAuB;AAC7B,MAAM,mBAAmB;AAElB,SAAS,+BAA+B,MAA0B,QAAQ,KAAc;AAC7F,QAAM,SAAS,kBAAkB,IAAI,kBAAkB;AACvD,MAAI,WAAW,KAAM,QAAO;AAC5B,QAAM,UAAU,kBAAkB,IAAI,qBAAqB;AAC3D,MAAI,YAAY,KAAM,QAAO;AAC7B,SAAO;AACT;AAEO,SAAS,4BAA4B,MAA0B,QAAQ,KAAc;AAC1F,SAAO,kBAAkB,IAAI,0BAA0B,MAAM;AAC/D;AAEO,SAAS,4BAA4B,MAA0B,QAAQ,KAA2B;AACvG,MAAI,CAAC,+BAA+B,GAAG,EAAG,QAAO;AACjD,MAAI,4BAA4B,GAAG,EAAG,QAAO;AAC7C,SAAO;AACT;AAEO,SAAS,kBAAkB,MAA0B,QAAQ,KAAa;AAC/E,QAAM,MAAM,IAAI;AAChB,MAAI,OAAO,QAAQ,YAAY,IAAI,KAAK,MAAM,GAAI,QAAO;AACzD,QAAM,SAAS,OAAO,GAAG;AACzB,MAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,EAAG,QAAO;AACpD,SAAO,KAAK,IAAI,kBAAkB,KAAK,MAAM,MAAM,CAAC;AACtD;AAEO,SAAS,mBAAmB,MAA0B,QAAQ,KAAc;AACjF,QAAM,SAAS,kBAAkB,IAAI,kCAAkC;AACvE,SAAO,WAAW,OAAO,OAAO;AAClC;",
+  "names": []
+}

package/dist/lib/queue-worker-supervisor.js

@@ -0,0 +1,222 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import {
+  getQueuePendingProbe
+} from "@open-mercato/queue";
+function groupWorkersByQueue(workers) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const worker of workers) {
+    const existing = groups.get(worker.queue);
+    if (existing) {
+      existing.workerCount += 1;
+      if (worker.concurrency > existing.concurrency) {
+        existing.concurrency = worker.concurrency;
+      }
+    } else {
+      groups.set(worker.queue, {
+        queueName: worker.queue,
+        concurrency: Math.max(worker.concurrency, 1),
+        workerCount: 1
+      });
+    }
+  }
+  return [...groups.values()].sort((a, b) => a.queueName.localeCompare(b.queueName));
+}
+function resolveStrategyFromEnv(env) {
+  return env.QUEUE_STRATEGY === "async" ? "async" : "local";
+}
+const PROBE_ERROR_LOG_THROTTLE_MS = 6e4;
+function startLazyWorkerSupervisor(options) {
+  const logger = options.logger ?? console;
+  const strategy = options.strategy ?? resolveStrategyFromEnv(options.runtimeEnv);
+  const probe = options.probeFn ?? ((queueName) => getQueuePendingProbe(queueName, strategy));
+  const groups = groupWorkersByQueue(options.workers);
+  const startedQueues = /* @__PURE__ */ new Set();
+  const activeChildren = /* @__PURE__ */ new Map();
+  const startingQueues = /* @__PURE__ */ new Set();
+  const probeErrorLastLoggedAt = /* @__PURE__ */ new Map();
+  let stopping = false;
+  let pollTimer = null;
+  let watchPromiseResolve = null;
+  const done = new Promise((resolve) => {
+    watchPromiseResolve = resolve;
+  });
+  if (groups.length === 0) {
+    logger.warn(
+      "[lazy-supervisor] No queues discovered. Idle until queues are registered or run `yarn generate`."
+    );
+  } else {
+    logger.log(
+      `[lazy-supervisor] Watching ${groups.length} queue(s): ${groups.map((g) => g.queueName).join(", ")}`
+    );
+  }
+  const spawnFn = options.spawnFn ?? ((command, args, opts) => nodeSpawn(command, args, opts));
+  function logProbeError(queueName, message) {
+    const now = Date.now();
+    const lastAt = probeErrorLastLoggedAt.get(queueName) ?? 0;
+    if (now - lastAt < PROBE_ERROR_LOG_THROTTLE_MS) return;
+    probeErrorLastLoggedAt.set(queueName, now);
+    logger.warn(`[lazy-supervisor] Probe failed for queue "${queueName}": ${message}`);
+  }
+  function spawnQueueWorker(queueName) {
+    if (stopping) return;
+    if (activeChildren.has(queueName)) return;
+    if (startingQueues.has(queueName)) return;
+    startingQueues.add(queueName);
+    logger.log(`[lazy-supervisor] Pending job detected \u2014 starting worker for queue "${queueName}"`);
+    let child;
+    try {
+      child = spawnFn(
+        "node",
+        [options.mercatoBin, "queue", "worker", queueName],
+        {
+          stdio: "inherit",
+          env: options.runtimeEnv,
+          cwd: options.appDir
+        }
+      );
+    } catch (err) {
+      startingQueues.delete(queueName);
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(`[lazy-supervisor] Failed to spawn worker for "${queueName}": ${message}`);
+      return;
+    }
+    activeChildren.set(queueName, child);
+    startedQueues.add(queueName);
+    startingQueues.delete(queueName);
+    if (options.onSpawn) {
+      try {
+        options.onSpawn(queueName, child);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[lazy-supervisor] onSpawn callback threw for "${queueName}": ${message}`);
+      }
+    }
+    child.on("exit", (code, signal) => {
+      activeChildren.delete(queueName);
+      if (options.onChildExit) {
+        try {
+          options.onChildExit(queueName, code, signal);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          logger.warn(`[lazy-supervisor] onChildExit callback threw for "${queueName}": ${message}`);
+        }
+      }
+      if (stopping) return;
+      const expected = signal === "SIGTERM" || signal === "SIGINT";
+      if (expected) return;
+      const reason = code !== null ? `code ${code}` : `signal ${signal ?? "unknown"}`;
+      logger.warn(`[lazy-supervisor] Worker for "${queueName}" exited (${reason}).`);
+      if (!options.restartOnUnexpectedExit) return;
+      void (async () => {
+        const result = await safeProbe(queueName);
+        if (!result || result.error) return;
+        if (result.ready > 0) {
+          logger.warn(`[lazy-supervisor] Restarting worker for "${queueName}" because jobs remain pending.`);
+          spawnQueueWorker(queueName);
+        }
+      })();
+    });
+  }
+  async function safeProbe(queueName) {
+    try {
+      return await probe(queueName, strategy);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logProbeError(queueName, message);
+      return null;
+    }
+  }
+  async function tickOnce() {
+    if (stopping) return;
+    if (groups.length === 0) return;
+    const toCheck = groups.filter((g) => !activeChildren.has(g.queueName) && !startingQueues.has(g.queueName));
+    if (toCheck.length === 0) return;
+    const probes = await Promise.all(
+      toCheck.map(async (group) => ({
+        group,
+        result: await safeProbe(group.queueName)
+      }))
+    );
+    if (stopping) return;
+    for (const { group, result } of probes) {
+      if (!result) continue;
+      if (result.error) {
+        if (result.errorMessage) {
+          logProbeError(group.queueName, result.errorMessage);
+        }
+        continue;
+      }
+      if (result.ready > 0) {
+        spawnQueueWorker(group.queueName);
+      }
+    }
+  }
+  function scheduleNext() {
+    if (stopping) return;
+    pollTimer = setTimeout(() => {
+      void (async () => {
+        try {
+          await tickOnce();
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          logger.warn(`[lazy-supervisor] Poll cycle failed: ${message}`);
+        } finally {
+          if (!stopping) scheduleNext();
+        }
+      })();
+    }, options.pollMs);
+    pollTimer.unref?.();
+  }
+  void (async () => {
+    try {
+      await tickOnce();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn(`[lazy-supervisor] Initial poll failed: ${message}`);
+    } finally {
+      scheduleNext();
+    }
+  })();
+  async function close() {
+    if (stopping) {
+      await done;
+      return;
+    }
+    stopping = true;
+    if (pollTimer) {
+      clearTimeout(pollTimer);
+      pollTimer = null;
+    }
+    const exitWaiters = [];
+    for (const [queueName, child] of activeChildren) {
+      exitWaiters.push(
+        new Promise((resolve) => {
+          if (child.exitCode !== null || child.signalCode !== null) return resolve();
+          child.once("exit", () => resolve());
+        })
+      );
+      try {
+        if (!child.killed) child.kill("SIGTERM");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[lazy-supervisor] Failed to send SIGTERM to "${queueName}": ${message}`);
+      }
+    }
+    await Promise.all(exitWaiters);
+    activeChildren.clear();
+    if (watchPromiseResolve) {
+      watchPromiseResolve();
+      watchPromiseResolve = null;
+    }
+  }
+  return {
+    startedQueues,
+    getActiveChild: (queueName) => activeChildren.get(queueName),
+    close,
+    done
+  };
+}
+export {
+  startLazyWorkerSupervisor
+};
+//# sourceMappingURL=queue-worker-supervisor.js.map

package/dist/lib/queue-worker-supervisor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/queue-worker-supervisor.ts"],
+  "sourcesContent": ["/**\n * Lazy queue worker supervisor.\n *\n * Replaces `mercato queue worker --all` with a lightweight watcher that\n * starts a per-queue worker process only after the first ready job appears\n * on that queue. Discovered queues with no jobs stay completely idle.\n *\n * Design:\n *   - Probes every queue on a configurable interval using\n *     `getQueuePendingProbe()` from `@open-mercato/queue`.\n *   - The first non-error probe with `ready > 0` triggers `spawn('node', [\n *     mercatoBin, 'queue', 'worker', queueName ])`.\n *   - Each spawned child inherits stdio so its logs flow through the\n *     surrounding dev runtime.\n *   - On unexpected exit while jobs are still pending, the supervisor\n *     restarts the worker if `restartOnUnexpectedExit` is enabled.\n *   - On `close()`, all active children receive SIGTERM and the supervisor\n *     waits for them to exit before resolving.\n *\n * Probes never invoke handlers, never create BullMQ Workers, and never\n * import generated worker handler modules. The contract is preserved by\n * `getQueuePendingProbe()`.\n */\n\nimport { spawn as nodeSpawn } from 'node:child_process'\nimport type { ChildProcess, SpawnOptions } from 'node:child_process'\nimport {\n  getQueuePendingProbe,\n  type QueuePendingProbeResult,\n  type QueueStrategyType,\n} from '@open-mercato/queue'\nimport type { ModuleWorker } from '@open-mercato/shared/modules/registry'\n\nexport type LazySupervisorSpawnFn = (\n  command: string,\n  args: readonly string[],\n  options: SpawnOptions,\n) => ChildProcess\n\nexport type LazySupervisorProbeFn = (\n  queueName: string,\n  strategy: QueueStrategyType,\n) => Promise<QueuePendingProbeResult>\n\nexport type LazyWorkerSupervisorOptions = {\n  mercatoBin: string\n  appDir: string\n  runtimeEnv: NodeJS.ProcessEnv\n  workers: ModuleWorker[]\n  pollMs: number\n  restartOnUnexpectedExit: boolean\n  strategy?: QueueStrategyType\n  /** Override for tests. Defaults to `child_process.spawn`. */\n  spawnFn?: LazySupervisorSpawnFn\n  /** Override for tests. Defaults to `getQueuePendingProbe`. */\n  probeFn?: LazySupervisorProbeFn\n  /** Logger override. Defaults to `console`. */\n  logger?: Pick<Console, 'log' | 'warn' | 'error'>\n  onSpawn?: (queueName: string, child: ChildProcess) => void\n  onChildExit?: (\n    queueName: string,\n    code: number | null,\n    signal: NodeJS.Signals | null,\n  ) => void\n}\n\nexport type LazyWorkerSupervisorHandle = {\n  /** Set of queue names whose worker has started at least once. */\n  readonly startedQueues: ReadonlySet<string>\n  /** Currently running child process per queue (if any). */\n  getActiveChild(queueName: string): ChildProcess | undefined\n  /** Stop polling, kill children, wait for exit. Idempotent. */\n  close(): Promise<void>\n  /** Resolves when the watcher loop has stopped (after `close()`). */\n  done: Promise<void>\n}\n\ntype QueueGroup = {\n  queueName: string\n  concurrency: number\n  workerCount: number\n}\n\nfunction groupWorkersByQueue(workers: ModuleWorker[]): QueueGroup[] {\n  const groups = new Map<string, QueueGroup>()\n  for (const worker of workers) {\n    const existing = groups.get(worker.queue)\n    if (existing) {\n      existing.workerCount += 1\n      if (worker.concurrency > existing.concurrency) {\n        existing.concurrency = worker.concurrency\n      }\n    } else {\n      groups.set(worker.queue, {\n        queueName: worker.queue,\n        concurrency: Math.max(worker.concurrency, 1),\n        workerCount: 1,\n      })\n    }\n  }\n  return [...groups.values()].sort((a, b) => a.queueName.localeCompare(b.queueName))\n}\n\nfunction resolveStrategyFromEnv(env: NodeJS.ProcessEnv): QueueStrategyType {\n  return env.QUEUE_STRATEGY === 'async' ? 'async' : 'local'\n}\n\nconst PROBE_ERROR_LOG_THROTTLE_MS = 60_000\n\nexport function startLazyWorkerSupervisor(\n  options: LazyWorkerSupervisorOptions,\n): LazyWorkerSupervisorHandle {\n  const logger = options.logger ?? console\n  const strategy: QueueStrategyType = options.strategy ?? resolveStrategyFromEnv(options.runtimeEnv)\n  const probe: LazySupervisorProbeFn = options.probeFn\n    ?? ((queueName) => getQueuePendingProbe(queueName, strategy))\n  const groups = groupWorkersByQueue(options.workers)\n\n  const startedQueues = new Set<string>()\n  const activeChildren = new Map<string, ChildProcess>()\n  const startingQueues = new Set<string>()\n  const probeErrorLastLoggedAt = new Map<string, number>()\n\n  let stopping = false\n  let pollTimer: ReturnType<typeof setTimeout> | null = null\n  let watchPromiseResolve: (() => void) | null = null\n  const done = new Promise<void>((resolve) => {\n    watchPromiseResolve = resolve\n  })\n\n  if (groups.length === 0) {\n    logger.warn(\n      '[lazy-supervisor] No queues discovered. Idle until queues are registered or run `yarn generate`.',\n    )\n  } else {\n    logger.log(\n      `[lazy-supervisor] Watching ${groups.length} queue(s): ${groups\n        .map((g) => g.queueName)\n        .join(', ')}`,\n    )\n  }\n\n  const spawnFn: LazySupervisorSpawnFn =\n    options.spawnFn ?? ((command, args, opts) => nodeSpawn(command, args as string[], opts))\n\n  function logProbeError(queueName: string, message: string): void {\n    const now = Date.now()\n    const lastAt = probeErrorLastLoggedAt.get(queueName) ?? 0\n    if (now - lastAt < PROBE_ERROR_LOG_THROTTLE_MS) return\n    probeErrorLastLoggedAt.set(queueName, now)\n    logger.warn(`[lazy-supervisor] Probe failed for queue \"${queueName}\": ${message}`)\n  }\n\n  function spawnQueueWorker(queueName: string): void {\n    if (stopping) return\n    if (activeChildren.has(queueName)) return\n    if (startingQueues.has(queueName)) return\n    startingQueues.add(queueName)\n\n    logger.log(`[lazy-supervisor] Pending job detected \u2014 starting worker for queue \"${queueName}\"`)\n    let child: ChildProcess\n    try {\n      child = spawnFn(\n        'node',\n        [options.mercatoBin, 'queue', 'worker', queueName],\n        {\n          stdio: 'inherit',\n          env: options.runtimeEnv,\n          cwd: options.appDir,\n        },\n      )\n    } catch (err) {\n      startingQueues.delete(queueName)\n      const message = err instanceof Error ? err.message : String(err)\n      logger.error(`[lazy-supervisor] Failed to spawn worker for \"${queueName}\": ${message}`)\n      return\n    }\n\n    activeChildren.set(queueName, child)\n    startedQueues.add(queueName)\n    startingQueues.delete(queueName)\n    if (options.onSpawn) {\n      try {\n        options.onSpawn(queueName, child)\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err)\n        logger.warn(`[lazy-supervisor] onSpawn callback threw for \"${queueName}\": ${message}`)\n      }\n    }\n\n    child.on('exit', (code, signal) => {\n      activeChildren.delete(queueName)\n      if (options.onChildExit) {\n        try {\n          options.onChildExit(queueName, code, signal)\n        } catch (err) {\n          const message = err instanceof Error ? err.message : String(err)\n          logger.warn(`[lazy-supervisor] onChildExit callback threw for \"${queueName}\": ${message}`)\n        }\n      }\n      if (stopping) return\n      const expected = signal === 'SIGTERM' || signal === 'SIGINT'\n      if (expected) return\n      const reason = code !== null ? `code ${code}` : `signal ${signal ?? 'unknown'}`\n      logger.warn(`[lazy-supervisor] Worker for \"${queueName}\" exited (${reason}).`)\n      if (!options.restartOnUnexpectedExit) return\n      void (async () => {\n        const result = await safeProbe(queueName)\n        if (!result || result.error) return\n        if (result.ready > 0) {\n          logger.warn(`[lazy-supervisor] Restarting worker for \"${queueName}\" because jobs remain pending.`)\n          spawnQueueWorker(queueName)\n        }\n      })()\n    })\n  }\n\n  async function safeProbe(queueName: string): Promise<QueuePendingProbeResult | null> {\n    try {\n      return await probe(queueName, strategy)\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err)\n      logProbeError(queueName, message)\n      return null\n    }\n  }\n\n  async function tickOnce(): Promise<void> {\n    if (stopping) return\n    if (groups.length === 0) return\n\n    const toCheck = groups.filter((g) => !activeChildren.has(g.queueName) && !startingQueues.has(g.queueName))\n    if (toCheck.length === 0) return\n\n    const probes = await Promise.all(\n      toCheck.map(async (group) => ({\n        group,\n        result: await safeProbe(group.queueName),\n      })),\n    )\n\n    if (stopping) return\n\n    for (const { group, result } of probes) {\n      if (!result) continue\n      if (result.error) {\n        if (result.errorMessage) {\n          logProbeError(group.queueName, result.errorMessage)\n        }\n        continue\n      }\n      if (result.ready > 0) {\n        spawnQueueWorker(group.queueName)\n      }\n    }\n  }\n\n  function scheduleNext(): void {\n    if (stopping) return\n    pollTimer = setTimeout(() => {\n      void (async () => {\n        try {\n          await tickOnce()\n        } catch (err) {\n          const message = err instanceof Error ? err.message : String(err)\n          logger.warn(`[lazy-supervisor] Poll cycle failed: ${message}`)\n        } finally {\n          if (!stopping) scheduleNext()\n        }\n      })()\n    }, options.pollMs)\n    pollTimer.unref?.()\n  }\n\n  // Kick off immediately so the first probe doesn't wait one full poll interval.\n  void (async () => {\n    try {\n      await tickOnce()\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err)\n      logger.warn(`[lazy-supervisor] Initial poll failed: ${message}`)\n    } finally {\n      scheduleNext()\n    }\n  })()\n\n  async function close(): Promise<void> {\n    if (stopping) {\n      await done\n      return\n    }\n    stopping = true\n    if (pollTimer) {\n      clearTimeout(pollTimer)\n      pollTimer = null\n    }\n\n    const exitWaiters: Promise<void>[] = []\n    for (const [queueName, child] of activeChildren) {\n      exitWaiters.push(\n        new Promise<void>((resolve) => {\n          if (child.exitCode !== null || child.signalCode !== null) return resolve()\n          child.once('exit', () => resolve())\n        }),\n      )\n      try {\n        if (!child.killed) child.kill('SIGTERM')\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err)\n        logger.warn(`[lazy-supervisor] Failed to send SIGTERM to \"${queueName}\": ${message}`)\n      }\n    }\n    await Promise.all(exitWaiters)\n    activeChildren.clear()\n    if (watchPromiseResolve) {\n      watchPromiseResolve()\n      watchPromiseResolve = null\n    }\n  }\n\n  return {\n    startedQueues,\n    getActiveChild: (queueName) => activeChildren.get(queueName),\n    close,\n    done,\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mercato.js

@@ -4,6 +4,12 @@ import { parseBooleanToken } from "@open-mercato/shared/lib/boolean";
 import { getSslConfig } from "@open-mercato/shared/lib/db/ssl";
 import { getRedisUrl, getRedisUrlOrThrow } from "@open-mercato/shared/lib/redis/connection";
 import { resolveInitDerivedSecrets } from "./lib/init-secrets.js";
+import {
+  resolveAutoSpawnWorkersMode,
+  resolveLazyPollMs,
+  resolveLazyRestart
+} from "./lib/auto-spawn-workers.js";
+import { startLazyWorkerSupervisor } from "./lib/queue-worker-supervisor.js";
 import { parseModuleInstallArgs } from "./lib/module-install-args.js";
 import { resolveNextBuildIdCandidate } from "./lib/next-build-id.js";
 import { acquireServerStartLock } from "./lib/server-start-lock.js";
@@ -1382,6 +1388,7 @@ async function run(argv = process.argv) {
           let didRetryCorruptedTurbopackCache = false;
           let stopping = false;
           let envChangePromiseResolve = null;
+          let activeLazySupervisor = null;
           const envReloader = createDevEnvReloader(appDir, process.env, initialProcessEnvironmentEntries);
           function cleanup() {
             console.log("[server] Shutting down...");
@@ -1390,6 +1397,9 @@ async function run(argv = process.argv) {
                 proc.kill("SIGTERM");
               }
             }
+            if (activeLazySupervisor) {
+              void activeLazySupervisor.close().catch(() => void 0);
+            }
           }
           async function cleanupAndWait() {
             cleanup();
@@ -1401,6 +1411,13 @@ async function run(argv = process.argv) {
                 })
               )
             );
+            if (activeLazySupervisor) {
+              try {
+                await activeLazySupervisor.close();
+              } catch {
+              }
+              activeLazySupervisor = null;
+            }
             const lockFile = path.join(appDir, ".mercato", "next", "dev", "lock");
             try {
               fs.unlinkSync(lockFile);
@@ -1474,7 +1491,7 @@ async function run(argv = process.argv) {
             while (!stopping) {
               envReloader.reload();
               const runtimeEnv = buildServerProcessEnvironment(process.env);
-              const autoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS !== "false";
+              const autoSpawnWorkersMode = resolveAutoSpawnWorkersMode(process.env);
               const autoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER !== "false";
               const queueStrategy = process.env.QUEUE_STRATEGY || "local";
               const schedulerCommand = lookupModuleCommand(getCliModules(), "scheduler", "start");
@@ -1482,10 +1499,21 @@ async function run(argv = process.argv) {
                 startNextDev(runtimeEnv),
                 waitForEnvChange()
               ];
-              if (autoSpawnWorkers) {
-                const discoveredWorkerQueues = [...new Set(getRegisteredCliWorkers().map((worker) => worker.queue))];
+              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 \u2014 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] Starting workers for all queues...");
                   const workerProcess = spawn("node", [mercatoBin, "queue", "worker", "--all"], {
@@ -1537,7 +1565,7 @@ async function run(argv = process.argv) {
           const appDir = env.appDir;
           const nodeModulesBases = Array.from(/* @__PURE__ */ new Set([env.rootDir, appDir]));
           const processes = [];
-          const autoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS !== "false";
+          const autoSpawnWorkersMode = resolveAutoSpawnWorkersMode(process.env);
           const autoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER !== "false";
           const queueStrategy = process.env.QUEUE_STRATEGY || "local";
           const runtimeEnv = buildServerProcessEnvironment(process.env);
@@ -1545,6 +1573,7 @@ async function run(argv = process.argv) {
           const serverStartLock = acquireServerStartLock(appDir, {
             port: runtimeEnv.PORT ?? process.env.PORT ?? null
           });
+          let activeLazySupervisor = null;
           function cleanup() {
             console.log("[server] Shutting down...");
             for (const proc of processes) {
@@ -1552,6 +1581,9 @@ async function run(argv = process.argv) {
                 proc.kill("SIGTERM");
               }
             }
+            if (activeLazySupervisor) {
+              void activeLazySupervisor.close().catch(() => void 0);
+            }
           }
           async function cleanupAndWait() {
             cleanup();
@@ -1563,6 +1595,13 @@ async function run(argv = process.argv) {
                 })
               )
             );
+            if (activeLazySupervisor) {
+              try {
+                await activeLazySupervisor.close();
+              } catch {
+              }
+              activeLazySupervisor = null;
+            }
           }
           process.on("SIGTERM", cleanup);
           process.on("SIGINT", cleanup);
@@ -1580,10 +1619,21 @@ async function run(argv = process.argv) {
             const managedExitPromises = [
               waitForManagedProcessExit(nextProcess, "Next.js production server")
             ];
-            if (autoSpawnWorkers) {
-              const discoveredWorkerQueues = [...new Set(getRegisteredCliWorkers().map((worker) => worker.queue))];
+            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 \u2014 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] Starting workers for all queues...");
                 const workerProcess = spawn("node", [mercatoBin, "queue", "worker", "--all"], {