@open-mercato/core 0.4.11-develop.1416.adda6008da → 0.4.11-develop.1418.27a299bdaf

package/dist/modules/configs/cli.js

@@ -1,6 +1,221 @@
+import { runWithCacheTenant } from "@open-mercato/cache";
 import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
 import { parseBooleanToken } from "@open-mercato/shared/lib/boolean";
 import { DEFAULT_NOTIFICATION_DELIVERY_CONFIG, NOTIFICATIONS_DELIVERY_CONFIG_KEY } from "../notifications/lib/deliveryConfig.js";
+import { Tenant } from "../directory/data/entities.js";
+import {
+  collectCacheStats,
+  executeCachePurge,
+  previewCachePurge
+} from "./lib/cache-cli.js";
+function parseArgs(rest) {
+  const args = {};
+  for (let i = 0; i < rest.length; i += 1) {
+    const part = rest[i];
+    if (!part?.startsWith("--")) continue;
+    const [rawKey, rawValue] = part.slice(2).split("=");
+    if (!rawKey) continue;
+    if (rawValue !== void 0) {
+      args[rawKey] = rawValue;
+    } else if (i + 1 < rest.length && !rest[i + 1].startsWith("--")) {
+      args[rawKey] = rest[i + 1];
+      i += 1;
+    } else {
+      args[rawKey] = true;
+    }
+  }
+  return args;
+}
+function stringOption(args, ...keys) {
+  for (const key of keys) {
+    const raw = args[key];
+    if (typeof raw !== "string") continue;
+    const trimmed = raw.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  return void 0;
+}
+function flagEnabled(args, ...keys) {
+  for (const key of keys) {
+    const raw = args[key];
+    if (raw === void 0) continue;
+    if (raw === true) return true;
+    if (typeof raw === "string") {
+      const parsed = parseBooleanToken(raw);
+      return parsed === null ? true : parsed;
+    }
+  }
+  return false;
+}
+function splitListOption(raw) {
+  if (!raw) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const values = [];
+  for (const item of raw.split(",")) {
+    const trimmed = item.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    values.push(trimmed);
+  }
+  return values;
+}
+async function resolveCacheScopes(em, args) {
+  const explicitTenantId = stringOption(args, "tenant", "tenantId");
+  const globalOnly = flagEnabled(args, "global");
+  const allTenants = flagEnabled(args, "all-tenants", "allTenants");
+  if (explicitTenantId && globalOnly) {
+    throw new Error("Cannot combine `--tenant` with `--global`.");
+  }
+  if (explicitTenantId && allTenants) {
+    throw new Error("Cannot combine `--tenant` with `--all-tenants`.");
+  }
+  if (globalOnly && allTenants) {
+    throw new Error("Cannot combine `--global` with `--all-tenants`.");
+  }
+  if (explicitTenantId) {
+    return [{ label: `tenant:${explicitTenantId}`, tenantId: explicitTenantId }];
+  }
+  if (globalOnly) {
+    return [{ label: "global", tenantId: null }];
+  }
+  if (!allTenants) {
+    return [{ label: "global", tenantId: null }];
+  }
+  const tenants = await em.find(Tenant, { deletedAt: null }, { orderBy: { name: "asc" } });
+  const scopes = [{ label: "global", tenantId: null }];
+  const seen = /* @__PURE__ */ new Set();
+  for (const tenant of tenants) {
+    const tenantId = typeof tenant.id === "string" ? tenant.id : "";
+    if (!tenantId || seen.has(tenantId)) continue;
+    seen.add(tenantId);
+    scopes.push({ label: `tenant:${tenantId}`, tenantId });
+  }
+  return scopes;
+}
+function resolveCachePurgeRequest(args) {
+  if (flagEnabled(args, "all")) return { kind: "all" };
+  const segment = stringOption(args, "segment");
+  if (segment) return { kind: "segment", segment };
+  const tags = splitListOption(stringOption(args, "tag", "tags"));
+  if (tags.length > 0) return { kind: "tags", tags };
+  const keys = splitListOption(stringOption(args, "key", "keys"));
+  if (keys.length > 0) return { kind: "keys", keys };
+  const ids = splitListOption(stringOption(args, "id", "ids"));
+  if (ids.length > 0) return { kind: "ids", ids };
+  const pattern = stringOption(args, "pattern");
+  if (pattern) return { kind: "pattern", pattern };
+  throw new Error(
+    "Choose a purge target: `--all`, `--segment <id>`, `--tag <tag1,tag2>`, `--key <key1,key2>`, `--id <token1,token2>`, or `--pattern <glob>`."
+  );
+}
+function printCacheHelp() {
+  console.log("\u{1F9F9} Cache CLI");
+  console.log("");
+  console.log("\u{1F680} Usage:");
+  console.log("  yarn mercato configs cache stats [--tenant <id> | --global | --all-tenants] [--json]");
+  console.log("  yarn mercato configs cache purge --all [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("  yarn mercato configs cache purge --segment <segment> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("  yarn mercato configs cache purge --tag <tag1,tag2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("  yarn mercato configs cache purge --key <key1,key2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("  yarn mercato configs cache purge --id <token1,token2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("  yarn mercato configs cache purge --pattern <glob> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("  yarn mercato configs cache structural [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]");
+  console.log("");
+  console.log("\u2139\uFE0F Notes:");
+  console.log("  `stats` mirrors the cache admin page segment overview for CRUD/widget caches.");
+  console.log("  `purge --id` removes every key whose name contains the provided token (for example a user id or entity id).");
+  console.log("  `structural` targets navigation caches (`nav:*`) and is the recommended post-step after module/sidebar structure changes.");
+  console.log("  When no scope flag is supplied, this command uses the global cache scope only.");
+}
+async function disposeContainer(container) {
+  const disposable = container;
+  if (typeof disposable.dispose === "function") {
+    await disposable.dispose();
+  }
+}
+async function runCacheStats(args) {
+  const json = flagEnabled(args, "json");
+  const container = await createRequestContainer();
+  try {
+    const em = container.resolve("em");
+    const cache = container.resolve("cache");
+    const scopes = await resolveCacheScopes(em, args);
+    const results = [];
+    for (const scope of scopes) {
+      const stats = await runWithCacheTenant(scope.tenantId, async () => collectCacheStats(cache));
+      results.push({ scope: scope.label, ...stats });
+    }
+    if (json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+    for (const result of results) {
+      console.log(`\u{1F50E} [cache] scope=${result.scope} totalKeys=${result.totalKeys} generatedAt=${result.generatedAt}`);
+      if (result.segments.length === 0) {
+        console.log("  \u2205 segments: none");
+        continue;
+      }
+      for (const segment of result.segments) {
+        console.log(`  \u2022 ${segment.segment} (${segment.keyCount})${segment.path ? ` ${segment.path}` : ""}`);
+      }
+    }
+  } finally {
+    await disposeContainer(container);
+  }
+}
+async function runCachePurge(args) {
+  const json = flagEnabled(args, "json");
+  const quiet = flagEnabled(args, "quiet");
+  const dryRun = flagEnabled(args, "dry-run", "dryRun");
+  const request = resolveCachePurgeRequest(args);
+  const container = await createRequestContainer();
+  try {
+    const em = container.resolve("em");
+    const cache = container.resolve("cache");
+    const scopes = await resolveCacheScopes(em, args);
+    const results = [];
+    for (const scope of scopes) {
+      const result = await runWithCacheTenant(
+        scope.tenantId,
+        async () => dryRun ? previewCachePurge(cache, request) : executeCachePurge(cache, request)
+      );
+      results.push({
+        scope: scope.label,
+        dryRun,
+        request,
+        deleted: result.deleted,
+        keyCount: result.keys.length,
+        keys: result.keys,
+        note: result.note
+      });
+    }
+    if (json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+    if (quiet) {
+      return;
+    }
+    for (const result of results) {
+      console.log(`${result.dryRun ? "\u{1F9EA}" : "\u{1F9F9}"} [cache] scope=${result.scope} deleted=${result.deleted}${result.dryRun ? " (dry-run)" : ""}`);
+      if (result.note) console.log(`  \u2139\uFE0F note: ${result.note}`);
+      if (result.keys.length > 0) {
+        for (const key of result.keys) {
+          console.log(`  \u2022 ${key}`);
+        }
+      }
+    }
+  } finally {
+    await disposeContainer(container);
+  }
+}
+async function runStructuralCachePurge(args) {
+  const nextArgs = {
+    ...args,
+    pattern: "nav:*"
+  };
+  await runCachePurge(nextArgs);
+}
 function envDisablesAutoIndexing() {
   const raw = process.env.DISABLE_VECTOR_SEARCH_AUTOINDEXING;
   if (!raw) return false;
@@ -49,11 +264,39 @@ const restoreDefaults = {
 const help = {
   command: "help",
   async run() {
-    console.log("Usage: yarn mercato configs restore-defaults");
+    console.log("\u2699\uFE0F Configs CLI");
+    console.log("");
+    console.log("\u{1F680} Usage: yarn mercato configs restore-defaults");
     console.log("  Ensures global module configuration defaults exist.");
+    console.log("");
+    printCacheHelp();
+  }
+};
+const cacheCommand = {
+  command: "cache",
+  async run(rest) {
+    const [subcommand, ...subRest] = rest;
+    const args = parseArgs(subRest);
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+      printCacheHelp();
+      return;
+    }
+    if (subcommand === "stats") {
+      await runCacheStats(args);
+      return;
+    }
+    if (subcommand === "purge") {
+      await runCachePurge(args);
+      return;
+    }
+    if (subcommand === "structural") {
+      await runStructuralCachePurge(args);
+      return;
+    }
+    throw new Error(`Unknown cache subcommand "${subcommand}".`);
   }
 };
-var cli_default = [restoreDefaults, help];
+var cli_default = [restoreDefaults, cacheCommand, help];
 export {
   cli_default as default
 };

package/dist/modules/configs/cli.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/configs/cli.ts"],
-  "sourcesContent": ["import type { ModuleCli } from '@open-mercato/shared/modules/registry'\nimport { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport type { ModuleConfigService } from './lib/module-config-service'\nimport { parseBooleanToken } from '@open-mercato/shared/lib/boolean'\nimport { DEFAULT_NOTIFICATION_DELIVERY_CONFIG, NOTIFICATIONS_DELIVERY_CONFIG_KEY } from '../notifications/lib/deliveryConfig'\n\nfunction envDisablesAutoIndexing(): boolean {\n  const raw = process.env.DISABLE_VECTOR_SEARCH_AUTOINDEXING\n  if (!raw) return false\n  return parseBooleanToken(raw) === true\n}\n\nconst restoreDefaults: ModuleCli = {\n  command: 'restore-defaults',\n  async run() {\n    const container = await createRequestContainer()\n    try {\n      let service: ModuleConfigService\n      try {\n        service = (container.resolve('moduleConfigService') as ModuleConfigService)\n      } catch {\n        console.error('[configs] moduleConfigService is not registered in the container.')\n        return\n      }\n\n      const disabledByEnv = envDisablesAutoIndexing()\n      const defaultEnabled = !disabledByEnv\n      await service.restoreDefaults(\n        [\n          {\n            moduleId: 'vector',\n            name: 'auto_index_enabled',\n            value: defaultEnabled,\n          },\n          {\n            moduleId: 'notifications',\n            name: NOTIFICATIONS_DELIVERY_CONFIG_KEY,\n            value: DEFAULT_NOTIFICATION_DELIVERY_CONFIG,\n          },\n        ],\n        { force: true },\n      )\n      console.log(\n        `[configs] Vector auto-indexing default set to ${defaultEnabled ? 'enabled' : 'disabled'}${\n          disabledByEnv ? ' (forced by DISABLE_VECTOR_SEARCH_AUTOINDEXING)' : ''\n        }.`,\n      )\n    } finally {\n      const disposable = container as unknown as { dispose?: () => Promise<void> }\n      if (typeof disposable.dispose === 'function') {\n        await disposable.dispose()\n      }\n    }\n  },\n}\n\nconst help: ModuleCli = {\n  command: 'help',\n  async run() {\n    console.log('Usage: yarn mercato configs restore-defaults')\n    console.log('  Ensures global module configuration defaults exist.')\n  },\n}\n\nexport default [restoreDefaults, help]\n"],
-  "mappings": "AACA,SAAS,8BAA8B;AAEvC,SAAS,yBAAyB;AAClC,SAAS,sCAAsC,yCAAyC;AAExF,SAAS,0BAAmC;AAC1C,QAAM,MAAM,QAAQ,IAAI;AACxB,MAAI,CAAC,IAAK,QAAO;AACjB,SAAO,kBAAkB,GAAG,MAAM;AACpC;AAEA,MAAM,kBAA6B;AAAA,EACjC,SAAS;AAAA,EACT,MAAM,MAAM;AACV,UAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAI;AACF,UAAI;AACJ,UAAI;AACF,kBAAW,UAAU,QAAQ,qBAAqB;AAAA,MACpD,QAAQ;AACN,gBAAQ,MAAM,mEAAmE;AACjF;AAAA,MACF;AAEA,YAAM,gBAAgB,wBAAwB;AAC9C,YAAM,iBAAiB,CAAC;AACxB,YAAM,QAAQ;AAAA,QACZ;AAAA,UACE;AAAA,YACE,UAAU;AAAA,YACV,MAAM;AAAA,YACN,OAAO;AAAA,UACT;AAAA,UACA;AAAA,YACE,UAAU;AAAA,YACV,MAAM;AAAA,YACN,OAAO;AAAA,UACT;AAAA,QACF;AAAA,QACA,EAAE,OAAO,KAAK;AAAA,MAChB;AACA,cAAQ;AAAA,QACN,iDAAiD,iBAAiB,YAAY,UAAU,GACtF,gBAAgB,oDAAoD,EACtE;AAAA,MACF;AAAA,IACF,UAAE;AACA,YAAM,aAAa;AACnB,UAAI,OAAO,WAAW,YAAY,YAAY;AAC5C,cAAM,WAAW,QAAQ;AAAA,MAC3B;AAAA,IACF;AAAA,EACF;AACF;AAEA,MAAM,OAAkB;AAAA,EACtB,SAAS;AAAA,EACT,MAAM,MAAM;AACV,YAAQ,IAAI,8CAA8C;AAC1D,YAAQ,IAAI,uDAAuD;AAAA,EACrE;AACF;AAEA,IAAO,cAAQ,CAAC,iBAAiB,IAAI;",
+  "sourcesContent": ["import type { ModuleCli } from '@open-mercato/shared/modules/registry'\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { runWithCacheTenant, type CacheStrategy } from '@open-mercato/cache'\nimport { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport type { ModuleConfigService } from './lib/module-config-service'\nimport { parseBooleanToken } from '@open-mercato/shared/lib/boolean'\nimport { DEFAULT_NOTIFICATION_DELIVERY_CONFIG, NOTIFICATIONS_DELIVERY_CONFIG_KEY } from '../notifications/lib/deliveryConfig'\nimport { Tenant } from '../directory/data/entities'\nimport {\n  collectCacheStats,\n  executeCachePurge,\n  previewCachePurge,\n  type CachePurgeRequest,\n} from './lib/cache-cli'\n\ntype ParsedArgs = Record<string, string | boolean>\n\ntype CacheScope = {\n  label: string\n  tenantId: string | null\n}\n\nfunction parseArgs(rest: string[]): ParsedArgs {\n  const args: ParsedArgs = {}\n  for (let i = 0; i < rest.length; i += 1) {\n    const part = rest[i]\n    if (!part?.startsWith('--')) continue\n    const [rawKey, rawValue] = part.slice(2).split('=')\n    if (!rawKey) continue\n    if (rawValue !== undefined) {\n      args[rawKey] = rawValue\n    } else if (i + 1 < rest.length && !rest[i + 1]!.startsWith('--')) {\n      args[rawKey] = rest[i + 1]!\n      i += 1\n    } else {\n      args[rawKey] = true\n    }\n  }\n  return args\n}\n\nfunction stringOption(args: ParsedArgs, ...keys: string[]): string | undefined {\n  for (const key of keys) {\n    const raw = args[key]\n    if (typeof raw !== 'string') continue\n    const trimmed = raw.trim()\n    if (trimmed.length > 0) return trimmed\n  }\n  return undefined\n}\n\nfunction flagEnabled(args: ParsedArgs, ...keys: string[]): boolean {\n  for (const key of keys) {\n    const raw = args[key]\n    if (raw === undefined) continue\n    if (raw === true) return true\n    if (typeof raw === 'string') {\n      const parsed = parseBooleanToken(raw)\n      return parsed === null ? true : parsed\n    }\n  }\n  return false\n}\n\nfunction splitListOption(raw: string | undefined): string[] {\n  if (!raw) return []\n  const seen = new Set<string>()\n  const values: string[] = []\n  for (const item of raw.split(',')) {\n    const trimmed = item.trim()\n    if (!trimmed || seen.has(trimmed)) continue\n    seen.add(trimmed)\n    values.push(trimmed)\n  }\n  return values\n}\n\nasync function resolveCacheScopes(\n  em: EntityManager,\n  args: ParsedArgs,\n): Promise<CacheScope[]> {\n  const explicitTenantId = stringOption(args, 'tenant', 'tenantId')\n  const globalOnly = flagEnabled(args, 'global')\n  const allTenants = flagEnabled(args, 'all-tenants', 'allTenants')\n\n  if (explicitTenantId && globalOnly) {\n    throw new Error('Cannot combine `--tenant` with `--global`.')\n  }\n  if (explicitTenantId && allTenants) {\n    throw new Error('Cannot combine `--tenant` with `--all-tenants`.')\n  }\n  if (globalOnly && allTenants) {\n    throw new Error('Cannot combine `--global` with `--all-tenants`.')\n  }\n\n  if (explicitTenantId) {\n    return [{ label: `tenant:${explicitTenantId}`, tenantId: explicitTenantId }]\n  }\n\n  if (globalOnly) {\n    return [{ label: 'global', tenantId: null }]\n  }\n\n  if (!allTenants) {\n    return [{ label: 'global', tenantId: null }]\n  }\n\n  const tenants = await em.find(Tenant, { deletedAt: null }, { orderBy: { name: 'asc' } })\n  const scopes: CacheScope[] = [{ label: 'global', tenantId: null }]\n  const seen = new Set<string>()\n  for (const tenant of tenants) {\n    const tenantId = typeof tenant.id === 'string' ? tenant.id : ''\n    if (!tenantId || seen.has(tenantId)) continue\n    seen.add(tenantId)\n    scopes.push({ label: `tenant:${tenantId}`, tenantId })\n  }\n  return scopes\n}\n\nfunction resolveCachePurgeRequest(args: ParsedArgs): CachePurgeRequest {\n  if (flagEnabled(args, 'all')) return { kind: 'all' }\n\n  const segment = stringOption(args, 'segment')\n  if (segment) return { kind: 'segment', segment }\n\n  const tags = splitListOption(stringOption(args, 'tag', 'tags'))\n  if (tags.length > 0) return { kind: 'tags', tags }\n\n  const keys = splitListOption(stringOption(args, 'key', 'keys'))\n  if (keys.length > 0) return { kind: 'keys', keys }\n\n  const ids = splitListOption(stringOption(args, 'id', 'ids'))\n  if (ids.length > 0) return { kind: 'ids', ids }\n\n  const pattern = stringOption(args, 'pattern')\n  if (pattern) return { kind: 'pattern', pattern }\n\n  throw new Error(\n    'Choose a purge target: `--all`, `--segment <id>`, `--tag <tag1,tag2>`, `--key <key1,key2>`, `--id <token1,token2>`, or `--pattern <glob>`.',\n  )\n}\n\nfunction printCacheHelp() {\n  console.log('\uD83E\uDDF9 Cache CLI')\n  console.log('')\n  console.log('\uD83D\uDE80 Usage:')\n  console.log('  yarn mercato configs cache stats [--tenant <id> | --global | --all-tenants] [--json]')\n  console.log('  yarn mercato configs cache purge --all [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('  yarn mercato configs cache purge --segment <segment> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('  yarn mercato configs cache purge --tag <tag1,tag2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('  yarn mercato configs cache purge --key <key1,key2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('  yarn mercato configs cache purge --id <token1,token2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('  yarn mercato configs cache purge --pattern <glob> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('  yarn mercato configs cache structural [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')\n  console.log('')\n  console.log('\u2139\uFE0F Notes:')\n  console.log('  `stats` mirrors the cache admin page segment overview for CRUD/widget caches.')\n  console.log('  `purge --id` removes every key whose name contains the provided token (for example a user id or entity id).')\n  console.log('  `structural` targets navigation caches (`nav:*`) and is the recommended post-step after module/sidebar structure changes.')\n  console.log('  When no scope flag is supplied, this command uses the global cache scope only.')\n}\n\nasync function disposeContainer(container: unknown) {\n  const disposable = container as { dispose?: () => Promise<void> }\n  if (typeof disposable.dispose === 'function') {\n    await disposable.dispose()\n  }\n}\n\nasync function runCacheStats(args: ParsedArgs) {\n  const json = flagEnabled(args, 'json')\n  const container = await createRequestContainer()\n  try {\n    const em = container.resolve('em') as EntityManager\n    const cache = container.resolve('cache') as CacheStrategy\n    const scopes = await resolveCacheScopes(em, args)\n    const results = []\n    for (const scope of scopes) {\n      const stats = await runWithCacheTenant(scope.tenantId, async () => collectCacheStats(cache))\n      results.push({ scope: scope.label, ...stats })\n    }\n\n    if (json) {\n      console.log(JSON.stringify(results, null, 2))\n      return\n    }\n\n    for (const result of results) {\n      console.log(`\uD83D\uDD0E [cache] scope=${result.scope} totalKeys=${result.totalKeys} generatedAt=${result.generatedAt}`)\n      if (result.segments.length === 0) {\n        console.log('  \u2205 segments: none')\n        continue\n      }\n      for (const segment of result.segments) {\n        console.log(`  \u2022 ${segment.segment} (${segment.keyCount})${segment.path ? ` ${segment.path}` : ''}`)\n      }\n    }\n  } finally {\n    await disposeContainer(container)\n  }\n}\n\nasync function runCachePurge(args: ParsedArgs) {\n  const json = flagEnabled(args, 'json')\n  const quiet = flagEnabled(args, 'quiet')\n  const dryRun = flagEnabled(args, 'dry-run', 'dryRun')\n  const request = resolveCachePurgeRequest(args)\n  const container = await createRequestContainer()\n  try {\n    const em = container.resolve('em') as EntityManager\n    const cache = container.resolve('cache') as CacheStrategy\n    const scopes = await resolveCacheScopes(em, args)\n    const results = []\n\n    for (const scope of scopes) {\n      const result = await runWithCacheTenant(scope.tenantId, async () =>\n        dryRun ? previewCachePurge(cache, request) : executeCachePurge(cache, request)\n      )\n      results.push({\n        scope: scope.label,\n        dryRun,\n        request,\n        deleted: result.deleted,\n        keyCount: result.keys.length,\n        keys: result.keys,\n        note: result.note,\n      })\n    }\n\n    if (json) {\n      console.log(JSON.stringify(results, null, 2))\n      return\n    }\n\n    if (quiet) {\n      return\n    }\n\n    for (const result of results) {\n      console.log(`${result.dryRun ? '\uD83E\uDDEA' : '\uD83E\uDDF9'} [cache] scope=${result.scope} deleted=${result.deleted}${result.dryRun ? ' (dry-run)' : ''}`)\n      if (result.note) console.log(`  \u2139\uFE0F note: ${result.note}`)\n      if (result.keys.length > 0) {\n        for (const key of result.keys) {\n          console.log(`  \u2022 ${key}`)\n        }\n      }\n    }\n  } finally {\n    await disposeContainer(container)\n  }\n}\n\nasync function runStructuralCachePurge(args: ParsedArgs) {\n  const nextArgs: ParsedArgs = {\n    ...args,\n    pattern: 'nav:*',\n  }\n  await runCachePurge(nextArgs)\n}\n\nfunction envDisablesAutoIndexing(): boolean {\n  const raw = process.env.DISABLE_VECTOR_SEARCH_AUTOINDEXING\n  if (!raw) return false\n  return parseBooleanToken(raw) === true\n}\n\nconst restoreDefaults: ModuleCli = {\n  command: 'restore-defaults',\n  async run() {\n    const container = await createRequestContainer()\n    try {\n      let service: ModuleConfigService\n      try {\n        service = (container.resolve('moduleConfigService') as ModuleConfigService)\n      } catch {\n        console.error('[configs] moduleConfigService is not registered in the container.')\n        return\n      }\n\n      const disabledByEnv = envDisablesAutoIndexing()\n      const defaultEnabled = !disabledByEnv\n      await service.restoreDefaults(\n        [\n          {\n            moduleId: 'vector',\n            name: 'auto_index_enabled',\n            value: defaultEnabled,\n          },\n          {\n            moduleId: 'notifications',\n            name: NOTIFICATIONS_DELIVERY_CONFIG_KEY,\n            value: DEFAULT_NOTIFICATION_DELIVERY_CONFIG,\n          },\n        ],\n        { force: true },\n      )\n      console.log(\n        `[configs] Vector auto-indexing default set to ${defaultEnabled ? 'enabled' : 'disabled'}${\n          disabledByEnv ? ' (forced by DISABLE_VECTOR_SEARCH_AUTOINDEXING)' : ''\n        }.`,\n      )\n    } finally {\n      const disposable = container as unknown as { dispose?: () => Promise<void> }\n      if (typeof disposable.dispose === 'function') {\n        await disposable.dispose()\n      }\n    }\n  },\n}\n\nconst help: ModuleCli = {\n  command: 'help',\n  async run() {\n    console.log('\u2699\uFE0F Configs CLI')\n    console.log('')\n    console.log('\uD83D\uDE80 Usage: yarn mercato configs restore-defaults')\n    console.log('  Ensures global module configuration defaults exist.')\n    console.log('')\n    printCacheHelp()\n  },\n}\n\nconst cacheCommand: ModuleCli = {\n  command: 'cache',\n  async run(rest) {\n    const [subcommand, ...subRest] = rest\n    const args = parseArgs(subRest)\n\n    if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {\n      printCacheHelp()\n      return\n    }\n\n    if (subcommand === 'stats') {\n      await runCacheStats(args)\n      return\n    }\n\n    if (subcommand === 'purge') {\n      await runCachePurge(args)\n      return\n    }\n\n    if (subcommand === 'structural') {\n      await runStructuralCachePurge(args)\n      return\n    }\n\n    throw new Error(`Unknown cache subcommand \"${subcommand}\".`)\n  },\n}\n\nexport default [restoreDefaults, cacheCommand, help]\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/configs/lib/cache-cli.js

@@ -0,0 +1,143 @@
+import { collectCrudCacheStats, purgeCrudCacheSegment } from "@open-mercato/shared/lib/crud/cache-stats";
+function normalizeUnique(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    normalized.push(trimmed);
+  }
+  return normalized;
+}
+async function deleteKeys(cache, keys) {
+  let deleted = 0;
+  for (const key of keys) {
+    const removed = await cache.delete(key);
+    if (removed) deleted += 1;
+  }
+  return deleted;
+}
+async function resolveIdentifierKeys(cache, ids) {
+  const matches = /* @__PURE__ */ new Set();
+  for (const id of normalizeUnique(ids)) {
+    const keys = await cache.keys(`*${id}*`);
+    for (const key of keys) matches.add(key);
+  }
+  return Array.from(matches).sort((a, b) => a.localeCompare(b));
+}
+async function collectCacheStats(cache) {
+  const stats = await collectCrudCacheStats(cache);
+  return {
+    generatedAt: stats.generatedAt,
+    totalKeys: stats.totalKeys,
+    segments: stats.segments.map((segment) => ({
+      segment: segment.segment,
+      keyCount: segment.keyCount,
+      method: segment.method,
+      path: segment.path,
+      resource: segment.resource
+    }))
+  };
+}
+async function previewCachePurge(cache, request) {
+  if (request.kind === "all") {
+    const keys2 = (await cache.keys()).sort((a, b) => a.localeCompare(b));
+    return { deleted: keys2.length, keys: keys2, note: null };
+  }
+  if (request.kind === "segment") {
+    const stats = await collectCrudCacheStats(cache);
+    const target = stats.segments.find((segment) => segment.segment === request.segment);
+    return {
+      deleted: target?.keys.length ?? 0,
+      keys: (target?.keys ?? []).slice().sort((a, b) => a.localeCompare(b)),
+      note: target ? null : `Cache segment "${request.segment}" was not found in this scope.`
+    };
+  }
+  if (request.kind === "tags") {
+    return {
+      deleted: 0,
+      keys: [],
+      note: "Tag purges do not expose matching keys through the cache interface. Run without `--dry-run` to execute."
+    };
+  }
+  if (request.kind === "keys") {
+    const requested = normalizeUnique(request.keys);
+    const existingKeys = await cache.keys();
+    const existingSet = new Set(existingKeys);
+    const keys2 = requested.filter((key) => existingSet.has(key));
+    return {
+      deleted: keys2.length,
+      keys: keys2,
+      note: keys2.length === requested.length ? null : "Some requested keys were not present in this scope."
+    };
+  }
+  if (request.kind === "ids") {
+    const keys2 = await resolveIdentifierKeys(cache, request.ids);
+    return {
+      deleted: keys2.length,
+      keys: keys2,
+      note: keys2.length > 0 ? null : "No cache keys matched the requested identifier tokens."
+    };
+  }
+  const keys = (await cache.keys(request.pattern)).sort((a, b) => a.localeCompare(b));
+  return {
+    deleted: keys.length,
+    keys,
+    note: keys.length > 0 ? null : `No cache keys matched pattern "${request.pattern}".`
+  };
+}
+async function executeCachePurge(cache, request) {
+  if (request.kind === "all") {
+    const keys2 = (await cache.keys()).sort((a, b) => a.localeCompare(b));
+    const deleted2 = await cache.clear();
+    return { deleted: deleted2, keys: keys2, note: null };
+  }
+  if (request.kind === "segment") {
+    const result = await purgeCrudCacheSegment(cache, request.segment);
+    return {
+      deleted: result.deleted,
+      keys: result.keys.slice().sort((a, b) => a.localeCompare(b)),
+      note: result.keys.length > 0 ? null : `Cache segment "${request.segment}" was not found in this scope.`
+    };
+  }
+  if (request.kind === "tags") {
+    const deleted2 = await cache.deleteByTags(normalizeUnique(request.tags));
+    return {
+      deleted: deleted2,
+      keys: [],
+      note: "Tag purges report counts only because the cache interface does not expose tag-to-key listings."
+    };
+  }
+  if (request.kind === "keys") {
+    const preview = await previewCachePurge(cache, request);
+    const deleted2 = await deleteKeys(cache, preview.keys);
+    return {
+      deleted: deleted2,
+      keys: preview.keys,
+      note: preview.note
+    };
+  }
+  if (request.kind === "ids") {
+    const keys2 = await resolveIdentifierKeys(cache, request.ids);
+    const deleted2 = await deleteKeys(cache, keys2);
+    return {
+      deleted: deleted2,
+      keys: keys2,
+      note: keys2.length > 0 ? null : "No cache keys matched the requested identifier tokens."
+    };
+  }
+  const keys = (await cache.keys(request.pattern)).sort((a, b) => a.localeCompare(b));
+  const deleted = await deleteKeys(cache, keys);
+  return {
+    deleted,
+    keys,
+    note: keys.length > 0 ? null : `No cache keys matched pattern "${request.pattern}".`
+  };
+}
+export {
+  collectCacheStats,
+  executeCachePurge,
+  previewCachePurge
+};
+//# sourceMappingURL=cache-cli.js.map

package/dist/modules/configs/lib/cache-cli.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/configs/lib/cache-cli.ts"],
+  "sourcesContent": ["import type { CacheStrategy } from '@open-mercato/cache'\nimport { collectCrudCacheStats, purgeCrudCacheSegment } from '@open-mercato/shared/lib/crud/cache-stats'\n\nexport type CachePurgeRequest =\n  | { kind: 'all' }\n  | { kind: 'segment'; segment: string }\n  | { kind: 'tags'; tags: string[] }\n  | { kind: 'keys'; keys: string[] }\n  | { kind: 'ids'; ids: string[] }\n  | { kind: 'pattern'; pattern: string }\n\nexport type CachePurgeResult = {\n  deleted: number\n  keys: string[]\n  note: string | null\n}\n\nfunction normalizeUnique(values: string[]): string[] {\n  const seen = new Set<string>()\n  const normalized: string[] = []\n  for (const value of values) {\n    const trimmed = value.trim()\n    if (!trimmed || seen.has(trimmed)) continue\n    seen.add(trimmed)\n    normalized.push(trimmed)\n  }\n  return normalized\n}\n\nasync function deleteKeys(cache: CacheStrategy, keys: string[]): Promise<number> {\n  let deleted = 0\n  for (const key of keys) {\n    const removed = await cache.delete(key)\n    if (removed) deleted += 1\n  }\n  return deleted\n}\n\nasync function resolveIdentifierKeys(cache: CacheStrategy, ids: string[]): Promise<string[]> {\n  const matches = new Set<string>()\n  for (const id of normalizeUnique(ids)) {\n    const keys = await cache.keys(`*${id}*`)\n    for (const key of keys) matches.add(key)\n  }\n  return Array.from(matches).sort((a, b) => a.localeCompare(b))\n}\n\nexport async function collectCacheStats(cache: CacheStrategy) {\n  const stats = await collectCrudCacheStats(cache)\n  return {\n    generatedAt: stats.generatedAt,\n    totalKeys: stats.totalKeys,\n    segments: stats.segments.map((segment) => ({\n      segment: segment.segment,\n      keyCount: segment.keyCount,\n      method: segment.method,\n      path: segment.path,\n      resource: segment.resource,\n    })),\n  }\n}\n\nexport async function previewCachePurge(\n  cache: CacheStrategy,\n  request: CachePurgeRequest,\n): Promise<CachePurgeResult> {\n  if (request.kind === 'all') {\n    const keys = (await cache.keys()).sort((a, b) => a.localeCompare(b))\n    return { deleted: keys.length, keys, note: null }\n  }\n\n  if (request.kind === 'segment') {\n    const stats = await collectCrudCacheStats(cache)\n    const target = stats.segments.find((segment) => segment.segment === request.segment)\n    return {\n      deleted: target?.keys.length ?? 0,\n      keys: (target?.keys ?? []).slice().sort((a, b) => a.localeCompare(b)),\n      note: target ? null : `Cache segment \"${request.segment}\" was not found in this scope.`,\n    }\n  }\n\n  if (request.kind === 'tags') {\n    return {\n      deleted: 0,\n      keys: [],\n      note: 'Tag purges do not expose matching keys through the cache interface. Run without `--dry-run` to execute.',\n    }\n  }\n\n  if (request.kind === 'keys') {\n    const requested = normalizeUnique(request.keys)\n    const existingKeys = await cache.keys()\n    const existingSet = new Set(existingKeys)\n    const keys = requested.filter((key) => existingSet.has(key))\n    return {\n      deleted: keys.length,\n      keys,\n      note: keys.length === requested.length ? null : 'Some requested keys were not present in this scope.',\n    }\n  }\n\n  if (request.kind === 'ids') {\n    const keys = await resolveIdentifierKeys(cache, request.ids)\n    return {\n      deleted: keys.length,\n      keys,\n      note: keys.length > 0 ? null : 'No cache keys matched the requested identifier tokens.',\n    }\n  }\n\n  const keys = (await cache.keys(request.pattern)).sort((a, b) => a.localeCompare(b))\n  return {\n    deleted: keys.length,\n    keys,\n    note: keys.length > 0 ? null : `No cache keys matched pattern \"${request.pattern}\".`,\n  }\n}\n\nexport async function executeCachePurge(\n  cache: CacheStrategy,\n  request: CachePurgeRequest,\n): Promise<CachePurgeResult> {\n  if (request.kind === 'all') {\n    const keys = (await cache.keys()).sort((a, b) => a.localeCompare(b))\n    const deleted = await cache.clear()\n    return { deleted, keys, note: null }\n  }\n\n  if (request.kind === 'segment') {\n    const result = await purgeCrudCacheSegment(cache, request.segment)\n    return {\n      deleted: result.deleted,\n      keys: result.keys.slice().sort((a, b) => a.localeCompare(b)),\n      note: result.keys.length > 0 ? null : `Cache segment \"${request.segment}\" was not found in this scope.`,\n    }\n  }\n\n  if (request.kind === 'tags') {\n    const deleted = await cache.deleteByTags(normalizeUnique(request.tags))\n    return {\n      deleted,\n      keys: [],\n      note: 'Tag purges report counts only because the cache interface does not expose tag-to-key listings.',\n    }\n  }\n\n  if (request.kind === 'keys') {\n    const preview = await previewCachePurge(cache, request)\n    const deleted = await deleteKeys(cache, preview.keys)\n    return {\n      deleted,\n      keys: preview.keys,\n      note: preview.note,\n    }\n  }\n\n  if (request.kind === 'ids') {\n    const keys = await resolveIdentifierKeys(cache, request.ids)\n    const deleted = await deleteKeys(cache, keys)\n    return {\n      deleted,\n      keys,\n      note: keys.length > 0 ? null : 'No cache keys matched the requested identifier tokens.',\n    }\n  }\n\n  const keys = (await cache.keys(request.pattern)).sort((a, b) => a.localeCompare(b))\n  const deleted = await deleteKeys(cache, keys)\n  return {\n    deleted,\n    keys,\n    note: keys.length > 0 ? null : `No cache keys matched pattern \"${request.pattern}\".`,\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["keys", "deleted"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.4.11-develop.1416.adda6008da",
+  "version": "0.4.11-develop.1418.27a299bdaf",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -230,10 +230,10 @@
     "ts-pattern": "^5.0.0"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.4.11-develop.1416.adda6008da"
+    "@open-mercato/shared": "0.4.11-develop.1418.27a299bdaf"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.4.11-develop.1416.adda6008da",
+    "@open-mercato/shared": "0.4.11-develop.1418.27a299bdaf",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/modules/configs/cli.ts

@@ -1,8 +1,262 @@
 import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { runWithCacheTenant, type CacheStrategy } from '@open-mercato/cache'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import type { ModuleConfigService } from './lib/module-config-service'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import { DEFAULT_NOTIFICATION_DELIVERY_CONFIG, NOTIFICATIONS_DELIVERY_CONFIG_KEY } from '../notifications/lib/deliveryConfig'
+import { Tenant } from '../directory/data/entities'
+import {
+  collectCacheStats,
+  executeCachePurge,
+  previewCachePurge,
+  type CachePurgeRequest,
+} from './lib/cache-cli'
+
+type ParsedArgs = Record<string, string | boolean>
+
+type CacheScope = {
+  label: string
+  tenantId: string | null
+}
+
+function parseArgs(rest: string[]): ParsedArgs {
+  const args: ParsedArgs = {}
+  for (let i = 0; i < rest.length; i += 1) {
+    const part = rest[i]
+    if (!part?.startsWith('--')) continue
+    const [rawKey, rawValue] = part.slice(2).split('=')
+    if (!rawKey) continue
+    if (rawValue !== undefined) {
+      args[rawKey] = rawValue
+    } else if (i + 1 < rest.length && !rest[i + 1]!.startsWith('--')) {
+      args[rawKey] = rest[i + 1]!
+      i += 1
+    } else {
+      args[rawKey] = true
+    }
+  }
+  return args
+}
+
+function stringOption(args: ParsedArgs, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const raw = args[key]
+    if (typeof raw !== 'string') continue
+    const trimmed = raw.trim()
+    if (trimmed.length > 0) return trimmed
+  }
+  return undefined
+}
+
+function flagEnabled(args: ParsedArgs, ...keys: string[]): boolean {
+  for (const key of keys) {
+    const raw = args[key]
+    if (raw === undefined) continue
+    if (raw === true) return true
+    if (typeof raw === 'string') {
+      const parsed = parseBooleanToken(raw)
+      return parsed === null ? true : parsed
+    }
+  }
+  return false
+}
+
+function splitListOption(raw: string | undefined): string[] {
+  if (!raw) return []
+  const seen = new Set<string>()
+  const values: string[] = []
+  for (const item of raw.split(',')) {
+    const trimmed = item.trim()
+    if (!trimmed || seen.has(trimmed)) continue
+    seen.add(trimmed)
+    values.push(trimmed)
+  }
+  return values
+}
+
+async function resolveCacheScopes(
+  em: EntityManager,
+  args: ParsedArgs,
+): Promise<CacheScope[]> {
+  const explicitTenantId = stringOption(args, 'tenant', 'tenantId')
+  const globalOnly = flagEnabled(args, 'global')
+  const allTenants = flagEnabled(args, 'all-tenants', 'allTenants')
+
+  if (explicitTenantId && globalOnly) {
+    throw new Error('Cannot combine `--tenant` with `--global`.')
+  }
+  if (explicitTenantId && allTenants) {
+    throw new Error('Cannot combine `--tenant` with `--all-tenants`.')
+  }
+  if (globalOnly && allTenants) {
+    throw new Error('Cannot combine `--global` with `--all-tenants`.')
+  }
+
+  if (explicitTenantId) {
+    return [{ label: `tenant:${explicitTenantId}`, tenantId: explicitTenantId }]
+  }
+
+  if (globalOnly) {
+    return [{ label: 'global', tenantId: null }]
+  }
+
+  if (!allTenants) {
+    return [{ label: 'global', tenantId: null }]
+  }
+
+  const tenants = await em.find(Tenant, { deletedAt: null }, { orderBy: { name: 'asc' } })
+  const scopes: CacheScope[] = [{ label: 'global', tenantId: null }]
+  const seen = new Set<string>()
+  for (const tenant of tenants) {
+    const tenantId = typeof tenant.id === 'string' ? tenant.id : ''
+    if (!tenantId || seen.has(tenantId)) continue
+    seen.add(tenantId)
+    scopes.push({ label: `tenant:${tenantId}`, tenantId })
+  }
+  return scopes
+}
+
+function resolveCachePurgeRequest(args: ParsedArgs): CachePurgeRequest {
+  if (flagEnabled(args, 'all')) return { kind: 'all' }
+
+  const segment = stringOption(args, 'segment')
+  if (segment) return { kind: 'segment', segment }
+
+  const tags = splitListOption(stringOption(args, 'tag', 'tags'))
+  if (tags.length > 0) return { kind: 'tags', tags }
+
+  const keys = splitListOption(stringOption(args, 'key', 'keys'))
+  if (keys.length > 0) return { kind: 'keys', keys }
+
+  const ids = splitListOption(stringOption(args, 'id', 'ids'))
+  if (ids.length > 0) return { kind: 'ids', ids }
+
+  const pattern = stringOption(args, 'pattern')
+  if (pattern) return { kind: 'pattern', pattern }
+
+  throw new Error(
+    'Choose a purge target: `--all`, `--segment <id>`, `--tag <tag1,tag2>`, `--key <key1,key2>`, `--id <token1,token2>`, or `--pattern <glob>`.',
+  )
+}
+
+function printCacheHelp() {
+  console.log('🧹 Cache CLI')
+  console.log('')
+  console.log('🚀 Usage:')
+  console.log('  yarn mercato configs cache stats [--tenant <id> | --global | --all-tenants] [--json]')
+  console.log('  yarn mercato configs cache purge --all [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('  yarn mercato configs cache purge --segment <segment> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('  yarn mercato configs cache purge --tag <tag1,tag2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('  yarn mercato configs cache purge --key <key1,key2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('  yarn mercato configs cache purge --id <token1,token2> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('  yarn mercato configs cache purge --pattern <glob> [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('  yarn mercato configs cache structural [--tenant <id> | --global | --all-tenants] [--dry-run] [--json]')
+  console.log('')
+  console.log('ℹ️ Notes:')
+  console.log('  `stats` mirrors the cache admin page segment overview for CRUD/widget caches.')
+  console.log('  `purge --id` removes every key whose name contains the provided token (for example a user id or entity id).')
+  console.log('  `structural` targets navigation caches (`nav:*`) and is the recommended post-step after module/sidebar structure changes.')
+  console.log('  When no scope flag is supplied, this command uses the global cache scope only.')
+}
+
+async function disposeContainer(container: unknown) {
+  const disposable = container as { dispose?: () => Promise<void> }
+  if (typeof disposable.dispose === 'function') {
+    await disposable.dispose()
+  }
+}
+
+async function runCacheStats(args: ParsedArgs) {
+  const json = flagEnabled(args, 'json')
+  const container = await createRequestContainer()
+  try {
+    const em = container.resolve('em') as EntityManager
+    const cache = container.resolve('cache') as CacheStrategy
+    const scopes = await resolveCacheScopes(em, args)
+    const results = []
+    for (const scope of scopes) {
+      const stats = await runWithCacheTenant(scope.tenantId, async () => collectCacheStats(cache))
+      results.push({ scope: scope.label, ...stats })
+    }
+
+    if (json) {
+      console.log(JSON.stringify(results, null, 2))
+      return
+    }
+
+    for (const result of results) {
+      console.log(`🔎 [cache] scope=${result.scope} totalKeys=${result.totalKeys} generatedAt=${result.generatedAt}`)
+      if (result.segments.length === 0) {
+        console.log('  ∅ segments: none')
+        continue
+      }
+      for (const segment of result.segments) {
+        console.log(`  • ${segment.segment} (${segment.keyCount})${segment.path ? ` ${segment.path}` : ''}`)
+      }
+    }
+  } finally {
+    await disposeContainer(container)
+  }
+}
+
+async function runCachePurge(args: ParsedArgs) {
+  const json = flagEnabled(args, 'json')
+  const quiet = flagEnabled(args, 'quiet')
+  const dryRun = flagEnabled(args, 'dry-run', 'dryRun')
+  const request = resolveCachePurgeRequest(args)
+  const container = await createRequestContainer()
+  try {
+    const em = container.resolve('em') as EntityManager
+    const cache = container.resolve('cache') as CacheStrategy
+    const scopes = await resolveCacheScopes(em, args)
+    const results = []
+
+    for (const scope of scopes) {
+      const result = await runWithCacheTenant(scope.tenantId, async () =>
+        dryRun ? previewCachePurge(cache, request) : executeCachePurge(cache, request)
+      )
+      results.push({
+        scope: scope.label,
+        dryRun,
+        request,
+        deleted: result.deleted,
+        keyCount: result.keys.length,
+        keys: result.keys,
+        note: result.note,
+      })
+    }
+
+    if (json) {
+      console.log(JSON.stringify(results, null, 2))
+      return
+    }
+
+    if (quiet) {
+      return
+    }
+
+    for (const result of results) {
+      console.log(`${result.dryRun ? '🧪' : '🧹'} [cache] scope=${result.scope} deleted=${result.deleted}${result.dryRun ? ' (dry-run)' : ''}`)
+      if (result.note) console.log(`  ℹ️ note: ${result.note}`)
+      if (result.keys.length > 0) {
+        for (const key of result.keys) {
+          console.log(`  • ${key}`)
+        }
+      }
+    }
+  } finally {
+    await disposeContainer(container)
+  }
+}
+
+async function runStructuralCachePurge(args: ParsedArgs) {
+  const nextArgs: ParsedArgs = {
+    ...args,
+    pattern: 'nav:*',
+  }
+  await runCachePurge(nextArgs)
+}
 
 function envDisablesAutoIndexing(): boolean {
   const raw = process.env.DISABLE_VECTOR_SEARCH_AUTOINDEXING
@@ -57,9 +311,43 @@ const restoreDefaults: ModuleCli = {
 const help: ModuleCli = {
   command: 'help',
   async run() {
-    console.log('Usage: yarn mercato configs restore-defaults')
+    console.log('⚙️ Configs CLI')
+    console.log('')
+    console.log('🚀 Usage: yarn mercato configs restore-defaults')
     console.log('  Ensures global module configuration defaults exist.')
+    console.log('')
+    printCacheHelp()
+  },
+}
+
+const cacheCommand: ModuleCli = {
+  command: 'cache',
+  async run(rest) {
+    const [subcommand, ...subRest] = rest
+    const args = parseArgs(subRest)
+
+    if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+      printCacheHelp()
+      return
+    }
+
+    if (subcommand === 'stats') {
+      await runCacheStats(args)
+      return
+    }
+
+    if (subcommand === 'purge') {
+      await runCachePurge(args)
+      return
+    }
+
+    if (subcommand === 'structural') {
+      await runStructuralCachePurge(args)
+      return
+    }
+
+    throw new Error(`Unknown cache subcommand "${subcommand}".`)
   },
 }
 
-export default [restoreDefaults, help]
+export default [restoreDefaults, cacheCommand, help]

package/src/modules/configs/lib/cache-cli.ts

@@ -0,0 +1,174 @@
+import type { CacheStrategy } from '@open-mercato/cache'
+import { collectCrudCacheStats, purgeCrudCacheSegment } from '@open-mercato/shared/lib/crud/cache-stats'
+
+export type CachePurgeRequest =
+  | { kind: 'all' }
+  | { kind: 'segment'; segment: string }
+  | { kind: 'tags'; tags: string[] }
+  | { kind: 'keys'; keys: string[] }
+  | { kind: 'ids'; ids: string[] }
+  | { kind: 'pattern'; pattern: string }
+
+export type CachePurgeResult = {
+  deleted: number
+  keys: string[]
+  note: string | null
+}
+
+function normalizeUnique(values: string[]): string[] {
+  const seen = new Set<string>()
+  const normalized: string[] = []
+  for (const value of values) {
+    const trimmed = value.trim()
+    if (!trimmed || seen.has(trimmed)) continue
+    seen.add(trimmed)
+    normalized.push(trimmed)
+  }
+  return normalized
+}
+
+async function deleteKeys(cache: CacheStrategy, keys: string[]): Promise<number> {
+  let deleted = 0
+  for (const key of keys) {
+    const removed = await cache.delete(key)
+    if (removed) deleted += 1
+  }
+  return deleted
+}
+
+async function resolveIdentifierKeys(cache: CacheStrategy, ids: string[]): Promise<string[]> {
+  const matches = new Set<string>()
+  for (const id of normalizeUnique(ids)) {
+    const keys = await cache.keys(`*${id}*`)
+    for (const key of keys) matches.add(key)
+  }
+  return Array.from(matches).sort((a, b) => a.localeCompare(b))
+}
+
+export async function collectCacheStats(cache: CacheStrategy) {
+  const stats = await collectCrudCacheStats(cache)
+  return {
+    generatedAt: stats.generatedAt,
+    totalKeys: stats.totalKeys,
+    segments: stats.segments.map((segment) => ({
+      segment: segment.segment,
+      keyCount: segment.keyCount,
+      method: segment.method,
+      path: segment.path,
+      resource: segment.resource,
+    })),
+  }
+}
+
+export async function previewCachePurge(
+  cache: CacheStrategy,
+  request: CachePurgeRequest,
+): Promise<CachePurgeResult> {
+  if (request.kind === 'all') {
+    const keys = (await cache.keys()).sort((a, b) => a.localeCompare(b))
+    return { deleted: keys.length, keys, note: null }
+  }
+
+  if (request.kind === 'segment') {
+    const stats = await collectCrudCacheStats(cache)
+    const target = stats.segments.find((segment) => segment.segment === request.segment)
+    return {
+      deleted: target?.keys.length ?? 0,
+      keys: (target?.keys ?? []).slice().sort((a, b) => a.localeCompare(b)),
+      note: target ? null : `Cache segment "${request.segment}" was not found in this scope.`,
+    }
+  }
+
+  if (request.kind === 'tags') {
+    return {
+      deleted: 0,
+      keys: [],
+      note: 'Tag purges do not expose matching keys through the cache interface. Run without `--dry-run` to execute.',
+    }
+  }
+
+  if (request.kind === 'keys') {
+    const requested = normalizeUnique(request.keys)
+    const existingKeys = await cache.keys()
+    const existingSet = new Set(existingKeys)
+    const keys = requested.filter((key) => existingSet.has(key))
+    return {
+      deleted: keys.length,
+      keys,
+      note: keys.length === requested.length ? null : 'Some requested keys were not present in this scope.',
+    }
+  }
+
+  if (request.kind === 'ids') {
+    const keys = await resolveIdentifierKeys(cache, request.ids)
+    return {
+      deleted: keys.length,
+      keys,
+      note: keys.length > 0 ? null : 'No cache keys matched the requested identifier tokens.',
+    }
+  }
+
+  const keys = (await cache.keys(request.pattern)).sort((a, b) => a.localeCompare(b))
+  return {
+    deleted: keys.length,
+    keys,
+    note: keys.length > 0 ? null : `No cache keys matched pattern "${request.pattern}".`,
+  }
+}
+
+export async function executeCachePurge(
+  cache: CacheStrategy,
+  request: CachePurgeRequest,
+): Promise<CachePurgeResult> {
+  if (request.kind === 'all') {
+    const keys = (await cache.keys()).sort((a, b) => a.localeCompare(b))
+    const deleted = await cache.clear()
+    return { deleted, keys, note: null }
+  }
+
+  if (request.kind === 'segment') {
+    const result = await purgeCrudCacheSegment(cache, request.segment)
+    return {
+      deleted: result.deleted,
+      keys: result.keys.slice().sort((a, b) => a.localeCompare(b)),
+      note: result.keys.length > 0 ? null : `Cache segment "${request.segment}" was not found in this scope.`,
+    }
+  }
+
+  if (request.kind === 'tags') {
+    const deleted = await cache.deleteByTags(normalizeUnique(request.tags))
+    return {
+      deleted,
+      keys: [],
+      note: 'Tag purges report counts only because the cache interface does not expose tag-to-key listings.',
+    }
+  }
+
+  if (request.kind === 'keys') {
+    const preview = await previewCachePurge(cache, request)
+    const deleted = await deleteKeys(cache, preview.keys)
+    return {
+      deleted,
+      keys: preview.keys,
+      note: preview.note,
+    }
+  }
+
+  if (request.kind === 'ids') {
+    const keys = await resolveIdentifierKeys(cache, request.ids)
+    const deleted = await deleteKeys(cache, keys)
+    return {
+      deleted,
+      keys,
+      note: keys.length > 0 ? null : 'No cache keys matched the requested identifier tokens.',
+    }
+  }
+
+  const keys = (await cache.keys(request.pattern)).sort((a, b) => a.localeCompare(b))
+  const deleted = await deleteKeys(cache, keys)
+  return {
+    deleted,
+    keys,
+    note: keys.length > 0 ? null : `No cache keys matched pattern "${request.pattern}".`,
+  }
+}

package/src/modules/customers/i18n/de.json

@@ -211,6 +211,7 @@
   "customers.companies.form.submit": "Unternehmen erstellen",
   "customers.companies.form.success": "Unternehmen erstellt",
   "customers.companies.form.updateSuccess": "Unternehmen aktualisiert.",
+  "customers.companies.list.actions.bulkDelete": "Auswahl löschen",
   "customers.companies.list.actions.delete": "Löschen",
   "customers.companies.list.actions.new": "Neues Unternehmen",
   "customers.companies.list.actions.openInNewTab": "In neuem Tab öffnen",
@@ -488,6 +489,7 @@
   "customers.errors.company_required": "Unternehmens-ID ist erforderlich",
   "customers.errors.deal_required": "Deal-ID ist erforderlich",
   "customers.errors.interaction_required": "Interaction-ID ist erforderlich",
+  "customers.errors.internalError": "Interner Serverfehler",
   "customers.errors.invalid_query": "Ungültige Abfrageparameter",
   "customers.errors.lookup_failed": "Lexikon konnte nicht geladen werden",
   "customers.errors.organization_forbidden": "Organisation nicht verfügbar",
@@ -506,6 +508,7 @@
   "customers.errors.todo_unlink_failed": "To-do-Verknüpfung konnte nicht gelöst werden",
   "customers.errors.unassign_failed": "Tag konnte nicht entfernt werden",
   "customers.errors.unauthorized": "Nicht autorisiert",
+  "customers.errors.validationFailed": "Validierung fehlgeschlagen",
   "customers.interactions.cancel.confirm": "Cancel this interaction?",
   "customers.interactions.cancel.error": "Failed to cancel interaction.",
   "customers.interactions.cancel.success": "Interaction canceled.",
@@ -720,7 +723,9 @@
   "customers.people.detail.fields.jobTitle": "Position",
   "customers.people.detail.fields.lifecycleStage": "Lebenszyklusphase",
   "customers.people.detail.fields.linkedIn": "LinkedIn",
+  "customers.people.detail.fields.seniority": "Senioritätsstufe",
   "customers.people.detail.fields.source": "Quelle",
+  "customers.people.detail.fields.timezone": "Zeitzone",
   "customers.people.detail.fields.twitter": "Twitter",
   "customers.people.detail.highlights.company": "Unternehmen",
   "customers.people.detail.highlights.nextInteraction": "Nächste Interaktion",
@@ -964,6 +969,7 @@
   "customers.people.form.phoneChecking": "Prüfe auf bestehende Telefonnummern…",
   "customers.people.form.phoneDuplicateLink": "Datensatz öffnen",
   "customers.people.form.phoneDuplicateNotice": "Diese Telefonnummer ist bereits {{name}} zugeordnet.",
+  "customers.people.form.preferredName": "Bevorzugter Name",
   "customers.people.form.primaryEmail": "E-Mail",
   "customers.people.form.primaryEmailPlaceholder": "name@beispiel.de",
   "customers.people.form.primaryPhone": "Telefon",

package/src/modules/customers/i18n/en.json

@@ -211,6 +211,7 @@
   "customers.companies.form.submit": "Create Company",
   "customers.companies.form.success": "Company created",
   "customers.companies.form.updateSuccess": "Company updated.",
+  "customers.companies.list.actions.bulkDelete": "Delete selected",
   "customers.companies.list.actions.delete": "Delete",
   "customers.companies.list.actions.new": "New Company",
   "customers.companies.list.actions.openInNewTab": "Open in new tab",
@@ -488,6 +489,7 @@
   "customers.errors.company_required": "Company id is required",
   "customers.errors.deal_required": "Deal id is required",
   "customers.errors.interaction_required": "Interaction id is required",
+  "customers.errors.internalError": "Internal server error",
   "customers.errors.invalid_query": "Invalid query parameters",
   "customers.errors.lookup_failed": "Failed to load dictionary entries",
   "customers.errors.organization_forbidden": "Organization not accessible",
@@ -506,6 +508,7 @@
   "customers.errors.todo_unlink_failed": "Failed to unlink todo",
   "customers.errors.unassign_failed": "Failed to unassign tag",
   "customers.errors.unauthorized": "Unauthorized",
+  "customers.errors.validationFailed": "Validation failed",
   "customers.interactions.cancel.confirm": "Cancel this interaction?",
   "customers.interactions.cancel.error": "Failed to cancel interaction.",
   "customers.interactions.cancel.success": "Interaction canceled.",
@@ -720,7 +723,9 @@
   "customers.people.detail.fields.jobTitle": "Job title",
   "customers.people.detail.fields.lifecycleStage": "Lifecycle stage",
   "customers.people.detail.fields.linkedIn": "LinkedIn",
+  "customers.people.detail.fields.seniority": "Seniority",
   "customers.people.detail.fields.source": "Source",
+  "customers.people.detail.fields.timezone": "Timezone",
   "customers.people.detail.fields.twitter": "Twitter",
   "customers.people.detail.highlights.company": "Company",
   "customers.people.detail.highlights.nextInteraction": "Next interaction",
@@ -964,6 +969,7 @@
   "customers.people.form.phoneChecking": "Checking for matching phone numbers…",
   "customers.people.form.phoneDuplicateLink": "Open record",
   "customers.people.form.phoneDuplicateNotice": "This phone number is already assigned to {{name}}.",
+  "customers.people.form.preferredName": "Preferred name",
   "customers.people.form.primaryEmail": "Primary email",
   "customers.people.form.primaryEmailPlaceholder": "name@example.com",
   "customers.people.form.primaryPhone": "Primary phone",

package/src/modules/customers/i18n/es.json

@@ -211,6 +211,7 @@
   "customers.companies.form.submit": "Crear empresa",
   "customers.companies.form.success": "Empresa creada",
   "customers.companies.form.updateSuccess": "Empresa actualizada.",
+  "customers.companies.list.actions.bulkDelete": "Eliminar seleccionados",
   "customers.companies.list.actions.delete": "Eliminar",
   "customers.companies.list.actions.new": "Nueva empresa",
   "customers.companies.list.actions.openInNewTab": "Abrir en nueva pestaña",
@@ -488,6 +489,7 @@
   "customers.errors.company_required": "Se requiere el ID de la empresa",
   "customers.errors.deal_required": "Se requiere el ID de la oportunidad",
   "customers.errors.interaction_required": "Se requiere el ID de la interaccion",
+  "customers.errors.internalError": "Error interno del servidor",
   "customers.errors.invalid_query": "Parámetros de consulta no válidos",
   "customers.errors.lookup_failed": "No se pudo cargar el diccionario",
   "customers.errors.organization_forbidden": "Organización no accesible",
@@ -506,6 +508,7 @@
   "customers.errors.todo_unlink_failed": "No se pudo desvincular la tarea",
   "customers.errors.unassign_failed": "No se pudo quitar la etiqueta",
   "customers.errors.unauthorized": "No autorizado",
+  "customers.errors.validationFailed": "La validación falló",
   "customers.interactions.cancel.confirm": "Cancel this interaction?",
   "customers.interactions.cancel.error": "Failed to cancel interaction.",
   "customers.interactions.cancel.success": "Interaction canceled.",
@@ -720,7 +723,9 @@
   "customers.people.detail.fields.jobTitle": "Cargo",
   "customers.people.detail.fields.lifecycleStage": "Etapa",
   "customers.people.detail.fields.linkedIn": "LinkedIn",
+  "customers.people.detail.fields.seniority": "Seniority",
   "customers.people.detail.fields.source": "Origen",
+  "customers.people.detail.fields.timezone": "Zona horaria",
   "customers.people.detail.fields.twitter": "Twitter",
   "customers.people.detail.highlights.company": "Empresa",
   "customers.people.detail.highlights.nextInteraction": "Próxima interacción",
@@ -964,6 +969,7 @@
   "customers.people.form.phoneChecking": "Comprobando si el número de teléfono ya existe…",
   "customers.people.form.phoneDuplicateLink": "Abrir registro",
   "customers.people.form.phoneDuplicateNotice": "Este número de teléfono ya está asignado a {{name}}.",
+  "customers.people.form.preferredName": "Nombre preferido",
   "customers.people.form.primaryEmail": "Correo electrónico",
   "customers.people.form.primaryEmailPlaceholder": "nombre@ejemplo.com",
   "customers.people.form.primaryPhone": "Teléfono",

package/src/modules/customers/i18n/pl.json

@@ -211,6 +211,7 @@
   "customers.companies.form.submit": "Utwórz firmę",
   "customers.companies.form.success": "Firma została utworzona",
   "customers.companies.form.updateSuccess": "Firma została zaktualizowana.",
+  "customers.companies.list.actions.bulkDelete": "Usuń zaznaczone",
   "customers.companies.list.actions.delete": "Usuń",
   "customers.companies.list.actions.new": "Nowa firma",
   "customers.companies.list.actions.openInNewTab": "Otwórz w nowej karcie",
@@ -488,6 +489,7 @@
   "customers.errors.company_required": "Wymagany identyfikator firmy",
   "customers.errors.deal_required": "Wymagany identyfikator szansy",
   "customers.errors.interaction_required": "Wymagany identyfikator interakcji",
+  "customers.errors.internalError": "Wewnętrzny błąd serwera",
   "customers.errors.invalid_query": "Nieprawidłowe parametry zapytania",
   "customers.errors.lookup_failed": "Nie udało się załadować słownika",
   "customers.errors.organization_forbidden": "Organizacja jest niedostępna",
@@ -506,6 +508,7 @@
   "customers.errors.todo_unlink_failed": "Nie udało się odpiąć zadania",
   "customers.errors.unassign_failed": "Nie udało się odpiąć tagu",
   "customers.errors.unauthorized": "Brak autoryzacji",
+  "customers.errors.validationFailed": "Walidacja nie powiodła się",
   "customers.interactions.cancel.confirm": "Cancel this interaction?",
   "customers.interactions.cancel.error": "Failed to cancel interaction.",
   "customers.interactions.cancel.success": "Interaction canceled.",
@@ -720,7 +723,9 @@
   "customers.people.detail.fields.jobTitle": "Stanowisko",
   "customers.people.detail.fields.lifecycleStage": "Etap cyklu",
   "customers.people.detail.fields.linkedIn": "LinkedIn",
+  "customers.people.detail.fields.seniority": "Poziom seniority",
   "customers.people.detail.fields.source": "Źródło",
+  "customers.people.detail.fields.timezone": "Strefa czasowa",
   "customers.people.detail.fields.twitter": "Twitter",
   "customers.people.detail.highlights.company": "Firma",
   "customers.people.detail.highlights.nextInteraction": "Następna interakcja",
@@ -964,6 +969,7 @@
   "customers.people.form.phoneChecking": "Sprawdzanie, czy numer telefonu jest już używany…",
   "customers.people.form.phoneDuplicateLink": "Otwórz rekord",
   "customers.people.form.phoneDuplicateNotice": "Ten numer telefonu jest już przypisany do {{name}}.",
+  "customers.people.form.preferredName": "Preferowane imię",
   "customers.people.form.primaryEmail": "E-mail",
   "customers.people.form.primaryEmailPlaceholder": "nazwa@example.com",
   "customers.people.form.primaryPhone": "Telefon",