@soleri/core 9.0.4 → 9.3.0

package/src/flows/chain-runner.test.ts

@@ -0,0 +1,273 @@
+/**
+ * ChainRunner — colocated contract tests.
+ *
+ * Contract:
+ * - execute() runs steps sequentially, resolving $variable references between steps
+ * - Gates pause (user-approval) or fail (auto-test) execution
+ * - resume()/approve() continues from paused gate
+ * - getInstance()/list() retrieve persisted state
+ * - State persists to SQLite via PersistenceProvider
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ChainRunner, type DispatchFn } from './chain-runner.js';
+import type { ChainDef } from './chain-types.js';
+import type { PersistenceProvider } from '../persistence/types.js';
+
+// ---------------------------------------------------------------------------
+// Mock persistence provider (in-memory)
+// ---------------------------------------------------------------------------
+
+function createMockProvider(): PersistenceProvider {
+  const store = new Map<string, Record<string, unknown>>();
+
+  return {
+    backend: 'sqlite' as const,
+    execSql: vi.fn(),
+    run: vi.fn((sql: string, params?: unknown[]) => {
+      if (sql.includes('INSERT OR REPLACE') && Array.isArray(params)) {
+        store.set(params[0] as string, {
+          id: params[0],
+          chain_id: params[1],
+          chain_name: params[2],
+          status: params[3],
+          current_step: params[4],
+          paused_at_gate: params[5],
+          input: params[6],
+          context: params[7],
+          step_outputs: params[8],
+          steps_completed: params[9],
+          total_steps: params[10],
+          created_at: params[11],
+          updated_at: params[12],
+        });
+      }
+      return { changes: 1, lastInsertRowid: 1 };
+    }),
+    get: vi.fn((_sql: string, params?: unknown[]) => {
+      if (Array.isArray(params)) {
+        return store.get(params[0] as string) ?? undefined;
+      }
+      return undefined;
+    }),
+    all: vi.fn((_sql: string, _params?: unknown[]) => {
+      return [...store.values()];
+    }),
+    transaction: vi.fn((fn) => fn()),
+    ftsSearch: vi.fn(() => []),
+    ftsRebuild: vi.fn(),
+    close: vi.fn(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function twoStepChain(): ChainDef {
+  return {
+    id: 'test-chain',
+    name: 'Test Chain',
+    steps: [
+      { id: 'step-1', op: 'vault_search', params: { query: 'test' }, output: 'search' },
+      { id: 'step-2', op: 'brain_recommend', params: { context: '$search' } },
+    ],
+  };
+}
+
+function gatedChain(gate: 'user-approval' | 'auto-test'): ChainDef {
+  return {
+    id: 'gated-chain',
+    steps: [
+      { id: 'step-1', op: 'op-a', gate },
+      { id: 'step-2', op: 'op-b' },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ChainRunner', () => {
+  let provider: PersistenceProvider;
+  let runner: ChainRunner;
+
+  beforeEach(() => {
+    provider = createMockProvider();
+    runner = new ChainRunner(provider);
+  });
+
+  it('initializes the chain_instances table on construction', () => {
+    expect(provider.execSql).toHaveBeenCalledWith(
+      expect.stringContaining('CREATE TABLE IF NOT EXISTS chain_instances'),
+    );
+  });
+
+  describe('execute', () => {
+    it('runs all steps to completion', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ result: 'ok' }));
+      const instance = await runner.execute(twoStepChain(), { q: 'hello' }, dispatch);
+
+      expect(instance.status).toBe('completed');
+      expect(instance.stepsCompleted).toBe(2);
+      expect(instance.totalSteps).toBe(2);
+      expect(instance.stepOutputs).toHaveLength(2);
+    });
+
+    it('stores step results in context for $variable resolution', async () => {
+      const dispatch: DispatchFn = vi.fn(async (op) => {
+        if (op === 'vault_search') return { items: ['a', 'b'] };
+        return { recommendation: 'use-a' };
+      });
+
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      expect(instance.context['step-1']).toEqual({ items: ['a', 'b'] });
+      expect(instance.context['search']).toEqual({ items: ['a', 'b'] });
+    });
+
+    it('passes resolved $variable params to subsequent steps', async () => {
+      const dispatch: DispatchFn = vi.fn(async (op) => {
+        if (op === 'vault_search') return { found: true };
+        return {};
+      });
+
+      await runner.execute(twoStepChain(), {}, dispatch);
+
+      // Second call should have resolved $search to the first step's result
+      expect(dispatch).toHaveBeenCalledTimes(2);
+      const secondCallParams = (dispatch as ReturnType<typeof vi.fn>).mock.calls[1][1];
+      expect(secondCallParams.context).toEqual({ found: true });
+    });
+
+    it('marks instance as failed when a step throws', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => {
+        throw new Error('kaboom');
+      });
+
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      expect(instance.status).toBe('failed');
+      expect(instance.stepsCompleted).toBe(0);
+      expect(instance.stepOutputs[0].status).toBe('failed');
+    });
+
+    it('starts from a specific step when startFromStep is provided', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ ok: true }));
+      const instance = await runner.execute(twoStepChain(), {}, dispatch, undefined, 'step-2');
+
+      expect(dispatch).toHaveBeenCalledTimes(1);
+      expect(instance.stepsCompleted).toBe(1);
+    });
+
+    it('assigns input to context.input', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      const input = { url: 'https://example.com' };
+      const instance = await runner.execute(twoStepChain(), input, dispatch);
+
+      expect(instance.context['input']).toEqual(input);
+    });
+  });
+
+  describe('gates', () => {
+    it('pauses on user-approval gate', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ done: true }));
+      const instance = await runner.execute(gatedChain('user-approval'), {}, dispatch);
+
+      expect(instance.status).toBe('paused');
+      expect(instance.pausedAtGate).toBe('step-1');
+      expect(instance.stepsCompleted).toBe(1);
+      // step-2 should NOT have been called
+      expect(dispatch).toHaveBeenCalledTimes(1);
+    });
+
+    it('fails on auto-test gate when step returns error', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ error: 'bad data' }));
+      const instance = await runner.execute(gatedChain('auto-test'), {}, dispatch);
+
+      expect(instance.status).toBe('failed');
+      expect(dispatch).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes auto-test gate when step returns clean result', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ data: 'clean' }));
+      const instance = await runner.execute(gatedChain('auto-test'), {}, dispatch);
+
+      expect(instance.status).toBe('completed');
+      expect(instance.stepsCompleted).toBe(2);
+    });
+
+    it('uses custom gateCheck for vault-check gate', async () => {
+      const chain: ChainDef = {
+        id: 'vault-gated',
+        steps: [
+          { id: 's1', op: 'op-a', gate: 'vault-check' },
+          { id: 's2', op: 'op-b' },
+        ],
+      };
+      const dispatch: DispatchFn = vi.fn(async () => ({ ok: true }));
+      const gateCheck = vi.fn(async () => ({ passed: false, message: 'vault says no' }));
+
+      const instance = await runner.execute(chain, {}, dispatch, gateCheck);
+
+      expect(instance.status).toBe('failed');
+      expect(gateCheck).toHaveBeenCalledWith('vault-check', 's1', { ok: true });
+    });
+  });
+
+  describe('resume / approve', () => {
+    it('resumes a paused chain from the next step', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ ok: true }));
+      const chain = gatedChain('user-approval');
+      const paused = await runner.execute(chain, {}, dispatch);
+
+      expect(paused.status).toBe('paused');
+
+      const resumed = await runner.approve(paused.id, chain, dispatch);
+
+      expect(resumed.status).toBe('completed');
+      expect(resumed.stepsCompleted).toBe(2);
+    });
+
+    it('throws when resuming a non-existent instance', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      await expect(runner.resume('nope', twoStepChain(), dispatch)).rejects.toThrow(
+        'Chain instance not found',
+      );
+    });
+
+    it('throws when resuming a completed (non-paused) chain', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      await expect(runner.resume(instance.id, twoStepChain(), dispatch)).rejects.toThrow(
+        'not paused',
+      );
+    });
+  });
+
+  describe('getInstance / list', () => {
+    it('returns null for unknown instance', () => {
+      expect(runner.getInstance('unknown-id')).toBeNull();
+    });
+
+    it('retrieves a persisted instance by ID', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      const retrieved = runner.getInstance(instance.id);
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.chainId).toBe('test-chain');
+    });
+
+    it('lists instances ordered by updated_at', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      await runner.execute(twoStepChain(), {}, dispatch);
+      await runner.execute(twoStepChain(), {}, dispatch);
+
+      const list = runner.list();
+      expect(list.length).toBe(2);
+    });
+  });
+});

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,113 @@
+/**
+ * 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);
+  });
+});