@open-mercato/cli 0.6.6-develop.5505.1.f08e81a6fe → 0.6.6-develop.5523.1.e223ca1915

package/.turbo/turbo-build.log

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

package/dist/lib/single-instance-strategy-guard.js

@@ -0,0 +1,89 @@
+import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
+import { resolveQueueStrategy } from "@open-mercato/queue";
+const MULTI_INSTANCE_SAFE_STRATEGIES = {
+  cache: ["redis"],
+  queue: ["async"],
+  rateLimit: ["redis"]
+};
+const COMPONENT_ENV_VARS = {
+  cache: "CACHE_STRATEGY",
+  queue: "QUEUE_STRATEGY",
+  rateLimit: "RATE_LIMIT_STRATEGY"
+};
+class SingleInstanceStrategyError extends Error {
+  constructor(result) {
+    super(
+      `Refusing to start: single-instance infrastructure strategies (${result.offenders.map((offender) => `${offender.envVar}=${offender.configured}`).join(", ")}) are configured under a declared multi-instance topology. Switch to a multi-instance-safe strategy or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override.`
+    );
+    this.name = "SingleInstanceStrategyError";
+    this.offenders = result.offenders;
+  }
+}
+function readInfraStrategySnapshot(env = process.env) {
+  return {
+    cacheStrategy: env.CACHE_STRATEGY?.trim() || "memory",
+    queueStrategy: resolveQueueStrategy(),
+    rateLimitStrategy: env.RATE_LIMIT_STRATEGY?.trim() || "memory"
+  };
+}
+function resolveMultiInstanceHint(env) {
+  if (parseBooleanWithDefault(env.OM_MULTI_INSTANCE, false)) return true;
+  const instanceCount = Number.parseInt(env.OM_INSTANCE_COUNT ?? "", 10);
+  return Number.isFinite(instanceCount) && instanceCount > 1;
+}
+function evaluateSingleInstanceGuard(snapshot, env = process.env) {
+  const configured = {
+    cache: snapshot.cacheStrategy,
+    queue: snapshot.queueStrategy,
+    rateLimit: snapshot.rateLimitStrategy
+  };
+  const offenders = [];
+  for (const component of Object.keys(configured)) {
+    const safeValues = MULTI_INSTANCE_SAFE_STRATEGIES[component];
+    if (!safeValues.includes(configured[component])) {
+      offenders.push({
+        component,
+        envVar: COMPONENT_ENV_VARS[component],
+        configured: configured[component],
+        safeValues
+      });
+    }
+  }
+  const production = (env.NODE_ENV ?? "").trim() === "production";
+  const multiInstance = resolveMultiInstanceHint(env);
+  const overridden = parseBooleanWithDefault(env.OM_ALLOW_SINGLE_INSTANCE_STRATEGIES, false);
+  let action = "ok";
+  if (offenders.length > 0 && production) {
+    action = multiInstance && !overridden ? "fail" : "warn";
+  }
+  return { action, offenders, production, multiInstance, overridden };
+}
+function formatSingleInstanceGuardMessage(result) {
+  const offenderLines = result.offenders.map(
+    (offender) => `  - ${offender.envVar}=${offender.configured} (multi-instance-safe: ${offender.safeValues.join(", ")})`
+  );
+  const header = result.action === "fail" ? "[server] Refusing to start: single-instance infrastructure strategies under a multi-instance topology." : "[server] WARNING: single-instance infrastructure strategies detected in production.";
+  const guidance = result.action === "fail" ? "[server] Switch each strategy above to a multi-instance-safe value, or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override (accepting duplicate jobs, stale ACLs, and weakened rate limits)." : result.multiInstance ? "[server] OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 is set \u2014 proceeding despite the risks above (duplicate jobs, stale ACLs, weakened rate limits)." : "[server] Running multiple instances against these strategies will cause duplicate jobs, stale ACLs, and weakened rate limits. Set OM_MULTI_INSTANCE=1 to make this a hard failure once you scale out.";
+  return [header, ...offenderLines, guidance];
+}
+function assertSingleInstanceStrategies(env = process.env, options) {
+  const snapshot = options?.snapshot ?? readInfraStrategySnapshot(env);
+  const result = evaluateSingleInstanceGuard(snapshot, env);
+  const logger = options?.logger ?? console;
+  if (result.action === "fail") {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.error(line);
+    throw new SingleInstanceStrategyError(result);
+  }
+  if (result.action === "warn") {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.warn(line);
+  }
+  return result;
+}
+export {
+  SingleInstanceStrategyError,
+  assertSingleInstanceStrategies,
+  evaluateSingleInstanceGuard,
+  formatSingleInstanceGuardMessage,
+  readInfraStrategySnapshot
+};
+//# sourceMappingURL=single-instance-strategy-guard.js.map

package/dist/lib/single-instance-strategy-guard.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/single-instance-strategy-guard.ts"],
+  "sourcesContent": ["import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\nimport { resolveQueueStrategy } from '@open-mercato/queue'\n\n/**\n * Boot-time guard that refuses to start (or warns) when an infrastructure\n * strategy that is only safe for a single process/instance is configured under\n * a declared multi-instance topology.\n *\n * Background: `CACHE_STRATEGY`, `RATE_LIMIT_STRATEGY` and `QUEUE_STRATEGY` all\n * default to single-instance modes (`memory`/`memory`/`local`). Running more\n * than one app instance against those defaults silently breaks three\n * correctness invariants at once \u2014 stale RBAC caches after a privilege\n * revocation, rate limits multiplied by the instance count, and duplicate job\n * processing from the leaderless local file queue. None of them warn.\n *\n * Only strategies that coordinate across processes via shared external state\n * are considered multi-instance safe. Everything else (the in-process memory\n * strategies, the local file queue, and disk-backed caches that are not shared\n * across hosts) is treated as single-instance.\n */\nconst MULTI_INSTANCE_SAFE_STRATEGIES = {\n  cache: ['redis'],\n  queue: ['async'],\n  rateLimit: ['redis'],\n} as const\n\nexport type SingleInstanceGuardComponent = 'cache' | 'queue' | 'rateLimit'\n\nexport type SingleInstanceGuardOffender = {\n  component: SingleInstanceGuardComponent\n  envVar: string\n  configured: string\n  safeValues: readonly string[]\n}\n\nexport type SingleInstanceGuardAction = 'ok' | 'warn' | 'fail'\n\nexport type SingleInstanceGuardResult = {\n  action: SingleInstanceGuardAction\n  offenders: SingleInstanceGuardOffender[]\n  production: boolean\n  multiInstance: boolean\n  overridden: boolean\n}\n\nexport type InfraStrategySnapshot = {\n  cacheStrategy: string\n  queueStrategy: string\n  rateLimitStrategy: string\n}\n\nconst COMPONENT_ENV_VARS: Record<SingleInstanceGuardComponent, string> = {\n  cache: 'CACHE_STRATEGY',\n  queue: 'QUEUE_STRATEGY',\n  rateLimit: 'RATE_LIMIT_STRATEGY',\n}\n\nexport class SingleInstanceStrategyError extends Error {\n  readonly offenders: SingleInstanceGuardOffender[]\n\n  constructor(result: SingleInstanceGuardResult) {\n    super(\n      `Refusing to start: single-instance infrastructure strategies (${result.offenders\n        .map((offender) => `${offender.envVar}=${offender.configured}`)\n        .join(', ')}) are configured under a declared multi-instance topology. ` +\n        'Switch to a multi-instance-safe strategy or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override.',\n    )\n    this.name = 'SingleInstanceStrategyError'\n    this.offenders = result.offenders\n  }\n}\n\n/**\n * Read the configured infrastructure strategies. Queue resolution reuses the\n * canonical `resolveQueueStrategy()` so the default stays single-sourced; cache\n * and rate-limit values are read directly with their documented defaults\n * (`packages/cache/src/service.ts`, `packages/shared/src/lib/ratelimit/config.ts`)\n * because the guard's safe-set policy \u2014 not the resolver default \u2014 decides what\n * counts as single-instance.\n */\nexport function readInfraStrategySnapshot(env: NodeJS.ProcessEnv = process.env): InfraStrategySnapshot {\n  return {\n    cacheStrategy: env.CACHE_STRATEGY?.trim() || 'memory',\n    queueStrategy: resolveQueueStrategy(),\n    rateLimitStrategy: env.RATE_LIMIT_STRATEGY?.trim() || 'memory',\n  }\n}\n\nfunction resolveMultiInstanceHint(env: NodeJS.ProcessEnv): boolean {\n  if (parseBooleanWithDefault(env.OM_MULTI_INSTANCE, false)) return true\n  const instanceCount = Number.parseInt(env.OM_INSTANCE_COUNT ?? '', 10)\n  return Number.isFinite(instanceCount) && instanceCount > 1\n}\n\nexport function evaluateSingleInstanceGuard(\n  snapshot: InfraStrategySnapshot,\n  env: NodeJS.ProcessEnv = process.env,\n): SingleInstanceGuardResult {\n  const configured: Record<SingleInstanceGuardComponent, string> = {\n    cache: snapshot.cacheStrategy,\n    queue: snapshot.queueStrategy,\n    rateLimit: snapshot.rateLimitStrategy,\n  }\n\n  const offenders: SingleInstanceGuardOffender[] = []\n  for (const component of Object.keys(configured) as SingleInstanceGuardComponent[]) {\n    const safeValues: readonly string[] = MULTI_INSTANCE_SAFE_STRATEGIES[component]\n    if (!safeValues.includes(configured[component])) {\n      offenders.push({\n        component,\n        envVar: COMPONENT_ENV_VARS[component],\n        configured: configured[component],\n        safeValues,\n      })\n    }\n  }\n\n  const production = (env.NODE_ENV ?? '').trim() === 'production'\n  const multiInstance = resolveMultiInstanceHint(env)\n  const overridden = parseBooleanWithDefault(env.OM_ALLOW_SINGLE_INSTANCE_STRATEGIES, false)\n\n  let action: SingleInstanceGuardAction = 'ok'\n  if (offenders.length > 0 && production) {\n    action = multiInstance && !overridden ? 'fail' : 'warn'\n  }\n\n  return { action, offenders, production, multiInstance, overridden }\n}\n\nexport function formatSingleInstanceGuardMessage(result: SingleInstanceGuardResult): string[] {\n  const offenderLines = result.offenders.map(\n    (offender) =>\n      `  - ${offender.envVar}=${offender.configured} (multi-instance-safe: ${offender.safeValues.join(', ')})`,\n  )\n  const header =\n    result.action === 'fail'\n      ? '[server] Refusing to start: single-instance infrastructure strategies under a multi-instance topology.'\n      : '[server] WARNING: single-instance infrastructure strategies detected in production.'\n  const guidance =\n    result.action === 'fail'\n      ? '[server] Switch each strategy above to a multi-instance-safe value, or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override (accepting duplicate jobs, stale ACLs, and weakened rate limits).'\n      : result.multiInstance\n        ? '[server] OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 is set \u2014 proceeding despite the risks above (duplicate jobs, stale ACLs, weakened rate limits).'\n        : '[server] Running multiple instances against these strategies will cause duplicate jobs, stale ACLs, and weakened rate limits. Set OM_MULTI_INSTANCE=1 to make this a hard failure once you scale out.'\n  return [header, ...offenderLines, guidance]\n}\n\nexport type SingleInstanceGuardLogger = Pick<Console, 'warn' | 'error'>\n\n/**\n * Evaluate the guard and enforce it: throw on `fail`, log prominently on\n * `warn`, and stay silent on `ok`. Safe to call on every `start`; it never\n * fires for dev boots or single-instance production deployments.\n */\nexport function assertSingleInstanceStrategies(\n  env: NodeJS.ProcessEnv = process.env,\n  options?: { snapshot?: InfraStrategySnapshot; logger?: SingleInstanceGuardLogger },\n): SingleInstanceGuardResult {\n  const snapshot = options?.snapshot ?? readInfraStrategySnapshot(env)\n  const result = evaluateSingleInstanceGuard(snapshot, env)\n  const logger = options?.logger ?? console\n\n  if (result.action === 'fail') {\n    for (const line of formatSingleInstanceGuardMessage(result)) logger.error(line)\n    throw new SingleInstanceStrategyError(result)\n  }\n  if (result.action === 'warn') {\n    for (const line of formatSingleInstanceGuardMessage(result)) logger.warn(line)\n  }\n\n  return result\n}\n"],
+  "mappings": "AAAA,SAAS,+BAA+B;AACxC,SAAS,4BAA4B;AAmBrC,MAAM,iCAAiC;AAAA,EACrC,OAAO,CAAC,OAAO;AAAA,EACf,OAAO,CAAC,OAAO;AAAA,EACf,WAAW,CAAC,OAAO;AACrB;AA2BA,MAAM,qBAAmE;AAAA,EACvE,OAAO;AAAA,EACP,OAAO;AAAA,EACP,WAAW;AACb;AAEO,MAAM,oCAAoC,MAAM;AAAA,EAGrD,YAAY,QAAmC;AAC7C;AAAA,MACE,iEAAiE,OAAO,UACrE,IAAI,CAAC,aAAa,GAAG,SAAS,MAAM,IAAI,SAAS,UAAU,EAAE,EAC7D,KAAK,IAAI,CAAC;AAAA,IAEf;AACA,SAAK,OAAO;AACZ,SAAK,YAAY,OAAO;AAAA,EAC1B;AACF;AAUO,SAAS,0BAA0B,MAAyB,QAAQ,KAA4B;AACrG,SAAO;AAAA,IACL,eAAe,IAAI,gBAAgB,KAAK,KAAK;AAAA,IAC7C,eAAe,qBAAqB;AAAA,IACpC,mBAAmB,IAAI,qBAAqB,KAAK,KAAK;AAAA,EACxD;AACF;AAEA,SAAS,yBAAyB,KAAiC;AACjE,MAAI,wBAAwB,IAAI,mBAAmB,KAAK,EAAG,QAAO;AAClE,QAAM,gBAAgB,OAAO,SAAS,IAAI,qBAAqB,IAAI,EAAE;AACrE,SAAO,OAAO,SAAS,aAAa,KAAK,gBAAgB;AAC3D;AAEO,SAAS,4BACd,UACA,MAAyB,QAAQ,KACN;AAC3B,QAAM,aAA2D;AAAA,IAC/D,OAAO,SAAS;AAAA,IAChB,OAAO,SAAS;AAAA,IAChB,WAAW,SAAS;AAAA,EACtB;AAEA,QAAM,YAA2C,CAAC;AAClD,aAAW,aAAa,OAAO,KAAK,UAAU,GAAqC;AACjF,UAAM,aAAgC,+BAA+B,SAAS;AAC9E,QAAI,CAAC,WAAW,SAAS,WAAW,SAAS,CAAC,GAAG;AAC/C,gBAAU,KAAK;AAAA,QACb;AAAA,QACA,QAAQ,mBAAmB,SAAS;AAAA,QACpC,YAAY,WAAW,SAAS;AAAA,QAChC;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,cAAc,IAAI,YAAY,IAAI,KAAK,MAAM;AACnD,QAAM,gBAAgB,yBAAyB,GAAG;AAClD,QAAM,aAAa,wBAAwB,IAAI,qCAAqC,KAAK;AAEzF,MAAI,SAAoC;AACxC,MAAI,UAAU,SAAS,KAAK,YAAY;AACtC,aAAS,iBAAiB,CAAC,aAAa,SAAS;AAAA,EACnD;AAEA,SAAO,EAAE,QAAQ,WAAW,YAAY,eAAe,WAAW;AACpE;AAEO,SAAS,iCAAiC,QAA6C;AAC5F,QAAM,gBAAgB,OAAO,UAAU;AAAA,IACrC,CAAC,aACC,OAAO,SAAS,MAAM,IAAI,SAAS,UAAU,0BAA0B,SAAS,WAAW,KAAK,IAAI,CAAC;AAAA,EACzG;AACA,QAAM,SACJ,OAAO,WAAW,SACd,2GACA;AACN,QAAM,WACJ,OAAO,WAAW,SACd,mMACA,OAAO,gBACL,wJACA;AACR,SAAO,CAAC,QAAQ,GAAG,eAAe,QAAQ;AAC5C;AASO,SAAS,+BACd,MAAyB,QAAQ,KACjC,SAC2B;AAC3B,QAAM,WAAW,SAAS,YAAY,0BAA0B,GAAG;AACnE,QAAM,SAAS,4BAA4B,UAAU,GAAG;AACxD,QAAM,SAAS,SAAS,UAAU;AAElC,MAAI,OAAO,WAAW,QAAQ;AAC5B,eAAW,QAAQ,iCAAiC,MAAM,EAAG,QAAO,MAAM,IAAI;AAC9E,UAAM,IAAI,4BAA4B,MAAM;AAAA,EAC9C;AACA,MAAI,OAAO,WAAW,QAAQ;AAC5B,eAAW,QAAQ,iCAAiC,MAAM,EAAG,QAAO,KAAK,IAAI;AAAA,EAC/E;AAEA,SAAO;AACT;",
+  "names": []
+}

package/dist/mercato.js

@@ -25,6 +25,7 @@ import {
 import { parseModuleInstallArgs } from "./lib/module-install-args.js";
 import { resolveNextBuildIdCandidate } from "./lib/next-build-id.js";
 import { acquireServerStartLock } from "./lib/server-start-lock.js";
+import { assertSingleInstanceStrategies } from "./lib/single-instance-strategy-guard.js";
 import { createDevEnvReloader, watchDevEnvFiles } from "./lib/dev-env-reload.js";
 const lazyIntegration = () => import("./lib/testing/integration.js");
 import path from "node:path";
@@ -1781,6 +1782,7 @@ async function run(argv = process.argv) {
           const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env);
           const queueStrategy = process.env.QUEUE_STRATEGY || "local";
           const runtimeEnv = buildServerProcessEnvironment(process.env);
+          assertSingleInstanceStrategies(runtimeEnv);
           const schedulerCommand = lookupModuleCommand(getCliModules(), "scheduler", "start");
           const serverStartLock = acquireServerStartLock(appDir, {
             port: runtimeEnv.PORT ?? process.env.PORT ?? null