Merge pull request #783 from objectstack-ai/copilot/implement-studio-ui-nodes

Author: hotlong

ROADMAP.md

@@ -1,6 +1,6 @@
 # ObjectStack Protocol — Road Map
 
-> **Last Updated:** 2026-02-21  
+> **Last Updated:** 2026-02-22  
 > **Current Version:** v3.0.6  
 > **Status:** Protocol Specification Complete · Runtime Implementation In Progress
 
@@ -30,8 +30,8 @@
 
 ## Current State Summary
 
-ObjectStack v3.0 has achieved **comprehensive protocol specification** with 175 Zod schemas,
-27 service contracts, and 7,111 `.describe()` annotations providing machine-readable documentation.
+ObjectStack v3.0 has achieved **comprehensive protocol specification** with 193 Zod schemas,
+27 service contracts, and 8,425 `.describe()` annotations providing machine-readable documentation.
 The core kernel, data engine, metadata system, and developer tooling are production-ready.
 The primary focus now shifts to implementing the remaining 19 service contracts and hardening
 the ecosystem for enterprise workloads.
@@ -93,13 +93,13 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 | Packages (total) | 27 |
 | Apps | 2 (Studio, Docs) |
 | Examples | 4 (Todo, CRM, Host, BI Plugin) |
-| Zod Schema Files | 178 |
+| Zod Schema Files | 193 |
 | Exported Schemas | 1,100+ |
-| `.describe()` Annotations | 7,111+ |
+| `.describe()` Annotations | 8,425+ |
 | Service Contracts | 27 |
 | Contracts Implemented | 13 (52%) |
-| Test Files | 210 |
-| Tests Passing | 5,953 / 5,953 |
+| Test Files | 218 |
+| Tests Passing | 6,202 / 6,202 |
 | `@deprecated` Items | 3 |
 | Protocol Domains | 15 (Data, UI, AI, API, Automation, Cloud, Contracts, Identity, Integration, Kernel, QA, Security, Shared, Studio, System) |
 
@@ -109,7 +109,7 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 
 > **Goal:** Prioritize APIs and client capabilities needed by [ObjectUI](https://github.com/objectstack-ai/objectui/blob/main/ROADMAP.md) frontend development.  
 > **Target:** v3.1 protocol to fill core platform gaps.  
-> **Updated:** 2026-02-21  
+> **Updated:** 2026-02-22  
 > **Owner:** @hotlong
 
 ### 1. Comments & Collaboration API for ObjectUI
@@ -171,6 +171,12 @@ Multi-stage triggers, action pipelines, execution logs, and cron scheduling stan
 | BPMN boundary events (error/timer/signal) | ✅ | `automation/flow.zod.ts` → `boundary_event` node type + `boundaryConfig` (interrupting/non-interrupting) |
 | BPMN wait event configuration | ✅ | `automation/flow.zod.ts` → `waitEventConfig` (timer/signal/webhook/manual/condition event types) |
 | BPMN checkpoint reasons (parallel join, boundary) | ✅ | `automation/execution.zod.ts` → `parallel_join`, `boundary_event` in `CheckpointSchema.reason` |
+| Wait node executor plugin protocol | ✅ | `automation/node-executor.zod.ts` → `WaitExecutorConfigSchema`, `WaitResumePayloadSchema`, `NodeExecutorDescriptorSchema` (19 tests) |
+| BPMN XML interop protocol (import/export) | ✅ | `automation/bpmn-interop.zod.ts` → `BpmnImportOptionsSchema`, `BpmnExportOptionsSchema`, `BpmnInteropResultSchema`, `BUILT_IN_BPMN_MAPPINGS` (20 tests) |
+| Studio Flow Builder protocol (canvas nodes/edges) | ✅ | `studio/flow-builder.zod.ts` → `FlowBuilderConfigSchema`, `FlowCanvasNodeSchema`, `FlowCanvasEdgeSchema`, `BUILT_IN_NODE_DESCRIPTORS` (23 tests) |
+| Wait node runtime pause/resume executor | 🔴 | Runtime: `NodeExecutor` plugin for `wait` nodes (spec ready, runtime not yet implemented) |
+| Studio Flow Builder canvas UI | 🔴 | Runtime: visual canvas with parallel/join/boundary node controls (spec ready, UI not yet implemented) |
+| BPMN XML import/export plugin | 🔴 | Runtime: plugin-based BPMN 2.0 XML importer/exporter (spec ready, low priority) |
 
 ### 3. File Direct Upload & Resumable Upload Protocol
 
@@ -305,7 +311,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 ## Phase 1: Protocol Specification (✅ Complete)
 
 > **Goal:** Define every schema, type, and contract as a Zod-first source of truth.  
-> **Result:** 175 Zod schemas, 27 service contracts, 7,111+ `.describe()` annotations across 15 protocol domains.
+> **Result:** 193 Zod schemas, 27 service contracts, 8,425+ `.describe()` annotations across 15 protocol domains.
 
 <details>
 <summary>Deliverables — All Completed (click to expand)</summary>
@@ -314,7 +320,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - [x] **Driver Specifications** — Memory, PostgreSQL, MongoDB driver schemas + SQL/NoSQL abstractions
 - [x] **UI Protocol** — View (List/Form/Kanban/Calendar/Gantt), App, Dashboard, Report, Action, Page (16 types), Chart, Widget, Theme, Animation, DnD, Touch, Keyboard, Responsive, Offline, Notification, i18n, Content Elements, Enhanced Activity Timeline (`RecordActivityProps` unified timeline, `RecordChatterProps` sidebar/drawer), Unified Navigation Protocol (`NavigationItem` as single source of truth with 7 types: object/dashboard/page/url/report/action/group; `NavigationArea` for business domain partitioning; `order`/`badge`/`requiredPermissions` on all nav items), Airtable Interface Parity (`UserActionsConfig`, `AppearanceConfig`, `ViewTab`, `AddRecordConfig`, `InterfacePageConfig`, `showRecordCount`, `allowPrinting`)
 - [x] **System Protocol** — Manifest, Auth Config, Cache, Logging, Metrics, Tracing, Audit, Encryption, Masking, Migration, Tenant, Translation, Search Engine, HTTP Server, Worker, Job, Object Storage, Notification, Message Queue, Registry Config, Collaboration, Compliance, Change Management, Disaster Recovery, License, Security Context, Core Services, SystemObjectName/SystemFieldName Constants, StorageNameMapping Utilities
-- [x] **Automation Protocol** — Flow (autolaunched/screen/schedule), Workflow, State Machine, Trigger Registry, Approval, ETL, Sync, Webhook
+- [x] **Automation Protocol** — Flow (autolaunched/screen/schedule), Workflow, State Machine, Trigger Registry, Approval, ETL, Sync, Webhook, BPMN Semantics (parallel/join gateways, boundary events, wait events, default sequence flows), Node Executor Plugin Protocol (wait pause/resume, executor descriptors), BPMN XML Interop (import/export options, element mappings, diagnostics)
 - [x] **AI Protocol** — Agent, Agent Action, Conversation, Cost, MCP, Model Registry, NLQ, Orchestration, Predictive, RAG Pipeline, Runtime Ops, Feedback Loop, DevOps Agent, Plugin Development
 - [x] **API Protocol** — Protocol (104 schemas), Endpoint, Contract, Router, Dispatcher, REST Server, GraphQL, OData, WebSocket, Realtime, Batch, Versioning, HTTP Cache, Documentation, Discovery, Registry, Errors, Auth, Auth Endpoints, Metadata, Analytics, Query Adapter, Storage, Plugin REST API, Feed API (Feed CRUD, Reactions, Subscription), Automation API (CRUD + Toggle + Runs)
 - [x] **Security Protocol** — Permission, Policy, RLS, Sharing, Territory
@@ -323,7 +329,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - [x] **Cloud Protocol** — Marketplace, App Store, Developer Portal, Marketplace Admin
 - [x] **Integration Protocol** — Connector (Database, SaaS, File Storage, GitHub, Message Queue, Vercel)
 - [x] **QA Protocol** — Testing framework schemas
-- [x] **Studio Protocol** — Plugin extension schemas
+- [x] **Studio Protocol** — Plugin extension schemas, Object Designer (field editor, relationship mapper, ER diagram), Page Builder (canvas, palette), Flow Builder (canvas nodes, edges, BPMN node descriptors, layout algorithms)
 - [x] **Contracts** — 27 service interfaces with full method signatures
 - [x] **Stack Definition** — `defineStack()`, `defineView()`, `defineApp()`, `defineFlow()`, `defineAgent()` helpers
 - [x] **Stack Composition** — `composeStacks()` for declarative multi-stack merging with conflict resolution (`error`/`override`/`merge`)
@@ -683,7 +689,8 @@ Final polish and advanced features.
 - [ ] Object Manager — unified object list with search, filter, card/table/tree views, quick preview, statistics
 - [ ] View Builder — drag-and-drop list/form/dashboard designers
 - [ ] Page Builder — drag-and-drop page designer with element palette (see [Gap Analysis](docs/design/airtable-interface-gap-analysis.md))
-- [ ] Flow Builder — visual automation flow editor
+- [x] Flow Builder Protocol — canvas node shapes, edge styles, BPMN node descriptors (parallel_gateway, join_gateway, boundary_event, wait), layout algorithms, palette categories (`studio/flow-builder.zod.ts`)
+- [ ] Flow Builder Runtime — visual automation flow editor with drag-and-drop canvas, node palette, property panel, minimap
 - [ ] Security Console — permission matrix, RLS policy editor
 - [ ] AI Playground — agent testing, NLQ sandbox
 - [ ] Code Editor — Monaco-based TypeScript editing with live preview

packages/spec/src/automation/bpmn-interop.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect } from 'vitest';
+import {
+  BpmnElementMappingSchema,
+  BpmnUnmappedStrategySchema,
+  BpmnImportOptionsSchema,
+  BpmnVersionSchema,
+  BpmnExportOptionsSchema,
+  BpmnDiagnosticSchema,
+  BpmnInteropResultSchema,
+  BUILT_IN_BPMN_MAPPINGS,
+  type BpmnImportOptions,
+  type BpmnExportOptions,
+  type BpmnInteropResult,
+} from './bpmn-interop.zod';
+
+// ---------------------------------------------------------------------------
+// BpmnElementMappingSchema
+// ---------------------------------------------------------------------------
+describe('BpmnElementMappingSchema', () => {
+  it('should accept a valid mapping', () => {
+    const mapping = BpmnElementMappingSchema.parse({
+      bpmnType: 'bpmn:parallelGateway',
+      flowNodeAction: 'parallel_gateway',
+    });
+    expect(mapping.bpmnType).toBe('bpmn:parallelGateway');
+    expect(mapping.bidirectional).toBe(true); // default
+  });
+
+  it('should accept mapping with notes', () => {
+    const mapping = BpmnElementMappingSchema.parse({
+      bpmnType: 'bpmn:serviceTask',
+      flowNodeAction: 'http_request',
+      bidirectional: true,
+      notes: 'Maps HTTP/connector tasks',
+    });
+    expect(mapping.notes).toBe('Maps HTTP/connector tasks');
+  });
+
+  it('should reject without required fields', () => {
+    expect(() => BpmnElementMappingSchema.parse({})).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BpmnUnmappedStrategySchema
+// ---------------------------------------------------------------------------
+describe('BpmnUnmappedStrategySchema', () => {
+  it('should accept all strategies', () => {
+    ['skip', 'warn', 'error', 'comment'].forEach(s => {
+      expect(BpmnUnmappedStrategySchema.parse(s)).toBe(s);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BpmnImportOptionsSchema
+// ---------------------------------------------------------------------------
+describe('BpmnImportOptionsSchema', () => {
+  it('should accept empty options with defaults', () => {
+    const opts: BpmnImportOptions = BpmnImportOptionsSchema.parse({});
+    expect(opts.unmappedStrategy).toBe('warn');
+    expect(opts.importLayout).toBe(true);
+    expect(opts.importDocumentation).toBe(true);
+    expect(opts.validateAfterImport).toBe(true);
+  });
+
+  it('should accept custom import options', () => {
+    const opts = BpmnImportOptionsSchema.parse({
+      unmappedStrategy: 'error',
+      customMappings: [
+        { bpmnType: 'bpmn:businessRuleTask', flowNodeAction: 'script' },
+      ],
+      importLayout: false,
+      importDocumentation: true,
+      flowName: 'imported_approval_flow',
+      validateAfterImport: true,
+    });
+    expect(opts.unmappedStrategy).toBe('error');
+    expect(opts.customMappings).toHaveLength(1);
+    expect(opts.flowName).toBe('imported_approval_flow');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BpmnExportOptionsSchema
+// ---------------------------------------------------------------------------
+describe('BpmnExportOptionsSchema', () => {
+  it('should accept empty options with defaults', () => {
+    const opts: BpmnExportOptions = BpmnExportOptionsSchema.parse({});
+    expect(opts.version).toBe('2.0');
+    expect(opts.includeLayout).toBe(true);
+    expect(opts.includeExtensions).toBe(false);
+    expect(opts.prettyPrint).toBe(true);
+    expect(opts.namespacePrefix).toBe('bpmn');
+  });
+
+  it('should accept custom export options', () => {
+    const opts = BpmnExportOptionsSchema.parse({
+      version: '2.0.2',
+      includeLayout: true,
+      includeExtensions: true,
+      prettyPrint: false,
+      namespacePrefix: 'bpmn2',
+    });
+    expect(opts.version).toBe('2.0.2');
+    expect(opts.includeExtensions).toBe(true);
+    expect(opts.namespacePrefix).toBe('bpmn2');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BpmnVersionSchema
+// ---------------------------------------------------------------------------
+describe('BpmnVersionSchema', () => {
+  it('should accept valid versions', () => {
+    expect(BpmnVersionSchema.parse('2.0')).toBe('2.0');
+    expect(BpmnVersionSchema.parse('2.0.2')).toBe('2.0.2');
+  });
+
+  it('should reject invalid version', () => {
+    expect(() => BpmnVersionSchema.parse('1.0')).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BpmnDiagnosticSchema
+// ---------------------------------------------------------------------------
+describe('BpmnDiagnosticSchema', () => {
+  it('should accept a warning diagnostic', () => {
+    const diag = BpmnDiagnosticSchema.parse({
+      severity: 'warning',
+      message: 'BPMN element bpmn:businessRuleTask has no direct mapping',
+      bpmnElementId: 'Task_12345',
+    });
+    expect(diag.severity).toBe('warning');
+    expect(diag.bpmnElementId).toBe('Task_12345');
+  });
+
+  it('should accept all severities', () => {
+    ['info', 'warning', 'error'].forEach(s => {
+      expect(() => BpmnDiagnosticSchema.parse({
+        severity: s,
+        message: 'test',
+      })).not.toThrow();
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BpmnInteropResultSchema
+// ---------------------------------------------------------------------------
+describe('BpmnInteropResultSchema', () => {
+  it('should accept a successful result', () => {
+    const result: BpmnInteropResult = BpmnInteropResultSchema.parse({
+      success: true,
+      mappedCount: 15,
+      unmappedCount: 0,
+    });
+    expect(result.success).toBe(true);
+    expect(result.diagnostics).toEqual([]); // default
+  });
+
+  it('should accept a result with diagnostics', () => {
+    const result = BpmnInteropResultSchema.parse({
+      success: true,
+      diagnostics: [
+        { severity: 'warning', message: 'Unmapped element: bpmn:textAnnotation' },
+        { severity: 'info', message: 'Imported 12 nodes and 15 edges' },
+      ],
+      mappedCount: 12,
+      unmappedCount: 1,
+    });
+    expect(result.diagnostics).toHaveLength(2);
+    expect(result.unmappedCount).toBe(1);
+  });
+
+  it('should accept a failed result', () => {
+    const result = BpmnInteropResultSchema.parse({
+      success: false,
+      diagnostics: [
+        { severity: 'error', message: 'Invalid BPMN XML: missing process element' },
+      ],
+    });
+    expect(result.success).toBe(false);
+    expect(result.diagnostics[0].severity).toBe('error');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BUILT_IN_BPMN_MAPPINGS
+// ---------------------------------------------------------------------------
+describe('BUILT_IN_BPMN_MAPPINGS', () => {
+  it('should validate all built-in mappings', () => {
+    BUILT_IN_BPMN_MAPPINGS.forEach(m => {
+      expect(() => BpmnElementMappingSchema.parse(m)).not.toThrow();
+    });
+  });
+
+  it('should include BPMN parallel gateway mapping', () => {
+    const parallel = BUILT_IN_BPMN_MAPPINGS.find(m => m.bpmnType === 'bpmn:parallelGateway');
+    expect(parallel).toBeDefined();
+    expect(parallel?.flowNodeAction).toBe('parallel_gateway');
+  });
+
+  it('should include boundary event mapping', () => {
+    const boundary = BUILT_IN_BPMN_MAPPINGS.find(m => m.bpmnType === 'bpmn:boundaryEvent');
+    expect(boundary).toBeDefined();
+    expect(boundary?.flowNodeAction).toBe('boundary_event');
+  });
+
+  it('should include wait/intermediate catch event mapping', () => {
+    const wait = BUILT_IN_BPMN_MAPPINGS.find(m => m.bpmnType === 'bpmn:intermediateCatchEvent');
+    expect(wait).toBeDefined();
+    expect(wait?.flowNodeAction).toBe('wait');
+  });
+
+  it('should map all core BPMN elements', () => {
+    const bpmnTypes = BUILT_IN_BPMN_MAPPINGS.map(m => m.bpmnType);
+    expect(bpmnTypes).toContain('bpmn:startEvent');
+    expect(bpmnTypes).toContain('bpmn:endEvent');
+    expect(bpmnTypes).toContain('bpmn:exclusiveGateway');
+    expect(bpmnTypes).toContain('bpmn:parallelGateway');
+    expect(bpmnTypes).toContain('bpmn:serviceTask');
+    expect(bpmnTypes).toContain('bpmn:scriptTask');
+    expect(bpmnTypes).toContain('bpmn:userTask');
+    expect(bpmnTypes).toContain('bpmn:callActivity');
+    expect(bpmnTypes).toContain('bpmn:boundaryEvent');
+  });
+});