@open-mercato/shared 0.4.2-canary-c02407ff85

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

@@ -0,0 +1,349 @@
+import type { ActionLog } from '@open-mercato/core/modules/audit_logs/data/entities'
+import type { ActionLogCreateInput } from '@open-mercato/core/modules/audit_logs/data/validators'
+import { commandRegistry } from './registry'
+import type {
+  CommandExecutionOptions,
+  CommandExecuteResult,
+  CommandHandler,
+  CommandLogBuilderArgs,
+  CommandLogMetadata,
+  CommandRuntimeContext,
+} from './types'
+import { defaultUndoToken } from './types'
+import type { ActionLogService } from '@open-mercato/core/modules/audit_logs/services/actionLogService'
+import type { AwilixContainer } from 'awilix'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import {
+  canonicalizeResourceTag,
+  deriveResourceFromCommandId,
+  invalidateCrudCache,
+  pickFirstIdentifier,
+  isCrudCacheDebugEnabled,
+} from '@open-mercato/shared/lib/crud/cache'
+
+const SKIPPED_ACTION_LOG_RESOURCE_KINDS = new Set<string>([
+  'audit_logs.access',
+  'audit_logs.action',
+  'dashboards.layout',
+  'dashboards.user_widgets',
+  'dashboards.role_widgets',
+])
+
+function asRecord(input: unknown): Record<string, unknown> | null {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null
+  return input as Record<string, unknown>
+}
+
+function extractAliasList(source: unknown): string[] {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return []
+  const record = source as Record<string, unknown>
+  const raw = record.cacheAliases
+  if (!Array.isArray(raw)) return []
+  const aliases = new Set<string>()
+  for (const value of raw) {
+    if (typeof value !== 'string') continue
+    const normalized = canonicalizeResourceTag(value)
+    if (normalized) aliases.add(normalized)
+  }
+  return Array.from(aliases)
+}
+
+export class CommandBus {
+  async execute<TInput = unknown, TResult = unknown>(
+    commandId: string,
+    options: CommandExecutionOptions<TInput>
+  ): Promise<CommandExecuteResult<TResult>> {
+    const handler = this.resolveHandler<TInput, TResult>(commandId)
+    const snapshots = await this.prepareSnapshots(handler, options)
+    const result = await handler.execute(options.input, options.ctx)
+    const afterSnapshot = await this.captureAfter(handler, options, result)
+    const snapshotsWithAfter = { ...snapshots, after: afterSnapshot }
+    const logMeta = await this.buildLog(handler, options, result, snapshotsWithAfter)
+    let mergedMeta = this.mergeMetadata(options.metadata, logMeta)
+    const undoable = this.isUndoable(handler)
+    if (undoable) {
+      mergedMeta = mergedMeta ?? {}
+      if (!mergedMeta.undoToken) mergedMeta.undoToken = defaultUndoToken()
+      if (mergedMeta.actorUserId === undefined) mergedMeta.actorUserId = options.ctx.auth?.sub ?? null
+    }
+    if (afterSnapshot !== undefined && afterSnapshot !== null) {
+      if (!mergedMeta) {
+        mergedMeta = { snapshotAfter: afterSnapshot }
+      } else if (!mergedMeta.snapshotAfter) {
+        mergedMeta.snapshotAfter = afterSnapshot
+      }
+    }
+    if (snapshots.before) {
+      if (!mergedMeta) {
+        mergedMeta = { snapshotBefore: snapshots.before }
+      } else if (!mergedMeta.snapshotBefore) {
+        mergedMeta.snapshotBefore = snapshots.before
+      }
+    }
+    const logEntry = await this.persistLog(commandId, options, mergedMeta)
+    await this.invalidateCacheAfterExecute(commandId, options, result, mergedMeta)
+    await this.flushCrudSideEffects(options.ctx.container)
+    return { result, logEntry }
+  }
+
+  async undo(undoToken: string, ctx: CommandRuntimeContext): Promise<void> {
+    const service = (ctx.container.resolve('actionLogService') as ActionLogService)
+    const log = await service.findByUndoToken(undoToken)
+    if (!log) throw new Error('Undo token expired or not found')
+    const handler = this.resolveHandler(log.commandId)
+    if (!handler.undo || this.isUndoable(handler) === false) {
+      throw new Error(`Command ${log.commandId} is not undoable`)
+    }
+    await handler.undo({
+      input: log.commandPayload as Parameters<NonNullable<typeof handler.undo>>[0]['input'],
+      ctx,
+      logEntry: log,
+    })
+    await service.markUndone(log.id)
+    await this.invalidateCacheAfterUndo(log, ctx)
+    await this.flushCrudSideEffects(ctx.container)
+  }
+
+  private resolveHandler<TInput, TResult>(commandId: string): CommandHandler<TInput, TResult> {
+    const handler = commandRegistry.get<TInput, TResult>(commandId)
+    if (!handler) throw new Error(`Command handler not registered for id ${commandId}`)
+    return handler
+  }
+
+  private async prepareSnapshots<TInput, TResult>(
+    handler: CommandHandler<TInput, TResult>,
+    options: CommandExecutionOptions<TInput>
+  ): Promise<{ before?: unknown }> {
+    if (!handler.prepare) return {}
+    try {
+      return (await handler.prepare(options.input, options.ctx)) || {}
+    } catch (err) {
+      throw err
+    }
+  }
+
+  private async captureAfter<TInput, TResult>(
+    handler: CommandHandler<TInput, TResult>,
+    options: CommandExecutionOptions<TInput>,
+    result: TResult
+  ): Promise<unknown> {
+    if (!handler.captureAfter) return undefined
+    return handler.captureAfter(options.input, result, options.ctx)
+  }
+
+  private async buildLog<TInput, TResult>(
+    handler: CommandHandler<TInput, TResult>,
+    options: CommandExecutionOptions<TInput>,
+    result: TResult,
+    snapshots: { before?: unknown; after?: unknown }
+  ): Promise<CommandLogMetadata | null> {
+    if (!handler.buildLog) return null
+    const args: CommandLogBuilderArgs<TInput, TResult> = {
+      input: options.input,
+      result,
+      ctx: options.ctx,
+      snapshots,
+    }
+    return (await handler.buildLog(args)) || null
+  }
+
+  private mergeMetadata(primary?: CommandLogMetadata | null, secondary?: CommandLogMetadata | null): CommandLogMetadata | null {
+    if (!primary && !secondary) return null
+    return {
+      tenantId: primary?.tenantId ?? secondary?.tenantId ?? null,
+      organizationId: primary?.organizationId ?? secondary?.organizationId ?? null,
+      actorUserId: primary?.actorUserId ?? secondary?.actorUserId ?? null,
+      actionLabel: primary?.actionLabel ?? secondary?.actionLabel ?? null,
+      resourceKind: primary?.resourceKind ?? secondary?.resourceKind ?? null,
+      resourceId: primary?.resourceId ?? secondary?.resourceId ?? null,
+      undoToken: primary?.undoToken ?? secondary?.undoToken ?? null,
+      payload: primary?.payload ?? secondary?.payload ?? null,
+      snapshotBefore: primary?.snapshotBefore ?? secondary?.snapshotBefore ?? null,
+      snapshotAfter: primary?.snapshotAfter ?? secondary?.snapshotAfter ?? null,
+      changes: primary?.changes ?? secondary?.changes ?? null,
+      context: primary?.context ?? secondary?.context ?? null,
+    }
+  }
+
+  private async persistLog<TInput>(
+    commandId: string,
+    options: CommandExecutionOptions<TInput>,
+    metadata: CommandLogMetadata | null
+  ): Promise<ActionLog | null> {
+    if (!metadata) return null
+    const resourceKind =
+      typeof metadata.resourceKind === 'string' ? metadata.resourceKind : null
+    if (resourceKind && SKIPPED_ACTION_LOG_RESOURCE_KINDS.has(resourceKind)) {
+      return null
+    }
+    let service: ActionLogService | null = null
+    try {
+      service = (options.ctx.container.resolve('actionLogService') as ActionLogService)
+    } catch {
+      service = null
+    }
+    if (!service) return null
+
+    const tenantId = metadata.tenantId ?? options.ctx.auth?.tenantId ?? null
+    const organizationId =
+      metadata.organizationId ?? options.ctx.selectedOrganizationId ?? options.ctx.auth?.orgId ?? null
+    const actorUserId = metadata.actorUserId ?? options.ctx.auth?.sub ?? null
+    const payload: Record<string, unknown> = {
+      tenantId: tenantId ?? undefined,
+      organizationId: organizationId ?? undefined,
+      actorUserId: actorUserId ?? undefined,
+      commandId,
+    }
+
+    if (metadata) {
+      if ('actionLabel' in metadata && metadata.actionLabel != null) payload.actionLabel = metadata.actionLabel
+      if ('resourceKind' in metadata && metadata.resourceKind != null) payload.resourceKind = metadata.resourceKind
+      if ('resourceId' in metadata && metadata.resourceId != null) payload.resourceId = metadata.resourceId
+      if ('undoToken' in metadata && metadata.undoToken != null) payload.undoToken = metadata.undoToken
+      if ('payload' in metadata && metadata.payload !== undefined) payload.commandPayload = metadata.payload
+      if ('snapshotBefore' in metadata && metadata.snapshotBefore !== undefined) payload.snapshotBefore = metadata.snapshotBefore
+      if ('snapshotAfter' in metadata && metadata.snapshotAfter !== undefined) payload.snapshotAfter = metadata.snapshotAfter
+      if ('changes' in metadata && metadata.changes !== undefined && metadata.changes !== null) payload.changes = metadata.changes
+      if ('context' in metadata && metadata.context !== undefined && metadata.context !== null) payload.context = metadata.context
+    }
+
+    const redoEnvelope = wrapRedoPayload('commandPayload' in payload ? (payload.commandPayload as unknown) : undefined, options.input)
+    payload.commandPayload = redoEnvelope
+
+    return await service.log(payload as ActionLogCreateInput)
+  }
+
+  private isUndoable(handler: CommandHandler<unknown, unknown>): boolean {
+    return handler.isUndoable !== false && typeof handler.undo === 'function'
+  }
+
+  private async invalidateCacheAfterExecute<TResult>(
+    commandId: string,
+    options: CommandExecutionOptions<unknown>,
+    result: TResult,
+    metadata: CommandLogMetadata | null
+  ): Promise<void> {
+    const resource = typeof metadata?.resourceKind === 'string' ? metadata.resourceKind : null
+    if (!resource) return
+    try {
+      const ctx = options.ctx
+      const resultRecord = asRecord(result)
+      const resultEntity = asRecord(resultRecord?.entity)
+      const inputRecord = asRecord(options.input)
+      const inputEntity = asRecord(inputRecord?.entity)
+
+      const recordId = pickFirstIdentifier(
+        metadata?.resourceId,
+        resultRecord?.entityId,
+        resultRecord?.id,
+        resultRecord?.recordId,
+        resultEntity?.id,
+        inputRecord?.id,
+        inputRecord?.entityId,
+        inputRecord?.recordId,
+        inputEntity?.id
+      )
+
+      const organizationId = pickFirstIdentifier(
+        metadata?.organizationId,
+        resultRecord?.organizationId,
+        resultEntity?.organizationId,
+        inputRecord?.organizationId,
+        inputEntity?.organizationId,
+        ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+      )
+
+      const tenantId = pickFirstIdentifier(
+        metadata?.tenantId,
+        resultRecord?.tenantId,
+        resultEntity?.tenantId,
+        inputRecord?.tenantId,
+        inputEntity?.tenantId,
+        ctx.auth?.tenantId ?? null
+      )
+
+      const fallbackTenant = pickFirstIdentifier(metadata?.tenantId, ctx.auth?.tenantId ?? null)
+
+      const aliasSet = new Set<string>()
+      for (const alias of extractAliasList(metadata?.context ?? null)) {
+        aliasSet.add(alias)
+      }
+      const derived = deriveResourceFromCommandId(commandId)
+      if (derived) aliasSet.add(derived)
+      const aliasExtras = Array.from(aliasSet)
+      await invalidateCrudCache(
+        ctx.container,
+        resource,
+        { id: recordId, organizationId, tenantId },
+        fallbackTenant,
+        `command:${commandId}:execute`,
+        aliasExtras
+      )
+    } catch (err) {
+      if (isCrudCacheDebugEnabled()) {
+        try {
+          console.debug('[crud][cache] execute-invalidation failed', { commandId, err })
+        } catch {}
+      }
+    }
+  }
+
+  private async invalidateCacheAfterUndo(log: ActionLog, ctx: CommandRuntimeContext): Promise<void> {
+    const resource = typeof log.resourceKind === 'string' ? log.resourceKind : null
+    if (!resource) return
+    try {
+      const recordId = pickFirstIdentifier(log.resourceId)
+      const organizationId = pickFirstIdentifier(log.organizationId, ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null)
+      const tenantId = pickFirstIdentifier(log.tenantId, ctx.auth?.tenantId ?? null)
+      const fallbackTenant = pickFirstIdentifier(log.tenantId, ctx.auth?.tenantId ?? null)
+      const aliasSet = new Set<string>()
+      for (const alias of extractAliasList(log.contextJson ?? null)) {
+        aliasSet.add(alias)
+      }
+      const derived = deriveResourceFromCommandId(log.commandId)
+      if (derived) aliasSet.add(derived)
+      const aliasExtras = Array.from(aliasSet)
+      await invalidateCrudCache(
+        ctx.container,
+        resource,
+        { id: recordId, organizationId, tenantId },
+        fallbackTenant,
+        `command:${log.commandId}:undo`,
+        aliasExtras
+      )
+    } catch (err) {
+      if (isCrudCacheDebugEnabled()) {
+        try {
+          console.debug('[crud][cache] undo-invalidation failed', { commandId: log.commandId, err })
+        } catch {}
+      }
+    }
+  }
+
+  private async flushCrudSideEffects(container: AwilixContainer): Promise<void> {
+    try {
+      const dataEngine = (container.resolve('dataEngine') as DataEngine)
+      await dataEngine.flushOrmEntityChanges()
+    } catch {
+      // best-effort: failures should not block command execution
+    }
+  }
+}
+
+type RedoEnvelope = {
+  __redoInput: unknown
+  [key: string]: unknown
+}
+
+function wrapRedoPayload(existing: unknown, input: unknown): RedoEnvelope {
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+    const envelope: RedoEnvelope = { __redoInput: input }
+    if (existing !== undefined) envelope.value = existing
+    return envelope
+  }
+  const current = existing as Record<string, unknown>
+  if ('__redoInput' in current && current.__redoInput !== undefined) {
+    return current as RedoEnvelope
+  }
+  return { __redoInput: input, ...current }
+}

package/src/lib/commands/customFieldSnapshots.ts

@@ -0,0 +1,86 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { loadCustomFieldValues } from '@open-mercato/shared/lib/crud/custom-fields'
+
+export type CustomFieldSnapshot = Record<string, unknown>
+
+type LoadSnapshotOptions = {
+  entityId: string
+  recordId: string
+  tenantId?: string | null
+  organizationId?: string | null
+  tenantFallbacks?: Array<string | null | undefined>
+}
+
+export async function loadCustomFieldSnapshot(
+  em: EntityManager,
+  { entityId, recordId, tenantId, organizationId, tenantFallbacks }: LoadSnapshotOptions
+): Promise<CustomFieldSnapshot> {
+  const tenant = tenantId ?? null
+  const organization = organizationId ?? undefined
+  const records = await loadCustomFieldValues({
+    em,
+    entityId: entityId as any,
+    recordIds: [recordId],
+    tenantIdByRecord: { [recordId]: tenant },
+    organizationIdByRecord: organization === undefined ? undefined : { [recordId]: organization ?? null },
+    tenantFallbacks: tenantFallbacks ?? [tenant],
+  })
+  const raw = records[recordId] ?? {}
+  const custom: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.startsWith('cf_')) custom[key.slice(3)] = value
+  }
+  return custom
+}
+
+export function buildCustomFieldResetMap(
+  before: CustomFieldSnapshot | undefined,
+  after: CustomFieldSnapshot | undefined
+): Record<string, unknown> {
+  const values: Record<string, unknown> = {}
+  const keys = new Set<string>()
+  if (before) for (const key of Object.keys(before)) keys.add(key)
+  if (after) for (const key of Object.keys(after)) keys.add(key)
+  for (const key of keys) {
+    const hasBefore = Boolean(before && Object.prototype.hasOwnProperty.call(before, key))
+    if (hasBefore) {
+      const beforeValue = before?.[key]
+      if (beforeValue === null && Array.isArray(after?.[key])) {
+        values[key] = []
+      } else {
+        values[key] = beforeValue
+      }
+    } else {
+      values[key] = Array.isArray(after?.[key]) ? [] : null
+    }
+  }
+  return values
+}
+
+export type CustomFieldChangeSet = Record<string, { from: unknown; to: unknown }>
+
+export function diffCustomFieldChanges(
+  before: CustomFieldSnapshot | undefined,
+  after: CustomFieldSnapshot | undefined
+): CustomFieldChangeSet {
+  const out: CustomFieldChangeSet = {}
+  const keys = new Set<string>()
+  if (before) for (const key of Object.keys(before)) keys.add(key)
+  if (after) for (const key of Object.keys(after)) keys.add(key)
+  for (const key of keys) {
+    const prev = before ? before[key] : undefined
+    const next = after ? after[key] : undefined
+    if (!customFieldValuesEqual(prev, next)) {
+      out[key] = { from: prev ?? null, to: next ?? null }
+    }
+  }
+  return out
+}
+
+function customFieldValuesEqual(a: unknown, b: unknown): boolean {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false
+    return a.every((value, idx) => customFieldValuesEqual(value, b[idx]))
+  }
+  return a === b
+}

package/src/lib/commands/helpers.ts

@@ -0,0 +1,143 @@
+import { splitCustomFieldPayload } from '@open-mercato/shared/lib/crud/custom-fields'
+import type { z } from 'zod'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { normalizeCustomFieldValues } from '../custom-fields/normalize'
+export { normalizeCustomFieldValues } from '../custom-fields/normalize'
+import type { CrudEventsConfig, CrudIndexerConfig, CrudEmitContext } from '@open-mercato/shared/lib/crud/types'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { CommandLogMetadata } from '@open-mercato/shared/lib/commands'
+
+export type ParsedPayload<TSchema extends z.ZodTypeAny> = {
+  parsed: z.infer<TSchema>
+  custom: Record<string, unknown>
+}
+
+export function parseWithCustomFields<TSchema extends z.ZodTypeAny>(
+  schema: TSchema,
+  raw: unknown
+): ParsedPayload<TSchema> {
+  const { base, custom } = splitCustomFieldPayload(raw)
+  const parsed = schema.parse(base)
+  return { parsed, custom }
+}
+
+export async function setCustomFieldsIfAny(opts: {
+  dataEngine: DataEngine
+  entityId: string
+  recordId: string
+  tenantId: string | null
+  organizationId: string | null
+  values: Record<string, unknown>
+  notify?: boolean
+}) {
+  const { values } = opts
+  if (!values || !Object.keys(values).length) return
+  const { dataEngine, entityId, recordId, tenantId, organizationId, notify = false } = opts
+  const normalized = normalizeCustomFieldValues(values)
+  await dataEngine.setCustomFields({
+    entityId,
+    recordId,
+    tenantId,
+    organizationId,
+    values: normalized,
+    notify,
+  })
+}
+
+export async function emitCrudSideEffects<TEntity>(opts: {
+  dataEngine: DataEngine
+  action: 'created' | 'updated' | 'deleted'
+  entity: TEntity
+  identifiers: CrudEmitContext<TEntity>['identifiers']
+  events?: CrudEventsConfig<TEntity>
+  indexer?: CrudIndexerConfig<TEntity>
+}) {
+  const { dataEngine, action, entity, identifiers, events, indexer } = opts
+  dataEngine.markOrmEntityChange({
+    action,
+    entity,
+    identifiers,
+    events,
+    indexer,
+  })
+}
+
+export async function emitCrudUndoSideEffects<TEntity>(opts: {
+  dataEngine: DataEngine
+  action: 'created' | 'updated' | 'deleted'
+  entity: TEntity | null | undefined
+  identifiers: CrudEmitContext<TEntity>['identifiers']
+  events?: CrudEventsConfig<TEntity>
+  indexer?: CrudIndexerConfig<TEntity>
+}) {
+  const { dataEngine, action, entity, identifiers, events, indexer } = opts
+  if (!entity) return
+  dataEngine.markOrmEntityChange({
+    action,
+    entity,
+    identifiers,
+    events,
+    indexer,
+  })
+}
+
+export async function flushCrudSideEffects(dataEngine: DataEngine): Promise<void> {
+  await dataEngine.flushOrmEntityChanges()
+}
+
+export function buildChanges(
+  before: Record<string, unknown> | null | undefined,
+  after: Record<string, unknown>,
+  keys: readonly string[]
+): Record<string, { from: unknown; to: unknown }> {
+  if (!before) return {}
+  const diff: Record<string, { from: unknown; to: unknown }> = {}
+  for (const key of keys) {
+    const prev = before[key]
+    const next = after[key]
+    if (prev !== next) diff[key] = { from: prev, to: next }
+  }
+  return diff
+}
+
+export function requireTenantScope(authTenantId: string | null, requested?: string | null): string {
+  if (authTenantId && requested && requested !== authTenantId) {
+    throw new CrudHttpError(403, { error: 'Forbidden' })
+  }
+  const tenantId = requested || authTenantId
+  if (!tenantId) throw new CrudHttpError(400, { error: 'Tenant scope required' })
+  return tenantId
+}
+
+export function requireId(value: unknown, message = 'ID is required'): string {
+  if (typeof value === 'string' && value.trim()) return value
+  if (typeof value === 'number' || typeof value === 'bigint') return String(value)
+  if (value && typeof value === 'object') {
+    const source = value as Record<string, unknown>
+    const candidates: unknown[] = [
+      source.id,
+      source.recordId,
+      isRecord(source.body) ? source.body.id : undefined,
+      isRecord(source.query) ? source.query.id : undefined,
+    ]
+    for (const candidate of candidates) {
+      if (typeof candidate === 'string' && candidate.trim()) return candidate
+      if (typeof candidate === 'number' || typeof candidate === 'bigint') return String(candidate)
+    }
+  }
+  throw new CrudHttpError(400, { error: message })
+}
+
+function isRecord(input: unknown): input is { [key: string]: unknown } {
+  return !!input && typeof input === 'object'
+}
+
+export type LogBuilderArgs<TInput, TResult> = {
+  input: TInput
+  result: TResult
+  ctx: CommandRuntimeContext
+  snapshots: { before?: unknown; after?: unknown }
+}
+
+export type LogBuilder<TInput, TResult> = (args: LogBuilderArgs<TInput, TResult>) => CommandLogMetadata | null | Promise<CommandLogMetadata | null>

package/src/lib/commands/index.ts

@@ -0,0 +1,4 @@
+export * from './types'
+export * from './registry'
+export { CommandBus } from './command-bus'
+export * from './customFieldSnapshots'

package/src/lib/commands/operationMetadata.ts

@@ -0,0 +1,40 @@
+export type OperationMetadataPayload = {
+  id: string
+  undoToken: string
+  commandId: string
+  actionLabel: string | null
+  resourceKind: string | null
+  resourceId: string | null
+  executedAt: string
+}
+
+const HEADER_PREFIX = 'omop:'
+
+export function serializeOperationMetadata(payload: OperationMetadataPayload): string {
+  const encoded = encodeURIComponent(JSON.stringify(payload))
+  return `${HEADER_PREFIX}${encoded}`
+}
+
+export function deserializeOperationMetadata(value: string | null | undefined): OperationMetadataPayload | null {
+  if (!value || typeof value !== 'string') return null
+  const trimmed = value.startsWith(HEADER_PREFIX) ? value.slice(HEADER_PREFIX.length) : value
+  try {
+    const parsed = JSON.parse(decodeURIComponent(trimmed))
+    if (!parsed || typeof parsed !== 'object') return null
+    if (typeof parsed.id !== 'string' || typeof parsed.commandId !== 'string') return null
+    if (typeof parsed.undoToken !== 'string' || !parsed.undoToken) return null
+    if (typeof parsed.executedAt !== 'string') return null
+    return {
+      id: parsed.id,
+      undoToken: parsed.undoToken,
+      commandId: parsed.commandId,
+      actionLabel: parsed.actionLabel ?? null,
+      resourceKind: parsed.resourceKind ?? null,
+      resourceId: parsed.resourceId ?? null,
+      executedAt: parsed.executedAt,
+    }
+  } catch {
+    return null
+  }
+}
+

package/src/lib/commands/registry.ts

@@ -0,0 +1,46 @@
+import type { CommandHandler } from './types'
+
+class CommandRegistry {
+  private handlers = new Map<string, CommandHandler>()
+
+  register(handler: CommandHandler) {
+    if (!handler?.id) throw new Error('Command handler must define an id')
+    if (this.handlers.has(handler.id)) {
+      throw new Error(`Duplicate command registration for id ${handler.id}`)
+    }
+    this.handlers.set(handler.id, handler)
+  }
+
+  unregister(id: string) {
+    this.handlers.delete(id)
+  }
+
+  get<TInput = unknown, TResult = unknown>(id: string): CommandHandler<TInput, TResult> | null {
+    return (this.handlers.get(id) as CommandHandler<TInput, TResult> | undefined) ?? null
+  }
+
+  has(id: string): boolean {
+    return this.handlers.has(id)
+  }
+
+  /**
+   * List all registered command handler IDs.
+   */
+  list(): string[] {
+    return Array.from(this.handlers.keys())
+  }
+
+  clear() {
+    this.handlers.clear()
+  }
+}
+
+export const commandRegistry = new CommandRegistry()
+
+export function registerCommand(handler: CommandHandler) {
+  commandRegistry.register(handler)
+}
+
+export function unregisterCommand(id: string) {
+  commandRegistry.unregister(id)
+}