@objectstack/plugin-approvals 7.3.0 → 7.4.0

package/src/approvals-plugin.ts

@@ -1,30 +1,31 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Plugin, PluginContext } from '@objectstack/core';
-import {
-  SysApprovalProcess,
-  SysApprovalRequest,
-  SysApprovalAction,
-} from '@objectstack/platform-objects/audit';
+import { SysApprovalRequest } from './sys-approval-request.object.js';
+import { SysApprovalAction } from './sys-approval-action.object.js';
 import { ApprovalService, type ApprovalEngine } from './approval-service.js';
-import { bindProcessHooks, unbindAllHooks } from './lifecycle-hooks.js';
+import { bindApprovalLockHook, unbindAllHooks } from './lifecycle-hooks.js';
+import { registerApprovalNode, type ApprovalAutomationSurface } from './approval-node.js';
 
 export interface ApprovalsPluginOptions {
   /** Disable runtime registration (schemas still register). */
   disableService?: boolean;
   /**
-   * Disable Phase B auto-trigger / lock hooks. Schema definition stays
-   * intact; only the engine-level wiring is suppressed. Useful when a
-   * caller wants the manual API only (e.g. tests).
+   * Disable the record-lock hook. Schema + service stay intact; only the
+   * engine-level lock wiring is suppressed. Useful when a caller wants the
+   * manual API only (e.g. tests).
    */
   disableAutoHooks?: boolean;
 }
 
 /**
- * ApprovalsServicePlugin — registers sys_approval_{process,request,action},
- * the `approvals` service, and Phase B lifecycle hooks (auto-trigger,
- * record lock, status mirror). SLA escalation dispatcher is a later
- * milestone.
+ * ApprovalsServicePlugin — registers sys_approval_{request,action}, the
+ * `approvals` service, the `approval` flow node executor (ADR-0019), and the
+ * record-lock hook.
+ *
+ * ADR-0019: approval is no longer a standalone process engine. A flow's
+ * Approval node opens a request and suspends the run; a decision via the
+ * service resumes it down the matching branch.
  */
 export class ApprovalsServicePlugin implements Plugin {
   name = 'com.objectstack.service.approvals';
@@ -35,7 +36,6 @@ export class ApprovalsServicePlugin implements Plugin {
   private readonly options: ApprovalsPluginOptions;
   private service?: ApprovalService;
   private engine?: any;
-  private logger?: any;
 
   constructor(options: ApprovalsPluginOptions = {}) {
     this.options = options;
@@ -50,8 +50,37 @@ export class ApprovalsServicePlugin implements Plugin {
       scope: 'system',
       defaultDatasource: 'cloud',
       namespace: 'sys',
-      objects: [SysApprovalProcess, SysApprovalRequest, SysApprovalAction],
+      objects: [SysApprovalRequest, SysApprovalAction],
+      // ADR-0029 D7 — contribute the Approvals entries into the Setup app's
+      // `group_approvals` slot. This plugin owns these objects (K2.b), so it
+      // ships their menu too; when the plugin isn't installed the slot is empty.
+      navigationContributions: [
+        {
+          app: 'setup',
+          group: 'group_approvals',
+          priority: 100,
+          items: [
+            { id: 'nav_approval_requests', type: 'object', label: 'Requests', objectName: 'sys_approval_request', icon: 'inbox', requiresObject: 'sys_approval_request' },
+            { id: 'nav_approval_actions', type: 'object', label: 'Action History', objectName: 'sys_approval_action', icon: 'history', requiresObject: 'sys_approval_action' },
+          ],
+        },
+      ],
     });
+    // ADR-0029 D8 — contribute this plugin's object translations to the i18n
+    // service on kernel:ready (the i18n plugin may register after this one).
+    if (typeof (ctx as any).hook === 'function') {
+      (ctx as any).hook('kernel:ready', async () => {
+        try {
+          const i18n = ctx.getService<any>('i18n');
+          if (i18n && typeof i18n.loadTranslations === 'function') {
+            const { ApprovalsTranslations } = await import('./translations/index.js');
+            for (const [locale, data] of Object.entries(ApprovalsTranslations)) {
+              i18n.loadTranslations(locale, data as Record<string, unknown>);
+            }
+          }
+        } catch { /* i18n optional */ }
+      });
+    }
     ctx.logger.info('ApprovalsServicePlugin: schemas registered');
   }
 
@@ -65,57 +94,37 @@ export class ApprovalsServicePlugin implements Plugin {
       return;
     }
     this.engine = engine;
-    this.logger = ctx.logger;
-
-    // ADR-0009: try to wire the metadata repository for execution pinning.
-    // The approvals service degrades to the projection-table path if no
-    // metadata service is registered (e.g. in tests or minimal setups).
-    let metadataRepo: any;
-    try {
-      const meta = ctx.getService<any>('metadata');
-      metadataRepo = meta?.getRepository?.();
-    } catch { /* metadata plugin not loaded — fall back */ }
 
     this.service = new ApprovalService({
       engine: engine as ApprovalEngine,
       logger: ctx.logger,
-      metadataRepo,
     });
 
-    if (metadataRepo) {
-      ctx.logger.info('ApprovalsServicePlugin: execution pinning enabled (ADR-0009)');
-    }
-
+    // Record lock: block edits to a record while it has a pending request.
     if (!this.options.disableAutoHooks) {
-      // Re-bind hooks on every registry mutation.
-      this.service.setRegistryChangeHandler(() => this.rebindHooks());
-      // Initial bind happens once the kernel is ready so the AppPlugin's
-      // declarative process seeder has already populated sys_approval_process.
-      const hookOn = (ctx as any).hook ?? (ctx as any).on;
-      if (typeof hookOn === 'function') {
-        try {
-          hookOn.call(ctx, 'kernel:ready', async () => { await this.rebindHooks(); });
-        } catch {
-          // Fall through to immediate bind (no kernel:ready event).
-          await this.rebindHooks();
-        }
-      } else {
-        await this.rebindHooks();
+      try {
+        unbindAllHooks(engine);
+        bindApprovalLockHook(engine, ctx.logger);
+      } catch (err: any) {
+        ctx.logger.warn?.('[approvals] failed to bind record-lock hook', { error: err?.message });
       }
     }
 
     ctx.registerService('approvals', this.service);
     ctx.logger.info('ApprovalsServicePlugin: service registered');
-  }
 
-  private async rebindHooks(): Promise<void> {
-    if (!this.engine || !this.service) return;
+    // ADR-0019: contribute the `approval` node to the flow engine when one is
+    // present. The node lets a flow suspend on an approval and resume on
+    // decision; the service is wired to the same engine so `decide()` can
+    // resume the suspended run.
     try {
-      unbindAllHooks(this.engine);
-      const processes = await this.service.listProcesses({ activeOnly: true }, { isSystem: true, roles: [], permissions: [] } as any);
-      bindProcessHooks(this.engine, this.service, processes, this.logger);
-    } catch (err: any) {
-      this.logger?.warn?.('[approvals] rebindHooks failed', { error: err?.message });
+      const automation = ctx.getService<ApprovalAutomationSurface>('automation');
+      if (automation && typeof automation.registerNodeExecutor === 'function') {
+        this.service.attachAutomation(automation);
+        registerApprovalNode(automation, this.service, ctx.logger);
+      }
+    } catch {
+      ctx.logger.info('ApprovalsServicePlugin: no automation engine — approval node not registered');
     }
   }
 
@@ -125,4 +134,3 @@ export class ApprovalsServicePlugin implements Plugin {
     }
   }
 }
-

package/src/index.ts

@@ -3,34 +3,35 @@
 /**
  * @objectstack/plugin-approvals
  *
- * Multi-step approval engine for ObjectStack.
- * Persists sys_approval_process / sys_approval_request / sys_approval_action
- * and drives the cycle: submit → review → approve/reject → effects.
+ * Approval-as-flow-node runtime (ADR-0019). Persists sys_approval_request /
+ * sys_approval_action, resolves approvers, enforces the record lock, and
+ * records decisions that resume the owning flow run. Approval orchestration
+ * (when to pause, which branch to take) lives on the one automation engine via
+ * the `approval` node.
  */
 
-export {
-  SysApprovalProcess,
-  SysApprovalRequest,
-  SysApprovalAction,
-} from '@objectstack/platform-objects/audit';
+export { SysApprovalRequest } from './sys-approval-request.object.js';
+export { SysApprovalAction } from './sys-approval-action.object.js';
 export {
   ApprovalService,
   type ApprovalEngine,
   type ApprovalClock,
   type ApprovalServiceOptions,
+  type ApprovalResumeSurface,
 } from './approval-service.js';
 export {
   ApprovalsServicePlugin,
   type ApprovalsPluginOptions,
 } from './approvals-plugin.js';
+export {
+  registerApprovalNode,
+  type ApprovalAutomationSurface,
+} from './approval-node.js';
 export type {
   IApprovalService,
-  ApprovalProcessRow,
   ApprovalRequestRow,
   ApprovalActionRow,
   ApprovalDecisionInput,
   ApprovalDecisionResult,
   ApprovalStatus,
-  DefineApprovalProcessInput,
-  SubmitApprovalInput,
 } from '@objectstack/spec/contracts';

package/src/lifecycle-hooks.ts

@@ -1,32 +1,29 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Lifecycle Hooks — Phase B auto-takeover.
+ * Lifecycle Hooks — node-era record lock (ADR-0019).
  *
- * For each active ApprovalProcess we bind three hooks on its target object:
+ * Approval is now a flow node, so there is no per-object process registry to
+ * bind auto-trigger hooks against — a flow decides *when* to open an approval.
+ * What remains worth enforcing at the data layer is the **record lock**: while
+ * a record has a pending `sys_approval_request`, block edits to it.
  *
- *   1. `afterInsert` — evaluate `entryCriteria` against the new record;
- *      if truthy and no pending request exists, auto-submit one.
- *   2. `afterUpdate` — same as above but for updates that newly satisfy
- *      criteria (e.g. amount edited above threshold).
- *   3. `beforeUpdate` — when `lockRecord=true`, block edits to a record
- *      that has a pending request, EXCEPT when the only fields being
- *      changed are the configured `approvalStatusField` (so the engine's
- *      own status mirror is not blocked).
+ * A single global `beforeUpdate` hook handles every object (the target object
+ * of an approval node is only known at flow-run time). For each update it:
  *
- * All hooks are registered with `packageId: 'plugin-approvals:auto'` so
- * that re-bind on `defineProcess`/`deleteProcess` can call
- * `engine.unregisterHooksByPackage(...)` first.
+ *   1. Skips engine self-writes (status mirror) and `sys_approval_*` bookkeeping.
+ *   2. Looks up a pending request for `(object, recordId)`.
+ *   3. Reads the lock policy from that request's `node_config_json` snapshot:
+ *      - `lockRecord === false` → allow.
+ *      - otherwise block, EXCEPT when the only changed field is the configured
+ *        `approvalStatusField` (so the status mirror is never blocked) or the
+ *        caller is an `admin`.
+ *
+ * Registered under `packageId: 'plugin-approvals:lock'` so it can be cleanly
+ * unbound on plugin stop.
  */
 
-import { ExpressionEngine } from '@objectstack/formula';
-import type { Expression } from '@objectstack/spec';
-import type { ApprovalProcessRow } from '@objectstack/spec/contracts';
-import type { ApprovalService } from './approval-service.js';
-
-export const APPROVALS_HOOK_PACKAGE = 'plugin-approvals:auto';
-
-const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+export const APPROVALS_HOOK_PACKAGE = 'plugin-approvals:lock';
 
 interface MinimalEngine {
   registerHook(event: string, handler: (ctx: any) => any | Promise<any>, options?: {
@@ -45,206 +42,74 @@ interface MinimalLogger {
   error?: (msg: any, ...rest: any[]) => void;
 }
 
-/**
- * Evaluate an entry criteria expression against a record. Returns `true`
- * when no criteria is set (matches everything). Returns `false` on
- * evaluation failure (fail-closed — better to skip than auto-submit on a
- * broken expression).
- */
-function evaluateCriteria(criteria: unknown, record: Record<string, unknown>, logger?: MinimalLogger): boolean {
-  if (criteria == null || criteria === '' ) return true;
-  let expr: Expression;
-  if (typeof criteria === 'string') {
-    expr = { dialect: 'cel', source: criteria };
-  } else if (typeof criteria === 'object' && (criteria as any).dialect) {
-    expr = criteria as Expression;
-  } else {
-    return true;
+function parseJson<T = any>(raw: unknown, fallback: T): T {
+  if (raw == null || raw === '') return fallback;
+  if (typeof raw === 'string') {
+    try { return JSON.parse(raw) as T; } catch { return fallback; }
   }
-  if (!expr.source || !expr.source.trim()) return true;
-  const r = ExpressionEngine.evaluate<boolean>(expr, { record });
-  if (!r.ok) {
-    logger?.warn?.('[approvals] entryCriteria evaluation failed; skipping auto-submit', {
-      source: expr.source,
-      error: r.error.message,
-    });
-    return false;
-  }
-  return Boolean(r.value);
+  return raw as T;
 }
 
-/** Does this record already have a pending approval request? */
-async function hasPendingRequest(
+/** The pending request gating a record, plus its snapshotted node config. */
+async function pendingRequestFor(
   engine: MinimalEngine,
   objectName: string,
   recordId: string,
-): Promise<boolean> {
+): Promise<any | null> {
   try {
     const rows = await engine.find('sys_approval_request', {
       where: { object_name: objectName, record_id: String(recordId), status: 'pending' },
       limit: 1,
     } as any);
-    return Array.isArray(rows) && rows.length > 0;
+    return Array.isArray(rows) && rows[0] ? rows[0] : null;
   } catch {
-    return false;
+    return null;
   }
 }
 
 /**
- * Bind auto-trigger + lock hooks for the supplied active processes.
- * Caller is responsible for calling `unbindAll` first if re-binding.
+ * Bind the global record-lock hook. Caller is responsible for calling
+ * {@link unbindAllHooks} first if re-binding.
  */
-export function bindProcessHooks(
-  engine: MinimalEngine,
-  service: ApprovalService,
-  processes: ApprovalProcessRow[],
-  logger?: MinimalLogger,
-): void {
-  // Group processes by object so we can register one hook per object
-  // and fan out internally — keeps the engine's hook map compact.
-  const byObject = new Map<string, ApprovalProcessRow[]>();
-  for (const p of processes) {
-    if (!(p as any).active && !(p as any).is_active) continue;
-    if (!p.object_name) continue;
-    const list = byObject.get(p.object_name) ?? [];
-    list.push(p);
-    byObject.set(p.object_name, list);
-  }
-
-  for (const [objectName, procs] of byObject.entries()) {
-    // ---- auto-trigger (afterInsert) ----
-    engine.registerHook('afterInsert', async (ctx: any) => {
-      try {
-        const record = (ctx?.result ?? ctx?.input?.data ?? {}) as Record<string, unknown>;
-        const id = String((record as any)?.id ?? '');
-        if (!id) return;
-        for (const proc of procs) {
-          await tryAutoSubmit(engine, service, proc, objectName, id, record, ctx, logger);
-        }
-      } catch (err: any) {
-        logger?.warn?.('[approvals] afterInsert auto-trigger failed', { error: err?.message });
-      }
-    }, { object: objectName, packageId: APPROVALS_HOOK_PACKAGE, priority: 200 });
-
-    // ---- auto-trigger (afterUpdate) ----
-    engine.registerHook('afterUpdate', async (ctx: any) => {
-      // Ignore engine self-writes (status mirror, field_update from
-      // post-actions, etc) — otherwise post-finalize updates would loop
-      // a fresh approval on every state change.
-      if ((ctx?.session as any)?.isSystem) return;
-      try {
-        const result = (ctx?.result ?? {}) as Record<string, unknown>;
-        const id = String((ctx?.input?.id ?? (result as any)?.id ?? '') as string);
-        if (!id) return;
-        // result may be { affected: 1 } for some drivers; merge previous+input.data as the
-        // best-effort record snapshot for criteria evaluation.
-        const record: Record<string, unknown> = {
-          ...(ctx?.previous ?? {}),
-          ...((result as any)?.id ? result : {}),
-          ...((ctx?.input?.data ?? {}) as Record<string, unknown>),
-          id,
-        };
-        for (const proc of procs) {
-          await tryAutoSubmit(engine, service, proc, objectName, id, record, ctx, logger);
-        }
-      } catch (err: any) {
-        logger?.warn?.('[approvals] afterUpdate auto-trigger failed', { error: err?.message });
-      }
-    }, { object: objectName, packageId: APPROVALS_HOOK_PACKAGE, priority: 200 });
-
-    // ---- record lock (beforeUpdate) ----
-    const lockProcs = procs.filter((p) => (p.definition as any)?.lockRecord !== false);
-    if (lockProcs.length === 0) continue;
-    engine.registerHook('beforeUpdate', async (ctx: any) => {
-      const id = String((ctx?.input?.id ?? '') as string);
-      if (!id) return;
-      const data = (ctx?.input?.data ?? {}) as Record<string, unknown>;
-      const changedFields = Object.keys(data).filter((k) => k !== 'id' && k !== 'updated_at');
-      if (changedFields.length === 0) return;
-
-      // Allow engine self-writes (status mirror, field_update from actions, etc).
-      if ((ctx?.session as any)?.isSystem) return;
-
-      // Allow when every changed field is an approval status mirror.
-      const mirrorFields = new Set<string>();
-      for (const p of lockProcs) {
-        const f = (p.definition as any)?.approvalStatusField;
-        if (typeof f === 'string' && f) mirrorFields.add(f);
-      }
-      const onlyMirror = changedFields.every((f) => mirrorFields.has(f));
-      if (onlyMirror) return;
-
-      // Allow admin override: roles include 'admin'.
-      const roles = (ctx?.session?.roles ?? []) as string[];
-      if (Array.isArray(roles) && roles.includes('admin')) return;
-
-      const pending = await hasPendingRequest(engine, objectName, id);
-      if (!pending) return;
-
-      const err: any = new Error('RECORD_LOCKED: record is locked while an approval is in progress');
-      err.code = 'RECORD_LOCKED';
-      err.statusCode = 409;
-      throw err;
-    }, { object: objectName, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
-  }
-
-  logger?.info?.('[approvals] lifecycle hooks bound', {
-    objects: Array.from(byObject.keys()),
-    processCount: processes.length,
-  });
+export function bindApprovalLockHook(engine: MinimalEngine, logger?: MinimalLogger): void {
+  engine.registerHook('beforeUpdate', async (ctx: any) => {
+    const id = String((ctx?.input?.id ?? '') as string);
+    if (!id) return;
+    const object = (ctx?.object ?? ctx?.objectName) as string | undefined;
+    // No object name (shouldn't happen) or our own bookkeeping objects → skip.
+    if (!object || String(object).startsWith('sys_approval')) return;
+
+    const data = (ctx?.input?.data ?? {}) as Record<string, unknown>;
+    const changedFields = Object.keys(data).filter((k) => k !== 'id' && k !== 'updated_at');
+    if (changedFields.length === 0) return;
+
+    // Allow engine self-writes (status mirror from the approvals service, etc).
+    if ((ctx?.session as any)?.isSystem) return;
+
+    // Allow admin override.
+    const roles = (ctx?.session?.roles ?? []) as string[];
+    if (Array.isArray(roles) && roles.includes('admin')) return;
+
+    const pending = await pendingRequestFor(engine, object, id);
+    if (!pending) return;
+
+    const config = parseJson<any>(pending.node_config_json, {});
+    if (config?.lockRecord === false) return;
+
+    // Allow when every changed field is the approval status mirror.
+    const mirror = config?.approvalStatusField;
+    if (typeof mirror === 'string' && mirror && changedFields.every((f) => f === mirror)) return;
+
+    const err: any = new Error('RECORD_LOCKED: record is locked while an approval is in progress');
+    err.code = 'RECORD_LOCKED';
+    err.statusCode = 409;
+    throw err;
+  }, { packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
+
+  logger?.info?.('[approvals] record-lock hook bound');
 }
 
-/** Unregister every hook the auto-trigger module ever registered. */
+/** Unregister every hook the lock module registered. */
 export function unbindAllHooks(engine: MinimalEngine): number {
   return engine.unregisterHooksByPackage(APPROVALS_HOOK_PACKAGE);
 }
-
-async function tryAutoSubmit(
-  engine: MinimalEngine,
-  service: ApprovalService,
-  process: ApprovalProcessRow,
-  objectName: string,
-  recordId: string,
-  record: Record<string, unknown>,
-  ctx: any,
-  logger?: MinimalLogger,
-): Promise<void> {
-  try {
-    const criteria = (process.definition as any)?.entryCriteria;
-    const passes = evaluateCriteria(criteria, record, logger);
-    if (!passes) return;
-    if (await hasPendingRequest(engine, objectName, recordId)) return;
-    // Guard: if the record's mirror status field is already a terminal
-    // state (approved / rejected / recalled), do NOT auto-submit again —
-    // otherwise every post-finalize edit would loop a fresh approval.
-    const statusField = (process.definition as any)?.approvalStatusField;
-    if (statusField) {
-      const current = (record as any)?.[statusField];
-      if (current === 'approved' || current === 'rejected' || current === 'recalled') return;
-    }
-
-    const submitterId = (ctx?.session?.userId ?? null) as string | null;
-    const submitterOrg = (ctx?.session?.tenantId ?? ctx?.session?.organizationId ?? null) as string | null;
-    await service.submit({
-      object: objectName,
-      recordId,
-      processName: process.name,
-      payload: record,
-      submitterId,
-    }, { ...SYSTEM_CTX, userId: submitterId ?? undefined, organizationId: submitterOrg ?? undefined, tenantId: submitterOrg ?? undefined } as any);
-
-    logger?.info?.('[approvals] auto-submitted approval', {
-      process: process.name,
-      object: objectName,
-      record: recordId,
-    });
-  } catch (err: any) {
-    if (err?.code === 'DUPLICATE_REQUEST') return;
-    logger?.warn?.('[approvals] auto-submit failed', {
-      process: process.name,
-      object: objectName,
-      record: recordId,
-      error: err?.message ?? String(err),
-    });
-  }
-}

package/src/nav-contribution.test.ts

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { ApprovalsServicePlugin } from './approvals-plugin.js';
+
+/**
+ * ADR-0029 K2.b / D7 — the approvals plugin owns sys_approval_request /
+ * sys_approval_action and ships their Setup-app menu as a navigation
+ * contribution (rather than the entries living statically in the
+ * platform-objects Setup shell).
+ */
+describe('ApprovalsServicePlugin schema + nav contribution (ADR-0029 K2.b)', () => {
+  it('registers the approval objects and contributes the group_approvals slot', async () => {
+    const registered: any[] = [];
+    const ctx: any = {
+      getService: (name: string) =>
+        name === 'manifest' ? { register: (m: any) => registered.push(m) } : undefined,
+      logger: { info: () => {}, warn: () => {} },
+    };
+
+    const plugin = new ApprovalsServicePlugin({ disableService: true });
+    await plugin.init(ctx);
+
+    expect(registered).toHaveLength(1);
+    const manifest = registered[0];
+
+    // Owns both approval objects (moved out of platform-objects).
+    expect(manifest.objects.map((o: any) => o.name).sort()).toEqual([
+      'sys_approval_action',
+      'sys_approval_request',
+    ]);
+
+    // Contributes its menu into the Setup app's approvals slot.
+    expect(manifest.navigationContributions).toHaveLength(1);
+    const contribution = manifest.navigationContributions[0];
+    expect(contribution).toMatchObject({ app: 'setup', group: 'group_approvals' });
+    expect(contribution.items.map((i: any) => i.objectName).sort()).toEqual([
+      'sys_approval_action',
+      'sys_approval_request',
+    ]);
+    // Each entry is gated so the slot stays empty when the plugin is absent.
+    for (const item of contribution.items) {
+      expect(item.requiresObject).toBe(item.objectName);
+    }
+  });
+});