@open-mercato/ui 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/src/ai/parts/__tests__/MutationPreviewCard.test.tsx

@@ -0,0 +1,177 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { fireEvent, screen, waitFor } from '@testing-library/react'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+
+jest.mock('../useAiPendingActionPolling', () => ({
+  useAiPendingActionPolling: jest.fn(),
+}))
+
+jest.mock('../pending-action-api', () => ({
+  confirmPendingAction: jest.fn(),
+  cancelPendingAction: jest.fn(),
+}))
+
+import { useAiPendingActionPolling } from '../useAiPendingActionPolling'
+import {
+  confirmPendingAction,
+  cancelPendingAction,
+} from '../pending-action-api'
+import { MutationPreviewCard } from '../MutationPreviewCard'
+import type { AiPendingActionCardAction } from '../types'
+
+const dict = {
+  'ai_assistant.chat.mutation_cards.preview.title': 'Review proposed changes',
+  'ai_assistant.chat.mutation_cards.preview.batchSummary': 'Batch update',
+  'ai_assistant.chat.mutation_cards.preview.batchRecords': 'records',
+  'ai_assistant.chat.mutation_cards.preview.confirm': 'Confirm',
+  'ai_assistant.chat.mutation_cards.preview.cancel': 'Cancel',
+  'ai_assistant.chat.mutation_cards.preview.reviewDetails': 'Review details',
+  'ai_assistant.chat.mutation_cards.diff.fieldHeader': 'Field',
+  'ai_assistant.chat.mutation_cards.diff.beforeHeader': 'Before',
+  'ai_assistant.chat.mutation_cards.diff.afterHeader': 'After',
+  'ai_assistant.chat.mutation_cards.diff.empty': 'No field changes for this record.',
+}
+
+function makeAction(
+  overrides: Partial<AiPendingActionCardAction> = {},
+): AiPendingActionCardAction {
+  return {
+    id: 'pa-1',
+    agentId: 'customers.account_assistant',
+    toolName: 'customers.update_person',
+    status: 'pending',
+    fieldDiff: [{ field: 'name', before: 'Alice', after: 'Alicia' }],
+    records: null,
+    failedRecords: null,
+    sideEffectsSummary: 'Rename Alice to Alicia',
+    attachmentIds: [],
+    targetEntityType: 'customers.person',
+    targetRecordId: 'p-1',
+    recordVersion: '1',
+    executionResult: null,
+    createdAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 10_000).toISOString(),
+    resolvedAt: null,
+    resolvedByUserId: null,
+    ...overrides,
+  }
+}
+
+function installPollingMock(action: AiPendingActionCardAction | null) {
+  ;(useAiPendingActionPolling as jest.Mock).mockReturnValue({
+    action,
+    status: action?.status ?? null,
+    isPolling: false,
+    error: null,
+    refresh: jest.fn().mockResolvedValue(action),
+  })
+}
+
+describe('MutationPreviewCard', () => {
+  beforeEach(() => {
+    ;(useAiPendingActionPolling as jest.Mock).mockReset()
+    ;(confirmPendingAction as jest.Mock).mockReset()
+    ;(cancelPendingAction as jest.Mock).mockReset()
+    ;(confirmPendingAction as jest.Mock).mockResolvedValue({
+      ok: true,
+      data: { ok: true, pendingAction: makeAction({ status: 'confirmed' }) },
+    })
+    ;(cancelPendingAction as jest.Mock).mockResolvedValue({
+      ok: true,
+      data: { ok: true, pendingAction: makeAction({ status: 'cancelled' }) },
+    })
+  })
+
+  it('renders fieldDiff mode with before/after cells', () => {
+    installPollingMock(makeAction())
+    renderWithProviders(
+      <MutationPreviewCard
+        componentId="mutation-preview-card"
+        pendingActionId="pa-1"
+      />,
+      { dict },
+    )
+    expect(screen.getByText('Alice')).toBeInTheDocument()
+    expect(screen.getByText('Alicia')).toBeInTheDocument()
+    expect(document.querySelector('[data-ai-mutation-preview-mode]')?.getAttribute('data-ai-mutation-preview-mode')).toBe('single')
+  })
+
+  it('renders records[] batch mode with count + labels summary', () => {
+    installPollingMock(
+      makeAction({
+        records: [
+          { recordId: 'r-1', entityType: 'customers.person', label: 'Alice', fieldDiff: [] },
+          { recordId: 'r-2', entityType: 'customers.person', label: 'Bob', fieldDiff: [] },
+          { recordId: 'r-3', entityType: 'customers.person', label: 'Chris', fieldDiff: [] },
+        ],
+      }),
+    )
+    renderWithProviders(
+      <MutationPreviewCard
+        componentId="mutation-preview-card"
+        pendingActionId="pa-1"
+      />,
+      { dict },
+    )
+    expect(screen.getByText('3')).toBeInTheDocument()
+    expect(screen.getByText('records')).toBeInTheDocument()
+    expect(screen.getByText(/Alice, Bob, Chris/)).toBeInTheDocument()
+    expect(document.querySelector('[data-ai-mutation-preview-mode]')?.getAttribute('data-ai-mutation-preview-mode')).toBe('batch')
+  })
+
+  it('Cmd+Enter triggers confirm; Escape triggers cancel', async () => {
+    installPollingMock(makeAction())
+    renderWithProviders(
+      <MutationPreviewCard
+        componentId="mutation-preview-card"
+        pendingActionId="pa-1"
+      />,
+      { dict },
+    )
+    const host = document.querySelector('[data-ai-mutation-preview]') as HTMLElement
+    expect(host).not.toBeNull()
+
+    fireEvent.keyDown(host, { key: 'Enter', metaKey: true })
+    await waitFor(() => expect(confirmPendingAction).toHaveBeenCalledWith('pa-1', expect.any(Object)))
+
+    // Card flipped to confirming — reinstall mock with fresh action and mount again for Escape.
+    ;(confirmPendingAction as jest.Mock).mockClear()
+    installPollingMock(makeAction())
+    const { unmount } = renderWithProviders(
+      <MutationPreviewCard
+        componentId="mutation-preview-card"
+        pendingActionId="pa-2"
+      />,
+      { dict },
+    )
+    const hosts = document.querySelectorAll('[data-ai-mutation-preview]')
+    const host2 = hosts[hosts.length - 1] as HTMLElement
+    fireEvent.keyDown(host2, { key: 'Escape' })
+    await waitFor(() => expect(cancelPendingAction).toHaveBeenCalledWith('pa-2', expect.any(Object)))
+    unmount()
+  })
+
+  it('Review details toggles the expanded diff section', async () => {
+    installPollingMock(makeAction())
+    renderWithProviders(
+      <MutationPreviewCard
+        componentId="mutation-preview-card"
+        pendingActionId="pa-1"
+      />,
+      { dict },
+    )
+    expect(document.querySelector('[data-ai-mutation-preview-details]')).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: /Review details/i }))
+    await waitFor(() => {
+      expect(document.querySelector('[data-ai-mutation-preview-details]')).not.toBeNull()
+    })
+    fireEvent.click(screen.getByRole('button', { name: /Review details/i }))
+    await waitFor(() => {
+      expect(document.querySelector('[data-ai-mutation-preview-details]')).toBeNull()
+    })
+  })
+})

package/src/ai/parts/__tests__/MutationResultCard.test.tsx

@@ -0,0 +1,127 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { screen } from '@testing-library/react'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+
+jest.mock('../useAiPendingActionPolling', () => ({
+  useAiPendingActionPolling: jest.fn(),
+}))
+
+import { useAiPendingActionPolling } from '../useAiPendingActionPolling'
+import { MutationResultCard } from '../MutationResultCard'
+import type { AiPendingActionCardAction } from '../types'
+
+const dict = {
+  'ai_assistant.chat.mutation_cards.result.successTitle': 'Action applied',
+  'ai_assistant.chat.mutation_cards.result.successBody': 'The mutation completed successfully.',
+  'ai_assistant.chat.mutation_cards.result.successWithCommand': 'Completed',
+  'ai_assistant.chat.mutation_cards.result.viewRecord': 'View record',
+  'ai_assistant.chat.mutation_cards.result.partialTitle': 'Action applied with failures',
+  'ai_assistant.chat.mutation_cards.result.partialBody': 'Some records could not be updated.',
+  'ai_assistant.chat.mutation_cards.result.failureTitle': 'Action failed',
+  'ai_assistant.chat.mutation_cards.result.failureBody': 'The mutation could not be applied.',
+}
+
+function baseAction(
+  overrides: Partial<AiPendingActionCardAction> = {},
+): AiPendingActionCardAction {
+  return {
+    id: 'pa-1',
+    agentId: 'customers.account_assistant',
+    toolName: 'customers.update_person',
+    status: 'confirmed',
+    fieldDiff: [],
+    records: null,
+    failedRecords: null,
+    sideEffectsSummary: null,
+    attachmentIds: [],
+    targetEntityType: 'customers.person',
+    targetRecordId: 'p-1',
+    recordVersion: '1',
+    executionResult: { recordId: 'p-1', commandName: 'customers.updatePerson' },
+    createdAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 10_000).toISOString(),
+    resolvedAt: new Date().toISOString(),
+    resolvedByUserId: 'user-1',
+    ...overrides,
+  }
+}
+
+function installPollingMock(action: AiPendingActionCardAction | null) {
+  ;(useAiPendingActionPolling as jest.Mock).mockReturnValue({
+    action,
+    status: action?.status ?? null,
+    isPolling: false,
+    error: null,
+    refresh: jest.fn().mockResolvedValue(action),
+  })
+}
+
+describe('MutationResultCard', () => {
+  beforeEach(() => {
+    ;(useAiPendingActionPolling as jest.Mock).mockReset()
+  })
+
+  it('renders the success variant + record link', () => {
+    installPollingMock(baseAction())
+    renderWithProviders(
+      <MutationResultCard
+        componentId="mutation-result-card"
+        pendingActionId="pa-1"
+        payload={{ recordHref: '/backend/customers/people/p-1' }}
+      />,
+      { dict },
+    )
+    expect(
+      document.querySelector('[data-ai-mutation-result="success"]'),
+    ).not.toBeNull()
+    expect(screen.getByText('Action applied')).toBeInTheDocument()
+    const link = document.querySelector('[data-ai-mutation-result-link]') as HTMLAnchorElement
+    expect(link).not.toBeNull()
+    expect(link.getAttribute('href')).toBe('/backend/customers/people/p-1')
+  })
+
+  it('renders the partial success variant + list of failed records', () => {
+    installPollingMock(
+      baseAction({
+        failedRecords: [
+          { recordId: 'r-1', error: { code: 'stale_version', message: 'changed' } },
+          { recordId: 'r-2', error: { code: 'validation_error', message: 'bad name' } },
+        ],
+      }),
+    )
+    renderWithProviders(
+      <MutationResultCard componentId="mutation-result-card" pendingActionId="pa-1" />,
+      { dict },
+    )
+    expect(
+      document.querySelector('[data-ai-mutation-result="partial"]'),
+    ).not.toBeNull()
+    expect(
+      document.querySelectorAll('[data-ai-mutation-failed-record]').length,
+    ).toBe(2)
+  })
+
+  it('renders the destructive failure variant with the error code', () => {
+    installPollingMock(
+      baseAction({
+        status: 'failed',
+        executionResult: {
+          error: { code: 'tool_execution_failed', message: 'Internal error' },
+        },
+      }),
+    )
+    renderWithProviders(
+      <MutationResultCard componentId="mutation-result-card" pendingActionId="pa-1" />,
+      { dict },
+    )
+    expect(
+      document.querySelector('[data-ai-mutation-result="failure"]'),
+    ).not.toBeNull()
+    const code = document.querySelector('[data-ai-mutation-result-code]')
+    expect(code?.textContent).toBe('tool_execution_failed')
+  })
+})

package/src/ai/parts/__tests__/useAiPendingActionPolling.test.tsx

@@ -0,0 +1,151 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { act, renderHook, waitFor } from '@testing-library/react'
+
+jest.mock('../../../backend/utils/apiCall', () => ({
+  apiCallOrThrow: jest.fn(),
+}))
+
+import { apiCallOrThrow } from '../../../backend/utils/apiCall'
+import { useAiPendingActionPolling } from '../useAiPendingActionPolling'
+import type { AiPendingActionCardAction, AiPendingActionCardStatus } from '../types'
+
+function makeAction(
+  overrides: Partial<AiPendingActionCardAction> = {},
+): AiPendingActionCardAction {
+  return {
+    id: 'pa-1',
+    agentId: 'customers.account_assistant',
+    toolName: 'customers.update_person',
+    status: 'pending',
+    fieldDiff: [],
+    records: null,
+    failedRecords: null,
+    sideEffectsSummary: null,
+    attachmentIds: [],
+    targetEntityType: 'customers.person',
+    targetRecordId: 'p-1',
+    recordVersion: '1',
+    executionResult: null,
+    createdAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 10_000).toISOString(),
+    resolvedAt: null,
+    resolvedByUserId: null,
+    ...overrides,
+  }
+}
+
+function mockResponse(action: AiPendingActionCardAction) {
+  ;(apiCallOrThrow as jest.Mock).mockImplementation(async () => ({
+    ok: true,
+    status: 200,
+    result: { pendingAction: action },
+    response: {},
+    cacheStatus: null,
+  }))
+}
+
+describe('useAiPendingActionPolling', () => {
+  beforeEach(() => {
+    ;(apiCallOrThrow as jest.Mock).mockReset()
+  })
+
+  it('fetches on mount and continues polling while status is pending', async () => {
+    let status: AiPendingActionCardStatus = 'pending'
+    ;(apiCallOrThrow as jest.Mock).mockImplementation(async () => ({
+      ok: true,
+      status: 200,
+      result: { pendingAction: makeAction({ status }) },
+      response: {},
+      cacheStatus: null,
+    }))
+
+    jest.useFakeTimers()
+    try {
+      const { result, unmount } = renderHook(() =>
+        useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
+      )
+
+      // Flush the promise chain kicked off on mount.
+      await act(async () => {
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      expect(apiCallOrThrow).toHaveBeenCalledTimes(1)
+      expect(result.current.status).toBe('pending')
+
+      await act(async () => {
+        jest.advanceTimersByTime(1000)
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      expect((apiCallOrThrow as jest.Mock).mock.calls.length).toBeGreaterThanOrEqual(2)
+
+      status = 'confirmed'
+      await act(async () => {
+        jest.advanceTimersByTime(1000)
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      expect(result.current.status).toBe('confirmed')
+      const callsAfterTerminal = (apiCallOrThrow as jest.Mock).mock.calls.length
+
+      await act(async () => {
+        jest.advanceTimersByTime(5000)
+        await Promise.resolve()
+      })
+      expect((apiCallOrThrow as jest.Mock).mock.calls.length).toBe(callsAfterTerminal)
+      expect(result.current.isPolling).toBe(false)
+
+      unmount()
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
+  it('refresh() force-fetches and updates state', async () => {
+    mockResponse(makeAction({ status: 'pending' }))
+    const { result } = renderHook(() =>
+      useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 99999 }),
+    )
+
+    await waitFor(() => expect(result.current.action?.status).toBe('pending'))
+
+    ;(apiCallOrThrow as jest.Mock).mockImplementationOnce(async () => ({
+      ok: true,
+      status: 200,
+      result: { pendingAction: makeAction({ status: 'confirmed' }) },
+      response: {},
+      cacheStatus: null,
+    }))
+
+    await act(async () => {
+      await result.current.refresh()
+    })
+
+    expect(result.current.action?.status).toBe('confirmed')
+  })
+
+  it('clears outstanding timers when unmounted mid-poll', async () => {
+    jest.useFakeTimers()
+    try {
+      mockResponse(makeAction({ status: 'pending' }))
+      const { unmount } = renderHook(() =>
+        useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
+      )
+      await waitFor(() => expect(apiCallOrThrow).toHaveBeenCalledTimes(1))
+      unmount()
+      const callsAtUnmount = (apiCallOrThrow as jest.Mock).mock.calls.length
+      // Advance well past several intervals — no more calls must be fired.
+      await act(async () => {
+        jest.advanceTimersByTime(10_000)
+      })
+      expect((apiCallOrThrow as jest.Mock).mock.calls.length).toBe(callsAtUnmount)
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+})

package/src/ai/parts/approval-cards-map.ts

@@ -0,0 +1,24 @@
+"use client"
+
+import type { AiUiPartComponent, AiUiPartProps } from '../ui-part-registry'
+import { MutationPreviewCard } from './MutationPreviewCard'
+import { FieldDiffCard } from './FieldDiffCard'
+import { ConfirmationCard } from './ConfirmationCard'
+import { MutationResultCard } from './MutationResultCard'
+
+/**
+ * Canonical map of the four Phase 3 mutation-approval cards keyed by their
+ * reserved registry component ids. Consumers can spread this into any
+ * `AiUiPartRegistry` to wire the live cards at once. Isolated from
+ * `parts/index.ts` so the `ui-part-registry` module can import the map
+ * without importing the barrel (which would re-export back into the same
+ * module and trip Node's "Cannot access before initialization" ordering).
+ */
+export const AI_MUTATION_APPROVAL_CARDS: Readonly<
+  Record<string, AiUiPartComponent<AiUiPartProps>>
+> = Object.freeze({
+  'mutation-preview-card': MutationPreviewCard as AiUiPartComponent<AiUiPartProps>,
+  'field-diff-card': FieldDiffCard as unknown as AiUiPartComponent<AiUiPartProps>,
+  'confirmation-card': ConfirmationCard as AiUiPartComponent<AiUiPartProps>,
+  'mutation-result-card': MutationResultCard as AiUiPartComponent<AiUiPartProps>,
+})

package/src/ai/parts/index.ts

@@ -0,0 +1,27 @@
+"use client"
+
+export { MutationPreviewCard } from './MutationPreviewCard'
+export { FieldDiffCard } from './FieldDiffCard'
+export { ConfirmationCard } from './ConfirmationCard'
+export { MutationResultCard } from './MutationResultCard'
+export {
+  useAiPendingActionPolling,
+  type UseAiPendingActionPollingOptions,
+  type UseAiPendingActionPollingResult,
+} from './useAiPendingActionPolling'
+export {
+  confirmPendingAction,
+  cancelPendingAction,
+  type PendingActionMutationOk,
+  type PendingActionMutationError,
+  type PendingActionMutationResult,
+} from './pending-action-api'
+export type {
+  AiPendingActionCardAction,
+  AiPendingActionCardStatus,
+  AiPendingActionCardFieldDiff,
+  AiPendingActionCardRecordDiff,
+  AiPendingActionCardFailedRecord,
+  AiPendingActionCardExecutionResult,
+} from './types'
+export { AI_MUTATION_APPROVAL_CARDS } from './approval-cards-map'

package/src/ai/parts/pending-action-api.ts

@@ -0,0 +1,123 @@
+"use client"
+
+import { apiCall } from '../../backend/utils/apiCall'
+import type { AiPendingActionCardAction } from './types'
+
+/**
+ * Thin client wrappers over the pending-action confirm/cancel routes
+ * (Steps 5.8 / 5.9). Kept here so the mutation-approval cards (Step 5.10)
+ * can thread structured error envelopes — especially the 412 `stale_version`
+ * / 412 `schema_drift` / 409 `invalid_status` shapes — back into the UI
+ * without each card reimplementing the same fetch boilerplate.
+ *
+ * `apiCall` is used (not `apiCallOrThrow`) because the cards need the
+ * non-2xx response body (`{ error, code, failedRecords?, issues? }`) to
+ * surface a targeted alert, not a generic thrown error.
+ */
+
+export type PendingActionMutationOk = {
+  ok: boolean
+  pendingAction: AiPendingActionCardAction
+  mutationResult?: AiPendingActionCardAction['executionResult']
+}
+
+export type PendingActionMutationError = {
+  status: number
+  code?: string
+  message: string
+  extra?: Record<string, unknown>
+}
+
+export type PendingActionMutationResult =
+  | { ok: true; data: PendingActionMutationOk }
+  | { ok: false; error: PendingActionMutationError }
+
+// Hard ceiling for confirm/cancel calls. The dispatcher's mutation gate runs
+// the wrapped tool handler synchronously inside the POST, so for slow
+// providers (LLM-backed handlers, large bulk batches, external APIs) we still
+// give it ~1 minute. Going longer than this is almost always a server-side
+// hang and the operator should see an error rather than an indefinite
+// "processing…" spinner.
+const POST_JSON_TIMEOUT_MS = 60_000
+
+async function postJson(
+  url: string,
+  body?: unknown,
+): Promise<PendingActionMutationResult> {
+  const controller = new AbortController()
+  const timer =
+    typeof window !== 'undefined'
+      ? window.setTimeout(() => controller.abort(), POST_JSON_TIMEOUT_MS)
+      : null
+  try {
+    const call = await apiCall<Record<string, unknown>>(url, {
+      method: 'POST',
+      headers: body ? { 'Content-Type': 'application/json' } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    } as RequestInit)
+    if (call.ok) {
+      const data = call.result as PendingActionMutationOk
+      return { ok: true, data }
+    }
+    const raw = (call.result ?? {}) as {
+      error?: unknown
+      code?: unknown
+      [key: string]: unknown
+    }
+    const errorMessage =
+      typeof raw.error === 'string' && raw.error.length > 0
+        ? raw.error
+        : `Request failed (${call.status}).`
+    const code = typeof raw.code === 'string' ? raw.code : undefined
+    const { error: _err, code: _code, ...extra } = raw
+    return {
+      ok: false,
+      error: {
+        status: call.status,
+        code,
+        message: errorMessage,
+        extra: Object.keys(extra).length > 0 ? extra : undefined,
+      },
+    }
+  } catch (err) {
+    // Aborted (timeout) or network error. Surface a structured envelope so
+    // the card can render the failure inline instead of stalling.
+    const aborted =
+      (err as { name?: string } | null)?.name === 'AbortError' ||
+      controller.signal.aborted
+    return {
+      ok: false,
+      error: {
+        status: aborted ? 408 : 0,
+        code: aborted ? 'request_timeout' : 'network_error',
+        message: aborted
+          ? `Request timed out after ${Math.round(POST_JSON_TIMEOUT_MS / 1000)}s.`
+          : err instanceof Error
+            ? err.message
+            : 'Network error contacting the AI dispatcher.',
+      },
+    }
+  } finally {
+    if (timer !== null) window.clearTimeout(timer)
+  }
+}
+
+export async function confirmPendingAction(
+  pendingActionId: string,
+  options?: { endpoint?: string },
+): Promise<PendingActionMutationResult> {
+  const base = options?.endpoint ?? '/api/ai_assistant/ai/actions'
+  const url = `${base}/${encodeURIComponent(pendingActionId)}/confirm`
+  return postJson(url)
+}
+
+export async function cancelPendingAction(
+  pendingActionId: string,
+  options?: { endpoint?: string; reason?: string },
+): Promise<PendingActionMutationResult> {
+  const base = options?.endpoint ?? '/api/ai_assistant/ai/actions'
+  const url = `${base}/${encodeURIComponent(pendingActionId)}/cancel`
+  const body = options?.reason ? { reason: options.reason } : undefined
+  return postJson(url, body)
+}