@soleri/core 9.0.4 → 9.2.0

package/src/flows/context-router.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Context router — colocated contract tests.
+ *
+ * Lighter coverage since __tests__/flows.test.ts covers detectContext and
+ * applyContextOverrides thoroughly. Focus: getFlowOverrides and edge cases.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getFlowOverrides, detectContext } from './context-router.js';
+
+describe('getFlowOverrides', () => {
+  it('returns overrides for BUILD-flow', () => {
+    const overrides = getFlowOverrides('BUILD-flow');
+    expect(overrides.length).toBeGreaterThan(0);
+    const contexts = overrides.map((o) => o.context);
+    expect(contexts).toContain('small-component');
+    expect(contexts).toContain('large-component');
+  });
+
+  it('returns overrides for FIX-flow', () => {
+    const overrides = getFlowOverrides('FIX-flow');
+    expect(overrides.length).toBeGreaterThan(0);
+    const contexts = overrides.map((o) => o.context);
+    expect(contexts).toContain('design-fix');
+    expect(contexts).toContain('a11y-fix');
+  });
+
+  it('returns overrides for REVIEW-flow', () => {
+    const overrides = getFlowOverrides('REVIEW-flow');
+    expect(overrides.length).toBeGreaterThan(0);
+    const contexts = overrides.map((o) => o.context);
+    expect(contexts).toContain('pr-review');
+    expect(contexts).toContain('architecture-review');
+  });
+
+  it('returns empty array for unknown flow', () => {
+    expect(getFlowOverrides('NONEXISTENT-flow')).toEqual([]);
+  });
+});
+
+describe('detectContext (edge cases)', () => {
+  it('matches case-insensitively', () => {
+    const contexts = detectContext('Build a BUTTON component', { components: [], actions: [] });
+    expect(contexts).toContain('small-component');
+  });
+
+  it('does not duplicate contexts', () => {
+    const contexts = detectContext('button and icon and badge', { components: [], actions: [] });
+    const smallCount = contexts.filter((c) => c === 'small-component').length;
+    expect(smallCount).toBe(1);
+  });
+});

package/src/flows/dispatch-registry.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Dispatch registry — colocated contract tests.
+ *
+ * Contract:
+ * - createDispatcher() returns a function that routes tool calls to facade ops
+ * - Tool names follow convention: {agentId}_{facadeName}_{opName}
+ * - Strips agent prefix, splits remaining into facade + op
+ * - Tries progressively shorter facade prefixes for multi-segment names
+ * - Falls back to params.op when tool name matches a whole facade
+ * - Returns { status: 'unregistered' } for unknown tools
+ * - Catches handler errors and returns { status: 'error' }
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createDispatcher } from './dispatch-registry.js';
+import type { FacadeConfig } from '../facades/types.js';
+
+function facade(name: string, ops: Array<{ name: string; result?: unknown }>): FacadeConfig {
+  return {
+    name,
+    description: `Test facade ${name}`,
+    ops: ops.map((o) => ({
+      name: o.name,
+      description: `op ${o.name}`,
+      auth: 'read' as const,
+      handler: vi.fn(async () => o.result ?? { ok: true }),
+    })),
+  };
+}
+
+describe('createDispatcher', () => {
+  it('routes a prefixed tool call to the correct facade op', async () => {
+    const f = facade('agent_vault', [{ name: 'search', result: { items: [] } }]);
+    const dispatch = createDispatcher('agent', [f]);
+
+    const result = await dispatch('agent_vault_search', { query: 'test' });
+
+    expect(result.status).toBe('ok');
+    expect(result.data).toEqual({ items: [] });
+    expect(result.tool).toBe('agent_vault_search');
+    expect(f.ops[0].handler).toHaveBeenCalledWith({ query: 'test' });
+  });
+
+  it('handles multi-segment facade names', async () => {
+    const f = facade('agent_design_rules', [{ name: 'get', result: { rules: [] } }]);
+    const dispatch = createDispatcher('agent', [f]);
+
+    const result = await dispatch('agent_design_rules_get', {});
+
+    expect(result.status).toBe('ok');
+    expect(result.data).toEqual({ rules: [] });
+  });
+
+  it('returns unregistered for unknown tool', async () => {
+    const dispatch = createDispatcher('agent', []);
+
+    const result = await dispatch('agent_unknown_op', {});
+
+    expect(result.status).toBe('unregistered');
+    expect(result.tool).toBe('agent_unknown_op');
+  });
+
+  it('returns unregistered for known facade but unknown op', async () => {
+    const f = facade('agent_vault', [{ name: 'search' }]);
+    const dispatch = createDispatcher('agent', [f]);
+
+    const result = await dispatch('agent_vault_nonexistent', {});
+
+    expect(result.status).toBe('unregistered');
+  });
+
+  it('catches handler errors and returns error status', async () => {
+    const f: FacadeConfig = {
+      name: 'agent_vault',
+      description: 'Vault',
+      ops: [
+        {
+          name: 'search',
+          description: 'search',
+          auth: 'read',
+          handler: vi.fn(async () => {
+            throw new Error('DB connection failed');
+          }),
+        },
+      ],
+    };
+    const dispatch = createDispatcher('agent', [f]);
+
+    const result = await dispatch('agent_vault_search', {});
+
+    expect(result.status).toBe('error');
+    expect(result.error).toBe('DB connection failed');
+  });
+
+  it('supports params.op fallback for whole-facade tool names', async () => {
+    const f = facade('agent_vault', [{ name: 'search', result: { found: true } }]);
+    const dispatch = createDispatcher('agent', [f]);
+
+    const result = await dispatch('agent_vault', { op: 'search', query: 'x' });
+
+    expect(result.status).toBe('ok');
+    expect(result.data).toEqual({ found: true });
+  });
+
+  it('routes tool names without agent prefix by prepending it', async () => {
+    const f = facade('agent_brain', [{ name: 'recommend' }]);
+    const dispatch = createDispatcher('agent', [f]);
+
+    // Tool name without agent_ prefix — dispatcher tries unprefixed path
+    // which becomes "brain_recommend", then tries facade "agent_brain" + op "recommend"
+    const result = await dispatch('brain_recommend', {});
+
+    // The dispatcher prepends the prefix internally, so it still resolves
+    expect(result.status).toBe('ok');
+  });
+
+  it('dispatches to multiple facades independently', async () => {
+    const vaultFacade = facade('agent_vault', [{ name: 'search', result: { v: 1 } }]);
+    const brainFacade = facade('agent_brain', [{ name: 'recommend', result: { b: 2 } }]);
+    const dispatch = createDispatcher('agent', [vaultFacade, brainFacade]);
+
+    const r1 = await dispatch('agent_vault_search', {});
+    const r2 = await dispatch('agent_brain_recommend', {});
+
+    expect(r1.data).toEqual({ v: 1 });
+    expect(r2.data).toEqual({ b: 2 });
+  });
+});

package/src/flows/epilogue.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Epilogue — colocated contract tests.
+ *
+ * Contract:
+ * - runEpilogue() calls capture_knowledge when vault is available
+ * - runEpilogue() calls session_capture when sessionStore is available
+ * - Returns { captured: true, sessionId } on success
+ * - Silently ignores errors from dispatch (best-effort)
+ * - Returns { captured: false } when no probes are available
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { runEpilogue } from './epilogue.js';
+import type { ProbeResults } from './types.js';
+
+function probes(overrides?: Partial<ProbeResults>): ProbeResults {
+  return {
+    vault: false,
+    brain: false,
+    designSystem: false,
+    sessionStore: false,
+    projectRules: false,
+    active: true,
+    ...overrides,
+  };
+}
+
+describe('runEpilogue', () => {
+  it('captures knowledge when vault is available', async () => {
+    const dispatch = vi.fn(async () => ({ tool: 'capture_knowledge', status: 'ok', data: {} }));
+    const result = await runEpilogue(dispatch, probes({ vault: true }), '/project', 'summary');
+
+    expect(dispatch).toHaveBeenCalledWith('capture_knowledge', expect.objectContaining({
+      title: 'Flow execution summary',
+      content: 'summary',
+      type: 'workflow',
+      projectPath: '/project',
+    }));
+    expect(result.captured).toBe(true);
+  });
+
+  it('captures session when sessionStore is available', async () => {
+    const dispatch = vi.fn(async () => ({
+      tool: 'session_capture',
+      status: 'ok',
+      data: { sessionId: 'sess-123' },
+    }));
+    const result = await runEpilogue(
+      dispatch,
+      probes({ sessionStore: true }),
+      '/project',
+      'summary',
+    );
+
+    expect(dispatch).toHaveBeenCalledWith('session_capture', expect.objectContaining({
+      summary: 'summary',
+      projectPath: '/project',
+    }));
+    expect(result.captured).toBe(true);
+    expect(result.sessionId).toBe('sess-123');
+  });
+
+  it('calls both when vault and sessionStore are available', async () => {
+    const dispatch = vi.fn(async (tool: string) => ({
+      tool,
+      status: 'ok',
+      data: tool === 'session_capture' ? { sessionId: 's-1' } : {},
+    }));
+    const result = await runEpilogue(
+      dispatch,
+      probes({ vault: true, sessionStore: true }),
+      '/p',
+      'done',
+    );
+
+    expect(dispatch).toHaveBeenCalledTimes(2);
+    expect(result.captured).toBe(true);
+    expect(result.sessionId).toBe('s-1');
+  });
+
+  it('returns captured=false when no probes are active', async () => {
+    const dispatch = vi.fn();
+    const result = await runEpilogue(dispatch, probes(), '/project', 'summary');
+
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(result.captured).toBe(false);
+    expect(result.sessionId).toBeUndefined();
+  });
+
+  it('silently ignores dispatch errors for vault capture', async () => {
+    const dispatch = vi.fn(async () => {
+      throw new Error('vault down');
+    });
+    const result = await runEpilogue(dispatch, probes({ vault: true }), '/p', 'test');
+
+    expect(result.captured).toBe(false);
+  });
+
+  it('silently ignores dispatch errors for session capture', async () => {
+    const dispatch = vi.fn(async () => {
+      throw new Error('session store down');
+    });
+    const result = await runEpilogue(dispatch, probes({ sessionStore: true }), '/p', 'test');
+
+    expect(result.captured).toBe(false);
+  });
+});

package/src/flows/executor.test.ts

@@ -0,0 +1,263 @@
+/**
+ * FlowExecutor — colocated contract tests.
+ *
+ * Contract:
+ * - execute() runs plan steps sequentially, parallel tools within a step
+ * - Gates are evaluated after each step via evaluateGate()
+ * - STOP gate halts execution and returns partial result
+ * - BRANCH gate jumps to a target step (with max iteration guard)
+ * - Tool errors are captured per-tool without aborting the step
+ * - ExecutionResult includes toolsCalled (deduplicated), stepResults, timing
+ *
+ * Lighter coverage for basic happy path (covered in __tests__/flows.test.ts).
+ * Focus: BRANCH handling, error resilience, SCORE gates, edge cases.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { FlowExecutor } from './executor.js';
+import type { OrchestrationPlan, PlanStep } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makePlan(steps: PlanStep[], overrides?: Partial<OrchestrationPlan>): OrchestrationPlan {
+  return {
+    planId: 'test-plan',
+    intent: 'BUILD',
+    flowId: 'BUILD-flow',
+    steps,
+    skipped: [],
+    epilogue: [],
+    warnings: [],
+    summary: 'Test plan',
+    estimatedTools: steps.reduce((a, s) => a + s.tools.length, 0),
+    context: {
+      intent: 'BUILD',
+      probes: {
+        vault: true,
+        brain: false,
+        designSystem: false,
+        sessionStore: true,
+        projectRules: false,
+        active: true,
+      },
+      entities: { components: [], actions: [] },
+      projectPath: '/test',
+    },
+    ...overrides,
+  };
+}
+
+function step(id: string, tools: string[], opts?: Partial<PlanStep>): PlanStep {
+  return {
+    id,
+    name: id,
+    tools,
+    parallel: false,
+    requires: [],
+    status: 'pending',
+    ...opts,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('FlowExecutor', () => {
+  describe('error resilience', () => {
+    it('captures tool error without aborting entire step', async () => {
+      const dispatch = vi.fn(async (tool: string) => {
+        if (tool === 'fail-tool') throw new Error('tool broke');
+        return { tool, status: 'ok', data: {} };
+      });
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([step('s1', ['ok-tool', 'fail-tool'])]);
+      const result = await executor.execute(plan);
+
+      // Both tools were called
+      expect(result.toolsCalled).toContain('ok-tool');
+      expect(result.toolsCalled).toContain('fail-tool');
+      // Step still completes (gate evaluation may mark it passed/failed)
+      expect(result.stepResults).toHaveLength(1);
+      expect(result.stepResults[0].toolResults['fail-tool'].status).toBe('error');
+      expect(result.stepResults[0].toolResults['fail-tool'].error).toBe('tool broke');
+    });
+
+    it('deduplicates toolsCalled', async () => {
+      const dispatch = vi.fn(async (tool: string) => ({ tool, status: 'ok', data: {} }));
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([step('s1', ['tool-a']), step('s2', ['tool-a'])]);
+      const result = await executor.execute(plan);
+
+      expect(result.toolsCalled).toEqual(['tool-a']);
+    });
+  });
+
+  describe('BRANCH gate', () => {
+    it('jumps to target step on BRANCH action', async () => {
+      const callOrder: string[] = [];
+      const dispatch = vi.fn(async (tool: string) => {
+        callOrder.push(tool);
+        return { tool, status: 'ok', data: { branch: true } };
+      });
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([
+        step('s1', ['check'], {
+          gate: {
+            type: 'BRANCH',
+            onFail: { action: 'BRANCH', goto: 's3' },
+          },
+        }),
+        step('s2', ['skipped']),
+        step('s3', ['target']),
+      ]);
+
+      const result = await executor.execute(plan);
+
+      // s1 → branch to s3, skipping s2
+      expect(callOrder).toContain('check');
+      expect(callOrder).toContain('target');
+      expect(callOrder).not.toContain('skipped');
+      expect(result.status).toBe('completed');
+    });
+
+    it('stops after MAX_BRANCH_ITERATIONS to prevent infinite loops', async () => {
+      const dispatch = vi.fn(async (tool: string) => ({
+        tool,
+        status: 'ok',
+        data: {},
+      }));
+
+      const executor = new FlowExecutor(dispatch);
+      // Create a loop: s1 branches back to s1
+      const plan = makePlan([
+        step('s1', ['loop-tool'], {
+          gate: {
+            type: 'BRANCH',
+            onFail: { action: 'BRANCH', goto: 's1' },
+          },
+        }),
+        step('s2', ['after']),
+      ]);
+
+      const result = await executor.execute(plan);
+
+      // Should eventually stop with partial status
+      expect(result.status).toBe('partial');
+      expect(dispatch).toHaveBeenCalled();
+    });
+  });
+
+  describe('SCORE gate', () => {
+    it('stops execution when score is below minimum', async () => {
+      const dispatch = vi.fn(async (tool: string) => ({
+        tool,
+        status: 'ok',
+        data: { score: 30 },
+      }));
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([
+        step('s1', ['validate'], {
+          gate: {
+            type: 'SCORE',
+            min: 80,
+            onFail: { action: 'STOP', message: 'Score too low' },
+          },
+        }),
+        step('s2', ['next']),
+      ]);
+
+      const result = await executor.execute(plan);
+
+      expect(result.status).toBe('partial');
+      expect(result.stepsCompleted).toBe(0);
+      expect(result.stepResults[0].gateResult?.action).toBe('STOP');
+    });
+
+    it('continues when score meets minimum', async () => {
+      const dispatch = vi.fn(async (tool: string) => ({
+        tool,
+        status: 'ok',
+        data: { score: 95 },
+      }));
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([
+        step('s1', ['validate'], {
+          gate: { type: 'SCORE', min: 80, onFail: { action: 'STOP' } },
+        }),
+        step('s2', ['next']),
+      ]);
+
+      const result = await executor.execute(plan);
+
+      expect(result.status).toBe('completed');
+      expect(result.stepsCompleted).toBe(2);
+    });
+  });
+
+  describe('parallel tool execution', () => {
+    it('handles mixed success/failure in parallel tools', async () => {
+      const dispatch = vi.fn(async (tool: string) => {
+        if (tool === 'bad') throw new Error('parallel fail');
+        return { tool, status: 'ok', data: {} };
+      });
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([step('s1', ['good', 'bad'], { parallel: true })]);
+      const result = await executor.execute(plan);
+
+      const toolResults = result.stepResults[0].toolResults;
+      expect(toolResults['good'].status).toBe('ok');
+      expect(toolResults['bad'].status).toBe('error');
+      expect(toolResults['bad'].error).toBe('parallel fail');
+    });
+  });
+
+  describe('result structure', () => {
+    it('includes correct timing and counts', async () => {
+      const dispatch = vi.fn(async (tool: string) => ({ tool, status: 'ok', data: {} }));
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([step('s1', ['t1']), step('s2', ['t2'])]);
+
+      const result = await executor.execute(plan);
+
+      expect(result.planId).toBe('test-plan');
+      expect(result.totalSteps).toBe(2);
+      expect(result.stepsCompleted).toBe(2);
+      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+      expect(result.stepResults).toHaveLength(2);
+      expect(result.stepResults[0].durationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('returns failed status when a step has a STOP gate that fails', async () => {
+      const dispatch = vi.fn(async (tool: string) => ({
+        tool,
+        status: 'ok',
+        data: { pass: false },
+      }));
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([
+        step('s1', ['check'], {
+          gate: {
+            type: 'GATE',
+            condition: 'pass == true',
+            onFail: { action: 'STOP', message: 'Blocked' },
+          },
+        }),
+      ]);
+
+      const result = await executor.execute(plan);
+
+      expect(result.status).toBe('partial');
+      expect(result.stepResults[0].status).toBe('failed');
+      expect(result.stepResults[0].gateResult?.message).toBe('Blocked');
+    });
+  });
+});