@soleri/core 2.10.0 → 2.11.0

package/src/__tests__/playbook-executor.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PlaybookExecutor } from '../playbooks/playbook-executor.js';
+import { tddPlaybook } from '../playbooks/generic/tdd.js';
+import { brainstormingPlaybook } from '../playbooks/generic/brainstorming.js';
+import { mergePlaybooks } from '../playbooks/playbook-registry.js';
+import type { PlaybookDefinition } from '../playbooks/playbook-types.js';
+
+describe('PlaybookExecutor', () => {
+  let executor: PlaybookExecutor;
+
+  beforeEach(() => {
+    executor = new PlaybookExecutor();
+  });
+
+  // ─── start ──────────────────────────────────────────────────────
+
+  describe('start', () => {
+    it('should start a session from a PlaybookDefinition', () => {
+      const result = executor.start(tddPlaybook);
+
+      expect(result.sessionId).toMatch(/^pbk-/);
+      expect(result.label).toBe('Test-Driven Development');
+      expect(result.totalSteps).toBeGreaterThan(0);
+      expect(result.currentStep.index).toBe(0);
+      expect(result.currentStep.status).toBe('active');
+      expect(result.tools).toContain('search_intelligent');
+      expect(result.gates.length).toBeGreaterThan(0);
+    });
+
+    it('should start a session from a MergedPlaybook', () => {
+      const merged = mergePlaybooks(tddPlaybook, undefined);
+      const result = executor.start(merged);
+
+      expect(result.sessionId).toMatch(/^pbk-/);
+      expect(result.label).toBe('Test-Driven Development');
+      expect(result.totalSteps).toBeGreaterThan(0);
+    });
+
+    it('should parse numbered steps from playbook text', () => {
+      const result = executor.start(tddPlaybook);
+
+      // TDD playbook has 4 numbered steps
+      expect(result.totalSteps).toBe(4);
+      expect(result.currentStep.title).toContain('RED');
+    });
+
+    it('should track session in listSessions', () => {
+      executor.start(tddPlaybook);
+      executor.start(brainstormingPlaybook);
+
+      const sessions = executor.listSessions();
+      expect(sessions).toHaveLength(2);
+    });
+  });
+
+  // ─── step ───────────────────────────────────────────────────────
+
+  describe('step', () => {
+    it('should advance to the next step', () => {
+      const { sessionId } = executor.start(tddPlaybook);
+
+      const result = executor.step(sessionId, { output: 'Wrote failing test' });
+
+      expect('error' in result).toBe(false);
+      if ('error' in result) return;
+
+      expect(result.completedStep.status).toBe('done');
+      expect(result.completedStep.output).toBe('Wrote failing test');
+      expect(result.nextStep).not.toBeNull();
+      expect(result.nextStep!.status).toBe('active');
+      expect(result.progress.done).toBe(1);
+      expect(result.isComplete).toBe(false);
+    });
+
+    it('should mark step as skipped when skip=true', () => {
+      const { sessionId } = executor.start(tddPlaybook);
+
+      const result = executor.step(sessionId, { skip: true });
+
+      expect('error' in result).toBe(false);
+      if ('error' in result) return;
+
+      expect(result.completedStep.status).toBe('skipped');
+    });
+
+    it('should signal completion when all steps are done', () => {
+      const { sessionId, totalSteps } = executor.start(tddPlaybook);
+
+      let result;
+      for (let i = 0; i < totalSteps; i++) {
+        result = executor.step(sessionId, { output: `Step ${i + 1} done` });
+      }
+
+      expect(result).toBeDefined();
+      expect('error' in result!).toBe(false);
+      if ('error' in result!) return;
+
+      expect(result!.isComplete).toBe(true);
+      expect(result!.nextStep).toBeNull();
+      expect(result!.progress.done).toBe(totalSteps);
+    });
+
+    it('should return error for unknown session', () => {
+      const result = executor.step('nonexistent');
+      expect('error' in result).toBe(true);
+    });
+  });
+
+  // ─── complete ───────────────────────────────────────────────────
+
+  describe('complete', () => {
+    it('should complete a session with all gates passed', () => {
+      const { sessionId, totalSteps } = executor.start(tddPlaybook);
+
+      // Advance through all steps
+      for (let i = 0; i < totalSteps; i++) {
+        executor.step(sessionId);
+      }
+
+      const result = executor.complete(sessionId, {
+        gateResults: { 'tdd-red': true, 'tdd-green': true },
+      });
+
+      expect('error' in result).toBe(false);
+      if ('error' in result) return;
+
+      expect(result.status).toBe('completed');
+      expect(result.gatesPassed).toBe(true);
+      expect(result.unsatisfiedGates).toHaveLength(0);
+      expect(result.duration).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should report unsatisfied gates', () => {
+      const { sessionId, totalSteps } = executor.start(tddPlaybook);
+
+      for (let i = 0; i < totalSteps; i++) {
+        executor.step(sessionId);
+      }
+
+      // Only pass one of two gates
+      const result = executor.complete(sessionId, {
+        gateResults: { 'tdd-red': true },
+      });
+
+      expect('error' in result).toBe(false);
+      if ('error' in result) return;
+
+      expect(result.gatesPassed).toBe(false);
+      expect(result.unsatisfiedGates.length).toBeGreaterThan(0);
+      expect(result.unsatisfiedGates[0]).toContain('tdd-green');
+    });
+
+    it('should abort a session', () => {
+      const { sessionId } = executor.start(tddPlaybook);
+
+      // Only do one step then abort
+      executor.step(sessionId);
+      const result = executor.complete(sessionId, { abort: true });
+
+      expect('error' in result).toBe(false);
+      if ('error' in result) return;
+
+      expect(result.status).toBe('aborted');
+    });
+
+    it('should remove session after completion', () => {
+      const { sessionId, totalSteps } = executor.start(tddPlaybook);
+
+      for (let i = 0; i < totalSteps; i++) {
+        executor.step(sessionId);
+      }
+
+      executor.complete(sessionId);
+
+      expect(executor.getSession(sessionId)).toBeUndefined();
+      expect(executor.listSessions()).toHaveLength(0);
+    });
+
+    it('should return error for unknown session', () => {
+      const result = executor.complete('nonexistent');
+      expect('error' in result).toBe(true);
+    });
+  });
+
+  // ─── getSession ─────────────────────────────────────────────────
+
+  describe('getSession', () => {
+    it('should return active session state', () => {
+      const { sessionId } = executor.start(tddPlaybook);
+
+      const session = executor.getSession(sessionId);
+      expect(session).toBeDefined();
+      expect(session!.status).toBe('active');
+      expect(session!.playbookId).toBe('generic-tdd');
+    });
+
+    it('should reflect step progress', () => {
+      const { sessionId } = executor.start(tddPlaybook);
+      executor.step(sessionId, { output: 'done' });
+
+      const session = executor.getSession(sessionId);
+      expect(session!.currentStepIndex).toBe(1);
+      expect(session!.steps[0].status).toBe('done');
+      expect(session!.steps[1].status).toBe('active');
+    });
+  });
+
+  // ─── edge cases ─────────────────────────────────────────────────
+
+  describe('edge cases', () => {
+    it('should handle playbook with no parseable steps', () => {
+      const minimal: PlaybookDefinition = {
+        id: 'test-minimal',
+        tier: 'generic',
+        title: 'Minimal',
+        trigger: 'test',
+        description: 'A minimal playbook',
+        steps: 'Just do the thing',
+        expectedOutcome: 'Done',
+        category: 'test',
+        tags: [],
+        matchIntents: ['BUILD'],
+        matchKeywords: [],
+        gates: [],
+        taskTemplates: [],
+        toolInjections: [],
+        verificationCriteria: [],
+      };
+
+      const result = executor.start(minimal);
+
+      // Falls back to a single step
+      expect(result.totalSteps).toBe(1);
+      expect(result.currentStep.title).toBe('Minimal');
+    });
+
+    it('should not allow stepping a completed session', () => {
+      const { sessionId, totalSteps } = executor.start(tddPlaybook);
+
+      for (let i = 0; i < totalSteps; i++) {
+        executor.step(sessionId);
+      }
+      executor.complete(sessionId);
+
+      const result = executor.step(sessionId);
+      expect('error' in result).toBe(true);
+    });
+  });
+});

package/src/__tests__/playbook-ops-execution.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { createAgentRuntime } from '../runtime/runtime.js';
+import { createPlaybookOps } from '../runtime/playbook-ops.js';
+import type { AgentRuntime } from '../runtime/types.js';
+import type { OpDefinition } from '../facades/types.js';
+
+describe('playbook execution ops', () => {
+  let runtime: AgentRuntime;
+  let ops: OpDefinition[];
+
+  function findOp(name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  afterEach(() => {
+    runtime?.close();
+  });
+
+  function setup() {
+    runtime = createAgentRuntime({
+      agentId: 'test-playbook-exec',
+      vaultPath: ':memory:',
+    });
+    ops = createPlaybookOps(runtime);
+  }
+
+  it('should return 8 ops total', () => {
+    setup();
+    expect(ops).toHaveLength(8);
+    const names = ops.map((o) => o.name);
+    expect(names).toContain('playbook_start');
+    expect(names).toContain('playbook_step');
+    expect(names).toContain('playbook_complete');
+  });
+
+  // ─── playbook_start ─────────────────────────────────────────────
+
+  describe('playbook_start', () => {
+    it('should start by playbookId', async () => {
+      setup();
+      const result = (await findOp('playbook_start').handler({
+        playbookId: 'generic-tdd',
+      })) as { sessionId: string; label: string; totalSteps: number };
+
+      expect(result.sessionId).toMatch(/^pbk-/);
+      expect(result.label).toBe('Test-Driven Development');
+      expect(result.totalSteps).toBeGreaterThan(0);
+    });
+
+    it('should start by intent auto-match', async () => {
+      setup();
+      const result = (await findOp('playbook_start').handler({
+        intent: 'BUILD',
+        text: 'implement a new feature with tests',
+      })) as { sessionId: string; label: string };
+
+      expect(result.sessionId).toMatch(/^pbk-/);
+      expect(result.label).toBeDefined();
+    });
+
+    it('should return error for unknown playbookId', async () => {
+      setup();
+      const result = (await findOp('playbook_start').handler({
+        playbookId: 'nonexistent',
+      })) as { error: string };
+
+      expect(result.error).toContain('not found');
+    });
+
+    it('should return available playbooks when no match', async () => {
+      setup();
+      const result = (await findOp('playbook_start').handler({
+        intent: 'DELIVER',
+        text: 'something very obscure with no keyword matches',
+      })) as { error: string; available: Array<{ id: string }> };
+
+      // May or may not match — if error, should list available
+      if (result.error) {
+        expect(result.available).toBeDefined();
+        expect(result.available.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should return error with no params', async () => {
+      setup();
+      const result = (await findOp('playbook_start').handler({})) as {
+        error: string;
+        available: Array<{ id: string }>;
+      };
+
+      expect(result.error).toContain('Provide');
+      expect(result.available.length).toBeGreaterThan(0);
+    });
+  });
+
+  // ─── playbook_step ──────────────────────────────────────────────
+
+  describe('playbook_step', () => {
+    it('should advance through steps', async () => {
+      setup();
+      const start = (await findOp('playbook_start').handler({
+        playbookId: 'generic-tdd',
+      })) as { sessionId: string };
+
+      const step = (await findOp('playbook_step').handler({
+        sessionId: start.sessionId,
+        output: 'Wrote failing test for the feature',
+      })) as {
+        completedStep: { status: string; output: string };
+        nextStep: { status: string } | null;
+        progress: { done: number; total: number };
+      };
+
+      expect(step.completedStep.status).toBe('done');
+      expect(step.completedStep.output).toBe('Wrote failing test for the feature');
+      expect(step.nextStep).not.toBeNull();
+      expect(step.progress.done).toBe(1);
+    });
+
+    it('should return error for invalid session', async () => {
+      setup();
+      const result = (await findOp('playbook_step').handler({
+        sessionId: 'invalid',
+      })) as { error: string };
+
+      expect(result.error).toContain('not found');
+    });
+  });
+
+  // ─── playbook_complete ──────────────────────────────────────────
+
+  describe('playbook_complete', () => {
+    it('should complete with gate validation', async () => {
+      setup();
+      const start = (await findOp('playbook_start').handler({
+        playbookId: 'generic-tdd',
+      })) as { sessionId: string; totalSteps: number };
+
+      // Advance through all steps
+      for (let i = 0; i < start.totalSteps; i++) {
+        await findOp('playbook_step').handler({
+          sessionId: start.sessionId,
+          output: `Step ${i + 1}`,
+        });
+      }
+
+      const result = (await findOp('playbook_complete').handler({
+        sessionId: start.sessionId,
+        gateResults: { 'tdd-red': true, 'tdd-green': true },
+      })) as {
+        status: string;
+        gatesPassed: boolean;
+        unsatisfiedGates: string[];
+        duration: number;
+      };
+
+      expect(result.status).toBe('completed');
+      expect(result.gatesPassed).toBe(true);
+      expect(result.duration).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should abort a session', async () => {
+      setup();
+      const start = (await findOp('playbook_start').handler({
+        playbookId: 'generic-tdd',
+      })) as { sessionId: string };
+
+      const result = (await findOp('playbook_complete').handler({
+        sessionId: start.sessionId,
+        abort: true,
+      })) as { status: string };
+
+      expect(result.status).toBe('aborted');
+    });
+  });
+
+  // ─── auth levels ────────────────────────────────────────────────
+
+  describe('auth levels', () => {
+    it('should use write auth for execution ops', () => {
+      setup();
+      expect(findOp('playbook_start').auth).toBe('write');
+      expect(findOp('playbook_step').auth).toBe('write');
+      expect(findOp('playbook_complete').auth).toBe('write');
+    });
+  });
+});