@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/ai-tools/types.ts

@@ -0,0 +1,117 @@
+/**
+ * Local AI tool shape for the workflows module.
+ *
+ * `@open-mercato/core` carries `@open-mercato/ai-assistant` only as a dev/peer
+ * dependency, so — exactly as `customers` and `inbox_ops` already do — this
+ * module declares its tools as plain objects against a structural subset of
+ * `AiToolDefinition` instead of importing the framework at runtime. The
+ * generator walks every module root for a default/`aiTools` export of this
+ * shape and emits it into `ai-tools.generated.ts`, which the ai-assistant
+ * tool-loader registers through `registerMcpTool`.
+ */
+import type { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+import { hasFeature } from '@open-mercato/shared/security/features'
+import type { DefinitionValidationIssue } from '../lib/definition-error-body'
+
+export interface WorkflowsToolContext {
+  tenantId: string | null
+  organizationId: string | null
+  userId: string | null
+  container: AwilixContainer
+  userFeatures: string[]
+  isSuperAdmin: boolean
+  apiKeySecret?: string
+  sessionId?: string
+}
+
+export interface WorkflowsAiToolDefinition<TInput = unknown, TOutput = unknown> {
+  name: string
+  displayName?: string
+  description: string
+  inputSchema: z.ZodType<TInput>
+  requiredFeatures?: string[]
+  tags?: string[]
+  isMutation?: boolean
+  isDestructive?: boolean | ((input: TInput) => boolean)
+  handler: (input: TInput, context: WorkflowsToolContext) => Promise<TOutput>
+}
+
+/**
+ * Every tool in this pack answers with the same envelope: a boolean outcome and
+ * a list of STRUCTURED issues — never a prose error string. `issues` is the
+ * identical `{path, code, message, expected?, got?}` shape the definition
+ * create/update routes return in their 400 body.
+ */
+export interface WorkflowsToolEnvelope {
+  ok: boolean
+  issues: DefinitionValidationIssue[]
+}
+
+export function issue(
+  path: Array<string | number>,
+  code: string,
+  message: string,
+  extra: { expected?: string; got?: string } = {},
+): DefinitionValidationIssue {
+  return { path, code, message, ...extra }
+}
+
+export function failure(...issues: DefinitionValidationIssue[]): WorkflowsToolEnvelope {
+  return { ok: false, issues }
+}
+
+export interface WorkflowsToolScope {
+  tenantId: string
+  organizationId: string | null
+}
+
+/**
+ * Tenant scope is mandatory for every tool in this pack. An agent principal is
+ * still a principal: without a tenant there is no safe query to run, so the
+ * tool refuses rather than reading across tenants.
+ */
+export function resolveScope(ctx: WorkflowsToolContext): WorkflowsToolScope | null {
+  if (!ctx.tenantId) return null
+  return { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+}
+
+export const MISSING_TENANT_ISSUE = issue(
+  ['tenantId'],
+  'missing_tenant_context',
+  'Tenant context is required for workflows.* tools',
+)
+
+/**
+ * Defense in depth. The tool runtime already gates `requiredFeatures` through
+ * the wildcard-aware matcher before a handler runs; re-checking here keeps the
+ * guarantee when a handler is invoked directly (tests, in-process callers) and
+ * makes the refusal a structured issue rather than a thrown string.
+ */
+export function missingFeatures(
+  ctx: WorkflowsToolContext,
+  required: readonly string[],
+): string[] {
+  if (ctx.isSuperAdmin) return []
+  return required.filter((feature) => !hasFeature(ctx.userFeatures, feature))
+}
+
+export function featureRefusal(missing: readonly string[]): WorkflowsToolEnvelope {
+  return failure(
+    issue(
+      ['requiredFeatures'],
+      'insufficient_permissions',
+      `Missing required feature(s): ${missing.join(', ')}`,
+      { expected: missing.join(', ') },
+    ),
+  )
+}
+
+/**
+ * Organization where-clause fragment for a tenant-scoped lookup. A null
+ * organization stays tenant-wide, matching the REST routes' behaviour when the
+ * caller's scope spans every organization.
+ */
+export function organizationWhere(scope: WorkflowsToolScope): Record<string, unknown> {
+  return scope.organizationId ? { organizationId: scope.organizationId } : {}
+}

package/src/modules/workflows/ai-tools.ts

@@ -0,0 +1,20 @@
+/**
+ * Module-root AI tool contribution for the workflows module (spec §9.5,
+ * roadmap Phase 6 — "Agent-as-author (MCP tool pack)").
+ *
+ * The generator walks every module for a top-level `ai-tools.ts` and takes the
+ * default/`aiTools` export as the contribution; `ai-tools.generated.ts` is then
+ * loaded by the ai-assistant tool-loader, which registers each tool through
+ * `registerMcpTool`. That single registry serves BOTH consumers: the MCP server
+ * (external agents) and the in-app `<AiChat>` agent runtime.
+ *
+ * Requires `yarn generate` to be discovered.
+ */
+import workflowsAuthoringAiTools from './ai-tools/authoring-pack'
+import type { WorkflowsAiToolDefinition } from './ai-tools/types'
+
+export const aiTools: WorkflowsAiToolDefinition<never, never>[] = [
+  ...workflowsAuthoringAiTools,
+]
+
+export default aiTools

package/src/modules/workflows/api/command-settings/route.ts

@@ -0,0 +1,171 @@
+/**
+ * Tenant enablement for UPDATE_ENTITY commands (tier 2 of the model described
+ * in `lib/workflow-command-enablement.ts`).
+ *
+ * - GET  /api/workflows/command-settings — the catalogue with this tenant's answer
+ * - PUT  /api/workflows/command-settings — tick / untick candidates
+ *
+ * A new route, which BACKWARD_COMPATIBILITY.md §7 allows freely. Shape follows
+ * `api/task-settings/route.ts`.
+ *
+ * The PUT body carries command IDS, never a free-form command name: every id is
+ * checked against the code-declared catalogue and an unknown one is a 400. That
+ * refusal IS the safety model — an administrator who could type an arbitrary id
+ * would reach commands nobody designed for unattended execution, and a command
+ * with no declared `requiredFeatures` would have no gate left at all.
+ *
+ * `tenantId` always comes from the authenticated context and never from the
+ * request body — a settings write that accepted a tenant id would be a
+ * cross-tenant write primitive.
+ */
+
+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 type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { listWorkflowSafeCommands } from '../../lib/workflow-safe-commands'
+import {
+  findUncataloguedCommandIds,
+  mergeEnabledCommandIds,
+  resolveWorkflowCommandCatalogue,
+  UNSET_WORKFLOW_COMMAND_POLICY,
+} from '../../lib/workflow-command-enablement'
+import {
+  readEnabledWorkflowCommandIds,
+  resolveWorkflowCommandConfigService,
+  writeEnabledWorkflowCommandIds,
+  type WorkflowCommandConfigService,
+} from '../../lib/workflow-command-settings'
+import {
+  workflowsTag,
+  workflowErrorSchema,
+  workflowCommandSettingsResponseSchema,
+  workflowCommandSettingsPutBodySchema,
+  workflowCommandSettingsPutResponseSchema,
+} from '../openapi'
+
+export const metadata = {
+  // Reading which commands a workflow may execute is what a definition author
+  // needs in order to author one, so it rides on the definition-view feature
+  // rather than on task administration.
+  GET: { requireAuth: true, requireFeatures: ['workflows.definitions.view'] },
+  // Ticking a candidate widens what EVERY workflow in the tenant may mutate.
+  PUT: { requireAuth: true, requireFeatures: ['workflows.manage'] },
+}
+
+const putBodySchema = z.object({
+  enabledCommandIds: z.array(z.string().min(1)).max(500),
+})
+
+async function resolveModuleConfigService(): Promise<WorkflowCommandConfigService | null> {
+  try {
+    const container = await createRequestContainer()
+    return resolveWorkflowCommandConfigService(container)
+  } catch {
+    // Fails to the UNSET policy, i.e. the grandfathered set — never to
+    // "everything enabled".
+    return null
+  }
+}
+
+export async function GET(request: Request) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const moduleConfigService = await resolveModuleConfigService()
+  const stored = await readEnabledWorkflowCommandIds(moduleConfigService, auth.tenantId)
+  const catalogue = listWorkflowSafeCommands()
+
+  return NextResponse.json({
+    configured: stored !== null,
+    items: resolveWorkflowCommandCatalogue(
+      catalogue,
+      stored === null ? UNSET_WORKFLOW_COMMAND_POLICY : { enabledCommandIds: stored },
+    ),
+  })
+}
+
+export async function PUT(request: Request) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })
+  }
+
+  const parsed = putBodySchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: 'Validation failed', details: parsed.error.flatten() },
+      { status: 400 },
+    )
+  }
+
+  const catalogue = listWorkflowSafeCommands()
+  const unknownCommandIds = findUncataloguedCommandIds(parsed.data.enabledCommandIds, catalogue)
+  if (unknownCommandIds.length > 0) {
+    return NextResponse.json(
+      {
+        error: 'Unknown workflow-safe command',
+        code: 'WORKFLOW_COMMAND_NOT_IN_CATALOGUE',
+        commandIds: unknownCommandIds,
+      },
+      { status: 400 },
+    )
+  }
+
+  const moduleConfigService = await resolveModuleConfigService()
+  if (!moduleConfigService) {
+    return NextResponse.json({ error: 'Settings storage unavailable' }, { status: 503 })
+  }
+
+  const stored = await readEnabledWorkflowCommandIds(moduleConfigService, auth.tenantId)
+  const enabledCommandIds = mergeEnabledCommandIds(
+    parsed.data.enabledCommandIds,
+    stored,
+    catalogue,
+  )
+  await writeEnabledWorkflowCommandIds(moduleConfigService, auth.tenantId, enabledCommandIds)
+
+  return NextResponse.json({
+    ok: true,
+    configured: true,
+    items: resolveWorkflowCommandCatalogue(catalogue, { enabledCommandIds }),
+  })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Tenant UPDATE_ENTITY command enablement',
+  methods: {
+    GET: {
+      summary: 'List workflow-safe command candidates with tenant enablement',
+      description:
+        'Returns every command declared through registerWorkflowSafeCommands together with whether this tenant has switched it on. `configured: false` means the tenant has never saved the setting and the answers come from the grandfathered defaults.',
+      responses: [
+        { status: 200, description: 'Catalogue with tenant enablement', schema: workflowCommandSettingsResponseSchema },
+        { status: 401, description: 'Missing authentication', schema: workflowErrorSchema },
+      ],
+    },
+    PUT: {
+      summary: 'Set which workflow-safe commands are enabled for the tenant',
+      description:
+        'Replaces the tenant\'s enabled set. Every submitted id must be present in the code-declared catalogue; an unknown id is rejected with 400 rather than stored. Stored ids whose declaring module is not loaded in this process are retained so a save can never silently untick them.',
+      requestBody: { schema: workflowCommandSettingsPutBodySchema },
+      responses: [
+        { status: 200, description: 'Updated enablement', schema: workflowCommandSettingsPutResponseSchema },
+        { status: 400, description: 'Invalid payload or unknown command id', schema: workflowErrorSchema },
+        { status: 401, description: 'Missing authentication', schema: workflowErrorSchema },
+        { status: 503, description: 'Settings storage unavailable', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/commands/route.ts

@@ -0,0 +1,109 @@
+/**
+ * Workflow-Safe Commands API
+ *
+ * Endpoint:
+ * - GET /api/workflows/commands - List commands allowlisted for UPDATE_ENTITY activities
+ *
+ * ## Why this returns disabled candidates instead of hiding them
+ *
+ * It used to return the whole catalogue to any holder of
+ * `workflows.definitions.edit`, which meant an author could pick a command the
+ * tenant had not enabled and only discover it when a run failed. Returning ONLY
+ * the enabled ones would fix that failure but create a worse one: the field
+ * accepts free text (`allowCustomValues`), so a command that vanishes from the
+ * list is not prevented, it is merely unexplained — "why can I not update
+ * products here?" becomes unanswerable from the editor.
+ *
+ * So every candidate is returned with an explicit `enabled` flag and the picker
+ * renders the disabled ones as unavailable, naming the remedy. This is the same
+ * rule the command palette already follows: a command that cannot run right now
+ * is shown disabled, never hidden, because a missing entry reads as
+ * "unsupported" and a disabled one reads as "not now".
+ *
+ * `enabled`, `defaultEnabled` and `labelKey` are ADDITIVE fields on an existing
+ * response; `commandId` and `requiredFeatures` are unchanged.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+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 { listWorkflowSafeCommands } from '../../lib/workflow-safe-commands'
+import { resolveWorkflowCommandCatalogue } from '../../lib/workflow-command-enablement'
+import { resolveWorkflowCommandPolicyForContainer } from '../../lib/workflow-command-settings'
+import { workflowsTag, workflowErrorSchema, workflowSafeCommandListResponseSchema } from '../openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.definitions.edit'],
+}
+
+/**
+ * GET /api/workflows/commands
+ *
+ * List the workflow-safe command allowlist for the UPDATE_ENTITY command picker.
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const container = await createRequestContainer()
+    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 organizationId = scope?.selectedId ?? auth.orgId
+
+    if (!tenantId) {
+      return NextResponse.json({ error: 'Missing tenant context' }, { status: 400 })
+    }
+
+    const rbacService = container.resolve('rbacService')
+    const hasPermission = await rbacService.userHasAllFeatures(
+      auth.sub,
+      ['workflows.definitions.edit'],
+      { tenantId, organizationId }
+    )
+
+    if (!hasPermission) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 })
+    }
+
+    const policy = await resolveWorkflowCommandPolicyForContainer(container, tenantId)
+    const items = resolveWorkflowCommandCatalogue(listWorkflowSafeCommands(), policy)
+
+    return NextResponse.json({ items })
+  } catch (error) {
+    logger.error('Error listing workflow-safe commands', { err: error })
+    return NextResponse.json(
+      { error: 'Failed to list workflow-safe commands' },
+      { status: 500 }
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'List workflow-safe commands',
+  methods: {
+    GET: {
+      summary: 'List commands allowlisted for UPDATE_ENTITY activities',
+      description: 'Returns the registered workflow-safe command catalogue consumed by the UPDATE_ENTITY command picker, each entry carrying whether the caller\'s tenant has enabled it. Entries with enabled:false, and commands outside the catalogue entirely, can still be authored but fail at runtime.',
+      responses: [
+        { status: 200, description: 'Allowlisted workflow-safe commands', schema: workflowSafeCommandListResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Missing tenant context', schema: workflowErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
+        { status: 403, description: 'Insufficient permissions', schema: workflowErrorSchema },
+        { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/definitions/[id]/callers/route.ts

@@ -0,0 +1,95 @@
+/**
+ * Workflow Definition Callers (breaking-change preview)
+ *
+ * GET /api/workflows/definitions/[id]/callers
+ *
+ * Returns the parent definitions that invoke this workflow as a sub-workflow and,
+ * for each, the field mappings that this definition's current IO port contract
+ * would break.
+ */
+
+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 { createLogger } from '@open-mercato/shared/lib/logger'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { WorkflowDefinition } from '../../../../data/entities'
+import type { WorkflowIoContract } from '../../../../data/validators'
+import { findSubWorkflowCallers } from '../../../../lib/caller-graph'
+
+const logger = createLogger('workflows').child({ component: 'definition-callers-api' })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.definitions.view'],
+}
+
+interface RouteContext {
+  params: Promise<{ id: string }>
+}
+
+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 organizationId = scope?.selectedId ?? auth.orgId
+
+    if (!tenantId || !organizationId) {
+      return NextResponse.json({ error: 'Missing tenant or organization context' }, { status: 400 })
+    }
+
+    const definition = await em.findOne(WorkflowDefinition, {
+      id: params.id,
+      tenantId,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!definition) {
+      return NextResponse.json({ error: 'Workflow definition not found' }, { status: 404 })
+    }
+
+    const ports: WorkflowIoContract = (definition.definition as { io?: WorkflowIoContract })?.io || {}
+    const callers = await findSubWorkflowCallers(em, {
+      subWorkflowId: definition.workflowId,
+      tenantId,
+      organizationId,
+      ports,
+    })
+
+    return NextResponse.json({ callers })
+  } catch (error) {
+    logger.error('error resolving workflow definition callers', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return NextResponse.json({ error: 'Failed to resolve callers' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      summary: 'List sub-workflow callers and breaking mappings',
+      description: 'Returns parent definitions that invoke this workflow as a sub-workflow and the mappings its current port contract would break.',
+      tags: ['Workflows'],
+      pathParams: z.object({ id: z.string().describe('Workflow definition id') }),
+      responses: [
+        {
+          status: 200,
+          description: 'Callers',
+          example: { callers: [{ workflowId: 'order-flow', version: 1, stepId: 'sub', brokenMappings: ['input:orderId'] }] },
+        },
+        { status: 404, description: 'Not found', example: { error: 'Workflow definition not found' } },
+      ],
+    },
+  },
+}