@soleri/core 9.0.4 → 9.3.0

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

@@ -0,0 +1,153 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Vault } from '../vault/vault.js';
+import {
+  seedDefaultPlaybooks,
+  playbookDefinitionToEntry,
+  entryToPlaybookDefinition,
+} from './playbook-seeder.js';
+import { getAllBuiltinPlaybooks } from './playbook-registry.js';
+
+describe('playbookDefinitionToEntry', () => {
+  it('maps fields correctly', () => {
+    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('embeds full definition JSON in context field', () => {
+    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('round-trips 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);
+  });
+
+  it('returns null for non-playbook type', () => {
+    expect(
+      entryToPlaybookDefinition({
+        id: 'p1',
+        type: 'pattern',
+        domain: 'test',
+        title: 'Test',
+        severity: 'warning',
+        description: 'Not a playbook',
+        tags: [],
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null when context lacks markers', () => {
+    expect(
+      entryToPlaybookDefinition({
+        id: 'p1',
+        type: 'playbook',
+        domain: 'test',
+        title: 'Test',
+        severity: 'suggestion',
+        description: 'No markers',
+        context: 'plain text',
+        tags: [],
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null for malformed JSON between markers', () => {
+    expect(
+      entryToPlaybookDefinition({
+        id: 'p1',
+        type: 'playbook',
+        domain: 'test',
+        title: 'Test',
+        severity: 'suggestion',
+        description: 'Bad JSON',
+        context: '__PLAYBOOK_DEF__{invalid__END_DEF__',
+        tags: [],
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null when JSON lacks essential fields', () => {
+    expect(
+      entryToPlaybookDefinition({
+        id: 'p1',
+        type: 'playbook',
+        domain: 'test',
+        title: 'Test',
+        severity: 'suggestion',
+        description: 'Missing fields',
+        context: '__PLAYBOOK_DEF__{"foo":"bar"}__END_DEF__',
+        tags: [],
+      }),
+    ).toBeNull();
+  });
+});
+
+describe('seedDefaultPlaybooks', () => {
+  let vault: Vault;
+
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+  });
+
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('seeds all built-in playbooks into empty vault', () => {
+    const result = seedDefaultPlaybooks(vault);
+    expect(result.seeded).toBeGreaterThanOrEqual(6);
+    expect(result.skipped).toBe(0);
+    expect(result.errors).toBe(0);
+  });
+
+  it('is idempotent — second run skips all', () => {
+    const first = seedDefaultPlaybooks(vault);
+    const second = seedDefaultPlaybooks(vault);
+    expect(second.seeded).toBe(0);
+    expect(second.skipped).toBe(first.seeded);
+  });
+
+  it('does not overwrite user-modified entries', () => {
+    seedDefaultPlaybooks(vault);
+
+    const builtins = getAllBuiltinPlaybooks();
+    vault.remove(builtins[0].id);
+    vault.add({
+      id: builtins[0].id,
+      type: 'playbook',
+      domain: 'custom',
+      title: 'User Override',
+      severity: 'suggestion',
+      description: 'Modified',
+      tags: [],
+    });
+
+    seedDefaultPlaybooks(vault);
+
+    const entry = vault.get(builtins[0].id);
+    expect(entry?.title).toBe('User Override');
+  });
+});

package/src/plugins/plugin-loader.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadPlugins, validateDependencies, sortByDependencies } from './plugin-loader.js';
+import { pluginManifestSchema } from './types.js';
+import type { LoadedPlugin, PluginManifest } from './types.js';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+let testDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = join(
+    tmpdir(),
+    `soleri-loader-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  testDirs.push(dir);
+  return dir;
+}
+
+function writePlugin(parentDir: string, id: string, manifest: Record<string, unknown>): string {
+  const dir = join(parentDir, id);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'soleri-plugin.json'), JSON.stringify(manifest));
+  return dir;
+}
+
+function makeLoaded(
+  overrides: Partial<LoadedPlugin & { manifest: Partial<PluginManifest> }> = {},
+): LoadedPlugin {
+  return {
+    manifest: pluginManifestSchema.parse({
+      id: 'test-plugin',
+      name: 'Test',
+      version: '1.0.0',
+      ...overrides.manifest,
+    }),
+    directory: overrides.directory ?? '/tmp/test',
+    provenance: overrides.provenance ?? 'global',
+  };
+}
+
+afterEach(() => {
+  for (const dir of testDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* noop */
+    }
+  }
+  testDirs = [];
+});
+
+// =============================================================================
+// loadPlugins
+// =============================================================================
+
+describe('loadPlugins — colocated', () => {
+  it('loads from multiple custom directories and deduplicates by id', () => {
+    const dir1 = makeTempDir();
+    const dir2 = makeTempDir();
+
+    writePlugin(dir1, 'alpha', { id: 'alpha', name: 'Alpha', version: '1.0.0' });
+    writePlugin(dir2, 'alpha', { id: 'alpha', name: 'Alpha v2', version: '2.0.0' });
+    writePlugin(dir2, 'beta', { id: 'beta', name: 'Beta', version: '1.0.0' });
+
+    const result = loadPlugins('test-agent', undefined, [dir1, dir2]);
+
+    expect(result.loaded).toHaveLength(2);
+    const ids = result.loaded.map((p) => p.manifest.id);
+    expect(ids).toContain('alpha');
+    expect(ids).toContain('beta');
+    // First occurrence wins
+    expect(result.loaded.find((p) => p.manifest.id === 'alpha')!.manifest.name).toBe('Alpha');
+  });
+
+  it('skips files (non-directories) inside plugin dir', () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, 'not-a-directory.txt'), 'ignore me');
+    writePlugin(dir, 'valid', { id: 'valid', name: 'Valid', version: '1.0.0' });
+
+    const result = loadPlugins('test-agent', undefined, [dir]);
+
+    expect(result.loaded).toHaveLength(1);
+    expect(result.loaded[0].manifest.id).toBe('valid');
+  });
+
+  it('returns error for directory without manifest file', () => {
+    const dir = makeTempDir();
+    mkdirSync(join(dir, 'empty-dir'), { recursive: true });
+
+    const result = loadPlugins('test-agent', undefined, [dir]);
+
+    expect(result.loaded).toHaveLength(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].error).toContain('No soleri-plugin.json');
+  });
+
+  it('returns error for invalid JSON in manifest', () => {
+    const dir = makeTempDir();
+    const pluginDir = join(dir, 'broken');
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, 'soleri-plugin.json'), '{{not json}}');
+
+    const result = loadPlugins('test-agent', undefined, [dir]);
+
+    expect(result.loaded).toHaveLength(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].error).toContain('Invalid JSON');
+  });
+
+  it('returns error for manifest failing schema validation', () => {
+    const dir = makeTempDir();
+    writePlugin(dir, 'bad', { id: 'UPPERCASE', name: '', version: 'invalid' });
+
+    const result = loadPlugins('test-agent', undefined, [dir]);
+
+    expect(result.loaded).toHaveLength(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].error).toContain('Invalid manifest');
+  });
+
+  it('handles nonexistent custom directories gracefully', () => {
+    const result = loadPlugins('test-agent', undefined, ['/nonexistent/path/xyz123']);
+
+    expect(result.loaded).toHaveLength(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('loads with project path when directory exists', () => {
+    const projectDir = makeTempDir();
+    const pluginsDir = join(projectDir, '.test-agent', 'plugins');
+    mkdirSync(pluginsDir, { recursive: true });
+    writePlugin(pluginsDir, 'project-plugin', {
+      id: 'project-plugin',
+      name: 'Project Plugin',
+      version: '1.0.0',
+    });
+
+    const result = loadPlugins('test-agent', projectDir);
+
+    expect(result.loaded).toHaveLength(1);
+    expect(result.loaded[0].manifest.id).toBe('project-plugin');
+    expect(result.loaded[0].provenance).toBe('project');
+  });
+});
+
+// =============================================================================
+// validateDependencies
+// =============================================================================
+
+describe('validateDependencies — colocated', () => {
+  it('returns empty array when all dependencies are satisfied', () => {
+    const plugins = [
+      makeLoaded({ manifest: { id: 'base' } }),
+      makeLoaded({ manifest: { id: 'child', dependencies: ['base'] } }),
+    ];
+    expect(validateDependencies(plugins)).toEqual([]);
+  });
+
+  it('detects multiple missing dependencies', () => {
+    const plugins = [makeLoaded({ manifest: { id: 'lonely', dependencies: ['dep-a', 'dep-b'] } })];
+    const errors = validateDependencies(plugins);
+    expect(errors).toHaveLength(2);
+    expect(errors.map((e) => e.missingDep)).toEqual(['dep-a', 'dep-b']);
+  });
+
+  it('handles plugins with no dependencies', () => {
+    const plugins = [makeLoaded({ manifest: { id: 'standalone' } })];
+    expect(validateDependencies(plugins)).toEqual([]);
+  });
+});
+
+// =============================================================================
+// sortByDependencies
+// =============================================================================
+
+describe('sortByDependencies — colocated', () => {
+  it('sorts three-level dependency chain correctly', () => {
+    const c = makeLoaded({ manifest: { id: 'c', dependencies: ['b'] } });
+    const b = makeLoaded({ manifest: { id: 'b', dependencies: ['a'] } });
+    const a = makeLoaded({ manifest: { id: 'a' } });
+
+    const sorted = sortByDependencies([c, b, a]);
+    const ids = sorted.map((p) => p.manifest.id);
+
+    expect(ids.indexOf('a')).toBeLessThan(ids.indexOf('b'));
+    expect(ids.indexOf('b')).toBeLessThan(ids.indexOf('c'));
+  });
+
+  it('handles circular dependency without infinite loop', () => {
+    const x = makeLoaded({ manifest: { id: 'x', dependencies: ['y'] } });
+    const y = makeLoaded({ manifest: { id: 'y', dependencies: ['x'] } });
+
+    // Should not hang or throw
+    const sorted = sortByDependencies([x, y]);
+    expect(sorted.length).toBeLessThanOrEqual(2);
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(sortByDependencies([])).toEqual([]);
+  });
+
+  it('preserves all plugins when no dependencies exist', () => {
+    const plugins = [
+      makeLoaded({ manifest: { id: 'a' } }),
+      makeLoaded({ manifest: { id: 'b' } }),
+      makeLoaded({ manifest: { id: 'c' } }),
+    ];
+    const sorted = sortByDependencies(plugins);
+    expect(sorted).toHaveLength(3);
+  });
+});

package/src/plugins/plugin-registry.test.ts

@@ -0,0 +1,284 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PluginRegistry } from './plugin-registry.js';
+import { pluginManifestSchema } from './types.js';
+import type { LoadedPlugin, PluginManifest, PluginContext } from './types.js';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function makeManifest(overrides: Partial<PluginManifest> = {}): PluginManifest {
+  return pluginManifestSchema.parse({
+    id: 'test-plugin',
+    name: 'Test Plugin',
+    version: '1.0.0',
+    ...overrides,
+  });
+}
+
+function makeLoaded(overrides: Partial<LoadedPlugin> = {}): LoadedPlugin {
+  return {
+    manifest: makeManifest(overrides.manifest as Partial<PluginManifest>),
+    directory: '/tmp/test-plugin',
+    provenance: 'global',
+    ...overrides,
+  };
+}
+
+function makeContext(plugin: LoadedPlugin): PluginContext {
+  return {
+    packRuntime: {} as PluginContext['packRuntime'],
+    runtime: {},
+    manifest: plugin.manifest,
+    directory: plugin.directory,
+  };
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('PluginRegistry — colocated', () => {
+  let registry: PluginRegistry;
+
+  beforeEach(() => {
+    registry = new PluginRegistry();
+  });
+
+  describe('register', () => {
+    it('registers a plugin and sets initial status to registered', () => {
+      const loaded = makeLoaded();
+      const registered = registry.register(loaded);
+
+      expect(registered.id).toBe('test-plugin');
+      expect(registered.status).toBe('registered');
+      expect(registered.facades).toEqual([]);
+      expect(registered.registeredAt).toBeGreaterThan(0);
+    });
+
+    it('throws when registering duplicate id', () => {
+      registry.register(makeLoaded());
+      expect(() => registry.register(makeLoaded())).toThrow('already registered');
+    });
+
+    it('registers multiple distinct plugins', () => {
+      registry.register(makeLoaded({ manifest: makeManifest({ id: 'alpha' }) }));
+      registry.register(makeLoaded({ manifest: makeManifest({ id: 'beta' }) }));
+
+      expect(registry.list()).toHaveLength(2);
+    });
+  });
+
+  describe('activate', () => {
+    it('builds static facades from manifest when no index.js exists', async () => {
+      const loaded = makeLoaded({
+        manifest: makeManifest({
+          facades: [
+            {
+              name: 'my_facade',
+              description: 'Test facade',
+              ops: [
+                { name: 'do_thing', description: 'Does a thing', auth: 'read' },
+                { name: 'admin_thing', description: 'Admin action', auth: 'admin' },
+              ],
+            },
+          ],
+        }),
+      });
+
+      registry.register(loaded);
+      const result = await registry.activate('test-plugin', makeContext(loaded));
+
+      expect(result.status).toBe('active');
+      expect(result.activatedAt).toBeGreaterThan(0);
+      expect(result.facades).toHaveLength(1);
+      expect(result.facades[0].name).toBe('my_facade');
+      expect(result.facades[0].ops).toHaveLength(2);
+      expect(result.facades[0].ops[0].name).toBe('do_thing');
+    });
+
+    it('static facade ops return error message when called', async () => {
+      const loaded = makeLoaded({
+        manifest: makeManifest({
+          facades: [
+            {
+              name: 'f',
+              description: '',
+              ops: [{ name: 'op1', description: '', auth: 'read' }],
+            },
+          ],
+        }),
+      });
+
+      registry.register(loaded);
+      const result = await registry.activate('test-plugin', makeContext(loaded));
+      const handlerResult = await result.facades[0].ops[0].handler({});
+
+      expect(handlerResult).toHaveProperty('error');
+      expect((handlerResult as { error: string }).error).toContain('static plugin op');
+    });
+
+    it('returns same plugin without re-activating when already active', async () => {
+      const loaded = makeLoaded();
+      registry.register(loaded);
+
+      const first = await registry.activate('test-plugin', makeContext(loaded));
+      const second = await registry.activate('test-plugin', makeContext(loaded));
+
+      expect(first).toBe(second);
+      expect(second.status).toBe('active');
+    });
+
+    it('throws for unregistered plugin', async () => {
+      await expect(registry.activate('ghost', makeContext(makeLoaded()))).rejects.toThrow(
+        'not registered',
+      );
+    });
+
+    it('sets error status when index.js fails to load', async () => {
+      const loaded = makeLoaded({
+        directory: '/nonexistent/path/that/has/index.js',
+        manifest: makeManifest({ id: 'broken' }),
+      });
+
+      // The activate method checks for index.js existence with existsSync,
+      // so with a nonexistent dir, it falls back to static facades (no error).
+      // This tests the static fallback path for missing directory.
+      registry.register(loaded);
+      const result = await registry.activate('broken', makeContext(loaded));
+
+      expect(result.status).toBe('active');
+      expect(result.facades).toEqual([]);
+    });
+  });
+
+  describe('deactivate', () => {
+    it('deactivates an active plugin and clears facades', async () => {
+      const loaded = makeLoaded({
+        manifest: makeManifest({
+          facades: [
+            {
+              name: 'f',
+              description: '',
+              ops: [{ name: 'op', description: '', auth: 'read' }],
+            },
+          ],
+        }),
+      });
+
+      registry.register(loaded);
+      await registry.activate('test-plugin', makeContext(loaded));
+      expect(registry.get('test-plugin')!.facades).toHaveLength(1);
+
+      const result = registry.deactivate('test-plugin');
+
+      expect(result).toBe(true);
+      expect(registry.get('test-plugin')!.status).toBe('deactivated');
+      expect(registry.get('test-plugin')!.facades).toEqual([]);
+    });
+
+    it('returns false for unknown plugin', () => {
+      expect(registry.deactivate('nonexistent')).toBe(false);
+    });
+  });
+
+  describe('unregister', () => {
+    it('removes plugin completely', () => {
+      registry.register(makeLoaded());
+      expect(registry.unregister('test-plugin')).toBe(true);
+      expect(registry.get('test-plugin')).toBeUndefined();
+      expect(registry.list()).toHaveLength(0);
+    });
+
+    it('deactivates before unregistering active plugin', async () => {
+      const loaded = makeLoaded();
+      registry.register(loaded);
+      await registry.activate('test-plugin', makeContext(loaded));
+
+      expect(registry.unregister('test-plugin')).toBe(true);
+      expect(registry.list()).toHaveLength(0);
+    });
+
+    it('returns false for unknown plugin', () => {
+      expect(registry.unregister('ghost')).toBe(false);
+    });
+  });
+
+  describe('getActiveFacades and getActiveOps', () => {
+    it('returns facades only from active plugins', async () => {
+      const active = makeLoaded({
+        manifest: makeManifest({
+          id: 'active-one',
+          facades: [
+            {
+              name: 'af',
+              description: '',
+              ops: [{ name: 'aop', description: '', auth: 'read' }],
+            },
+          ],
+        }),
+      });
+      const inactive = makeLoaded({ manifest: makeManifest({ id: 'inactive-one' }) });
+
+      registry.register(active);
+      registry.register(inactive);
+      await registry.activate('active-one', makeContext(active));
+
+      const facades = registry.getActiveFacades();
+      expect(facades).toHaveLength(1);
+      expect(facades[0].name).toBe('af');
+    });
+
+    it('returns flattened ops across multiple facades', async () => {
+      const loaded = makeLoaded({
+        manifest: makeManifest({
+          id: 'multi',
+          facades: [
+            { name: 'f1', description: '', ops: [{ name: 'a', description: '', auth: 'read' }] },
+            {
+              name: 'f2',
+              description: '',
+              ops: [
+                { name: 'b', description: '', auth: 'write' },
+                { name: 'c', description: '', auth: 'admin' },
+              ],
+            },
+          ],
+        }),
+      });
+
+      registry.register(loaded);
+      await registry.activate('multi', makeContext(loaded));
+
+      const ops = registry.getActiveOps();
+      expect(ops).toHaveLength(3);
+      expect(ops.map((o) => o.name)).toEqual(['a', 'b', 'c']);
+    });
+
+    it('returns empty when no active plugins', () => {
+      registry.register(makeLoaded());
+      expect(registry.getActiveFacades()).toEqual([]);
+      expect(registry.getActiveOps()).toEqual([]);
+    });
+  });
+
+  describe('get and list', () => {
+    it('returns undefined for unknown plugin', () => {
+      expect(registry.get('nonexistent')).toBeUndefined();
+    });
+
+    it('lists all registered plugins regardless of status', async () => {
+      const a = makeLoaded({ manifest: makeManifest({ id: 'a' }) });
+      const b = makeLoaded({ manifest: makeManifest({ id: 'b' }) });
+
+      registry.register(a);
+      registry.register(b);
+      await registry.activate('a', makeContext(a));
+
+      const list = registry.list();
+      expect(list).toHaveLength(2);
+      expect(list.find((p) => p.id === 'a')!.status).toBe('active');
+      expect(list.find((p) => p.id === 'b')!.status).toBe('registered');
+    });
+  });
+});