elsabro 7.3.0 → 7.3.1

package/flow-engine/tests/execute-dispatcher.test.js

@@ -0,0 +1,738 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { getExecutor, checkRuntimeStatus, NotImplementedError, DeprecatedNodeError, ExecutorError } = require('../src/executors');
+
+/**
+ * Tests for the execute.md dispatcher pattern.
+ *
+ * The dispatcher (section 3 of commands/elsabro/execute.md) determines how to handle
+ * each instruction type returned by the CLI step command:
+ *
+ * Auto-resolved by engine: entry, exit, condition, router
+ * Require dispatcher action: agent, parallel, team, interrupt, sequence
+ *
+ * This test suite validates:
+ * - Executor selection via getExecutor
+ * - Runtime status validation (not_implemented, deprecated)
+ * - Error handling and propagation
+ * - Edge cases for each node type
+ */
+
+// Minimal context factory
+function makeContext(overrides = {}) {
+  return {
+    inputs: { task: 'test task', profile: 'default', complexity: 'medium', ...overrides.inputs },
+    nodes: { ...overrides.nodes },
+    steps: { ...overrides.steps },
+    state: { ...overrides.state },
+    _iterations: {}
+  };
+}
+
+describe('Execute Dispatcher: Executor Selection', () => {
+  it('dispatches to correct executor for each node type', () => {
+    const nodeTypes = [
+      'entry', 'exit', 'condition', 'router', 'sequence',
+      'agent', 'parallel', 'interrupt', 'team'
+    ];
+
+    for (const type of nodeTypes) {
+      const executor = getExecutor(type);
+      assert.equal(typeof executor, 'function', `Missing executor for type "${type}"`);
+      assert.ok(executor.name.includes('execute'), `Executor "${executor.name}" should be named execute*`);
+    }
+  });
+
+  it('throws ExecutorError for unknown node type', () => {
+    assert.throws(
+      () => getExecutor('subflow'),
+      (err) => {
+        assert.equal(err.name, 'ExecutorError');
+        assert.ok(err.message.includes('No executor for node type "subflow"'));
+        return true;
+      }
+    );
+  });
+
+  it('throws ExecutorError for undefined node type', () => {
+    assert.throws(
+      () => getExecutor(undefined),
+      /No executor/
+    );
+  });
+
+  it('throws ExecutorError for null node type', () => {
+    assert.throws(
+      () => getExecutor(null),
+      /No executor/
+    );
+  });
+});
+
+describe('Execute Dispatcher: Runtime Status Validation', () => {
+  it('allows execution of implemented nodes', () => {
+    const node = { id: 'test', runtime_status: 'implemented' };
+    assert.doesNotThrow(() => checkRuntimeStatus(node));
+  });
+
+  it('allows execution of partial nodes', () => {
+    const node = { id: 'test', runtime_status: 'partial' };
+    assert.doesNotThrow(() => checkRuntimeStatus(node));
+  });
+
+  it('allows execution when runtime_status is undefined', () => {
+    const node = { id: 'test' };
+    assert.doesNotThrow(() => checkRuntimeStatus(node));
+  });
+
+  it('throws NotImplementedError for not_implemented nodes', () => {
+    const node = {
+      id: 'bmad_solution',
+      runtime_status: 'not_implemented',
+      gaps: ['BMAD solutioning logic not yet implemented', 'Needs ADR generation']
+    };
+
+    assert.throws(
+      () => checkRuntimeStatus(node),
+      (err) => {
+        assert.equal(err.name, 'NotImplementedError');
+        assert.equal(err.nodeId, 'bmad_solution');
+        assert.ok(err.message.includes('BMAD solutioning logic not yet implemented'));
+        assert.ok(err.message.includes('Needs ADR generation'));
+        assert.deepEqual(err.gaps, node.gaps);
+        return true;
+      }
+    );
+  });
+
+  it('throws NotImplementedError with empty gaps array', () => {
+    const node = {
+      id: 'unimplemented',
+      runtime_status: 'not_implemented',
+      gaps: []
+    };
+
+    assert.throws(
+      () => checkRuntimeStatus(node),
+      (err) => {
+        assert.equal(err.name, 'NotImplementedError');
+        assert.equal(err.nodeId, 'unimplemented');
+        assert.deepEqual(err.gaps, []);
+        return true;
+      }
+    );
+  });
+
+  it('throws DeprecatedNodeError for deprecated nodes', () => {
+    const node = {
+      id: 'legacy_team_node',
+      runtime_status: 'deprecated',
+      deprecated_reason: 'Use parallel nodes with Agent Teams instead (Rule 8)'
+    };
+
+    assert.throws(
+      () => checkRuntimeStatus(node),
+      (err) => {
+        assert.equal(err.name, 'DeprecatedNodeError');
+        assert.equal(err.nodeId, 'legacy_team_node');
+        assert.ok(err.message.includes('Use parallel nodes with Agent Teams instead'));
+        assert.equal(err.reason, node.deprecated_reason);
+        return true;
+      }
+    );
+  });
+
+  it('throws DeprecatedNodeError with default reason when none provided', () => {
+    const node = {
+      id: 'old_node',
+      runtime_status: 'deprecated'
+    };
+
+    assert.throws(
+      () => checkRuntimeStatus(node),
+      (err) => {
+        assert.equal(err.name, 'DeprecatedNodeError');
+        assert.ok(err.message.includes('Node is deprecated'));
+        return true;
+      }
+    );
+  });
+});
+
+describe('Execute Dispatcher: Auto-Resolved Nodes', () => {
+  it('entry node: auto-resolved by engine, returns next', async () => {
+    const executor = getExecutor('entry');
+    const result = await executor(
+      { id: 'start', type: 'entry', next: 'skill_discovery' },
+      makeContext(),
+      {}
+    );
+    assert.equal(result.next, 'skill_discovery');
+    assert.deepEqual(result.outputs, {});
+  });
+
+  it('exit node: auto-resolved by engine, returns null next with outputs', async () => {
+    const executor = getExecutor('exit');
+    const ctx = makeContext({ inputs: { task: 'my task' } });
+    const result = await executor(
+      {
+        id: 'end_success',
+        type: 'exit',
+        status: 'success',
+        outputs: { success: true, task: '{{inputs.task}}' }
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, null);
+    assert.equal(result.status, 'success');
+    assert.equal(result.outputs.success, true);
+    assert.equal(result.outputs.task, 'my task');
+  });
+
+  it('condition node: auto-resolved by engine, evaluates and routes', async () => {
+    const executor = getExecutor('condition');
+    const ctx = makeContext({
+      nodes: {
+        quality_gate: { outputs: { tests: { exitCode: 0 } } }
+      }
+    });
+    const result = await executor(
+      {
+        id: 'check_tests',
+        type: 'condition',
+        condition: '{{nodes.quality_gate.outputs.tests.exitCode === 0}}',
+        true: 'review',
+        false: 'fix'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'review');
+    assert.equal(result.outputs.conditionResult, true);
+  });
+
+  it('router node: auto-resolved by engine, matches route', async () => {
+    const executor = getExecutor('router');
+    const ctx = makeContext({ inputs: { profile: 'yolo' } });
+    const result = await executor(
+      {
+        id: 'profile_router',
+        type: 'router',
+        condition: '{{inputs.profile}}',
+        routes: {
+          yolo: 'interview_yolo',
+          careful: 'interview_careful',
+          default: 'interview_default'
+        },
+        default: 'interview_default'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'interview_yolo');
+    assert.equal(result.outputs.routeKey, 'yolo');
+  });
+});
+
+describe('Execute Dispatcher: Action Nodes', () => {
+  it('agent node: dispatches to Task tool', async () => {
+    const executor = getExecutor('agent');
+    const callbacks = {
+      onAgent: async (params) => {
+        assert.equal(params.agent, 'elsabro-architect');
+        assert.equal(params.config.style, 'bmad');
+        assert.deepEqual(params.inputs, { task: 'test task' });
+        return { result: 'agent output' };
+      }
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'architect',
+        type: 'agent',
+        agent: 'elsabro-architect',
+        config: { style: 'bmad' },
+        inputs: { task: '{{inputs.task}}' }
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, undefined);
+    assert.ok(result.outputs.output);
+  });
+
+  it('sequence node: executes steps sequentially', async () => {
+    const executor = getExecutor('sequence');
+    const callbacks = {
+      onBash: async (cmd) => ({ output: 'bash output', exitCode: 0 })
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'seq',
+        type: 'sequence',
+        steps: [
+          { action: 'bash', command: 'echo test', as: 'step1' }
+        ],
+        outputs: { result: '{{steps.step1.output.output}}' },
+        next: 'next_node'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'next_node');
+    assert.equal(result.outputs.result, 'bash output');
+    assert.ok(ctx.steps.step1);
+  });
+
+  it('parallel node: dispatches branches', async () => {
+    const executor = getExecutor('parallel');
+    const callbacks = {
+      onParallel: async (params) => {
+        assert.equal(params.nodeId, 'review');
+        assert.equal(params.branches.length, 2);
+        return [
+          { id: 'security', result: 'secure' },
+          { id: 'performance', result: 'fast' }
+        ];
+      }
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'review',
+        type: 'parallel',
+        branches: [
+          { id: 'security', agent: 'security-reviewer', inputs: {} },
+          { id: 'performance', agent: 'perf-reviewer', inputs: {} }
+        ],
+        next: 'collect'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'collect');
+    assert.ok(result.outputs.branches.security);
+    assert.ok(result.outputs.branches.performance);
+  });
+
+  it('interrupt node: prompts user with AskUserQuestion', async () => {
+    const executor = getExecutor('interrupt');
+    const callbacks = {
+      onInterrupt: async (params) => {
+        assert.equal(params.nodeId, 'user_choice');
+        assert.ok(params.display.title);
+        return 'continue';
+      }
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'user_choice',
+        type: 'interrupt',
+        reason: 'User approval required',
+        display: {
+          title: 'Continue execution?',
+          options: [{ id: 'continue', label: 'Yes' }, { id: 'abort', label: 'No' }]
+        },
+        routes: { continue: 'next', abort: 'end' }
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'next');
+    assert.equal(result.outputs.selection, 'continue');
+  });
+
+  it('team node: deprecated but callable', async () => {
+    const executor = getExecutor('team');
+    const callbacks = {
+      onTeam: async (node) => {
+        assert.equal(node.id, 'legacy_team');
+        return { teamOutput: 'done' };
+      }
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'legacy_team',
+        type: 'team',
+        next: 'next'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'next');
+    assert.ok(result.outputs.teamOutput);
+  });
+});
+
+describe('Execute Dispatcher: Error Handling', () => {
+  it('condition node throws when condition field is missing', async () => {
+    const executor = getExecutor('condition');
+    await assert.rejects(
+      executor({ id: 'bad_cond', type: 'condition', true: 'a', false: 'b' }, makeContext(), {}),
+      (err) => {
+        assert.equal(err.name, 'ExecutorError');
+        assert.ok(err.message.includes('has no "condition" field'));
+        return true;
+      }
+    );
+  });
+
+  it('condition node throws when branch is missing', async () => {
+    const executor = getExecutor('condition');
+    const ctx = makeContext({ inputs: { val: true } });
+    await assert.rejects(
+      executor(
+        { id: 'cond', type: 'condition', condition: '{{inputs.val}}', true: 'next' },
+        ctx,
+        {}
+      ),
+      (err) => {
+        assert.equal(err.name, 'ExecutorError');
+        assert.ok(err.message.includes('no "false" branch defined'));
+        return true;
+      }
+    );
+  });
+
+  it('router node throws when condition is missing', async () => {
+    const executor = getExecutor('router');
+    await assert.rejects(
+      executor(
+        { id: 'router', type: 'router', routes: { a: 'b' } },
+        makeContext(),
+        {}
+      ),
+      /has no "condition" field/
+    );
+  });
+
+  it('router node throws when no route matches and no default', async () => {
+    const executor = getExecutor('router');
+    const ctx = makeContext({ inputs: { profile: 'unknown' } });
+    await assert.rejects(
+      executor(
+        {
+          id: 'router',
+          type: 'router',
+          condition: '{{inputs.profile}}',
+          routes: { yolo: 'a', careful: 'b' }
+        },
+        ctx,
+        {}
+      ),
+      /could not match "unknown"/
+    );
+  });
+
+  it('sequence node throws on step failure without errorPolicy', async () => {
+    const executor = getExecutor('sequence');
+    const callbacks = {
+      onBash: async () => { throw new Error('command failed'); }
+    };
+    await assert.rejects(
+      executor(
+        {
+          id: 'seq',
+          type: 'sequence',
+          steps: [{ action: 'bash', command: 'fail', as: 'step1' }],
+          next: 'done'
+        },
+        makeContext(),
+        callbacks
+      ),
+      /Step "step1" failed/
+    );
+  });
+
+  it('interrupt node throws when no route matches selection', async () => {
+    const executor = getExecutor('interrupt');
+    const callbacks = {
+      onInterrupt: async () => 'invalid_option'
+    };
+    await assert.rejects(
+      executor(
+        {
+          id: 'interrupt',
+          type: 'interrupt',
+          routes: { continue: 'next', abort: 'end' },
+          display: { title: 'Choose', options: [] }
+        },
+        makeContext(),
+        callbacks
+      ),
+      /no matching route found/
+    );
+  });
+});
+
+describe('Execute Dispatcher: Edge Cases', () => {
+  it('handles sequence with no steps', async () => {
+    const executor = getExecutor('sequence');
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'empty_seq',
+        type: 'sequence',
+        steps: [],
+        next: 'next'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'next');
+    assert.deepEqual(result.outputs, {});
+  });
+
+  it('handles parallel with no branches', async () => {
+    const executor = getExecutor('parallel');
+    const callbacks = {
+      onParallel: async () => []
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'empty_parallel',
+        type: 'parallel',
+        branches: [],
+        next: 'next'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'next');
+    assert.deepEqual(result.outputs.branches, {});
+  });
+
+  it('handles sequence with optional step failure', async () => {
+    const executor = getExecutor('sequence');
+    const callbacks = {
+      onReadFiles: async () => { throw new Error('file not found'); }
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'seq',
+        type: 'sequence',
+        steps: [
+          { action: 'read_files', files: ['missing.md'], optional: true, as: 'files' }
+        ],
+        next: 'done'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'done');
+    assert.ok(ctx.steps.files.error);
+  });
+
+  it('handles sequence with errorPolicy=continue', async () => {
+    const executor = getExecutor('sequence');
+    const callbacks = {
+      onBash: async () => { throw new Error('command failed'); }
+    };
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'seq',
+        type: 'sequence',
+        errorPolicy: 'continue',
+        steps: [
+          { action: 'bash', command: 'bad', as: 'bad_step' }
+        ],
+        next: 'done'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(result.next, 'done');
+    assert.ok(ctx.steps.bad_step.error);
+  });
+
+  it('handles condition with non-wrapped template', async () => {
+    const executor = getExecutor('condition');
+    const ctx = makeContext({ inputs: { val: true } });
+    const result = await executor(
+      {
+        id: 'cond',
+        type: 'condition',
+        condition: 'inputs.val === true',
+        true: 'yes',
+        false: 'no'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'yes');
+  });
+
+  it('handles router with string default route reference', async () => {
+    const executor = getExecutor('router');
+    const ctx = makeContext({ inputs: { profile: 'unknown' } });
+    const result = await executor(
+      {
+        id: 'router',
+        type: 'router',
+        condition: '{{inputs.profile}}',
+        routes: {
+          yolo: 'interview_yolo',
+          default: 'interview_default'
+        },
+        default: 'default'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'interview_default');
+  });
+
+  it('handles exit with no status field', async () => {
+    const executor = getExecutor('exit');
+    const result = await executor(
+      { id: 'end', type: 'exit', outputs: {} },
+      makeContext(),
+      {}
+    );
+    assert.equal(result.status, 'completed');
+  });
+
+  it('handles agent without callback (skipped)', async () => {
+    const executor = getExecutor('agent');
+    const result = await executor(
+      {
+        id: 'agent',
+        type: 'agent',
+        agent: 'test-agent',
+        inputs: {}
+      },
+      makeContext(),
+      {}
+    );
+    assert.ok(result.outputs.output.skipped);
+  });
+
+  it('handles parallel without callback (skipped)', async () => {
+    const executor = getExecutor('parallel');
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'parallel',
+        type: 'parallel',
+        branches: [{ id: 'a', agent: 'test', inputs: {} }],
+        next: 'next'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'next');
+    assert.ok(result.outputs.branches.a.skipped);
+  });
+
+  it('handles sequence with unrecognized step action', async () => {
+    const executor = getExecutor('sequence');
+    const ctx = makeContext();
+    const result = await executor(
+      {
+        id: 'seq',
+        type: 'sequence',
+        steps: [
+          { action: 'learn_patterns', as: 'learn' }
+        ],
+        next: 'done'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(result.next, 'done');
+    assert.ok(ctx.steps.learn.output.skipped);
+  });
+});
+
+describe('Execute Dispatcher: Integration', () => {
+  it('simulates full dispatch flow for auto-resolved nodes', async () => {
+    // entry → condition → exit
+    const entryExec = getExecutor('entry');
+    const condExec = getExecutor('condition');
+    const exitExec = getExecutor('exit');
+
+    const ctx = makeContext({ inputs: { success: true } });
+
+    const step1 = await entryExec(
+      { id: 'start', type: 'entry', next: 'check' },
+      ctx,
+      {}
+    );
+    assert.equal(step1.next, 'check');
+
+    const step2 = await condExec(
+      {
+        id: 'check',
+        type: 'condition',
+        condition: '{{inputs.success}}',
+        true: 'end_success',
+        false: 'end_failure'
+      },
+      ctx,
+      {}
+    );
+    assert.equal(step2.next, 'end_success');
+
+    const step3 = await exitExec(
+      {
+        id: 'end_success',
+        type: 'exit',
+        status: 'success',
+        outputs: { result: 'Task completed' }
+      },
+      ctx,
+      {}
+    );
+    assert.equal(step3.next, null);
+    assert.equal(step3.status, 'success');
+  });
+
+  it('simulates dispatch flow with sequence and agent', async () => {
+    const seqExec = getExecutor('sequence');
+    const agentExec = getExecutor('agent');
+
+    const callbacks = {
+      onBash: async () => ({ output: 'discovery complete', exitCode: 0 }),
+      onAgent: async () => ({ result: 'agent done' })
+    };
+
+    const ctx = makeContext();
+
+    // Execute sequence
+    const step1 = await seqExec(
+      {
+        id: 'skill_discovery',
+        type: 'sequence',
+        steps: [{ action: 'bash', command: 'hooks/skill-discovery.sh', as: 'discovery' }],
+        next: 'architect'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(step1.next, 'architect');
+    assert.ok(ctx.steps.discovery);
+
+    // Execute agent
+    const step2 = await agentExec(
+      {
+        id: 'architect',
+        type: 'agent',
+        agent: 'elsabro-architect',
+        inputs: { task: '{{inputs.task}}' },
+        next: 'end'
+      },
+      ctx,
+      callbacks
+    );
+    assert.equal(step2.next, 'end');
+  });
+});