@soleri/core 2.4.0 → 2.5.0

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

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Vault } from '../vault/vault.js';
+import {
+  seedDefaultPlaybooks,
+  playbookDefinitionToEntry,
+  entryToPlaybookDefinition,
+} from '../playbooks/playbook-seeder.js';
+import { getAllBuiltinPlaybooks } from '../playbooks/playbook-registry.js';
+
+describe('playbookDefinitionToEntry', () => {
+  it('should convert a PlaybookDefinition to IntelligenceEntry', () => {
+    const def = getAllBuiltinPlaybooks()[0];
+    const entry = playbookDefinitionToEntry(def);
+
+    expect(entry.id).toBe(def.id);
+    expect(entry.type).toBe('playbook');
+    expect(entry.domain).toBe(def.category);
+    expect(entry.title).toBe(def.title);
+    expect(entry.severity).toBe('suggestion');
+    expect(entry.description).toBe(def.description);
+    expect(entry.example).toBe(def.steps);
+    expect(entry.why).toBe(def.expectedOutcome);
+    expect(entry.tags).toEqual(def.tags);
+  });
+
+  it('should embed the full definition in context', () => {
+    const def = getAllBuiltinPlaybooks()[0];
+    const entry = playbookDefinitionToEntry(def);
+    expect(entry.context).toContain('__PLAYBOOK_DEF__');
+    expect(entry.context).toContain('__END_DEF__');
+    expect(entry.context).toContain(def.trigger);
+  });
+});
+
+describe('entryToPlaybookDefinition', () => {
+  it('should round-trip through entry and back', () => {
+    const original = getAllBuiltinPlaybooks()[0];
+    const entry = playbookDefinitionToEntry(original);
+    const restored = entryToPlaybookDefinition(entry);
+
+    expect(restored).not.toBeNull();
+    expect(restored!.id).toBe(original.id);
+    expect(restored!.tier).toBe(original.tier);
+    expect(restored!.title).toBe(original.title);
+    expect(restored!.matchIntents).toEqual(original.matchIntents);
+    expect(restored!.matchKeywords).toEqual(original.matchKeywords);
+    expect(restored!.gates).toEqual(original.gates);
+    expect(restored!.taskTemplates).toEqual(original.taskTemplates);
+  });
+
+  it('should return null for non-playbook entry', () => {
+    const result = entryToPlaybookDefinition({
+      id: 'pat-1',
+      type: 'pattern',
+      domain: 'test',
+      title: 'Test',
+      severity: 'warning',
+      description: 'Test',
+      tags: [],
+    });
+    expect(result).toBeNull();
+  });
+
+  it('should return null for playbook entry without metadata', () => {
+    const result = entryToPlaybookDefinition({
+      id: 'pb-1',
+      type: 'playbook',
+      domain: 'test',
+      title: 'Test',
+      severity: 'suggestion',
+      description: 'Test',
+      context: 'plain text without markers',
+      tags: [],
+    });
+    expect(result).toBeNull();
+  });
+
+  it('should return null for malformed JSON in metadata', () => {
+    const result = entryToPlaybookDefinition({
+      id: 'pb-1',
+      type: 'playbook',
+      domain: 'test',
+      title: 'Test',
+      severity: 'suggestion',
+      description: 'Test',
+      context: '__PLAYBOOK_DEF__{not valid json}__END_DEF__',
+      tags: [],
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe('seedDefaultPlaybooks', () => {
+  let vault: Vault;
+
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+  });
+
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('should seed 6 built-in playbooks into empty vault', () => {
+    const result = seedDefaultPlaybooks(vault);
+    expect(result.seeded).toBe(6);
+    expect(result.skipped).toBe(0);
+    expect(result.errors).toBe(0);
+    expect(result.details).toHaveLength(6);
+    expect(result.details.every((d) => d.action === 'seeded')).toBe(true);
+
+    // Verify they're in the vault
+    const entries = vault.list({ type: 'playbook' });
+    expect(entries).toHaveLength(6);
+  });
+
+  it('should be idempotent — second call skips all', () => {
+    seedDefaultPlaybooks(vault);
+    const result = seedDefaultPlaybooks(vault);
+
+    expect(result.seeded).toBe(0);
+    expect(result.skipped).toBe(6);
+    expect(result.errors).toBe(0);
+    expect(result.details.every((d) => d.action === 'skipped')).toBe(true);
+  });
+
+  it('should not overwrite user modifications', () => {
+    // Seed first
+    seedDefaultPlaybooks(vault);
+
+    // Simulate user modifying a playbook by removing and re-adding with different content
+    const builtins = getAllBuiltinPlaybooks();
+    vault.remove(builtins[0].id);
+    vault.add({
+      id: builtins[0].id,
+      type: 'playbook',
+      domain: 'user-custom',
+      title: 'User Modified Playbook',
+      severity: 'suggestion',
+      description: 'Modified by user',
+      tags: ['custom'],
+    });
+
+    // Re-seed should skip this one
+    const result = seedDefaultPlaybooks(vault);
+    expect(result.skipped).toBe(6); // all exist, including user-modified one
+
+    // Verify user's version is preserved
+    const entry = vault.get(builtins[0].id);
+    expect(entry?.title).toBe('User Modified Playbook');
+  });
+
+  it('should report correct counts in details', () => {
+    const result = seedDefaultPlaybooks(vault);
+    const ids = result.details.map((d) => d.id);
+    expect(ids).toContain('generic-tdd');
+    expect(ids).toContain('generic-brainstorming');
+    expect(ids).toContain('generic-code-review');
+    expect(ids).toContain('generic-subagent-execution');
+    expect(ids).toContain('generic-systematic-debugging');
+    expect(ids).toContain('generic-verification');
+  });
+});

package/src/__tests__/playbook.test.ts

@@ -0,0 +1,389 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { Vault } from '../vault/vault.js';
+import { validatePlaybook, parsePlaybookFromEntry } from '../vault/playbook.js';
+import type { Playbook } from '../vault/playbook.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import { createAgentRuntime } from '../runtime/runtime.js';
+import { createCoreOps } from '../runtime/core-ops.js';
+import type { AgentRuntime, OpDefinition } from '../runtime/types.js';
+
+function makePlaybook(overrides: Partial<Playbook> = {}): Playbook {
+  return {
+    id: overrides.id ?? 'pb-1',
+    title: overrides.title ?? 'Deploy Checklist',
+    domain: overrides.domain ?? 'ops',
+    description: overrides.description ?? 'Standard deploy procedure.',
+    steps: overrides.steps ?? [
+      {
+        order: 1,
+        title: 'Run tests',
+        description: 'Execute full test suite',
+        validation: 'All tests pass',
+      },
+      { order: 2, title: 'Build', description: 'Run production build' },
+      {
+        order: 3,
+        title: 'Deploy',
+        description: 'Push to production',
+        validation: 'Health check passes',
+      },
+    ],
+    tags: overrides.tags ?? ['deploy', 'checklist'],
+    createdAt: overrides.createdAt ?? Date.now(),
+    updatedAt: overrides.updatedAt ?? Date.now(),
+  };
+}
+
+function playbookToEntry(pb: Playbook): IntelligenceEntry {
+  return {
+    id: pb.id,
+    type: 'playbook',
+    domain: pb.domain,
+    title: pb.title,
+    severity: 'suggestion',
+    description: pb.description,
+    context: JSON.stringify({ steps: pb.steps }),
+    tags: pb.tags,
+  };
+}
+
+describe('validatePlaybook', () => {
+  it('should pass for a valid playbook', () => {
+    const result = validatePlaybook(makePlaybook());
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should fail for empty title', () => {
+    const result = validatePlaybook(makePlaybook({ title: '' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Playbook title must not be empty');
+  });
+
+  it('should fail for no steps', () => {
+    const result = validatePlaybook(makePlaybook({ steps: [] }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Playbook must have at least one step');
+  });
+
+  it('should fail for non-sequential step orders', () => {
+    const result = validatePlaybook(
+      makePlaybook({
+        steps: [
+          { order: 1, title: 'Step A', description: 'Desc A' },
+          { order: 3, title: 'Step B', description: 'Desc B' },
+        ],
+      }),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes('order 3, expected 2'))).toBe(true);
+  });
+});
+
+describe('parsePlaybookFromEntry', () => {
+  it('should parse a valid playbook entry', () => {
+    const pb = makePlaybook();
+    const entry = playbookToEntry(pb);
+    const parsed = parsePlaybookFromEntry(entry);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.id).toBe(pb.id);
+    expect(parsed!.title).toBe(pb.title);
+    expect(parsed!.steps).toHaveLength(3);
+    expect(parsed!.steps[0].title).toBe('Run tests');
+  });
+
+  it('should return null for a non-playbook entry', () => {
+    const entry: IntelligenceEntry = {
+      id: 'pat-1',
+      type: 'pattern',
+      domain: 'testing',
+      title: 'Some Pattern',
+      severity: 'warning',
+      description: 'A pattern.',
+      tags: [],
+    };
+    expect(parsePlaybookFromEntry(entry)).toBeNull();
+  });
+
+  it('should return null for invalid context JSON', () => {
+    const entry: IntelligenceEntry = {
+      id: 'pb-bad',
+      type: 'playbook',
+      domain: 'ops',
+      title: 'Bad Playbook',
+      severity: 'suggestion',
+      description: 'Has bad context.',
+      context: 'not valid json',
+      tags: [],
+    };
+    expect(parsePlaybookFromEntry(entry)).toBeNull();
+  });
+
+  it('should return null when context has no steps array', () => {
+    const entry: IntelligenceEntry = {
+      id: 'pb-nosteps',
+      type: 'playbook',
+      domain: 'ops',
+      title: 'No Steps',
+      severity: 'suggestion',
+      description: 'Missing steps.',
+      context: JSON.stringify({ something: 'else' }),
+      tags: [],
+    };
+    expect(parsePlaybookFromEntry(entry)).toBeNull();
+  });
+});
+
+describe('Vault playbook integration', () => {
+  let vault: Vault;
+
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+  });
+
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('should insert and retrieve a playbook via vault.list', () => {
+    const pb = makePlaybook();
+    const entry = playbookToEntry(pb);
+    vault.seed([entry]);
+
+    const results = vault.list({ type: 'playbook' });
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toBe('pb-1');
+    expect(results[0].type).toBe('playbook');
+  });
+
+  it('should find a playbook via FTS5 search', () => {
+    const pb = makePlaybook({ title: 'Deploy Checklist Procedure' });
+    const entry = playbookToEntry(pb);
+    vault.seed([entry]);
+
+    const results = vault.search('deploy checklist');
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].entry.id).toBe(pb.id);
+  });
+});
+
+describe('playbook_create op', () => {
+  let runtime: AgentRuntime;
+  let ops: OpDefinition[];
+  let plannerDir: string;
+
+  function findOp(name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  beforeEach(() => {
+    plannerDir = join(tmpdir(), 'playbook-create-test-' + Date.now());
+    mkdirSync(plannerDir, { recursive: true });
+    runtime = createAgentRuntime({
+      agentId: 'test',
+      vaultPath: ':memory:',
+      plansPath: join(plannerDir, 'plans.json'),
+    });
+    ops = createCoreOps(runtime);
+  });
+
+  afterEach(() => {
+    runtime.close();
+    rmSync(plannerDir, { recursive: true, force: true });
+  });
+
+  it('should create a playbook and store it in the vault', async () => {
+    const result = (await findOp('playbook_create').handler({
+      title: 'PR Review',
+      domain: 'engineering',
+      description: 'Standard PR review procedure.',
+      steps: [
+        { title: 'Read diff', description: 'Review all changed files' },
+        { title: 'Run tests', description: 'Ensure CI passes', validation: 'All green' },
+        { title: 'Approve', description: 'Leave approval comment' },
+      ],
+      tags: ['review', 'pr'],
+    })) as { created: boolean; id: string; steps: number };
+
+    expect(result.created).toBe(true);
+    expect(result.steps).toBe(3);
+
+    // Verify it's in the vault
+    const entry = runtime.vault.get(result.id);
+    expect(entry).not.toBeNull();
+    expect(entry!.type).toBe('playbook');
+    expect(entry!.domain).toBe('engineering');
+
+    // Verify it parses back correctly
+    const playbook = parsePlaybookFromEntry(entry!);
+    expect(playbook).not.toBeNull();
+    expect(playbook!.steps).toHaveLength(3);
+    expect(playbook!.steps[0].order).toBe(1);
+    expect(playbook!.steps[2].order).toBe(3);
+  });
+
+  it('should reject a playbook with empty steps', async () => {
+    const result = (await findOp('playbook_create').handler({
+      title: 'Empty',
+      domain: 'test',
+      description: 'No steps.',
+      steps: [],
+      tags: [],
+    })) as { created: boolean; errors: string[] };
+
+    expect(result.created).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('should reject a playbook with empty title', async () => {
+    const result = (await findOp('playbook_create').handler({
+      title: '',
+      domain: 'test',
+      description: 'Has steps but no title.',
+      steps: [{ title: 'Step 1', description: 'Do something' }],
+      tags: [],
+    })) as { created: boolean; errors: string[] };
+
+    expect(result.created).toBe(false);
+    expect(result.errors).toContain('Playbook title must not be empty');
+  });
+
+  it('should auto-generate ID when not provided', async () => {
+    const result = (await findOp('playbook_create').handler({
+      title: 'Auto ID Test',
+      domain: 'test',
+      description: 'Should get an auto ID.',
+      steps: [{ title: 'Step', description: 'Do it' }],
+      tags: [],
+    })) as { created: boolean; id: string };
+
+    expect(result.created).toBe(true);
+    expect(result.id).toMatch(/^playbook-test-/);
+  });
+
+  it('should use provided ID when given', async () => {
+    const result = (await findOp('playbook_create').handler({
+      id: 'my-custom-id',
+      title: 'Custom ID Test',
+      domain: 'test',
+      description: 'Has a custom ID.',
+      steps: [{ title: 'Step', description: 'Do it' }],
+      tags: [],
+    })) as { created: boolean; id: string };
+
+    expect(result.created).toBe(true);
+    expect(result.id).toBe('my-custom-id');
+  });
+});
+
+describe('playbook_match op', () => {
+  let runtime: AgentRuntime;
+  let ops: OpDefinition[];
+  let plannerDir: string;
+
+  function findOp(name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  beforeEach(() => {
+    plannerDir = join(tmpdir(), 'playbook-match-test-' + Date.now());
+    mkdirSync(plannerDir, { recursive: true });
+    runtime = createAgentRuntime({
+      agentId: 'test',
+      vaultPath: ':memory:',
+      plansPath: join(plannerDir, 'plans.json'),
+    });
+    ops = createCoreOps(runtime);
+  });
+
+  afterEach(() => {
+    runtime.close();
+    rmSync(plannerDir, { recursive: true, force: true });
+  });
+
+  it('should match TDD playbook for BUILD intent', async () => {
+    const result = (await findOp('playbook_match').handler({
+      intent: 'BUILD',
+      text: 'implement a new feature',
+    })) as { playbook: { label: string } | null; genericMatch?: { id: string } };
+
+    expect(result.playbook).not.toBeNull();
+    expect(result.genericMatch?.id).toBe('generic-tdd');
+  });
+
+  it('should match debugging playbook for FIX intent', async () => {
+    const result = (await findOp('playbook_match').handler({
+      intent: 'FIX',
+      text: 'fix the broken bug',
+    })) as { playbook: { label: string } | null; genericMatch?: { id: string } };
+
+    expect(result.playbook).not.toBeNull();
+    expect(result.genericMatch?.id).toBe('generic-systematic-debugging');
+  });
+
+  it('should return null playbook for unrelated text', async () => {
+    const result = (await findOp('playbook_match').handler({
+      text: 'random unrelated xyz',
+    })) as { playbook: null };
+
+    expect(result.playbook).toBeNull();
+  });
+});
+
+describe('playbook_seed op', () => {
+  let runtime: AgentRuntime;
+  let ops: OpDefinition[];
+  let plannerDir: string;
+
+  function findOp(name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  beforeEach(() => {
+    plannerDir = join(tmpdir(), 'playbook-seed-test-' + Date.now());
+    mkdirSync(plannerDir, { recursive: true });
+    runtime = createAgentRuntime({
+      agentId: 'test',
+      vaultPath: ':memory:',
+      plansPath: join(plannerDir, 'plans.json'),
+    });
+    ops = createCoreOps(runtime);
+  });
+
+  afterEach(() => {
+    runtime.close();
+    rmSync(plannerDir, { recursive: true, force: true });
+  });
+
+  it('should seed built-in playbooks', async () => {
+    const result = (await findOp('playbook_seed').handler({})) as {
+      seeded: number;
+      skipped: number;
+      errors: number;
+    };
+
+    expect(result.seeded).toBe(6);
+    expect(result.skipped).toBe(0);
+    expect(result.errors).toBe(0);
+  });
+
+  it('should be idempotent', async () => {
+    await findOp('playbook_seed').handler({});
+    const result = (await findOp('playbook_seed').handler({})) as {
+      seeded: number;
+      skipped: number;
+    };
+
+    expect(result.seeded).toBe(0);
+    expect(result.skipped).toBe(6);
+  });
+});

package/src/__tests__/project-ops.test.ts

@@ -143,7 +143,10 @@ describe('createProjectOps', () => {
         category: 'behavior',
         text: 'Always use semantic tokens',
         priority: 10,
-      })) as { added: boolean; rule: { id: string; category: string; text: string; priority: number } };
+      })) as {
+        added: boolean;
+        rule: { id: string; category: string; text: string; priority: number };
+      };
 
       expect(addResult.added).toBe(true);
       expect(addResult.rule.category).toBe('behavior');
@@ -197,8 +200,16 @@ describe('createProjectOps', () => {
       const p1 = runtime.projectRegistry.register('/tmp/p1', 'P1');
       const p2 = runtime.projectRegistry.register('/tmp/p2', 'P2');
       runtime.projectRegistry.addRule(p1.id, { category: 'behavior', text: 'Rule A', priority: 0 });
-      runtime.projectRegistry.addRule(p1.id, { category: 'convention', text: 'Rule B', priority: 1 });
-      runtime.projectRegistry.addRule(p2.id, { category: 'preference', text: 'Rule C', priority: 0 });
+      runtime.projectRegistry.addRule(p1.id, {
+        category: 'convention',
+        text: 'Rule B',
+        priority: 1,
+      });
+      runtime.projectRegistry.addRule(p2.id, {
+        category: 'preference',
+        text: 'Rule C',
+        priority: 0,
+      });
 
       const result = (await findOp('project_list_rules').handler({})) as {
         count: number;
@@ -225,7 +236,10 @@ describe('createProjectOps', () => {
         sourceId: p1.id,
         targetId: p2.id,
         linkType: 'related',
-      })) as { linked: boolean; link: { sourceProjectId: string; targetProjectId: string; linkType: string } };
+      })) as {
+        linked: boolean;
+        link: { sourceProjectId: string; targetProjectId: string; linkType: string };
+      };
 
       expect(linkResult.linked).toBe(true);
       expect(linkResult.link.sourceProjectId).toBe(p1.id);