@soleri/core 2.9.0 → 2.11.0

package/src/__tests__/deprecation.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Deprecation utility tests.
+ */
+
+import { describe, test, expect, beforeEach, vi } from 'vitest';
+import {
+  deprecationWarning,
+  wrapDeprecated,
+  resetDeprecationWarnings,
+} from '../runtime/deprecation.js';
+
+describe('deprecation utilities', () => {
+  beforeEach(() => {
+    resetDeprecationWarnings();
+    vi.restoreAllMocks();
+  });
+
+  test('logs deprecation warning to console.warn', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'old_op', since: '2.5.0' });
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy.mock.calls[0][0]).toContain('old_op');
+    expect(spy.mock.calls[0][0]).toContain('deprecated since v2.5.0');
+  });
+
+  test('includes replacement in warning', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'old_op', since: '2.5.0', replacement: 'new_op' });
+    expect(spy.mock.calls[0][0]).toContain('new_op');
+  });
+
+  test('includes removeIn in warning', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'old_op', since: '2.5.0', removeIn: '3.0.0' });
+    expect(spy.mock.calls[0][0]).toContain('v3.0.0');
+  });
+
+  test('warns only once per op', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'old_op', since: '2.5.0' });
+    deprecationWarning({ name: 'old_op', since: '2.5.0' });
+    deprecationWarning({ name: 'old_op', since: '2.5.0' });
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  test('warns separately for different ops', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'op_a', since: '2.5.0' });
+    deprecationWarning({ name: 'op_b', since: '2.5.0' });
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  test('resetDeprecationWarnings clears warned set', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    deprecationWarning({ name: 'old_op', since: '2.5.0' });
+    resetDeprecationWarnings();
+    deprecationWarning({ name: 'old_op', since: '2.5.0' });
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  test('wrapDeprecated calls original function and warns', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const original = (x: number) => x * 2;
+    const wrapped = wrapDeprecated(original, { name: 'double', since: '2.5.0' });
+    const result = wrapped(5);
+    expect(result).toBe(10);
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  test('wrapDeprecated warns only once across calls', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const wrapped = wrapDeprecated((x: number) => x, { name: 'identity', since: '2.5.0' });
+    wrapped(1);
+    wrapped(2);
+    wrapped(3);
+    expect(spy).toHaveBeenCalledOnce();
+  });
+});

package/src/__tests__/enforcement.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest';
+import { EnforcementRegistry } from '../enforcement/registry.js';
+import { ClaudeCodeAdapter } from '../enforcement/adapters/claude-code.js';
+import type { EnforcementRule } from '../enforcement/types.js';
+
+const makeRule = (overrides: Partial<EnforcementRule> = {}): EnforcementRule => ({
+  id: 'test-rule',
+  description: 'Test rule',
+  trigger: 'pre-tool-use',
+  action: 'block',
+  message: 'This is blocked',
+  ...overrides,
+});
+
+describe('EnforcementRegistry', () => {
+  it('adds and retrieves rules', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRule(makeRule({ id: 'r1' }));
+    reg.addRule(makeRule({ id: 'r2' }));
+    expect(reg.getRules()).toHaveLength(2);
+    expect(reg.getRule('r1')?.id).toBe('r1');
+  });
+
+  it('replaces rules with same ID', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRule(makeRule({ id: 'r1', message: 'old' }));
+    reg.addRule(makeRule({ id: 'r1', message: 'new' }));
+    expect(reg.getRules()).toHaveLength(1);
+    expect(reg.getRule('r1')?.message).toBe('new');
+  });
+
+  it('removes rules by ID', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRule(makeRule({ id: 'r1' }));
+    expect(reg.removeRule('r1')).toBe(true);
+    expect(reg.removeRule('r1')).toBe(false);
+    expect(reg.getRules()).toHaveLength(0);
+  });
+
+  it('filters disabled rules', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRule(makeRule({ id: 'active' }));
+    reg.addRule(makeRule({ id: 'disabled', enabled: false }));
+    expect(reg.getEnabledRules()).toHaveLength(1);
+    expect(reg.getEnabledRules()[0].id).toBe('active');
+  });
+
+  it('addRules adds multiple', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRules([makeRule({ id: 'a' }), makeRule({ id: 'b' }), makeRule({ id: 'c' })]);
+    expect(reg.getRules()).toHaveLength(3);
+  });
+
+  it('registers and lists adapters', () => {
+    const reg = new EnforcementRegistry();
+    reg.registerAdapter(new ClaudeCodeAdapter());
+    expect(reg.listAdapters()).toEqual(['claude-code']);
+    expect(reg.getAdapter('claude-code')).toBeDefined();
+  });
+
+  it('translate returns skipped when no adapter', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRule(makeRule({ id: 'r1' }));
+    const result = reg.translate('unknown-host');
+    expect(result.host).toBe('unknown-host');
+    expect(result.files).toHaveLength(0);
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0].ruleId).toBe('r1');
+  });
+
+  it('translateAll translates for all adapters', () => {
+    const reg = new EnforcementRegistry();
+    reg.addRule(makeRule());
+    reg.registerAdapter(new ClaudeCodeAdapter());
+    const results = reg.translateAll();
+    expect(results).toHaveLength(1);
+    expect(results[0].host).toBe('claude-code');
+  });
+});
+
+describe('ClaudeCodeAdapter', () => {
+  const adapter = new ClaudeCodeAdapter();
+
+  it('supports expected triggers', () => {
+    expect(adapter.supports('pre-tool-use')).toBe(true);
+    expect(adapter.supports('post-tool-use')).toBe(true);
+    expect(adapter.supports('pre-compact')).toBe(true);
+    expect(adapter.supports('session-start')).toBe(true);
+    expect(adapter.supports('pre-commit')).toBe(true);
+    expect(adapter.supports('on-save')).toBe(false);
+  });
+
+  it('translates pre-tool-use with pattern to settings.json hook', () => {
+    const result = adapter.translate({
+      rules: [makeRule({ id: 'no-console', pattern: 'console\\.log', trigger: 'pre-tool-use' })],
+    });
+    expect(result.files.length).toBeGreaterThan(0);
+    const settingsFile = result.files.find((f) => f.path.includes('settings.json'));
+    expect(settingsFile).toBeDefined();
+    const parsed = JSON.parse(settingsFile!.content);
+    expect(parsed.hooks).toHaveLength(1);
+    expect(parsed.hooks[0].event).toBe('PreToolUse');
+    expect(parsed.hooks[0].command).toContain('console\\.log');
+  });
+
+  it('translates pre-commit to hookify file', () => {
+    const result = adapter.translate({
+      rules: [makeRule({ id: 'no-debug', trigger: 'pre-commit', pattern: 'debugger' })],
+    });
+    const hookFile = result.files.find((f) => f.path.includes('hookify.no-debug'));
+    expect(hookFile).toBeDefined();
+    expect(hookFile!.content).toContain('name: no-debug');
+    expect(hookFile!.content).toContain('debugger');
+  });
+
+  it('skips unsupported triggers', () => {
+    const result = adapter.translate({
+      rules: [makeRule({ id: 'on-save-rule', trigger: 'on-save' })],
+    });
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0].ruleId).toBe('on-save-rule');
+  });
+
+  it('generates block command with exit 1', () => {
+    const result = adapter.translate({
+      rules: [makeRule({ id: 'blocker', action: 'block', pattern: 'bad-thing' })],
+    });
+    const settings = result.files.find((f) => f.path.includes('settings.json'));
+    const parsed = JSON.parse(settings!.content);
+    expect(parsed.hooks[0].command).toContain('exit 1');
+    expect(parsed.hooks[0].command).toContain('BLOCKED');
+  });
+
+  it('generates warn command without exit 1', () => {
+    const result = adapter.translate({
+      rules: [makeRule({ id: 'warner', action: 'warn', pattern: 'maybe-bad' })],
+    });
+    const settings = result.files.find((f) => f.path.includes('settings.json'));
+    const parsed = JSON.parse(settings!.content);
+    expect(parsed.hooks[0].command).toContain('WARNING');
+    expect(parsed.hooks[0].command).not.toContain('exit 1');
+  });
+
+  it('handles rules without patterns', () => {
+    const result = adapter.translate({
+      rules: [makeRule({ id: 'simple', trigger: 'session-start' })],
+    });
+    const settings = result.files.find((f) => f.path.includes('settings.json'));
+    const parsed = JSON.parse(settings!.content);
+    expect(parsed.hooks[0].event).toBe('SessionStart');
+    expect(parsed.hooks[0].command).toContain('simple');
+  });
+});

package/src/__tests__/facade-factory.test.ts

@@ -0,0 +1,271 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import type { FacadeConfig, AuthPolicy } from '../facades/types.js';
+
+import { registerFacade, registerAllFacades } from '../facades/facade-factory.js';
+
+function createTestFacade(): FacadeConfig {
+  return {
+    name: 'test_facade',
+    description: 'Test facade',
+    ops: [
+      {
+        name: 'read_op',
+        description: 'A read operation',
+        auth: 'read',
+        handler: async () => ({ status: 'ok' }),
+      },
+      {
+        name: 'write_op',
+        description: 'A write operation',
+        auth: 'write',
+        handler: async () => ({ written: true }),
+      },
+      {
+        name: 'admin_op',
+        description: 'An admin operation',
+        auth: 'admin',
+        handler: async () => ({ admin: true }),
+      },
+    ],
+  };
+}
+
+// Capture the handler registered with McpServer
+function captureHandler(
+  facade: FacadeConfig,
+  authPolicy?: () => AuthPolicy,
+): (args: { op: string; params: Record<string, unknown> }) => Promise<{
+  content: Array<{ type: string; text: string }>;
+}> {
+  let captured:
+    | ((args: { op: string; params: Record<string, unknown> }) => Promise<{
+        content: Array<{ type: string; text: string }>;
+      }>)
+    | null = null;
+  const mockServer = {
+    tool: (_name: string, _desc: string, _schema: unknown, handler: unknown) => {
+      captured = handler as typeof captured;
+    },
+  };
+  registerFacade(mockServer as never, facade, authPolicy);
+  return captured!;
+}
+
+async function callOp(
+  handler: ReturnType<typeof captureHandler>,
+  op: string,
+): Promise<{ success: boolean; error?: string; data?: unknown }> {
+  const result = await handler({ op, params: {} });
+  return JSON.parse(result.content[0].text);
+}
+
+describe('facade-factory auth enforcement', () => {
+  it('permissive mode allows all ops regardless of caller level', async () => {
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode: 'permissive',
+      callerLevel: 'read',
+    }));
+
+    const read = await callOp(handler, 'read_op');
+    const write = await callOp(handler, 'write_op');
+    const admin = await callOp(handler, 'admin_op');
+
+    expect(read.success).toBe(true);
+    expect(write.success).toBe(true);
+    expect(admin.success).toBe(true);
+  });
+
+  it('enforce mode blocks ops above caller level', async () => {
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode: 'enforce',
+      callerLevel: 'read',
+    }));
+
+    const read = await callOp(handler, 'read_op');
+    const write = await callOp(handler, 'write_op');
+    const admin = await callOp(handler, 'admin_op');
+
+    expect(read.success).toBe(true);
+    expect(write.success).toBe(false);
+    expect(write.error).toContain('requires write');
+    expect(admin.success).toBe(false);
+    expect(admin.error).toContain('requires admin');
+  });
+
+  it('enforce mode allows write caller to execute read and write ops', async () => {
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode: 'enforce',
+      callerLevel: 'write',
+    }));
+
+    const read = await callOp(handler, 'read_op');
+    const write = await callOp(handler, 'write_op');
+    const admin = await callOp(handler, 'admin_op');
+
+    expect(read.success).toBe(true);
+    expect(write.success).toBe(true);
+    expect(admin.success).toBe(false);
+  });
+
+  it('enforce mode allows admin caller to execute all ops', async () => {
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode: 'enforce',
+      callerLevel: 'admin',
+    }));
+
+    expect((await callOp(handler, 'read_op')).success).toBe(true);
+    expect((await callOp(handler, 'write_op')).success).toBe(true);
+    expect((await callOp(handler, 'admin_op')).success).toBe(true);
+  });
+
+  it('warn mode allows ops but logs warning', async () => {
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode: 'warn',
+      callerLevel: 'read',
+    }));
+
+    // Warn mode allows execution even for higher auth levels
+    const write = await callOp(handler, 'write_op');
+    expect(write.success).toBe(true);
+  });
+
+  it('no auth policy defaults to permissive', async () => {
+    const handler = captureHandler(createTestFacade());
+
+    const admin = await callOp(handler, 'admin_op');
+    expect(admin.success).toBe(true);
+  });
+
+  it('per-op overrides take precedence', async () => {
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode: 'enforce',
+      callerLevel: 'write',
+      overrides: { read_op: 'admin' }, // escalate read_op to admin
+    }));
+
+    // read_op normally requires 'read' but override says 'admin'
+    const read = await callOp(handler, 'read_op');
+    expect(read.success).toBe(false);
+    expect(read.error).toContain('requires admin');
+
+    // write_op still works at write level
+    const write = await callOp(handler, 'write_op');
+    expect(write.success).toBe(true);
+  });
+
+  it('auth policy getter is called per dispatch (mutable)', async () => {
+    let mode: AuthPolicy['mode'] = 'permissive';
+    const handler = captureHandler(createTestFacade(), () => ({
+      mode,
+      callerLevel: 'read',
+    }));
+
+    // Permissive — write op works
+    expect((await callOp(handler, 'write_op')).success).toBe(true);
+
+    // Switch to enforce at runtime
+    mode = 'enforce';
+    expect((await callOp(handler, 'write_op')).success).toBe(false);
+  });
+});
+
+describe('hot ops promotion', () => {
+  function createFacadeWithSchema(): FacadeConfig {
+    return {
+      name: 'test_facade',
+      description: 'Test facade',
+      ops: [
+        {
+          name: 'search',
+          description: 'Search knowledge',
+          auth: 'read',
+          hot: true,
+          schema: z.object({ query: z.string(), limit: z.number().optional() }),
+          handler: async (params) => ({ results: [], query: params.query }),
+        },
+        {
+          name: 'delete',
+          description: 'Delete entry',
+          auth: 'admin',
+          handler: async () => ({ deleted: true }),
+        },
+      ],
+    };
+  }
+
+  it('registers hot ops as standalone MCP tools', () => {
+    const registered: Array<{ name: string; description: string }> = [];
+    const mockServer = {
+      tool: (name: string, desc: string, _schema: unknown, _handler: unknown) => {
+        registered.push({ name, description: desc });
+      },
+    };
+
+    registerAllFacades(mockServer as never, [createFacadeWithSchema()], {
+      agentId: 'myagent',
+      hotOps: ['search'],
+    });
+
+    const names = registered.map((r) => r.name);
+    // Facade is registered
+    expect(names).toContain('test_facade');
+    // Hot op is promoted to standalone tool
+    expect(names).toContain('myagent_search');
+    // Non-hot op is NOT promoted
+    expect(names).not.toContain('myagent_delete');
+  });
+
+  it('hot flag on op definition also triggers promotion', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => {
+        registered.push(name);
+      },
+    };
+
+    registerAllFacades(mockServer as never, [createFacadeWithSchema()], {
+      agentId: 'myagent',
+    });
+
+    // op.hot = true on 'search' should promote it even without hotOps list
+    expect(registered).toContain('myagent_search');
+  });
+
+  it('hot ops execute correctly with full schema validation', async () => {
+    let capturedHandler: ((params: unknown) => Promise<unknown>) | null = null;
+    const mockServer = {
+      tool: (name: string, _desc: string, _schema: unknown, handler: unknown) => {
+        if (name === 'myagent_search') {
+          capturedHandler = handler as typeof capturedHandler;
+        }
+      },
+    };
+
+    registerAllFacades(mockServer as never, [createFacadeWithSchema()], {
+      agentId: 'myagent',
+    });
+
+    expect(capturedHandler).not.toBeNull();
+    const result = (await capturedHandler!({ query: 'test', limit: 5 })) as {
+      content: Array<{ text: string }>;
+    };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.success).toBe(true);
+    expect(parsed.data.query).toBe('test');
+  });
+
+  it('no agentId means no hot ops promoted', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => {
+        registered.push(name);
+      },
+    };
+
+    registerAllFacades(mockServer as never, [createFacadeWithSchema()]);
+
+    // Only facade, no standalone tools
+    expect(registered).toEqual(['test_facade']);
+  });
+});

package/src/__tests__/feature-flags.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FeatureFlags } from '../runtime/feature-flags.js';
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+describe('FeatureFlags', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'soleri-flags-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    // Clean up env vars
+    for (const key of Object.keys(process.env)) {
+      if (key.startsWith('SOLERI_FLAG_')) {
+        delete process.env[key];
+      }
+    }
+  });
+
+  it('initializes with built-in defaults', () => {
+    const flags = new FeatureFlags();
+    expect(flags.isEnabled('auth-enforcement')).toBe(false);
+    expect(flags.isEnabled('hot-reload')).toBe(true);
+    expect(flags.isEnabled('search-feedback')).toBe(true);
+    expect(flags.isEnabled('telemetry')).toBe(true);
+    expect(flags.isEnabled('agency-mode')).toBe(false);
+    expect(flags.isEnabled('cognee-sync')).toBe(true);
+  });
+
+  it('returns false for unknown flags', () => {
+    const flags = new FeatureFlags();
+    expect(flags.isEnabled('nonexistent-flag')).toBe(false);
+  });
+
+  it('set() changes flag value and persists to file', () => {
+    const filePath = join(tempDir, 'flags.json');
+    const flags = new FeatureFlags(filePath);
+
+    flags.set('auth-enforcement', true);
+    expect(flags.isEnabled('auth-enforcement')).toBe(true);
+
+    // Verify persisted
+    const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+    expect(data['auth-enforcement']).toBe(true);
+  });
+
+  it('loads flags from file on construction', () => {
+    const filePath = join(tempDir, 'flags.json');
+
+    // First instance sets a flag
+    const flags1 = new FeatureFlags(filePath);
+    flags1.set('auth-enforcement', true);
+    flags1.set('telemetry', false);
+
+    // Second instance loads from file
+    const flags2 = new FeatureFlags(filePath);
+    expect(flags2.isEnabled('auth-enforcement')).toBe(true);
+    expect(flags2.isEnabled('telemetry')).toBe(false);
+    // Unchanged defaults still work
+    expect(flags2.isEnabled('hot-reload')).toBe(true);
+  });
+
+  it('env vars override file and defaults', () => {
+    const filePath = join(tempDir, 'flags.json');
+    const flags1 = new FeatureFlags(filePath);
+    flags1.set('telemetry', true); // file says true
+
+    process.env.SOLERI_FLAG_TELEMETRY = 'false';
+    const flags2 = new FeatureFlags(filePath);
+    expect(flags2.isEnabled('telemetry')).toBe(false); // env wins
+  });
+
+  it('env var format: SOLERI_FLAG_AUTH_ENFORCEMENT=1', () => {
+    process.env.SOLERI_FLAG_AUTH_ENFORCEMENT = '1';
+    const flags = new FeatureFlags();
+    expect(flags.isEnabled('auth-enforcement')).toBe(true);
+  });
+
+  it('env var custom flags work', () => {
+    process.env.SOLERI_FLAG_MY_CUSTOM = 'true';
+    const flags = new FeatureFlags();
+    expect(flags.isEnabled('my-custom')).toBe(true);
+  });
+
+  it('getAll() returns all flags with metadata', () => {
+    const flags = new FeatureFlags();
+    const all = flags.getAll();
+
+    expect(all['auth-enforcement']).toEqual({
+      enabled: false,
+      description: 'Enforce auth levels in facade dispatch',
+      source: 'default',
+    });
+    expect(all['hot-reload']).toEqual({
+      enabled: true,
+      description: 'Enable hot reload of vault and config',
+      source: 'default',
+    });
+  });
+
+  it('getAll() reports env source when env var is set', () => {
+    process.env.SOLERI_FLAG_TELEMETRY = 'true';
+    const flags = new FeatureFlags();
+    const all = flags.getAll();
+    expect(all['telemetry'].source).toBe('env');
+  });
+
+  it('set() creates custom flags not in built-in list', () => {
+    const flags = new FeatureFlags();
+    flags.set('experimental-feature', true);
+    expect(flags.isEnabled('experimental-feature')).toBe(true);
+
+    const all = flags.getAll();
+    expect(all['experimental-feature'].description).toBe('Custom flag');
+    expect(all['experimental-feature'].source).toBe('runtime');
+  });
+
+  it('handles corrupt flags file gracefully', () => {
+    const filePath = join(tempDir, 'flags.json');
+    const { writeFileSync } = require('node:fs');
+    writeFileSync(filePath, 'not json!!!');
+
+    // Should not throw — falls back to defaults
+    const flags = new FeatureFlags(filePath);
+    expect(flags.isEnabled('hot-reload')).toBe(true);
+  });
+
+  it('no file path means in-memory only (no persistence)', () => {
+    const flags = new FeatureFlags();
+    flags.set('auth-enforcement', true);
+    expect(flags.isEnabled('auth-enforcement')).toBe(true);
+    // No crash, just works in-memory
+  });
+});