@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/api/instances/[id]/steps/route.ts

@@ -0,0 +1,160 @@
+/**
+ * Workflow Step Instances API (spec §8.3)
+ *
+ * Endpoint:
+ * - GET /api/workflows/instances/[id]/steps - Per-step execution record
+ *
+ * `StepInstance` has always recorded `inputData`, `outputData`, `errorData`,
+ * `executionTimeMs` and `retryCount`, but until this route no API or page read
+ * any of it. The per-step I/O inspector and the run Gantt both need it, so the
+ * read surface comes first.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
+import { WorkflowInstance, StepInstance } from '../../../../data/entities'
+import { workflowStepInstanceRowSchema, paginationSchema } from '../../../openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.instances.view'],
+}
+
+/**
+ * Platform cap: no list surface pages above 100 rows. A run with more step
+ * executions than this reports `pagination.hasMore` so the caller can page
+ * rather than silently rendering a truncated timeline.
+ */
+export const STEP_INSTANCE_PAGE_SIZE_MAX = 100
+
+interface RouteContext {
+  params: Promise<{
+    id: string
+  }>
+}
+
+function parsePositiveInt(raw: string | null, fallback: number): number {
+  if (raw === null) return fallback
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isFinite(parsed)) return fallback
+  return parsed
+}
+
+/**
+ * GET /api/workflows/instances/[id]/steps
+ */
+export async function GET(request: NextRequest, context: RouteContext) {
+  try {
+    const params = await context.params
+    const container = await createRequestContainer()
+    const em = container.resolve('em')
+    const auth = await getAuthFromRequest(request)
+
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const orgFilter = resolveOrganizationScopeFilter(scope, auth)
+
+    if (!tenantId) {
+      return NextResponse.json({ error: 'Missing tenant context' }, { status: 400 })
+    }
+
+    const instance = await em.findOne(WorkflowInstance, {
+      id: params.id,
+      tenantId,
+      ...orgFilter.where,
+    })
+
+    if (!instance) {
+      return NextResponse.json({ error: 'Workflow instance not found' }, { status: 404 })
+    }
+
+    const { searchParams } = new URL(request.url)
+    const requestedLimit = parsePositiveInt(searchParams.get('limit'), STEP_INSTANCE_PAGE_SIZE_MAX)
+    const limit = Math.min(Math.max(requestedLimit, 1), STEP_INSTANCE_PAGE_SIZE_MAX)
+    const offset = Math.max(parsePositiveInt(searchParams.get('offset'), 0), 0)
+
+    // Ordered by when the step was entered so the Gantt and the overlay read the
+    // run in execution order. `createdAt` is the tiebreaker because a step
+    // instance is persisted before `enteredAt` is stamped on some paths.
+    const [steps, total] = await em.findAndCount(
+      StepInstance,
+      {
+        workflowInstanceId: params.id,
+        tenantId,
+        ...orgFilter.where,
+      },
+      {
+        orderBy: [{ enteredAt: 'ASC' }, { createdAt: 'ASC' }],
+        limit,
+        offset,
+      }
+    )
+
+    return NextResponse.json({
+      data: steps,
+      pagination: {
+        total,
+        limit,
+        offset,
+        hasMore: offset + limit < total,
+      },
+    })
+  } catch (error) {
+    logger.error('Error getting workflow step instances', { err: error })
+    return NextResponse.json({ error: 'Failed to get workflow step instances' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      summary: 'Get workflow instance step executions',
+      description:
+        'List the step executions recorded for a workflow instance, including per-step input, output, error payload, duration and attempt count.',
+      tags: ['Workflows'],
+      params: z.object({
+        id: z.string().uuid(),
+      }),
+      query: z.object({
+        limit: z.number().int().positive().max(STEP_INSTANCE_PAGE_SIZE_MAX).default(STEP_INSTANCE_PAGE_SIZE_MAX).optional(),
+        offset: z.number().int().min(0).default(0).optional(),
+      }),
+      responses: [
+        {
+          status: 200,
+          description: 'List of step executions',
+          schema: z.object({
+            data: z.array(workflowStepInstanceRowSchema),
+            pagination: paginationSchema,
+          }),
+        },
+        {
+          status: 401,
+          description: 'Unauthorized',
+          schema: z.object({ error: z.string() }),
+        },
+        {
+          status: 404,
+          description: 'Workflow instance not found',
+          schema: z.object({ error: z.string() }),
+        },
+        {
+          status: 500,
+          description: 'Internal server error',
+          schema: z.object({ error: z.string() }),
+        },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/instances/[id]/would-do/route.ts

@@ -0,0 +1,216 @@
+/**
+ * Workflow "Would do" report API (spec section 8.2)
+ *
+ * Endpoint:
+ * - GET /api/workflows/instances/[id]/would-do - the ordered list of every side
+ *   effect a dry run suppressed.
+ *
+ * The report is DERIVED, never stored twice: a dry run writes its would-do
+ * entries as ordinary `WorkflowEvent` rows, so the report inherits the run
+ * views' tenant scoping, ordering and retention instead of owning a second
+ * table that could disagree with the run log.
+ *
+ * A real run answers `{ isDryRun: false, entries: [] }` rather than 404 — the
+ * caller asks "what did this run suppress?" and "nothing, it was real" is a
+ * correct answer, not a missing resource.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
+import { WorkflowInstance, WorkflowEvent, StepInstance } from '../../../../data/entities'
+import { DRY_RUN_EVENT_TYPES, buildWouldDoReport, type WouldDoSourceEvent } from '../../../../lib/dry-run'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.instances.view'],
+}
+
+/** Platform cap: no list surface pages above 100 rows. */
+export const WOULD_DO_PAGE_SIZE_MAX = 100
+
+const REPORTED_EVENT_TYPES = [
+  DRY_RUN_EVENT_TYPES.activitySimulated,
+  DRY_RUN_EVENT_TYPES.activityRefused,
+  DRY_RUN_EVENT_TYPES.userTaskSimulated,
+  DRY_RUN_EVENT_TYPES.businessRuleActionsSuppressed,
+]
+
+interface RouteContext {
+  params: Promise<{ id: string }>
+}
+
+function parsePositiveInt(raw: string | null, fallback: number): number {
+  if (raw === null) return fallback
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isFinite(parsed)) return fallback
+  return parsed
+}
+
+export async function GET(request: NextRequest, context: RouteContext) {
+  try {
+    const params = await context.params
+    const container = await createRequestContainer()
+    const em = container.resolve('em')
+    const auth = await getAuthFromRequest(request)
+
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const orgFilter = resolveOrganizationScopeFilter(scope, auth)
+
+    if (!tenantId) {
+      return NextResponse.json({ error: 'Missing tenant context' }, { status: 400 })
+    }
+
+    const instance = await em.findOne(WorkflowInstance, {
+      id: params.id,
+      tenantId,
+      ...orgFilter.where,
+    })
+
+    if (!instance) {
+      return NextResponse.json({ error: 'Workflow instance not found' }, { status: 404 })
+    }
+
+    if (!instance.isDryRun) {
+      return NextResponse.json({
+        isDryRun: false,
+        entries: [],
+        stoppedByRefusal: false,
+        pagination: { total: 0, limit: 0, offset: 0, hasMore: false },
+      })
+    }
+
+    const { searchParams } = new URL(request.url)
+    const requestedLimit = parsePositiveInt(searchParams.get('limit'), WOULD_DO_PAGE_SIZE_MAX)
+    const limit = Math.min(Math.max(requestedLimit, 1), WOULD_DO_PAGE_SIZE_MAX)
+    const offset = Math.max(parsePositiveInt(searchParams.get('offset'), 0), 0)
+
+    const [events, total] = await em.findAndCount(
+      WorkflowEvent,
+      {
+        workflowInstanceId: params.id,
+        tenantId,
+        ...orgFilter.where,
+        eventType: { $in: REPORTED_EVENT_TYPES },
+      },
+      {
+        // `id` breaks ties: two entries can share a millisecond, and a report
+        // that reorders between two reads is not evidence.
+        orderBy: [{ occurredAt: 'ASC' }, { id: 'ASC' }],
+        limit,
+        offset,
+      }
+    )
+
+    // `WorkflowEvent` carries the step INSTANCE id; the report is read against
+    // the canvas, which addresses steps by their definition `stepId`. Resolving
+    // the handful of rows once here keeps the pure report builder free of the
+    // ORM and stops every consumer re-deriving the same join.
+    const stepInstanceIds = Array.from(
+      new Set(
+        events
+          .map((event: WorkflowEvent) => event.stepInstanceId)
+          .filter((id: string | null | undefined): id is string => !!id)
+      )
+    )
+    const stepInstances = stepInstanceIds.length
+      ? await em.find(StepInstance, {
+          id: { $in: stepInstanceIds },
+          tenantId,
+          ...orgFilter.where,
+        })
+      : []
+    const stepIdByInstanceId = new Map<string, string>(
+      stepInstances.map((step: StepInstance) => [step.id, step.stepId])
+    )
+
+    const sourceEvents: WouldDoSourceEvent[] = events.map((event: WorkflowEvent) => ({
+      // `WorkflowEvent.id` is a `bigint` column, and MikroORM v7's `BigIntType`
+      // hydrates it as a native JS `bigint` (its default mode) despite the
+      // `string` annotation. Lifting it out of the entity into a plain object
+      // bypasses the ORM serializer that would have stringified it, so
+      // `NextResponse.json` would throw "Do not know how to serialize a BigInt"
+      // and the catch below would report it as a generic 500. Same fix as
+      // `api/events/route.ts`.
+      id: String(event.id),
+      eventType: event.eventType,
+      stepId: event.stepInstanceId ? stepIdByInstanceId.get(event.stepInstanceId) ?? null : null,
+      occurredAt: event.occurredAt,
+      eventData: (event.eventData ?? null) as Record<string, unknown> | null,
+    }))
+
+    const report = buildWouldDoReport(sourceEvents)
+
+    return NextResponse.json({
+      isDryRun: true,
+      entries: report.entries,
+      stoppedByRefusal: report.stoppedByRefusal,
+      pagination: {
+        total,
+        limit,
+        offset,
+        hasMore: offset + limit < total,
+      },
+    })
+  } catch (error) {
+    logger.error('Error building workflow would-do report', { err: error })
+    return NextResponse.json({ error: 'Failed to build would-do report' }, { status: 500 })
+  }
+}
+
+const wouldDoEntrySchema = z.object({
+  id: z.string(),
+  kind: z.enum(['activity', 'refusal', 'userTask', 'businessRule']),
+  severity: z.enum(['error', 'warning', 'info']),
+  stepId: z.string().nullable(),
+  occurredAt: z.string(),
+  subject: z.string(),
+  detail: z.record(z.string(), z.unknown()),
+})
+
+export const openApi = {
+  methods: {
+    GET: {
+      summary: 'Get a dry run\'s "Would do" report',
+      description:
+        'List every side effect a dry run suppressed, in execution order: simulated activities with their would-do output, activity types that refused simulation and stopped the run, user tasks that were not raised, and business rules whose action arm was withheld. A real (non-dry) run answers with an empty report.',
+      tags: ['Workflows'],
+      params: z.object({ id: z.string().uuid() }),
+      query: z.object({
+        limit: z.number().int().positive().max(WOULD_DO_PAGE_SIZE_MAX).optional(),
+        offset: z.number().int().min(0).optional(),
+      }),
+      responses: [
+        {
+          status: 200,
+          description: 'The would-do report',
+          schema: z.object({
+            isDryRun: z.boolean(),
+            entries: z.array(wouldDoEntrySchema),
+            stoppedByRefusal: z.boolean(),
+            pagination: z.object({
+              total: z.number(),
+              limit: z.number(),
+              offset: z.number(),
+              hasMore: z.boolean(),
+            }),
+          }),
+        },
+        { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
+        { status: 404, description: 'Workflow instance not found', schema: z.object({ error: z.string() }) },
+        { status: 500, description: 'Internal server error', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/instances/bulk-replay/route.ts

@@ -0,0 +1,141 @@
+/**
+ * Failure-queue bulk replay (spec §8.4)
+ *
+ * Endpoint:
+ * - POST /api/workflows/instances/bulk-replay
+ *
+ * Queues the work through the progress module rather than doing it inline:
+ * replaying a page of parked instances re-executes that many real workflows,
+ * which cannot happen inside an HTTP handler and must survive the operator
+ * navigating away (`progress/AGENTS.md` MUST rules 1-4).
+ */
+
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { ProgressService } from '../../../../progress/lib/progressService'
+import { BULK_REPLAY_MAX_IDS, getBulkReplayQueue } from '../../../lib/bulk-replay'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+const requestSchema = z.object({
+  action: z.enum(['retry', 'cancel']),
+  ids: z.array(z.string().uuid()).min(1).max(BULK_REPLAY_MAX_IDS),
+})
+
+const responseSchema = z.object({
+  ok: z.boolean(),
+  progressJobId: z.string().uuid().nullable(),
+  message: z.string(),
+})
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['workflows.instances.bulk_ops'] },
+}
+
+const JOB_NAMES: Record<'retry' | 'cancel', string> = {
+  retry: 'Replay workflow instances',
+  cancel: 'Cancel workflow instances',
+}
+
+export async function POST(request: Request) {
+  try {
+    const auth = await getAuthFromRequest(request)
+    if (!auth?.tenantId || !auth.orgId) {
+      return NextResponse.json(
+        responseSchema.parse({ ok: false, progressJobId: null, message: 'Unauthorized' }),
+        { status: 401 }
+      )
+    }
+
+    const parsed = requestSchema.safeParse(await readJsonSafe(request))
+    if (!parsed.success) {
+      return NextResponse.json(
+        responseSchema.parse({ ok: false, progressJobId: null, message: 'Invalid payload' }),
+        { status: 400 }
+      )
+    }
+
+    const container = await createRequestContainer()
+
+    // The declarative `requireFeatures` guard already gates the route; this is
+    // the same defence-in-depth check the single-instance retry/cancel routes
+    // perform, and it is the one that is scoped to the caller's organization.
+    const rbacService = container.resolve('rbacService')
+    const hasPermission = await rbacService.userHasAllFeatures(
+      auth.sub,
+      ['workflows.instances.bulk_ops'],
+      { tenantId: auth.tenantId, organizationId: auth.orgId }
+    )
+    if (!hasPermission) {
+      return NextResponse.json(
+        responseSchema.parse({ ok: false, progressJobId: null, message: 'Insufficient permissions' }),
+        { status: 403 }
+      )
+    }
+
+    const ids = Array.from(new Set(parsed.data.ids))
+    const progressService = container.resolve('progressService') as ProgressService
+    const progressJob = await progressService.createJob(
+      {
+        jobType: `workflows.instances.bulk_${parsed.data.action}`,
+        name: JOB_NAMES[parsed.data.action],
+        description: `${ids.length} workflow instances queued`,
+        totalCount: ids.length,
+        cancellable: false,
+        meta: { source: 'workflows.failure-queue', action: parsed.data.action },
+      },
+      { tenantId: auth.tenantId, organizationId: auth.orgId, userId: auth.sub }
+    )
+
+    await getBulkReplayQueue().enqueue({
+      progressJobId: progressJob.id,
+      action: parsed.data.action,
+      ids,
+      // The worker re-reads every instance under this scope, so an id from
+      // another tenant resolves to nothing and is skipped rather than acted on.
+      scope: { tenantId: auth.tenantId, organizationId: auth.orgId, userId: auth.sub },
+    })
+
+    return NextResponse.json(
+      responseSchema.parse({
+        ok: true,
+        progressJobId: progressJob.id,
+        message: 'Bulk replay started.',
+      }),
+      { status: 202 }
+    )
+  } catch (error) {
+    logger.error('Error starting workflow bulk replay', { err: error })
+    return NextResponse.json(
+      responseSchema.parse({ ok: false, progressJobId: null, message: 'Failed to start bulk replay' }),
+      { status: 500 }
+    )
+  }
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      summary: 'Bulk retry or cancel workflow instances',
+      description:
+        'Queue a bulk retry or cancel over the failure queue. Work runs in a queue worker and reports through the progress module; the response returns the progress job id immediately.',
+      tags: ['Workflows'],
+      requestBody: {
+        contentType: 'application/json',
+        schema: requestSchema,
+        description: 'Action to apply and the instance ids to apply it to.',
+      },
+      responses: [
+        { status: 202, description: 'Bulk replay queued', schema: responseSchema },
+        { status: 400, description: 'Invalid payload', schema: responseSchema },
+        { status: 401, description: 'Unauthorized', schema: responseSchema },
+        { status: 403, description: 'Insufficient permissions', schema: responseSchema },
+        { status: 500, description: 'Internal server error', schema: responseSchema },
+      ],
+    },
+  },
+}