@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/blueprint-e2e.test.ts

@@ -0,0 +1,706 @@
+/**
+ * Blueprint MVP1 End-to-End Tests
+ *
+ * Exercises the complete PM Blueprint workflow definitions through the
+ * player-core engine. This tests the "declarative program" concept:
+ *
+ * 1. PM-Task workflow: todo → in_progress → done (with XP rewards)
+ * 2. PM-Project workflow: draft → active → completed (auto-complete when all tasks done)
+ * 3. PM-User-Stats workflow: XP progression with level-up system
+ * 4. Experience workflows: domain events → pattern matching → frontend actions
+ *
+ * These mirror the actual blueprint definitions from the PR.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { StateMachine } from '../state-machine/interpreter';
+import { EventBus } from '../events/event-bus';
+import { ActionDispatcher } from '../actions/dispatcher';
+import { createEvaluator, WEB_FAILURE_POLICIES, clearExpressionCache } from '../expression';
+import type { PlayerWorkflowDefinition } from '../state-machine/types';
+import type { Evaluator, ExpressionContext } from '../expression/types';
+
+// =============================================================================
+// Blueprint Domain Workflow Definitions (matching backend seeds)
+// =============================================================================
+
+const PM_TASK_DEFINITION: PlayerWorkflowDefinition = {
+  id: 'pm-task',
+  slug: 'pm-task',
+  states: [
+    {
+      name: 'todo',
+      type: 'START',
+      on_enter: [
+        {
+          type: 'set_field',
+          config: { field: 'status_label', value: 'To Do' },
+        },
+      ],
+    },
+    {
+      name: 'in_progress',
+      type: 'REGULAR',
+      on_enter: [
+        {
+          type: 'set_field',
+          config: { field: 'status_label', value: 'In Progress' },
+        },
+      ],
+    },
+    {
+      name: 'done',
+      type: 'END',
+      on_enter: [
+        {
+          type: 'set_field',
+          config: { field: 'status_label', value: 'Done' },
+        },
+      ],
+    },
+    {
+      name: 'cancelled',
+      type: 'CANCELLED',
+      on_enter: [
+        {
+          type: 'set_field',
+          config: { field: 'status_label', value: 'Cancelled' },
+        },
+      ],
+    },
+  ],
+  transitions: [
+    { name: 'start', from: ['todo'], to: 'in_progress' },
+    { name: 'complete', from: ['in_progress'], to: 'done' },
+    { name: 'cancel', from: ['todo', 'in_progress'], to: 'cancelled' },
+    { name: 'reopen', from: ['done', 'cancelled'], to: 'todo' },
+  ],
+};
+
+const PM_PROJECT_DEFINITION: PlayerWorkflowDefinition = {
+  id: 'pm-project',
+  slug: 'pm-project',
+  states: [
+    {
+      name: 'draft',
+      type: 'START',
+      on_enter: [
+        { type: 'set_field', config: { field: 'total_tasks', value: 0 } },
+        { type: 'set_field', config: { field: 'completed_tasks', value: 0 } },
+      ],
+    },
+    {
+      name: 'active',
+      type: 'REGULAR',
+      on_event: [
+        {
+          match: '*:*:pm-task:transition.completed',
+          actions: [
+            {
+              type: 'set_field',
+              config: { field: 'last_task_event', value: 'task_transitioned' },
+            },
+          ],
+        },
+      ],
+    },
+    { name: 'completed', type: 'END' },
+    { name: 'cancelled', type: 'CANCELLED' },
+  ],
+  transitions: [
+    { name: 'activate', from: ['draft'], to: 'active' },
+    {
+      name: 'auto_complete',
+      from: ['active'],
+      to: 'completed',
+      auto: true,
+      conditions: ['gt(completed_tasks, 0)', 'eq(completed_tasks, total_tasks)'],
+    },
+    { name: 'cancel', from: ['draft', 'active'], to: 'cancelled' },
+  ],
+};
+
+const PM_PROJECT_EXPERIENCE: PlayerWorkflowDefinition = {
+  id: 'pm-project-experience',
+  slug: 'pm-project-experience',
+  states: [
+    {
+      name: 'active',
+      type: 'START',
+      on_event: [
+        {
+          match: '*:*:pm-task:instance.completed',
+          actions: [
+            {
+              type: 'toast',
+              config: { variant: 'success', message: 'Task completed!', duration: 3000 },
+            },
+            {
+              type: 'refresh_query',
+              config: { queryKey: ['workflow-instances'] },
+            },
+          ],
+        },
+        {
+          match: '*:*:pm-task:transition.completed',
+          conditions: ["eq(event.transition_name, 'start')"],
+          actions: [
+            {
+              type: 'toast',
+              config: { variant: 'info', message: 'Task started', duration: 2000 },
+            },
+          ],
+        },
+        {
+          match: '*:*:pm-project:instance.completed',
+          actions: [
+            {
+              type: 'toast',
+              config: { variant: 'success', message: 'All tasks done — project completed!' },
+            },
+            {
+              type: 'play_sound',
+              config: { src: '/sounds/success.mp3', volume: 0.6 },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  transitions: [],
+};
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('Blueprint MVP1 E2E: Declarative Program Engine', () => {
+  let evaluator: Evaluator;
+
+  beforeEach(() => {
+    clearExpressionCache();
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // PM-Task: Full lifecycle
+  // ---------------------------------------------------------------------------
+
+  describe('PM-Task Workflow', () => {
+    it('completes full task lifecycle: todo → in_progress → done', async () => {
+      const actionHandler = vi.fn();
+      const sm = new StateMachine(PM_TASK_DEFINITION, {
+        title: 'Write tests',
+        priority: 'high',
+        xp_reward: 25,
+      }, {
+        evaluator,
+        actionHandlers: new Map([['set_field', actionHandler]]),
+      });
+
+      expect(sm.currentState).toBe('todo');
+      expect(sm.status).toBe('ACTIVE');
+
+      // Start the task
+      const r1 = await sm.transition('start');
+      expect(r1.success).toBe(true);
+      expect(sm.currentState).toBe('in_progress');
+      // on_enter set_field should have been called
+      expect(actionHandler).toHaveBeenCalled();
+
+      // Complete the task
+      const r2 = await sm.transition('complete');
+      expect(r2.success).toBe(true);
+      expect(sm.currentState).toBe('done');
+      expect(sm.status).toBe('COMPLETED');
+    });
+
+    it('allows cancel from any active state', async () => {
+      const sm = new StateMachine(PM_TASK_DEFINITION, {}, {
+        evaluator,
+        actionHandlers: new Map([['set_field', vi.fn()]]),
+      });
+
+      // Cancel from todo
+      const r = await sm.transition('cancel');
+      expect(r.success).toBe(true);
+      expect(sm.currentState).toBe('cancelled');
+    });
+
+    it('done/cancelled set terminal status blocking further transitions', async () => {
+      const sm = new StateMachine(PM_TASK_DEFINITION, {}, {
+        evaluator,
+        actionHandlers: new Map([['set_field', vi.fn()]]),
+      });
+
+      await sm.transition('start');
+      await sm.transition('complete');
+      expect(sm.currentState).toBe('done');
+      expect(sm.status).toBe('COMPLETED');
+
+      // Even though reopen is defined from done→todo, the instance status
+      // is COMPLETED so the state machine rejects all transitions
+      const r = await sm.transition('reopen');
+      expect(r.success).toBe(false);
+      expect(r.error).toContain('COMPLETED');
+    });
+
+    it('available transitions are correct per state', () => {
+      const sm = new StateMachine(PM_TASK_DEFINITION, {}, {
+        evaluator, actionHandlers: new Map([['set_field', vi.fn()]]),
+      });
+
+      // In todo: can start or cancel
+      const todoTransitions = sm.getAvailableTransitions().map(t => t.name);
+      expect(todoTransitions).toContain('start');
+      expect(todoTransitions).toContain('cancel');
+      expect(todoTransitions).not.toContain('complete');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // PM-Project: Auto-completion via conditions
+  // ---------------------------------------------------------------------------
+
+  describe('PM-Project Workflow', () => {
+    it('auto-completes when all tasks are done', async () => {
+      const sm = new StateMachine(PM_PROJECT_DEFINITION, {
+        name: 'Test Project',
+        total_tasks: 3,
+        completed_tasks: 0,
+      }, {
+        evaluator,
+        actionHandlers: new Map([['set_field', vi.fn()]]),
+      });
+
+      // Activate project
+      const r1 = await sm.transition('activate');
+      expect(r1.success).toBe(true);
+      expect(sm.currentState).toBe('active');
+
+      // Simulate completing tasks
+      sm.setField('completed_tasks', 1);
+      sm.setField('completed_tasks', 2);
+
+      // Not yet — 2/3 tasks done, auto transition should NOT fire
+      // (auto transitions check on explicit transitions, not on setField)
+
+      // Complete last task
+      sm.setField('completed_tasks', 3);
+
+      // Now trigger a transition check — auto_complete should evaluate
+      // In the real app, this would be triggered by a domain event
+      // For testing, we verify the conditions are evaluable
+      const ctx: ExpressionContext = {
+        ...sm.stateData,
+        state_data: sm.stateData,
+        completed_tasks: 3,
+        total_tasks: 3,
+      };
+      const cond1 = evaluator.evaluate('gt(completed_tasks, 0)', ctx);
+      const cond2 = evaluator.evaluate('eq(completed_tasks, total_tasks)', ctx);
+      expect(cond1.value).toBe(true);
+      expect(cond2.value).toBe(true);
+    });
+
+    it('auto-complete does NOT fire when tasks incomplete', () => {
+      const ctx: ExpressionContext = {
+        completed_tasks: 1,
+        total_tasks: 3,
+      };
+      const cond = evaluator.evaluate('eq(completed_tasks, total_tasks)', ctx);
+      expect(cond.value).toBe(false);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Experience Workflow: Domain events → frontend actions
+  // ---------------------------------------------------------------------------
+
+  describe('PM-Project Experience Workflow', () => {
+    it('fires toast when task completes (domain event pattern matching)', async () => {
+      const eventBus = new EventBus();
+      const dispatcher = new ActionDispatcher();
+      const toastHandler = vi.fn();
+      const refreshHandler = vi.fn();
+
+      dispatcher.register('toast', toastHandler);
+      dispatcher.register('refresh_query', refreshHandler);
+
+      const sm = new StateMachine(PM_PROJECT_EXPERIENCE, {}, {
+        evaluator,
+        actionHandlers: new Map(),
+      });
+
+      // Wire on_event subscriptions
+      const stateDef = sm.getCurrentStateDefinition()!;
+      for (const sub of stateDef.on_event!) {
+        eventBus.subscribe(sub.match, async (event) => {
+          const ctx: ExpressionContext = {
+            ...sm.stateData,
+            state_data: sm.stateData,
+            event: event.payload,
+            current_state: sm.currentState,
+            status: sm.status,
+          };
+
+          // Check conditions
+          if (sub.conditions?.length) {
+            for (const condition of sub.conditions) {
+              const result = evaluator.evaluate<boolean>(condition, ctx);
+              if (!result.value) return;
+            }
+          }
+
+          await dispatcher.execute(sub.actions, ctx, evaluator);
+        });
+      }
+
+      // Simulate: task instance completed (backend emits domain event via WebSocket)
+      await eventBus.publish('stakeholder:s1:pm-task:instance.completed', {
+        instance_id: 'task-1',
+        from_state: 'in_progress',
+        to_state: 'done',
+      });
+
+      // Toast should have fired
+      expect(toastHandler).toHaveBeenCalledOnce();
+      expect(toastHandler).toHaveBeenCalledWith(
+        { variant: 'success', message: 'Task completed!', duration: 3000 },
+        expect.objectContaining({ current_state: 'active' }),
+      );
+
+      // Refresh query should also fire
+      expect(refreshHandler).toHaveBeenCalledOnce();
+    });
+
+    it('fires toast on task start with condition check', async () => {
+      const eventBus = new EventBus();
+      const dispatcher = new ActionDispatcher();
+      const toastHandler = vi.fn();
+
+      dispatcher.register('toast', toastHandler);
+
+      const sm = new StateMachine(PM_PROJECT_EXPERIENCE, {}, {
+        evaluator, actionHandlers: new Map(),
+      });
+
+      const stateDef = sm.getCurrentStateDefinition()!;
+      for (const sub of stateDef.on_event!) {
+        eventBus.subscribe(sub.match, async (event) => {
+          const ctx: ExpressionContext = {
+            ...sm.stateData,
+            state_data: sm.stateData,
+            event: event.payload,
+            current_state: sm.currentState,
+            status: sm.status,
+          };
+          if (sub.conditions?.length) {
+            for (const condition of sub.conditions) {
+              const result = evaluator.evaluate<boolean>(condition, ctx);
+              if (!result.value) return;
+            }
+          }
+          await dispatcher.execute(sub.actions, ctx, evaluator);
+        });
+      }
+
+      // Simulate: task transition (start)
+      await eventBus.publish('stakeholder:s1:pm-task:transition.completed', {
+        transition_name: 'start',
+        from_state: 'todo',
+        to_state: 'in_progress',
+      });
+
+      // Should get "Task started" toast (condition matches transition_name == 'start')
+      expect(toastHandler).toHaveBeenCalledWith(
+        { variant: 'info', message: 'Task started', duration: 2000 },
+        expect.objectContaining({ current_state: 'active' }),
+      );
+    });
+
+    it('does NOT fire task-start toast for complete transition', async () => {
+      const eventBus = new EventBus();
+      const dispatcher = new ActionDispatcher();
+      const toastHandler = vi.fn();
+
+      dispatcher.register('toast', toastHandler);
+
+      const sm = new StateMachine(PM_PROJECT_EXPERIENCE, {}, {
+        evaluator, actionHandlers: new Map(),
+      });
+
+      const stateDef = sm.getCurrentStateDefinition()!;
+      for (const sub of stateDef.on_event!) {
+        eventBus.subscribe(sub.match, async (event) => {
+          const ctx: ExpressionContext = {
+            ...sm.stateData,
+            state_data: sm.stateData,
+            event: event.payload,
+            current_state: sm.currentState,
+            status: sm.status,
+          };
+          if (sub.conditions?.length) {
+            for (const condition of sub.conditions) {
+              const result = evaluator.evaluate<boolean>(condition, ctx);
+              if (!result.value) return;
+            }
+          }
+          await dispatcher.execute(sub.actions, ctx, evaluator);
+        });
+      }
+
+      // Simulate: task transition (complete) — condition is eq(event.transition_name, 'start')
+      await eventBus.publish('stakeholder:s1:pm-task:transition.completed', {
+        transition_name: 'complete',
+        from_state: 'in_progress',
+        to_state: 'done',
+      });
+
+      // Should NOT fire the "Task started" toast (transition_name != 'start')
+      expect(toastHandler).not.toHaveBeenCalled();
+    });
+
+    it('fires project completion celebration (toast + sound)', async () => {
+      const eventBus = new EventBus();
+      const dispatcher = new ActionDispatcher();
+      const toastHandler = vi.fn();
+      const soundHandler = vi.fn();
+
+      dispatcher.register('toast', toastHandler);
+      dispatcher.register('play_sound', soundHandler);
+
+      const sm = new StateMachine(PM_PROJECT_EXPERIENCE, {}, {
+        evaluator, actionHandlers: new Map(),
+      });
+
+      const stateDef = sm.getCurrentStateDefinition()!;
+      for (const sub of stateDef.on_event!) {
+        eventBus.subscribe(sub.match, async (event) => {
+          const ctx: ExpressionContext = {
+            ...sm.stateData, state_data: sm.stateData,
+            event: event.payload, current_state: sm.currentState, status: sm.status,
+          };
+          if (sub.conditions?.length) {
+            for (const condition of sub.conditions) {
+              const result = evaluator.evaluate<boolean>(condition, ctx);
+              if (!result.value) return;
+            }
+          }
+          await dispatcher.execute(sub.actions, ctx, evaluator);
+        });
+      }
+
+      // Simulate: project completed
+      await eventBus.publish('stakeholder:s1:pm-project:instance.completed', {
+        instance_id: 'project-1',
+        from_state: 'active',
+        to_state: 'completed',
+      });
+
+      expect(toastHandler).toHaveBeenCalledWith(
+        { variant: 'success', message: 'All tasks done — project completed!' },
+        expect.any(Object),
+      );
+      expect(soundHandler).toHaveBeenCalledWith(
+        { src: '/sounds/success.mp3', volume: 0.6 },
+        expect.any(Object),
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // User Stats: XP Progression
+  // ---------------------------------------------------------------------------
+
+  describe('PM-User-Stats Progression', () => {
+    it('evaluates XP level conditions correctly', () => {
+      // Level system from blueprint:
+      // Level 1: 0 XP, Level 2: 100 XP, Level 3: 300 XP, Level 4: 600 XP
+      const cases = [
+        { xp: 0, level: 1, expected_gte_100: false },
+        { xp: 50, level: 1, expected_gte_100: false },
+        { xp: 100, level: 2, expected_gte_100: true },
+        { xp: 300, level: 3, expected_gte_100: true },
+        { xp: 600, level: 4, expected_gte_100: true },
+      ];
+
+      for (const c of cases) {
+        const ctx: ExpressionContext = {
+          total_xp: c.xp,
+          current_level: c.level,
+        };
+        const result = evaluator.evaluate('gte(total_xp, 100)', ctx);
+        expect(result.value).toBe(c.expected_gte_100);
+      }
+    });
+
+    it('level-up condition evaluation chain works', () => {
+      // Test the progressive level conditions
+      const ctx: ExpressionContext = {
+        total_xp: 350,
+        current_level: 3,
+      };
+
+      // Should be level 3 (300-599 range)
+      expect(evaluator.evaluate('gte(total_xp, 300)', ctx).value).toBe(true);
+      expect(evaluator.evaluate('gte(total_xp, 600)', ctx).value).toBe(false);
+
+      // Level-up condition: total_xp >= next_threshold AND current_level < max_level
+      expect(evaluator.evaluate('gte(total_xp, 600) && lt(current_level, 8)', ctx).value).toBe(false);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Expression Engine: Blueprint expression patterns
+  // ---------------------------------------------------------------------------
+
+  describe('Blueprint Expression Patterns', () => {
+    it('supports event payload access via dot notation', () => {
+      const ctx: ExpressionContext = {
+        event: {
+          transition_name: 'start',
+          from_state: 'todo',
+          to_state: 'in_progress',
+          trigger: 'user',
+        },
+      };
+
+      expect(evaluator.evaluate('event.transition_name', ctx).value).toBe('start');
+      expect(evaluator.evaluate('event.from_state', ctx).value).toBe('todo');
+      expect(evaluator.evaluate("eq(event.transition_name, 'start')", ctx).value).toBe(true);
+      expect(evaluator.evaluate("eq(event.trigger, 'user')", ctx).value).toBe(true);
+    });
+
+    it('supports $ prefix paths for domain references', () => {
+      const ctx: ExpressionContext = {
+        $instance: {
+          fields: { name: 'Test Task' },
+          memory: { xp: 25 },
+        },
+      };
+
+      expect(evaluator.evaluate('$instance.fields.name', ctx).value).toBe('Test Task');
+      expect(evaluator.evaluate('$instance.memory.xp', ctx).value).toBe(25);
+    });
+
+    it('supports complex nested function calls for computed fields', () => {
+      const ctx: ExpressionContext = {
+        total_tasks: 10,
+        completed_tasks: 7,
+      };
+
+      // Progress percentage: round(divide(completed_tasks, total_tasks) * 100)
+      // But our safe evaluator doesn't support * operator directly
+      // Instead: round(multiply(divide(completed_tasks, total_tasks), 100))
+      const result = evaluator.evaluate(
+        'round(multiply(divide(completed_tasks, total_tasks), 100))',
+        ctx,
+      );
+      expect(result.value).toBe(70);
+    });
+
+    it('ternary expressions for conditional display', () => {
+      const ctx: ExpressionContext = { status: 'ACTIVE', priority: 'high' };
+
+      expect(evaluator.evaluate("status == 'ACTIVE' ? 'Running' : 'Stopped'", ctx).value)
+        .toBe('Running');
+      expect(evaluator.evaluate("priority == 'high' ? 'urgent' : 'normal'", ctx).value)
+        .toBe('urgent');
+    });
+
+    it('template interpolation for dynamic messages', () => {
+      const ctx: ExpressionContext = {
+        name: 'Alice',
+        completed_tasks: 7,
+        total_tasks: 10,
+      };
+
+      const result = evaluator.evaluateTemplate(
+        '{{name}} completed {{completed_tasks}} of {{total_tasks}} tasks',
+        ctx,
+      );
+      expect(result.value).toBe('Alice completed 7 of 10 tasks');
+    });
+
+    it('logical operators for multi-condition transitions', () => {
+      // Auto-complete: gt(completed_tasks, 0) && eq(completed_tasks, total_tasks)
+      const ctx: ExpressionContext = {
+        completed_tasks: 5,
+        total_tasks: 5,
+      };
+
+      expect(evaluator.evaluate(
+        'gt(completed_tasks, 0) && eq(completed_tasks, total_tasks)',
+        ctx,
+      ).value).toBe(true);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Full Pipeline: Event → Match → Condition → Action
+  // ---------------------------------------------------------------------------
+
+  describe('Full Pipeline Integration', () => {
+    it('complete blueprint cycle: create project → add tasks → complete tasks → auto-complete', async () => {
+      const actionLog: Array<{ type: string; config: Record<string, unknown> }> = [];
+
+      const eventBus = new EventBus();
+      const dispatcher = new ActionDispatcher();
+
+      // Register all action types
+      for (const type of ['toast', 'animate', 'refresh_query', 'play_sound', 'set_field']) {
+        dispatcher.register(type, (config: Record<string, unknown>) => {
+          actionLog.push({ type, config });
+        });
+      }
+
+      // Create the experience workflow
+      const sm = new StateMachine(PM_PROJECT_EXPERIENCE, {}, {
+        evaluator, actionHandlers: new Map(),
+      });
+
+      // Wire subscriptions
+      const stateDef = sm.getCurrentStateDefinition()!;
+      for (const sub of stateDef.on_event!) {
+        eventBus.subscribe(sub.match, async (event) => {
+          const ctx: ExpressionContext = {
+            ...sm.stateData, state_data: sm.stateData,
+            event: event.payload, current_state: sm.currentState, status: sm.status,
+          };
+          if (sub.conditions?.length) {
+            for (const condition of sub.conditions) {
+              const result = evaluator.evaluate<boolean>(condition, ctx);
+              if (!result.value) return;
+            }
+          }
+          await dispatcher.execute(sub.actions, ctx, evaluator);
+        });
+      }
+
+      // Simulate: Task 1 starts
+      await eventBus.publish('stakeholder:s1:pm-task:transition.completed', {
+        transition_name: 'start', from_state: 'todo', to_state: 'in_progress',
+      });
+      expect(actionLog.some(a => a.type === 'toast' && a.config.message === 'Task started')).toBe(true);
+
+      // Simulate: Task 1 completes
+      await eventBus.publish('stakeholder:s1:pm-task:instance.completed', {
+        from_state: 'in_progress', to_state: 'done',
+      });
+      expect(actionLog.some(a => a.type === 'toast' && a.config.message === 'Task completed!')).toBe(true);
+      expect(actionLog.some(a => a.type === 'refresh_query')).toBe(true);
+
+      // Simulate: All tasks done — project auto-completes
+      actionLog.length = 0;
+      await eventBus.publish('stakeholder:s1:pm-project:instance.completed', {
+        from_state: 'active', to_state: 'completed',
+      });
+      expect(actionLog.some(a => a.type === 'toast' && (a.config.message as string).includes('project completed'))).toBe(true);
+      expect(actionLog.some(a => a.type === 'play_sound')).toBe(true);
+    });
+  });
+});