@open-mercato/shared 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

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

@@ -4,11 +4,15 @@ import {
   registerCommand,
   registerCommandLoaders,
   CommandBus,
+  isCommandInterceptorError,
 } from '@open-mercato/shared/lib/commands'
+import { registerCommandInterceptors } from '@open-mercato/shared/lib/commands/command-interceptor-store'
+import type { CommandInterceptor } from '@open-mercato/shared/lib/commands/command-interceptor'
 
 describe('CommandBus', () => {
   afterEach(() => {
     commandRegistry.clear()
+    registerCommandInterceptors([])
   })
 
   it('executes registered command and logs action metadata', async () => {
@@ -119,4 +123,63 @@ describe('CommandBus', () => {
     expect(result).toEqual({ ok: true })
     expect(execute).toHaveBeenCalledTimes(1)
   })
+
+  describe('interceptor rejections', () => {
+    const blockingInterceptor = (result: Record<string, unknown>): CommandInterceptor => ({
+      id: 'test.block',
+      targetCommand: 'test.*',
+      beforeExecute: async () => result,
+    })
+
+    const runBlockedCommand = async (interceptor: CommandInterceptor) => {
+      const execute = jest.fn(async () => ({ ok: true }))
+      registerCommand({ id: 'test.command.blocked', execute })
+      registerCommandInterceptors([{ moduleId: 'test', interceptors: [interceptor] }])
+
+      const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+      const bus = new CommandBus()
+      const ctx = {
+        container,
+        auth: { sub: 'user-4', tenantId: 'tenant-4', orgId: null },
+        organizationScope: null,
+        selectedOrganizationId: null,
+        organizationIds: null,
+      }
+
+      const error = await bus.execute('test.command.blocked', { input: {}, ctx }).catch((e: unknown) => e)
+      return { error, execute }
+    }
+
+    it('forwards the interceptor status and derived body onto the thrown error', async () => {
+      const { error, execute } = await runBlockedCommand(
+        blockingInterceptor({ ok: false, message: 'Missing required fields: VAT id', status: 422 }),
+      )
+
+      expect(isCommandInterceptorError(error)).toBe(true)
+      expect((error as { status?: number }).status).toBe(422)
+      expect((error as { body?: Record<string, unknown> }).body).toEqual({
+        error: 'Missing required fields: VAT id',
+      })
+      expect(execute).not.toHaveBeenCalled()
+    })
+
+    it('forwards an explicit interceptor body verbatim', async () => {
+      const body = { error: 'Blocked', missingFields: ['vatId'] }
+      const { error } = await runBlockedCommand(
+        blockingInterceptor({ ok: false, message: 'Blocked', status: 409, body }),
+      )
+
+      expect((error as { status?: number }).status).toBe(409)
+      expect((error as { body?: Record<string, unknown> }).body).toEqual(body)
+    })
+
+    it('leaves status and body undefined when the interceptor supplies no status', async () => {
+      const { error } = await runBlockedCommand(blockingInterceptor({ ok: false, message: 'Blocked' }))
+
+      expect(isCommandInterceptorError(error)).toBe(true)
+      expect((error as Error).message).toBe('Blocked')
+      expect((error as { status?: number }).status).toBeUndefined()
+      expect((error as { body?: unknown }).body).toBeUndefined()
+    })
+  })
 })

package/src/lib/commands/__tests__/command-interceptor-error.test.ts

@@ -1,4 +1,8 @@
-import { CommandInterceptorError } from '../errors'
+import {
+  CommandInterceptorError,
+  getCommandInterceptorHttpRejection,
+  isCommandInterceptorError,
+} from '../errors'
 
 describe('CommandInterceptorError', () => {
   it('has the correct name', () => {
@@ -15,4 +19,90 @@ describe('CommandInterceptorError', () => {
     const error = new CommandInterceptorError('test')
     expect(error).toBeInstanceOf(Error)
   })
+
+  it('carries no transport information when constructed with a message alone', () => {
+    const error = new CommandInterceptorError('test')
+    expect(error.status).toBeUndefined()
+    expect(error.body).toBeUndefined()
+  })
+
+  it('carries the status and derives the body from the message', () => {
+    const error = new CommandInterceptorError('Missing required fields: VAT id', { status: 422 })
+    expect(error.status).toBe(422)
+    expect(error.body).toEqual({ error: 'Missing required fields: VAT id' })
+  })
+
+  it('keeps an explicit body verbatim', () => {
+    const body = { error: 'Blocked', missingFields: ['vatId'] }
+    const error = new CommandInterceptorError('Blocked', { status: 422, body })
+    expect(error.body).toEqual(body)
+  })
+
+  it('ignores a body supplied without a status, so status and body move together', () => {
+    const error = new CommandInterceptorError('Blocked', { body: { error: 'Blocked' } })
+    expect(error.status).toBeUndefined()
+    expect(error.body).toBeUndefined()
+  })
+
+  it('preserves the cause when one is supplied', () => {
+    const cause = new Error('underlying')
+    const error = new CommandInterceptorError('Blocked', { cause })
+    expect(error.cause).toBe(cause)
+  })
+
+  it('is detected by isCommandInterceptorError across module boundaries', () => {
+    expect(isCommandInterceptorError(new CommandInterceptorError('test'))).toBe(true)
+    // A structurally identical error from a duplicated bundle carries the same registered symbol.
+    const duplicated = Object.assign(new Error('test'), {
+      [Symbol.for('@open-mercato/CommandInterceptorError')]: true,
+    })
+    expect(isCommandInterceptorError(duplicated)).toBe(true)
+  })
+
+  it('does not treat unrelated values as interceptor errors', () => {
+    expect(isCommandInterceptorError(new Error('plain'))).toBe(false)
+    expect(isCommandInterceptorError(null)).toBe(false)
+    expect(isCommandInterceptorError('CommandInterceptorError')).toBe(false)
+  })
+})
+
+describe('getCommandInterceptorHttpRejection', () => {
+  it('returns the status and body of a status-carrying rejection', () => {
+    const error = new CommandInterceptorError('Missing required fields: VAT id', { status: 422 })
+    expect(getCommandInterceptorHttpRejection(error)).toEqual({
+      status: 422,
+      body: { error: 'Missing required fields: VAT id' },
+    })
+  })
+
+  it('returns the explicit body when the interceptor supplied one', () => {
+    const body = { error: 'Blocked', missingFields: ['vatId'] }
+    const error = new CommandInterceptorError('Blocked', { status: 409, body })
+    expect(getCommandInterceptorHttpRejection(error)).toEqual({ status: 409, body })
+  })
+
+  it('returns null for a rejection that carries no status', () => {
+    expect(getCommandInterceptorHttpRejection(new CommandInterceptorError('Blocked'))).toBeNull()
+  })
+
+  it('returns null for errors that are not interceptor rejections', () => {
+    expect(getCommandInterceptorHttpRejection(new Error('plain'))).toBeNull()
+    expect(getCommandInterceptorHttpRejection(null)).toBeNull()
+  })
+
+  it('rejects a status outside 4xx/5xx so the transport layer keeps its generic handling', () => {
+    // Statuses arrive as third-party interceptor data: outside 200-599 the Response constructor
+    // throws RangeError, and a 2xx would report a deliberate block as a success.
+    for (const status of [200, 302, 399, 600, 999, 0, -1]) {
+      const error = Object.assign(new CommandInterceptorError('Blocked'), { status })
+      expect(getCommandInterceptorHttpRejection(error)).toBeNull()
+    }
+  })
+
+  it('rejects a non-integer status', () => {
+    for (const status of [Number.NaN, 422.5, Number.POSITIVE_INFINITY]) {
+      const error = Object.assign(new CommandInterceptorError('Blocked'), { status })
+      expect(getCommandInterceptorHttpRejection(error)).toBeNull()
+    }
+  })
 })

package/src/lib/commands/__tests__/command-interceptor-runner.test.ts

@@ -7,6 +7,10 @@ import {
 } from '../command-interceptor-runner'
 import type { CommandInterceptor, CommandInterceptorContext, CommandInterceptorUndoContext } from '../command-interceptor'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  applyAclFeatureOverrides,
+  resetModuleContractOverridesForTests,
+} from '@open-mercato/shared/modules/overrides'
 
 jest.mock('@open-mercato/shared/lib/logger', () => {
   const mocked = {
@@ -59,6 +63,10 @@ describe('matchesCommandPattern', () => {
 })
 
 describe('runCommandInterceptorsBefore', () => {
+  afterEach(() => {
+    resetModuleContractOverridesForTests()
+  })
+
   it('returns ok when no interceptors match', async () => {
     const interceptor = makeInterceptor({
       id: 'i1',
@@ -104,6 +112,56 @@ describe('runCommandInterceptorsBefore', () => {
     expect(i2.beforeExecute).not.toHaveBeenCalled()
   })
 
+  // Issue #5045 — a rejection only carries transport information when the interceptor asks for it.
+  it('omits status and body when the rejection carries no status', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false, message: 'Blocked' }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error).toEqual({ message: 'Blocked' })
+  })
+
+  it('propagates the status and derives a body from the message', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false, message: 'Missing required fields', status: 422 }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error).toEqual({
+      message: 'Missing required fields',
+      status: 422,
+      body: { error: 'Missing required fields' },
+    })
+  })
+
+  it('propagates an explicit body alongside the status', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({
+        ok: false,
+        message: 'Blocked',
+        status: 422,
+        body: { error: 'Blocked', missingFields: ['vatId'] },
+      }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error?.body).toEqual({ error: 'Blocked', missingFields: ['vatId'] })
+  })
+
+  it('falls back to the generated message when a status-carrying rejection has none', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false, status: 422 }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error).toEqual({
+      message: 'Blocked by command interceptor: i1',
+      status: 422,
+      body: { error: 'Blocked by command interceptor: i1' },
+    })
+  })
+
   it('accumulates modified input', async () => {
     const i1 = makeInterceptor({
       id: 'i1',
@@ -158,6 +216,26 @@ describe('runCommandInterceptorsBefore', () => {
     expect(withWildcard.ok).toBe(false)
     expect(withWildcard.error?.message).toBe('Blocked by wildcard')
   })
+
+  it('does not run an interceptor gated by a nulled ACL feature', async () => {
+    applyAclFeatureOverrides({ 'premium.audit': null })
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      features: ['premium.audit'],
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false }),
+    })
+
+    const result = await runCommandInterceptorsBefore(
+      [interceptor],
+      'customers.create-person',
+      {},
+      baseContext,
+      ['*', 'premium.audit'],
+    )
+
+    expect(result.ok).toBe(true)
+    expect(interceptor.beforeExecute).not.toHaveBeenCalled()
+  })
 })
 
 describe('runCommandInterceptorsAfter', () => {
@@ -208,6 +286,29 @@ describe('runCommandInterceptorsBeforeUndo', () => {
     expect(result.ok).toBe(false)
     expect(result.error?.message).toBe('Cannot undo')
   })
+
+  // Issue #5045 — the undo path shares the before-result contract, so it carries a status too.
+  it('omits status and body when the undo rejection carries no status', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeUndo: jest.fn().mockResolvedValue({ ok: false, message: 'Cannot undo' }),
+    })
+    const result = await runCommandInterceptorsBeforeUndo([interceptor], 'customers.create-person', undoContext, baseContext, [])
+    expect(result.error).toEqual({ message: 'Cannot undo' })
+  })
+
+  it('propagates the status and body of an undo rejection', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeUndo: jest.fn().mockResolvedValue({ ok: false, message: 'Cannot undo a settled invoice', status: 409 }),
+    })
+    const result = await runCommandInterceptorsBeforeUndo([interceptor], 'customers.create-person', undoContext, baseContext, [])
+    expect(result.error).toEqual({
+      message: 'Cannot undo a settled invoice',
+      status: 409,
+      body: { error: 'Cannot undo a settled invoice' },
+    })
+  })
 })
 
 describe('runCommandInterceptorsAfterUndo', () => {

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

@@ -31,6 +31,7 @@ import {
 } from './command-interceptor-runner'
 import type { CommandInterceptorContext } from './command-interceptor'
 import { CommandInterceptorError } from './errors'
+import { isReadProjectionAlwaysConsistent } from '@open-mercato/shared/lib/data/consistency'
 import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'commands' })
@@ -244,7 +245,8 @@ export class CommandBus {
         allInterceptors, commandId, options.input, interceptorCtx, userFeatures,
       )
       if (!beforeResult.ok) {
-        throw new CommandInterceptorError(beforeResult.error!.message)
+        const blocked = beforeResult.error!
+        throw new CommandInterceptorError(blocked.message, { status: blocked.status, body: blocked.body })
       }
       interceptorMetadata = beforeResult.metadataByInterceptor
       if (beforeResult.modifiedInput) {
@@ -362,7 +364,8 @@ export class CommandBus {
           allInterceptors, log.commandId, undoCtx, interceptorCtx, userFeatures,
         )
         if (!beforeResult.ok) {
-          throw new CommandInterceptorError(beforeResult.error!.message)
+          const blocked = beforeResult.error!
+          throw new CommandInterceptorError(blocked.message, { status: blocked.status, body: blocked.body })
         }
         undoInterceptorMetadata = beforeResult.metadataByInterceptor
       }
@@ -697,7 +700,10 @@ export class CommandBus {
     try {
       const dataEngine = (container.resolve('dataEngine') as DataEngine)
       await dataEngine.flushOrmEntityChanges(suppress)
-    } catch {
+    } catch (error) {
+      if (isReadProjectionAlwaysConsistent()) {
+        throw error
+      }
       // best-effort: failures should not block command execution
     }
   }

package/src/lib/commands/command-interceptor-runner.ts

@@ -1,13 +1,34 @@
 import type {
   CommandInterceptor,
+  CommandInterceptorBeforeResult,
   CommandInterceptorContext,
   CommandInterceptorUndoContext,
 } from './command-interceptor'
-import { hasAllFeatures } from '../../security/features'
+import { authorizeFeatures } from '../../security/featurePolicy'
 import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'commands' })
 
+/**
+ * A blocking verdict from a before-hook, normalized for the command bus. `status`/`body` are
+ * present only when the interceptor supplied a status, so a rejection without one keeps the
+ * historical generic-500 handling downstream.
+ */
+export type CommandInterceptorBlockedError = {
+  message: string
+  status?: number
+  body?: Record<string, unknown>
+}
+
+function buildBlockedError(
+  result: CommandInterceptorBeforeResult,
+  fallbackMessage: string,
+): CommandInterceptorBlockedError {
+  const message = result.message ?? fallbackMessage
+  if (typeof result.status !== 'number') return { message }
+  return { message, status: result.status, body: result.body ?? { error: message } }
+}
+
 // ---------------------------------------------------------------------------
 // Command pattern matching
 // ---------------------------------------------------------------------------
@@ -33,7 +54,7 @@ function collectMatching(
 ): CommandInterceptor[] {
   return interceptors
     .filter((i) => matchesCommandPattern(i.targetCommand, commandId))
-    .filter((i) => hasAllFeatures(userFeatures, i.features))
+    .filter((i) => authorizeFeatures(i.features ?? [], { grantedFeatures: userFeatures }))
     .sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50))
 }
 
@@ -49,7 +70,7 @@ export async function runCommandInterceptorsBefore(
   userFeatures: string[],
 ): Promise<{
   ok: boolean
-  error?: { message: string }
+  error?: CommandInterceptorBlockedError
   modifiedInput?: Record<string, unknown>
   metadataByInterceptor: Map<string, Record<string, unknown>>
 }> {
@@ -65,7 +86,7 @@ export async function runCommandInterceptorsBefore(
     if (result?.ok === false) {
       return {
         ok: false,
-        error: { message: result.message ?? `Blocked by command interceptor: ${interceptor.id}` },
+        error: buildBlockedError(result, `Blocked by command interceptor: ${interceptor.id}`),
         metadataByInterceptor,
       }
     }
@@ -139,7 +160,7 @@ export async function runCommandInterceptorsBeforeUndo(
   userFeatures: string[],
 ): Promise<{
   ok: boolean
-  error?: { message: string }
+  error?: CommandInterceptorBlockedError
   metadataByInterceptor: Map<string, Record<string, unknown>>
 }> {
   const matching = collectMatching(interceptors, commandId, userFeatures)
@@ -153,7 +174,7 @@ export async function runCommandInterceptorsBeforeUndo(
     if (result?.ok === false) {
       return {
         ok: false,
-        error: { message: result.message ?? `Undo blocked by command interceptor: ${interceptor.id}` },
+        error: buildBlockedError(result, `Undo blocked by command interceptor: ${interceptor.id}`),
         metadataByInterceptor,
       }
     }

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

@@ -67,6 +67,14 @@ export interface CommandInterceptorBeforeResult {
   ok?: boolean
   /** Error message when blocking */
   message?: string
+  /**
+   * HTTP status code when blocking. Omit to keep the historical behaviour, where a rejection
+   * without a status surfaces as a generic 500 — set it (e.g. 422) to have the CRUD transport
+   * layer answer with a deliberate business-rejection status instead.
+   */
+  status?: number
+  /** Error body when blocking (overrides message). Only used together with `status`. */
+  body?: Record<string, unknown>
   /** Modified input — shallow-merged into command input if ok:true */
   modifiedInput?: Record<string, unknown>
   /** Metadata passed to the corresponding after hook */

package/src/lib/commands/errors.ts

@@ -1,6 +1,71 @@
+// Use Symbol.for so the marker survives module duplication across bundle boundaries
+// (same behaviour as CrudHttpError and the globalThis-based DI registries)
+const COMMAND_INTERCEPTOR_ERROR_MARKER = Symbol.for('@open-mercato/CommandInterceptorError')
+
+export type CommandInterceptorErrorOptions = {
+  /** HTTP status the transport layer should answer with. Omit to keep the generic 500. */
+  status?: number
+  /**
+   * Response body the transport layer should answer with, defaulting to `{ error: message }`.
+   * Only meaningful together with `status` — a body on its own is ignored, mirroring the same
+   * rule on `CommandInterceptorBeforeResult`.
+   */
+  body?: Record<string, unknown>
+  cause?: unknown
+}
+
 export class CommandInterceptorError extends Error {
-  constructor(message: string) {
-    super(message)
+  readonly [COMMAND_INTERCEPTOR_ERROR_MARKER] = true
+  /**
+   * HTTP status a deliberate interceptor rejection wants to surface. `undefined` when the
+   * interceptor supplied none, in which case the transport layer keeps its generic 500.
+   */
+  readonly status?: number
+  /**
+   * Response body for the rejection — `options.body`, else `{ error: message }`. Set only
+   * alongside `status`, so the two are always populated together or not at all.
+   */
+  readonly body?: Record<string, unknown>
+
+  constructor(message: string, options?: CommandInterceptorErrorOptions) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined)
     this.name = 'CommandInterceptorError'
+    if (typeof options?.status === 'number') {
+      this.status = options.status
+      this.body = options.body ?? { error: message }
+    }
   }
 }
+
+/**
+ * Type-safe check for CommandInterceptorError that works across module/bundle boundaries.
+ * Prefer this over `instanceof CommandInterceptorError` whenever the error may originate
+ * from a different module bundle (e.g. enterprise packages, dynamic imports).
+ */
+export function isCommandInterceptorError(err: unknown): err is CommandInterceptorError {
+  return !!err && typeof err === 'object'
+    && (err as Record<symbol, unknown>)[COMMAND_INTERCEPTOR_ERROR_MARKER] === true
+}
+
+export type CommandInterceptorHttpRejection = {
+  status: number
+  body: Record<string, unknown>
+}
+
+const MIN_REJECTION_STATUS = 400
+const MAX_REJECTION_STATUS = 599
+
+/**
+ * Transport data for a deliberate interceptor rejection, or `null` when the error is not one or
+ * carries no usable status. The status is restricted to 4xx/5xx on purpose: interceptor data is
+ * third-party input travelling through the runner and the bus, `new Response(body, { status })`
+ * throws `RangeError` outside 200-599, and a rejection answered with a 2xx would report a block as
+ * a success. Anything else falls through to the caller's generic handling.
+ */
+export function getCommandInterceptorHttpRejection(err: unknown): CommandInterceptorHttpRejection | null {
+  if (!isCommandInterceptorError(err)) return null
+  const status = err.status
+  if (typeof status !== 'number' || !Number.isInteger(status)) return null
+  if (status < MIN_REJECTION_STATUS || status > MAX_REJECTION_STATUS) return null
+  return { status, body: err.body ?? { error: err.message } }
+}

package/src/lib/commands/index.ts

@@ -4,7 +4,13 @@ export { CommandBus } from './command-bus'
 export * from './customFieldSnapshots'
 export * from './undo'
 export * from './redo'
-export { CommandInterceptorError } from './errors'
+export {
+  CommandInterceptorError,
+  isCommandInterceptorError,
+  getCommandInterceptorHttpRejection,
+  type CommandInterceptorErrorOptions,
+  type CommandInterceptorHttpRejection,
+} from './errors'
 export {
   runCrudCommandWrite,
   type RunCrudCommandWriteOptions,