@open-mercato/shared 0.4.2-canary-c02407ff85

package/src/lib/bootstrap/dynamicLoader.ts

@@ -0,0 +1,177 @@
+import type { BootstrapData } from './types'
+import { findAppRoot, type AppRoot } from './appResolver'
+import { registerEntityIds } from '../encryption/entityIds'
+import path from 'node:path'
+import fs from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Compile a TypeScript file to JavaScript using esbuild bundler.
+ * This bundles the file and all its dependencies, handling JSON imports properly.
+ * The compiled file is written next to the source file with a .mjs extension.
+ */
+async function compileAndImport(tsPath: string): Promise<Record<string, unknown>> {
+  const jsPath = tsPath.replace(/\.ts$/, '.mjs')
+
+  // Check if we need to recompile (source newer than compiled)
+  const tsExists = fs.existsSync(tsPath)
+  const jsExists = fs.existsSync(jsPath)
+
+  if (!tsExists) {
+    throw new Error(`Generated file not found: ${tsPath}`)
+  }
+
+  const needsCompile = !jsExists ||
+    fs.statSync(tsPath).mtimeMs > fs.statSync(jsPath).mtimeMs
+
+  if (needsCompile) {
+    // Dynamically import esbuild only when needed
+    const esbuild = await import('esbuild')
+
+    // The app root is 2 levels up from .mercato/generated/
+    const appRoot = path.dirname(path.dirname(path.dirname(tsPath)))
+
+    // Plugin to resolve @/ alias to app root (works for @app modules)
+    const aliasPlugin: import('esbuild').Plugin = {
+      name: 'alias-resolver',
+      setup(build) {
+        // Resolve @/ alias to app root
+        build.onResolve({ filter: /^@\// }, (args) => {
+          const resolved = path.join(appRoot, args.path.slice(2))
+          // Try with .ts extension if base path doesn't exist
+          if (!fs.existsSync(resolved) && fs.existsSync(resolved + '.ts')) {
+            return { path: resolved + '.ts' }
+          }
+          // Also check for /index.ts if it's a directory
+          if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory() && fs.existsSync(path.join(resolved, 'index.ts'))) {
+            return { path: path.join(resolved, 'index.ts') }
+          }
+          return { path: resolved }
+        })
+      },
+    }
+
+    // Plugin to mark non-JSON package imports as external
+    const externalNonJsonPlugin: import('esbuild').Plugin = {
+      name: 'external-non-json',
+      setup(build) {
+        // Mark all package imports as external EXCEPT JSON files
+        build.onResolve({ filter: /^[^./]/ }, (args) => {
+          // If it's a JSON file, let esbuild bundle it
+          if (args.path.endsWith('.json')) {
+            return null // Let esbuild handle it
+          }
+          // Otherwise mark as external
+          return { path: args.path, external: true }
+        })
+      },
+    }
+
+    // Use esbuild.build with bundling to handle JSON imports
+    await esbuild.build({
+      entryPoints: [tsPath],
+      outfile: jsPath,
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      target: 'node18',
+      plugins: [aliasPlugin, externalNonJsonPlugin],
+      // Allow JSON imports
+      loader: { '.json': 'json' },
+    })
+  }
+
+  // Import the compiled JavaScript
+  const fileUrl = pathToFileURL(jsPath).href
+  return import(fileUrl)
+}
+
+
+/**
+ * Dynamically load bootstrap data from a resolved app directory.
+ *
+ * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
+ * Do NOT use this in Next.js bundled code - use static imports instead.
+ *
+ * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
+ * CLI commands are discovered separately via the CLI module system.
+ *
+ * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
+ * @returns The loaded bootstrap data
+ * @throws Error if app root cannot be found or generated files are missing
+ */
+export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+  const resolved: AppRoot | null = appRoot
+    ? {
+        generatedDir: path.join(appRoot, '.mercato', 'generated'),
+        appDir: appRoot,
+        mercatoDir: path.join(appRoot, '.mercato'),
+      }
+    : findAppRoot()
+
+  if (!resolved) {
+    throw new Error(
+      'Could not find app root with .mercato/generated directory. ' +
+        'Make sure you run this command from within a Next.js app directory, ' +
+        'or run "yarn mercato generate" first to create the generated files.',
+    )
+  }
+
+  const { generatedDir } = resolved
+
+  // IMPORTANT: Load entity IDs FIRST and register them before loading modules.
+  // This is because modules (e.g., ce.ts files) use E.xxx.xxx at module scope,
+  // and they need entity IDs to be available when they're imported.
+  const entityIdsModule = await compileAndImport(path.join(generatedDir, 'entities.ids.generated.ts'))
+  registerEntityIds(entityIdsModule.E as BootstrapData['entityIds'])
+
+  // Now load the rest of the generated files.
+  // modules.cli.generated.ts excludes Next.js-dependent code (routes, APIs, widgets)
+  const [
+    modulesModule,
+    entitiesModule,
+    diModule,
+    searchModule,
+  ] = await Promise.all([
+    compileAndImport(path.join(generatedDir, 'modules.cli.generated.ts')),
+    compileAndImport(path.join(generatedDir, 'entities.generated.ts')),
+    compileAndImport(path.join(generatedDir, 'di.generated.ts')),
+    compileAndImport(path.join(generatedDir, 'search.generated.ts')).catch(() => ({ searchModuleConfigs: [] })),
+  ])
+
+  return {
+    modules: modulesModule.modules as BootstrapData['modules'],
+    entities: entitiesModule.entities as BootstrapData['entities'],
+    diRegistrars: diModule.diRegistrars as BootstrapData['diRegistrars'],
+    entityIds: entityIdsModule.E as BootstrapData['entityIds'],
+    // Search configs are needed by workers for indexing
+    searchModuleConfigs: (searchModule.searchModuleConfigs ?? []) as BootstrapData['searchModuleConfigs'],
+    // Empty UI-related data - not needed for CLI
+    dashboardWidgetEntries: [],
+    injectionWidgetEntries: [],
+    injectionTables: [],
+  }
+}
+
+/**
+ * Create and execute bootstrap in CLI context.
+ *
+ * This is a convenience function that finds the app root, loads the generated
+ * data dynamically, and runs bootstrap. Use this in CLI entry points.
+ *
+ * Returns the loaded bootstrap data so the CLI can register modules directly
+ * (avoids module resolution issues when importing @open-mercato/cli/mercato).
+ *
+ * @param appRoot - Optional explicit app root path
+ * @returns The loaded bootstrap data (modules, entities, etc.)
+ */
+export async function bootstrapFromAppRoot(appRoot?: string): Promise<BootstrapData> {
+  const { createBootstrap, waitForAsyncRegistration } = await import('./factory.js')
+  const data = await loadBootstrapData(appRoot)
+  const bootstrap = createBootstrap(data)
+  bootstrap()
+  // In CLI context, wait for async registrations (UI widgets, search configs, etc.)
+  await waitForAsyncRegistration()
+
+  return data
+}

package/src/lib/bootstrap/factory.ts

@@ -0,0 +1,108 @@
+import type { BootstrapData, BootstrapOptions } from './types'
+import { registerOrmEntities } from '../db/mikro'
+import { registerDiRegistrars } from '../di/container'
+import { registerModules } from '../modules/registry'
+import { registerEntityIds } from '../encryption/entityIds'
+import { registerEntityFields } from '../encryption/entityFields'
+import { registerSearchModuleConfigs } from '../../modules/search'
+
+let _bootstrapped = false
+
+// Store the async registration promise so callers can await it if needed
+let _asyncRegistrationPromise: Promise<void> | null = null
+
+/**
+ * Creates a bootstrap function that registers all application dependencies.
+ *
+ * The returned function should be called once at application startup.
+ * In development mode, it can be called multiple times (for HMR).
+ *
+ * @param data - All generated registry data from .mercato/generated/
+ * @param options - Optional configuration
+ * @returns A bootstrap function to call at app startup
+ */
+export function createBootstrap(data: BootstrapData, options: BootstrapOptions = {}) {
+  return function bootstrap(): void {
+    // In development, always re-run registrations to handle HMR
+    // (Module state may be reset when Turbopack reloads packages)
+    if (_bootstrapped && process.env.NODE_ENV !== 'development') return
+    _bootstrapped = true
+
+    // === 1. Foundation: ORM entities and DI registrars ===
+    registerOrmEntities(data.entities)
+    registerDiRegistrars(data.diRegistrars.filter((r): r is NonNullable<typeof r> => r != null))
+
+    // === 2. Modules registry (required by i18n, query engine, dashboards, CLI) ===
+    registerModules(data.modules)
+
+    // === 3. Entity IDs (required by encryption, indexing, entity links) ===
+    registerEntityIds(data.entityIds)
+
+    // === 4. Entity fields registry (for encryption manager, Turbopack compatibility) ===
+    if (data.entityFieldsRegistry) {
+      registerEntityFields(data.entityFieldsRegistry)
+    }
+
+    // === 5. Search module configs (for search service registration in DI) ===
+    if (data.searchModuleConfigs) {
+      registerSearchModuleConfigs(data.searchModuleConfigs)
+    }
+
+    // === 6-7. UI Widgets and Optional packages (async to avoid circular deps) ===
+    // Store the promise so CLI context can await it
+    _asyncRegistrationPromise = registerWidgetsAndOptionalPackages(data, options)
+    void _asyncRegistrationPromise
+
+    options.onRegistrationComplete?.()
+  }
+}
+
+/**
+ * Wait for async registrations (CLI modules, widgets, etc.) to complete.
+ * Call this after bootstrap() in CLI context where you need modules immediately.
+ */
+export async function waitForAsyncRegistration(): Promise<void> {
+  if (_asyncRegistrationPromise) {
+    await _asyncRegistrationPromise
+  }
+}
+
+async function registerWidgetsAndOptionalPackages(data: BootstrapData, options: BootstrapOptions): Promise<void> {
+  // Register UI widgets (dynamic imports to avoid circular deps with ui/core packages)
+  try {
+    const [dashboardRegistry, injectionRegistry, coreInjection] = await Promise.all([
+      import('@open-mercato/ui/backend/dashboard/widgetRegistry'),
+      import('@open-mercato/ui/backend/injection/widgetRegistry'),
+      import('@open-mercato/core/modules/widgets/lib/injection'),
+    ])
+
+    dashboardRegistry.registerDashboardWidgets(data.dashboardWidgetEntries)
+    injectionRegistry.registerInjectionWidgets(data.injectionWidgetEntries)
+    coreInjection.registerCoreInjectionWidgets(data.injectionWidgetEntries)
+    coreInjection.registerCoreInjectionTables(data.injectionTables)
+  } catch {
+    // UI packages may not be available in all contexts
+  }
+
+  // Note: Search module configs are registered synchronously in the main bootstrap.
+  // The actual registerSearchModule() call happens in core/bootstrap.ts when the
+  // DI container is created, using getSearchModuleConfigs() from the global registry.
+
+  // Note: CLI module registration is handled separately in CLI context
+  // via bootstrapFromAppRoot in dynamicLoader. We don't import CLI here
+  // to avoid Turbopack tracing through the CLI package in Next.js context.
+}
+
+/**
+ * Check if bootstrap has been called.
+ */
+export function isBootstrapped(): boolean {
+  return _bootstrapped
+}
+
+/**
+ * Reset bootstrap state. Useful for testing.
+ */
+export function resetBootstrapState(): void {
+  _bootstrapped = false
+}

package/src/lib/bootstrap/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Bootstrap module for Open Mercato applications.
+ *
+ * This module provides utilities for bootstrapping the application:
+ *
+ * - `createBootstrap(data)` - Factory to create a bootstrap function from generated data
+ * - `isBootstrapped()` - Check if bootstrap has been called
+ * - `resetBootstrapState()` - Reset bootstrap state (for testing)
+ * - `findAppRoot()` - Find the Next.js app root directory
+ *
+ * For CLI/dynamic contexts, import the dynamic loader directly:
+ * ```ts
+ * import { bootstrapFromAppRoot } from '@open-mercato/shared/lib/bootstrap/dynamicLoader'
+ * ```
+ */
+
+export * from './types'
+export { createBootstrap, isBootstrapped, resetBootstrapState } from './factory'
+export { findAppRoot, findAllApps, type AppRoot } from './appResolver'
+
+// Note: dynamicLoader is intentionally NOT exported from index
+// It should be imported directly when needed to make it clear
+// that it only works in unbundled contexts (CLI, tsx)

package/src/lib/bootstrap/types.ts

@@ -0,0 +1,31 @@
+import type { DiRegistrar } from '../di/container'
+import type { EntityIds } from '../encryption/entityIds'
+import type { EntityFieldsRegistry } from '../encryption/entityFields'
+import type { Module, ModuleDashboardWidgetEntry, ModuleInjectionWidgetEntry } from '../../modules/registry'
+import type { ModuleInjectionTable } from '../../modules/widgets/injection'
+import type { SearchModuleConfig } from '../../modules/search'
+import type { EntityClass, EntityClassGroup } from '@mikro-orm/core'
+
+export type OrmEntity = EntityClass<unknown> | EntityClassGroup<unknown>
+
+export interface InjectionTableEntry {
+  moduleId: string
+  table: ModuleInjectionTable
+}
+
+export interface BootstrapData {
+  modules: Module[]
+  entities: OrmEntity[]
+  diRegistrars: (DiRegistrar | undefined)[]
+  entityIds: EntityIds
+  entityFieldsRegistry?: EntityFieldsRegistry
+  dashboardWidgetEntries: ModuleDashboardWidgetEntry[]
+  injectionWidgetEntries: ModuleInjectionWidgetEntry[]
+  injectionTables: InjectionTableEntry[]
+  searchModuleConfigs: SearchModuleConfig[]
+}
+
+export interface BootstrapOptions {
+  skipSearchConfigs?: boolean
+  onRegistrationComplete?: () => void
+}

package/src/lib/cache/segments.ts

@@ -0,0 +1,56 @@
+import type { CacheStrategy } from '@open-mercato/cache'
+
+export type CacheSegmentAnalysisOptions = {
+  keysPattern: string
+  deriveSegment: (key: string) => string | null
+  filterKey?: (key: string) => boolean
+}
+
+export type CacheSegmentInfo = {
+  segment: string
+  keys: string[]
+}
+
+export async function analyzeCacheSegments(
+  cache: CacheStrategy,
+  options: CacheSegmentAnalysisOptions
+): Promise<CacheSegmentInfo[]> {
+  const keys = await cache.keys(options.keysPattern)
+  const segments = new Map<string, Set<string>>()
+
+  for (const key of keys) {
+    if (options.filterKey && !options.filterKey(key)) continue
+    const segment = options.deriveSegment(key)
+    if (!segment) continue
+    if (!segments.has(segment)) segments.set(segment, new Set<string>())
+    segments.get(segment)!.add(key)
+  }
+
+  const results: CacheSegmentInfo[] = []
+  for (const [segment, keySet] of segments.entries()) {
+    results.push({
+      segment,
+      keys: Array.from(keySet).sort(),
+    })
+  }
+  results.sort((a, b) => a.segment.localeCompare(b.segment))
+  return results
+}
+
+export async function purgeCacheSegment(
+  cache: CacheStrategy,
+  options: CacheSegmentAnalysisOptions,
+  segment: string
+): Promise<{ deleted: number; keys: string[] }> {
+  const analyses = await analyzeCacheSegments(cache, options)
+  const target = analyses.find((entry) => entry.segment === segment)
+  if (!target) return { deleted: 0, keys: [] }
+
+  let deleted = 0
+  for (const key of target.keys) {
+    const removed = await cache.delete(key)
+    if (removed) deleted += 1
+  }
+
+  return { deleted, keys: target.keys }
+}

package/src/lib/cli/progress.ts

@@ -0,0 +1,55 @@
+export type ProgressBar = {
+  update(completed: number): void
+  complete(): void
+}
+
+export function createProgressBar(label: string, total: number): ProgressBar {
+  const width = 28
+  let lastPercent = -1
+  let lastCompleted = -1
+  let finished = false
+  const startedAt = Date.now()
+  const minPercentStep =
+    total >= 1_000_000 ? 0.01 : total >= 100_000 ? 0.05 : total >= 10_000 ? 0.1 : 0.5
+  const minCompletedStep = Math.max(1, Math.floor(total / 1000))
+
+  const render = (completed: number) => {
+    if (total <= 0 || finished) return
+    const ratio = Math.min(1, Math.max(0, completed / total))
+    const percentRaw = ratio * 100
+    if (
+      completed < total &&
+      percentRaw - lastPercent < minPercentStep &&
+      completed - lastCompleted < minCompletedStep
+    ) {
+      return
+    }
+    lastPercent = percentRaw
+    lastCompleted = completed
+    const filled = Math.round(ratio * width)
+    const bar = '#'.repeat(filled).padEnd(width, '-')
+    const percentLabel =
+      (percentRaw >= 10 ? percentRaw.toFixed(1) : percentRaw.toFixed(2)).padStart(6, ' ')
+    const countsLabel = `${completed.toLocaleString()}/${total.toLocaleString()}`
+    const elapsedMs = Math.max(1, Date.now() - startedAt)
+    const recordsPerSecond = completed > 0 ? (completed / elapsedMs) * 1000 : 0
+    const rateLabel = `${recordsPerSecond.toFixed(1)} r/s`
+    process.stdout.write(`\r${label} [${bar}] ${percentLabel}% (${countsLabel}) ${rateLabel}`)
+    if (completed >= total) {
+      finished = true
+      process.stdout.write('\n')
+    }
+  }
+
+  return {
+    update: render,
+    complete() {
+      if (!finished && total > 0) {
+        render(total)
+      } else if (!finished) {
+        finished = true
+        process.stdout.write('\n')
+      }
+    },
+  }
+}

package/src/lib/commands/__tests__/command-bus.test.ts

@@ -0,0 +1,84 @@
+import { createContainer, asValue, InjectionMode } from 'awilix'
+import { unregisterCommand, registerCommand, CommandBus } from '@open-mercato/shared/lib/commands'
+
+describe('CommandBus', () => {
+  afterEach(() => {
+    unregisterCommand('test.command')
+    unregisterCommand('test.command.with-capture')
+  })
+
+  it('executes registered command and logs action metadata', async () => {
+    const logMock = jest.fn(async () => ({ id: 'log-entry' }))
+    registerCommand({
+      id: 'test.command',
+      execute: jest.fn(async () => ({ ok: true })),
+      buildLog: jest.fn(() => ({ actionLabel: 'Test', resourceKind: 'test', resourceId: '123' })),
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: null },
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+    }
+
+    const { result, logEntry } = await bus.execute('test.command', { input: {}, ctx })
+
+    expect(result).toEqual({ ok: true })
+    expect(logMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        commandId: 'test.command',
+        tenantId: 'tenant-1',
+        actorUserId: 'user-1',
+        resourceId: '123',
+      })
+    )
+    expect(logEntry).toEqual({ id: 'log-entry' })
+  })
+
+  it('passes captureAfter snapshot to buildLog as snapshots.after', async () => {
+    const logMock = jest.fn(async () => ({ id: 'log-entry-2' }))
+    const buildLogMock = jest.fn(() => ({
+      actionLabel: 'Test with capture',
+      resourceKind: 'test',
+      resourceId: '456',
+    }))
+
+    registerCommand({
+      id: 'test.command.with-capture',
+      prepare: jest.fn(async () => ({ before: { state: 'before-snapshot' } })),
+      execute: jest.fn(async () => ({ id: 'result-123' })),
+      captureAfter: jest.fn(async (_input, result) => ({ state: 'after-snapshot', resultId: result.id })),
+      buildLog: buildLogMock,
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: { sub: 'user-2', tenantId: 'tenant-2', orgId: null },
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+    }
+
+    await bus.execute('test.command.with-capture', { input: { foo: 'bar' }, ctx })
+
+    // Verify buildLog received both before and after snapshots
+    expect(buildLogMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        snapshots: {
+          before: { state: 'before-snapshot' },
+          after: { state: 'after-snapshot', resultId: 'result-123' },
+        },
+      })
+    )
+  })
+})

package/src/lib/commands/__tests__/helpers.test.ts

@@ -0,0 +1,42 @@
+import { buildChanges, requireTenantScope, requireId } from '@open-mercato/shared/lib/commands/helpers'
+
+describe('command helpers', () => {
+  describe('buildChanges', () => {
+    it('returns diff for changed keys', () => {
+      const diff = buildChanges({ a: 1, b: 2 }, { a: 1, b: 3, c: 4 }, ['a', 'b'])
+      expect(diff).toEqual({ b: { from: 2, to: 3 } })
+    })
+
+    it('handles missing before snapshot', () => {
+      expect(buildChanges(null, { a: 1 }, ['a'])).toEqual({})
+    })
+  })
+
+  describe('requireTenantScope', () => {
+    it('prefers requested when allowed', () => {
+      expect(requireTenantScope('tenant-1', 'tenant-1')).toBe('tenant-1')
+    })
+
+    it('throws when requested mismatches auth tenant', () => {
+      expect(() => requireTenantScope('tenant-1', 'tenant-2')).toThrow('Forbidden')
+    })
+
+    it('throws when tenant missing', () => {
+      expect(() => requireTenantScope(null, null)).toThrow('Tenant scope required')
+    })
+  })
+
+  describe('requireId', () => {
+    it('returns string id directly', () => {
+      expect(requireId('123')).toBe('123')
+    })
+
+    it('extracts from object tokens', () => {
+      expect(requireId({ body: { id: 'abc' } })).toBe('abc')
+    })
+
+    it('throws when missing', () => {
+      expect(() => requireId(null)).toThrow('ID is required')
+    })
+  })
+})