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

package/src/modules/workflows/lib/task-entity-types.ts

@@ -0,0 +1,66 @@
+/**
+ * Authored `entityType` → generated entity id.
+ *
+ * The bridge between what a task binding carries (free text an author typed)
+ * and what the entity-access model is keyed on (`entities.ids.generated.ts`
+ * ids, which `ENTITY_ACL_REQUIREMENTS` also keys on). It resolves through the
+ * enumerated alias dictionary or through EXACT membership in the entity
+ * registry, and refuses everything else.
+ *
+ * It never guesses. `resolveEntityTableName` pluralizes its way to a table name
+ * and logs a warning; doing that here would turn a typo into a plausible-looking
+ * grant, which is the opposite of fail-closed. A binding that does not resolve
+ * is `null`, and the caller denies.
+ *
+ * The spellings themselves live in `task-entity-aliases.ts` — one dictionary,
+ * shared with `work-inbox/entity-links.ts`.
+ */
+
+import { getEntityIds } from '@open-mercato/shared/lib/encryption/entityIds'
+import { normalizeTaskEntityTypeSpelling, resolveAliasedTaskEntityId } from './task-entity-aliases'
+
+export {
+  TASK_ENTITY_TYPE_ALIAS_GROUPS,
+  listTaskEntityTypeAliases,
+  normalizeTaskEntityTypeSpelling,
+  resolveAliasedTaskEntityId,
+} from './task-entity-aliases'
+export type { TaskEntityTypeAliasGroup } from './task-entity-aliases'
+
+// The registry is a mutable module singleton (re-registered on HMR), so the
+// derived id set is memoized against the registry's object identity rather than
+// built once and frozen.
+let registryIdsSource: unknown = null
+let registryIds: ReadonlySet<string> = new Set<string>()
+
+function knownEntityIds(): ReadonlySet<string> {
+  // `false`: an unregistered registry yields an empty set, so every binding
+  // outside the alias table resolves to null and the caller denies. Failing
+  // closed on a missing registry is intended, not a degradation.
+  const registry = getEntityIds(false)
+  if (registry !== registryIdsSource) {
+    registryIdsSource = registry
+    registryIds = new Set(
+      Object.values(registry ?? {}).flatMap((moduleEntities) => Object.values(moduleEntities ?? {})),
+    )
+  }
+  return registryIds
+}
+
+/**
+ * The generated entity id an authored binding means, or `null` when nothing
+ * enumerated matches it.
+ *
+ * `null` is a refusal, not a fallback: a typo such as `Custmers:Deal` must hide
+ * the task from everyone rather than resolve to something plausible.
+ */
+export function normalizeTaskEntityTypeToEntityId(
+  entityType: string | null | undefined,
+): string | null {
+  if (typeof entityType !== 'string') return null
+  const normalized = normalizeTaskEntityTypeSpelling(entityType)
+  if (!normalized) return null
+  const aliased = resolveAliasedTaskEntityId(normalized)
+  if (aliased) return aliased
+  return knownEntityIds().has(normalized) ? normalized : null
+}

package/src/modules/workflows/lib/task-form-registry.ts

@@ -0,0 +1,123 @@
+/**
+ * Workflows Module - External task form renderer registry (#4243)
+ *
+ * Spec §6.1 §6: *"**External form** […] completed as a **renderer registry**
+ * keyed by formKey, receiving/returning typed context — the same mechanism
+ * portal rendering (§6.4) and record-page widgets use."*
+ *
+ * Modeled on `registerActivityType` (`lib/activity-registry.ts`), including its
+ * purity contract: no React, no MikroORM/EntityManager and no Awilix imports at
+ * module scope — TYPE-ONLY imports — so the worker and the browser can both
+ * load this module. `Renderer` is a component TYPE, which is a type-level
+ * reference and never drags React into a server bundle.
+ *
+ * The registry is a lookup, never a gate: an unknown `formKey` resolves to
+ * `null` and the caller degrades to the built-in form with a visible notice.
+ * A blank screen is the one outcome this must never produce, so nothing here
+ * throws on a miss.
+ */
+
+import type { ComponentType } from 'react'
+import type { ZodTypeAny } from 'zod'
+
+/**
+ * What a renderer receives. Everything a task form could need to render itself
+ * without reaching back into the workflows module — which is what makes the
+ * same registry usable from the backoffice, the portal and a record-page
+ * widget.
+ */
+export interface TaskFormRendererContext<TValues = Record<string, unknown>> {
+  taskId: string
+  taskName: string
+  /** The key this renderer was resolved under. */
+  formKey: string
+  /** The authored schema, in whichever of the two accepted shapes it was written. */
+  formSchema: unknown
+  /** Records the task is about, as resolved at task-creation time. */
+  entityBindings: unknown[] | null
+  /** Decision buttons the surface will render beside the form. */
+  decisions: { id: string }[]
+  /** Current form values. */
+  values: TValues
+  /** True while a completion is in flight. */
+  disabled: boolean
+  /** Locale of the surrounding surface, for renderers that localize themselves. */
+  locale?: string
+}
+
+/**
+ * What a renderer returns: the values the task will be completed with. Called
+ * on every change so the host owns the state, exactly as the built-in form does.
+ */
+export type TaskFormRendererChange<TValues = Record<string, unknown>> = (values: TValues) => void
+
+export interface TaskFormRendererProps<TValues = Record<string, unknown>> {
+  context: TaskFormRendererContext<TValues>
+  onChange: TaskFormRendererChange<TValues>
+}
+
+export interface TaskFormRendererEntry<TValues = Record<string, unknown>> {
+  formKey: string
+  /** i18n key for the section heading the host renders above the form. */
+  titleKey?: string
+  Renderer: ComponentType<TaskFormRendererProps<TValues>>
+  /** Optional shape of the values handed IN (prefill). */
+  inputSchema?: ZodTypeAny
+  /** Optional shape of the values handed OUT (completion payload). */
+  outputSchema?: ZodTypeAny
+}
+
+const registry = new Map<string, TaskFormRendererEntry>()
+
+/**
+ * Register a renderer for one `formKey`.
+ *
+ * Duplicate registration throws, mirroring `registerActivityType`: two modules
+ * silently fighting over one key is a bug that must surface at load time, not a
+ * race whose winner depends on import order.
+ */
+export function registerTaskFormRenderer<TValues>(entry: TaskFormRendererEntry<TValues>): void {
+  if (!entry.formKey) {
+    throw new Error('[internal] Task form renderer requires a formKey')
+  }
+  if (registry.has(entry.formKey)) {
+    throw new Error(`[internal] Task form renderer already registered: ${entry.formKey}`)
+  }
+  registry.set(entry.formKey, entry as TaskFormRendererEntry)
+}
+
+/** Resolve a renderer, or `null` when the key is unknown. Never throws. */
+export function getTaskFormRenderer(
+  formKey: string | null | undefined
+): TaskFormRendererEntry | null {
+  if (!formKey) return null
+  return registry.get(formKey) ?? null
+}
+
+export function listTaskFormRenderers(): TaskFormRendererEntry[] {
+  return Array.from(registry.values())
+}
+
+/** Test seam; not part of the module's runtime contract. */
+export function clearTaskFormRenderers(): void {
+  registry.clear()
+}
+
+export type TaskFormResolution =
+  | { kind: 'registered'; entry: TaskFormRendererEntry }
+  | { kind: 'builtin' }
+  | { kind: 'missing'; formKey: string }
+
+/**
+ * What a task surface should render.
+ *
+ * `missing` is deliberately distinct from `builtin`: both fall back to the
+ * built-in form, but only `missing` means the author asked for a renderer that
+ * is not loaded — which the surface MUST say out loud instead of quietly
+ * rendering something else.
+ */
+export function resolveTaskForm(formKey: string | null | undefined): TaskFormResolution {
+  if (!formKey) return { kind: 'builtin' }
+  const entry = getTaskFormRenderer(formKey)
+  return entry ? { kind: 'registered', entry } : { kind: 'missing', formKey }
+}

package/src/modules/workflows/lib/task-form-schema.ts

@@ -0,0 +1,129 @@
+/**
+ * Workflows Module - Task form schema normalization (pure)
+ *
+ * `userTaskConfigSchema.formSchema` has always accepted TWO shapes:
+ *
+ *   - `{ properties, required }` — JSON Schema;
+ *   - `{ fields: [{ name, type, label, required, options }] }` — the authoring
+ *     shape the Studio's form-field editor writes (`lib/nodeFormTransforms.ts`).
+ *
+ * Only the first was ever read. The task page renders `formSchema.properties`,
+ * and `validateFormData` checked `formSchema.required` — so a task authored in
+ * the visual editor rendered NO fields and validated NOTHING, however many its
+ * author marked mandatory.
+ *
+ * This module is the one place the two shapes are reconciled: every reader goes
+ * through `normalizeTaskFormSchema` and every required-field check through
+ * `readRequiredFormFields`, so they cannot drift apart again. The mapping is the
+ * exact inverse of `mapJsonSchemaTypeToFieldType`, which is what makes the
+ * editor round trip.
+ *
+ * PURE: no ORM, DI, React or registry imports — the browser renderer and the
+ * server-side completion path both load it.
+ */
+
+import type { JsonSchema, JsonSchemaField } from '../data/types'
+
+interface AuthoredFormField {
+  name: string
+  type?: string
+  label?: string
+  required?: boolean
+  options?: unknown[]
+  placeholder?: string
+  defaultValue?: unknown
+}
+
+function readAuthoredFields(formSchema: unknown): AuthoredFormField[] | null {
+  if (!formSchema || typeof formSchema !== 'object') return null
+  const fields = (formSchema as { fields?: unknown }).fields
+  if (!Array.isArray(fields)) return null
+  return fields.filter(
+    (field): field is AuthoredFormField =>
+      !!field && typeof field === 'object' && typeof (field as { name?: unknown }).name === 'string'
+  )
+}
+
+function readJsonSchema(formSchema: unknown): JsonSchema | null {
+  if (!formSchema || typeof formSchema !== 'object') return null
+  const schema = formSchema as { properties?: unknown; required?: unknown }
+  if (!schema.properties || typeof schema.properties !== 'object') return null
+  return formSchema as JsonSchema
+}
+
+/** Inverse of the editor's `mapJsonSchemaTypeToFieldType`. */
+function authoredTypeToJsonSchemaField(field: AuthoredFormField): JsonSchemaField {
+  const options = Array.isArray(field.options)
+    ? field.options.filter((option): option is string => typeof option === 'string')
+    : null
+
+  const base: JsonSchemaField = {
+    title: field.label ?? field.name,
+    ...(field.placeholder ? { description: field.placeholder } : {}),
+  }
+
+  if (options?.length) return { ...base, type: 'string', enum: options }
+
+  switch (field.type) {
+    case 'number':
+      return { ...base, type: 'number' }
+    case 'integer':
+      return { ...base, type: 'integer' }
+    case 'checkbox':
+    case 'boolean':
+      return { ...base, type: 'boolean' }
+    case 'email':
+      return { ...base, type: 'string', format: 'email' }
+    case 'url':
+      return { ...base, type: 'string', format: 'uri' }
+    case 'date':
+      return { ...base, type: 'string', format: 'date' }
+    case 'time':
+      return { ...base, type: 'string', format: 'time' }
+    case 'datetime-local':
+      return { ...base, type: 'string', format: 'date-time' }
+    case 'textarea':
+      return { ...base, type: 'string', maxLength: 2000 }
+    default:
+      return { ...base, type: 'string' }
+  }
+}
+
+/**
+ * Present either authored shape as the JSON-Schema shape the renderer walks.
+ * Returns `null` when the schema declares no fields at all, which is what the
+ * "this task has no form" branch keys off.
+ */
+export function normalizeTaskFormSchema(formSchema: unknown): JsonSchema | null {
+  const authored = readAuthoredFields(formSchema)
+  if (authored) {
+    if (!authored.length) return null
+    const properties: Record<string, JsonSchemaField> = {}
+    const required: string[] = []
+    for (const field of authored) {
+      properties[field.name] = authoredTypeToJsonSchemaField(field)
+      if (field.required === true) required.push(field.name)
+    }
+    return { type: 'object', properties, ...(required.length ? { required } : {}) }
+  }
+
+  const jsonSchema = readJsonSchema(formSchema)
+  if (!jsonSchema) return null
+  return Object.keys(jsonSchema.properties ?? {}).length ? jsonSchema : null
+}
+
+/**
+ * Names of the fields a form schema declares as required, in EITHER shape.
+ * The authoring shape carries a per-field `required: true`; JSON Schema carries
+ * a `required` array.
+ */
+export function readRequiredFormFields(formSchema: unknown): string[] {
+  const normalized = normalizeTaskFormSchema(formSchema)
+  return normalized?.required ?? []
+}
+
+/** How many fields the schema declares, in either shape. */
+export function countTaskFormFields(formSchema: unknown): number {
+  const normalized = normalizeTaskFormSchema(formSchema)
+  return normalized ? Object.keys(normalized.properties ?? {}).length : 0
+}