@lssm/example.workflow-system 0.0.0-canary-20251206160926

package/dist/presentations/index.d.ts

@@ -0,0 +1,63 @@
+import { PresentationDescriptorV2 } from "@lssm/lib.contracts";
+
+//#region src/presentations/index.d.ts
+
+/**
+ * Workflow designer canvas for building workflows.
+ */
+declare const WorkflowDesignerPresentation: PresentationDescriptorV2;
+/**
+ * List of workflow definitions.
+ */
+declare const WorkflowListPresentation: PresentationDescriptorV2;
+/**
+ * Workflow definition detail view.
+ */
+declare const WorkflowDetailPresentation: PresentationDescriptorV2;
+/**
+ * List of running workflow instances.
+ */
+declare const InstanceListPresentation: PresentationDescriptorV2;
+/**
+ * Workflow instance detail view with timeline.
+ */
+declare const InstanceDetailPresentation: PresentationDescriptorV2;
+/**
+ * Workflow progress tracker widget.
+ */
+declare const ProgressTrackerPresentation: PresentationDescriptorV2;
+/**
+ * Approval inbox - list of pending approvals.
+ */
+declare const ApprovalInboxPresentation: PresentationDescriptorV2;
+/**
+ * Approval request detail view.
+ */
+declare const ApprovalDetailPresentation: PresentationDescriptorV2;
+/**
+ * Approval decision form.
+ */
+declare const ApprovalFormPresentation: PresentationDescriptorV2;
+/**
+ * Pending approvals count badge.
+ */
+declare const PendingApprovalsBadgePresentation: PresentationDescriptorV2;
+/**
+ * Workflow metrics dashboard widget.
+ */
+declare const WorkflowMetricsPresentation: PresentationDescriptorV2;
+declare const WorkflowSystemPresentations: {
+  WorkflowDesignerPresentation: PresentationDescriptorV2;
+  WorkflowListPresentation: PresentationDescriptorV2;
+  WorkflowDetailPresentation: PresentationDescriptorV2;
+  InstanceListPresentation: PresentationDescriptorV2;
+  InstanceDetailPresentation: PresentationDescriptorV2;
+  ProgressTrackerPresentation: PresentationDescriptorV2;
+  ApprovalInboxPresentation: PresentationDescriptorV2;
+  ApprovalDetailPresentation: PresentationDescriptorV2;
+  ApprovalFormPresentation: PresentationDescriptorV2;
+  PendingApprovalsBadgePresentation: PresentationDescriptorV2;
+  WorkflowMetricsPresentation: PresentationDescriptorV2;
+};
+//#endregion
+export { ApprovalDetailPresentation, ApprovalFormPresentation, ApprovalInboxPresentation, InstanceDetailPresentation, InstanceListPresentation, PendingApprovalsBadgePresentation, ProgressTrackerPresentation, WorkflowDesignerPresentation, WorkflowDetailPresentation, WorkflowListPresentation, WorkflowMetricsPresentation, WorkflowSystemPresentations };

package/dist/presentations/index.js

@@ -0,0 +1 @@
+import{WorkflowDefinitionModel as e}from"../contracts/workflow.js";import{WorkflowInstanceModel as t}from"../contracts/instance.js";import{ApprovalRequestModel as n}from"../contracts/approval.js";const r={meta:{name:`workflow.designer`,version:1,description:`Visual workflow designer with drag-and-drop steps`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`designer`,`admin`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowDesigner`,props:e},targets:[`react`],policy:{flags:[`workflow.designer.enabled`]}},i={meta:{name:`workflow.definition.list`,version:1,description:`List of workflow definitions with status and actions`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`list`,`admin`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowDefinitionList`,props:e},targets:[`react`,`markdown`],policy:{flags:[`workflow.enabled`]}},a={meta:{name:`workflow.definition.detail`,version:1,description:`Detailed view of a workflow definition with steps`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`detail`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowDefinitionDetail`,props:e},targets:[`react`,`markdown`],policy:{flags:[`workflow.enabled`]}},o={meta:{name:`workflow.instance.list`,version:1,description:`List of workflow instances with status and progress`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`instance`,`list`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowInstanceList`,props:t},targets:[`react`,`markdown`],policy:{flags:[`workflow.enabled`]}},s={meta:{name:`workflow.instance.detail`,version:1,description:`Detailed view of a workflow instance with step timeline`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`instance`,`detail`,`timeline`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowInstanceDetail`,props:t},targets:[`react`,`markdown`],policy:{flags:[`workflow.enabled`]}},c={meta:{name:`workflow.instance.progress`,version:1,description:`Visual progress tracker showing current step in workflow`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`progress`,`widget`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowProgressTracker`,props:t},targets:[`react`],policy:{flags:[`workflow.enabled`]}},l={meta:{name:`workflow.approval.inbox`,version:1,description:`Inbox showing pending approval requests for current user`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`approval`,`inbox`]},source:{type:`component`,framework:`react`,componentKey:`ApprovalInbox`,props:n},targets:[`react`,`markdown`],policy:{flags:[`workflow.approvals.enabled`]}},u={meta:{name:`workflow.approval.detail`,version:1,description:`Detailed approval request view with context and actions`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`approval`,`detail`]},source:{type:`component`,framework:`react`,componentKey:`ApprovalRequestDetail`,props:n},targets:[`react`,`markdown`],policy:{flags:[`workflow.approvals.enabled`]}},d={meta:{name:`workflow.approval.form`,version:1,description:`Form for submitting approval decisions`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`approval`,`form`]},source:{type:`component`,framework:`react`,componentKey:`ApprovalDecisionForm`},targets:[`react`],policy:{flags:[`workflow.approvals.enabled`]}},f={meta:{name:`workflow.approval.badge`,version:1,description:`Badge showing count of pending approvals`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`approval`,`badge`,`widget`]},source:{type:`component`,framework:`react`,componentKey:`PendingApprovalsBadge`},targets:[`react`],policy:{flags:[`workflow.approvals.enabled`]}},p={meta:{name:`workflow.metrics`,version:1,description:`Dashboard widget showing workflow metrics and statistics`,domain:`workflow-system`,owners:[`workflow-team`],tags:[`workflow`,`metrics`,`dashboard`]},source:{type:`component`,framework:`react`,componentKey:`WorkflowMetricsDashboard`},targets:[`react`,`markdown`],policy:{flags:[`workflow.metrics.enabled`]}},m={WorkflowDesignerPresentation:r,WorkflowListPresentation:i,WorkflowDetailPresentation:a,InstanceListPresentation:o,InstanceDetailPresentation:s,ProgressTrackerPresentation:c,ApprovalInboxPresentation:l,ApprovalDetailPresentation:u,ApprovalFormPresentation:d,PendingApprovalsBadgePresentation:f,WorkflowMetricsPresentation:p};export{u as ApprovalDetailPresentation,d as ApprovalFormPresentation,l as ApprovalInboxPresentation,s as InstanceDetailPresentation,o as InstanceListPresentation,f as PendingApprovalsBadgePresentation,c as ProgressTrackerPresentation,r as WorkflowDesignerPresentation,a as WorkflowDetailPresentation,i as WorkflowListPresentation,p as WorkflowMetricsPresentation,m as WorkflowSystemPresentations};

package/dist/state-machine/index.d.ts

@@ -0,0 +1,147 @@
+//#region src/state-machine/index.d.ts
+/**
+ * Workflow State Machine Engine
+ *
+ * Provides state machine logic for workflow transitions.
+ * This is a spec-level abstraction that defines the interface
+ * for workflow state transitions.
+ */
+/**
+ * Represents a transition definition in a workflow step.
+ */
+interface TransitionDefinition {
+  /** The action that triggers this transition (e.g., "approve", "reject") */
+  action: string;
+  /** The target step key to transition to */
+  targetStepKey: string;
+  /** Optional condition expression for conditional transitions */
+  condition?: string;
+  /** Optional guard roles - only users with these roles can take this action */
+  allowedRoles?: string[];
+}
+/**
+ * Step definition for state machine.
+ */
+interface StateMachineStep {
+  key: string;
+  name: string;
+  type: 'START' | 'APPROVAL' | 'TASK' | 'CONDITION' | 'PARALLEL' | 'WAIT' | 'ACTION' | 'END';
+  /** Map of action -> transition definition */
+  transitions: Record<string, string | TransitionDefinition>;
+  /** For approval steps: how approvals are handled */
+  approvalMode?: 'ANY' | 'ALL' | 'MAJORITY' | 'SEQUENTIAL';
+  /** Roles that can approve/act on this step */
+  allowedRoles?: string[];
+  /** Timeout in seconds */
+  timeoutSeconds?: number;
+  /** Condition expression for CONDITION type */
+  conditionExpression?: string;
+}
+/**
+ * Workflow state machine definition.
+ */
+interface StateMachineDefinition {
+  key: string;
+  name: string;
+  version: number;
+  initialStepKey: string;
+  steps: Record<string, StateMachineStep>;
+}
+/**
+ * Current state of an instance.
+ */
+interface StateMachineState {
+  currentStepKey: string;
+  status: 'PENDING' | 'RUNNING' | 'WAITING' | 'PAUSED' | 'COMPLETED' | 'CANCELLED' | 'FAILED' | 'TIMEOUT';
+  contextData: Record<string, unknown>;
+  history: {
+    stepKey: string;
+    action: string;
+    timestamp: Date;
+    executedBy: string;
+  }[];
+}
+/**
+ * Result of a transition attempt.
+ */
+interface TransitionResult {
+  success: boolean;
+  previousStepKey: string;
+  currentStepKey: string | null;
+  status: StateMachineState['status'];
+  error?: string;
+}
+/**
+ * Context for transition validation.
+ */
+interface TransitionContext {
+  userId: string;
+  userRoles: string[];
+  data?: Record<string, unknown>;
+}
+/**
+ * State machine engine interface.
+ * Implementation should be provided at runtime.
+ */
+interface IStateMachineEngine {
+  /**
+   * Validate that a transition is allowed.
+   */
+  canTransition(definition: StateMachineDefinition, state: StateMachineState, action: string, context: TransitionContext): {
+    allowed: boolean;
+    reason?: string;
+  };
+  /**
+   * Get available actions for the current step.
+   */
+  getAvailableActions(definition: StateMachineDefinition, state: StateMachineState, context: TransitionContext): string[];
+  /**
+   * Execute a transition.
+   */
+  transition(definition: StateMachineDefinition, state: StateMachineState, action: string, context: TransitionContext): TransitionResult;
+  /**
+   * Evaluate a condition expression.
+   */
+  evaluateCondition(expression: string, contextData: Record<string, unknown>): boolean;
+}
+/**
+ * Basic state machine engine implementation.
+ * This is a reference implementation for spec validation.
+ */
+declare class BasicStateMachineEngine implements IStateMachineEngine {
+  canTransition(definition: StateMachineDefinition, state: StateMachineState, action: string, context: TransitionContext): {
+    allowed: boolean;
+    reason?: string;
+  };
+  getAvailableActions(definition: StateMachineDefinition, state: StateMachineState, context: TransitionContext): string[];
+  transition(definition: StateMachineDefinition, state: StateMachineState, action: string, context: TransitionContext): TransitionResult;
+  evaluateCondition(expression: string, contextData: Record<string, unknown>): boolean;
+}
+/**
+ * Create a new state machine engine instance.
+ */
+declare function createStateMachineEngine(): IStateMachineEngine;
+/**
+ * Build a state machine definition from workflow entities.
+ */
+declare function buildStateMachineDefinition(workflow: {
+  key: string;
+  name: string;
+  version: number;
+  initialStepId: string | null;
+}, steps: {
+  key: string;
+  name: string;
+  type: string;
+  transitions: Record<string, string | TransitionDefinition>;
+  approvalMode?: string;
+  approverRoles?: string[];
+  timeoutSeconds?: number;
+  conditionExpression?: string;
+}[]): StateMachineDefinition;
+/**
+ * Create initial state for a new workflow instance.
+ */
+declare function createInitialState(definition: StateMachineDefinition, contextData?: Record<string, unknown>): StateMachineState;
+//#endregion
+export { BasicStateMachineEngine, IStateMachineEngine, StateMachineDefinition, StateMachineState, StateMachineStep, TransitionContext, TransitionDefinition, TransitionResult, buildStateMachineDefinition, createInitialState, createStateMachineEngine };

package/dist/state-machine/index.js

@@ -0,0 +1 @@
+var e=class{canTransition(e,t,n,r){if(t.status!==`RUNNING`&&t.status!==`WAITING`)return{allowed:!1,reason:`Workflow is ${t.status}, cannot transition`};let i=e.steps[t.currentStepKey];if(!i)return{allowed:!1,reason:`Step ${t.currentStepKey} not found`};let a=i.transitions[n];return a?i.allowedRoles&&i.allowedRoles.length>0&&!i.allowedRoles.some(e=>r.userRoles.includes(e))?{allowed:!1,reason:`User lacks required role for this action`}:typeof a==`object`&&a.allowedRoles&&a.allowedRoles.length>0&&!a.allowedRoles.some(e=>r.userRoles.includes(e))?{allowed:!1,reason:`User lacks required role for action ${n}`}:{allowed:!0}:{allowed:!1,reason:`Action ${n} not available in step ${t.currentStepKey}`}}getAvailableActions(e,t,n){if(t.status!==`RUNNING`&&t.status!==`WAITING`)return[];let r=e.steps[t.currentStepKey];return r?Object.keys(r.transitions).filter(r=>this.canTransition(e,t,r,n).allowed):[]}transition(e,t,n,r){let i=this.canTransition(e,t,n,r);if(!i.allowed)return{success:!1,previousStepKey:t.currentStepKey,currentStepKey:t.currentStepKey,status:t.status,error:i.reason};let a=e.steps[t.currentStepKey];if(!a)return{success:!1,previousStepKey:t.currentStepKey,currentStepKey:t.currentStepKey,status:t.status,error:`Current step ${t.currentStepKey} not found`};let o=a.transitions[n];if(!o)return{success:!1,previousStepKey:t.currentStepKey,currentStepKey:t.currentStepKey,status:t.status,error:`Transition for action ${n} not found`};let s=typeof o==`string`?o:o.targetStepKey,c=e.steps[s];if(!c)return{success:!1,previousStepKey:t.currentStepKey,currentStepKey:t.currentStepKey,status:t.status,error:`Target step ${s} not found`};let l=`RUNNING`;return c.type===`END`?l=`COMPLETED`:(c.type===`APPROVAL`||c.type===`WAIT`)&&(l=`WAITING`),{success:!0,previousStepKey:t.currentStepKey,currentStepKey:s,status:l}}evaluateCondition(e,t){try{let n=e.match(/^(\w+)\s*(>=|<=|>|<|===|!==|==|!=)\s*(.+)$/);if(n){let[,e,r,i]=n;if(!e||!r||i===void 0)return!1;let a=t[e],o=JSON.parse(i);switch(r){case`>`:return Number(a)>Number(o);case`<`:return Number(a)<Number(o);case`>=`:return Number(a)>=Number(o);case`<=`:return Number(a)<=Number(o);case`===`:case`==`:return a===o;case`!==`:case`!=`:return a!==o}}return e in t?!!t[e]:!1}catch{return!1}}};function t(){return new e}function n(e,t){let n={};for(let e of t)n[e.key]={key:e.key,name:e.name,type:e.type,transitions:e.transitions,approvalMode:e.approvalMode,allowedRoles:e.approverRoles,timeoutSeconds:e.timeoutSeconds,conditionExpression:e.conditionExpression};let r=t.find(e=>e.type===`START`)?.key??t[0]?.key??``;return{key:e.key,name:e.name,version:e.version,initialStepKey:r,steps:n}}function r(e,t={}){return{currentStepKey:e.initialStepKey,status:`RUNNING`,contextData:t,history:[]}}export{e as BasicStateMachineEngine,n as buildStateMachineDefinition,r as createInitialState,t as createStateMachineEngine};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@lssm/example.workflow-system",
+  "version": "0.0.0-canary-20251206160926",
+  "description": "Workflow and approval system example for ContractSpec - State machine with role-based transitions",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "dependencies": {
+    "@lssm/lib.schema": "workspace:*",
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.bus": "workspace:*",
+    "@lssm/lib.identity-rbac": "workspace:*",
+    "@lssm/lib.feature-flags": "workspace:*",
+    "@lssm/lib.jobs": "workspace:*",
+    "@lssm/module.audit-trail": "workspace:*",
+    "@lssm/module.notifications": "workspace:*",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@lssm/tool.typescript": "workspace:*",
+    "@lssm/tool.tsdown": "workspace:*",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./contracts": "./dist/contracts/index.js",
+    "./contracts/approval": "./dist/contracts/approval.js",
+    "./contracts/instance": "./dist/contracts/instance.js",
+    "./contracts/workflow": "./dist/contracts/workflow.js",
+    "./entities": "./dist/entities/index.js",
+    "./entities/approval": "./dist/entities/approval.js",
+    "./entities/instance": "./dist/entities/instance.js",
+    "./entities/step": "./dist/entities/step.js",
+    "./entities/workflow": "./dist/entities/workflow.js",
+    "./events": "./dist/events.js",
+    "./feature": "./dist/feature.js",
+    "./handlers": "./dist/handlers/index.js",
+    "./presentations": "./dist/presentations/index.js",
+    "./state-machine": "./dist/state-machine/index.js",
+    "./*": "./*"
+  },
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./entities": "./dist/entities/index.js",
+      "./entities/workflow": "./dist/entities/workflow.js",
+      "./entities/step": "./dist/entities/step.js",
+      "./entities/instance": "./dist/entities/instance.js",
+      "./entities/approval": "./dist/entities/approval.js",
+      "./contracts": "./dist/contracts/index.js",
+      "./contracts/workflow": "./dist/contracts/workflow.js",
+      "./contracts/instance": "./dist/contracts/instance.js",
+      "./contracts/approval": "./dist/contracts/approval.js",
+      "./events": "./dist/events.js",
+      "./feature": "./dist/feature.js",
+      "./handlers": "./dist/handlers/index.js",
+      "./presentations": "./dist/presentations/index.js",
+      "./state-machine": "./dist/state-machine/index.js",
+      "./*": "./*"
+    }
+  }
+}