@kb-labs/shared 1.1.0

package/packages/shared-testing/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kb-labs/shared-testing",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Test utilities for KB Labs plugin development — mock builders, platform setup, test context",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix"
+  },
+  "dependencies": {
+    "@kb-labs/core-platform": "link:../../../kb-labs-core/packages/core-platform",
+    "@kb-labs/core-runtime": "link:../../../kb-labs-core/packages/core-runtime",
+    "@kb-labs/plugin-contracts": "link:../../../../infra/kb-labs-plugin/packages/plugin-contracts",
+    "vitest": "^3.2.4"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.11.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/shared-testing/src/__tests__/create-test-context.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { platform, resetPlatform } from '@kb-labs/core-runtime';
+import { createTestContext } from '../create-test-context.js';
+import { mockLLM } from '../mock-llm.js';
+import { mockCache } from '../mock-cache.js';
+
+describe('createTestContext', () => {
+  afterEach(() => {
+    resetPlatform();
+  });
+
+  describe('basic creation', () => {
+    it('should create context with default values', () => {
+      const { ctx, cleanup } = createTestContext();
+      cleanup();
+
+      expect(ctx.pluginId).toBe('test-plugin');
+      expect(ctx.pluginVersion).toBe('0.0.0');
+      expect(ctx.host).toBe('cli');
+      expect(ctx.requestId).toBe('test-trace:test-span');
+    });
+
+    it('should accept custom pluginId and host', () => {
+      const { ctx, cleanup } = createTestContext({
+        pluginId: 'my-plugin',
+        host: 'rest',
+      });
+      cleanup();
+
+      expect(ctx.pluginId).toBe('my-plugin');
+      expect(ctx.host).toBe('rest');
+    });
+
+    it('should accept custom config', () => {
+      const { ctx, cleanup } = createTestContext<{ apiKey: string }>({
+        config: { apiKey: 'test-key' },
+      });
+      cleanup();
+
+      expect(ctx.config!.apiKey).toBe('test-key');
+    });
+  });
+
+  describe('singleton sync', () => {
+    it('should sync platform adapters to global singleton by default', () => {
+      const llm = mockLLM().onAnyComplete().respondWith('synced');
+      const { ctx, cleanup } = createTestContext({ platform: { llm } });
+
+      // ctx.platform has the mock
+      expect(ctx.platform.llm).toBe(llm);
+
+      // Global singleton also has the mock
+      expect(platform.llm).toBe(llm);
+
+      cleanup();
+    });
+
+    it('should not sync when syncSingleton is false', () => {
+      const llm = mockLLM();
+      const { ctx, cleanup } = createTestContext({
+        platform: { llm },
+        syncSingleton: false,
+      });
+
+      // ctx.platform has the mock
+      expect(ctx.platform.llm).toBe(llm);
+
+      // Global singleton should NOT have it (it was reset before the test)
+      expect(platform.hasAdapter('llm')).toBe(false);
+
+      cleanup();
+    });
+
+    it('cleanup should reset the global singleton', () => {
+      const llm = mockLLM();
+      const { cleanup } = createTestContext({ platform: { llm } });
+
+      expect(platform.hasAdapter('llm')).toBe(true);
+
+      cleanup();
+
+      expect(platform.hasAdapter('llm')).toBe(false);
+    });
+  });
+
+  describe('default mocks are spies', () => {
+    it('should provide LLM with vi.fn() spies', async () => {
+      const { ctx, cleanup } = createTestContext();
+
+      await ctx.platform.llm.complete('test');
+      expect(ctx.platform.llm.complete).toHaveBeenCalledWith('test');
+
+      cleanup();
+    });
+
+    it('should provide cache with vi.fn() spies', async () => {
+      const { ctx, cleanup } = createTestContext();
+
+      await ctx.platform.cache.set('key', 'value');
+      expect(ctx.platform.cache.set).toHaveBeenCalledWith('key', 'value');
+
+      cleanup();
+    });
+
+    it('should provide UI with vi.fn() spies', () => {
+      const { ctx, cleanup } = createTestContext();
+
+      ctx.ui.info('test message');
+      expect(ctx.ui.info).toHaveBeenCalledWith('test message');
+
+      cleanup();
+    });
+
+    it('should provide runtime with vi.fn() spies', async () => {
+      const { ctx, cleanup } = createTestContext();
+
+      await ctx.runtime.fs.readFile('test.txt');
+      expect(ctx.runtime.fs.readFile).toHaveBeenCalledWith('test.txt');
+
+      cleanup();
+    });
+
+    it('should provide plugin API with vi.fn() spies', async () => {
+      const { ctx, cleanup } = createTestContext();
+
+      await ctx.api.state.set('key', 'value');
+      expect(ctx.api.state.set).toHaveBeenCalledWith('key', 'value');
+
+      cleanup();
+    });
+
+    it('should provide environment/workspace/snapshot APIs by default', async () => {
+      const { ctx, cleanup } = createTestContext();
+
+      const workspace = await ctx.api.workspace.materialize({ sourceRef: 'repo://main' });
+      const environment = await ctx.api.environment.create({ templateId: 'node20' });
+      const snapshot = await ctx.api.snapshot.capture({ workspaceId: workspace.workspaceId });
+
+      expect(workspace.workspaceId).toBeDefined();
+      expect(environment.environmentId).toBeDefined();
+      expect(snapshot.snapshotId).toBeDefined();
+      expect(ctx.api.workspace.materialize).toHaveBeenCalled();
+      expect(ctx.api.environment.create).toHaveBeenCalled();
+      expect(ctx.api.snapshot.capture).toHaveBeenCalled();
+
+      cleanup();
+    });
+  });
+
+  describe('platform overrides', () => {
+    it('should use custom LLM mock', async () => {
+      const llm = mockLLM()
+        .onComplete('generate').respondWith('custom response');
+
+      const { ctx, cleanup } = createTestContext({ platform: { llm } });
+
+      const res = await ctx.platform.llm.complete('generate commit');
+      expect(res.content).toBe('custom response');
+
+      cleanup();
+    });
+
+    it('should use custom cache mock', async () => {
+      const cache = mockCache({ 'pre': 'loaded' });
+      const { ctx, cleanup } = createTestContext({ platform: { cache } });
+
+      expect(await ctx.platform.cache.get('pre')).toBe('loaded');
+
+      cleanup();
+    });
+  });
+
+  describe('host contexts', () => {
+    it('should generate CLI host context by default', () => {
+      const { ctx, cleanup } = createTestContext({ host: 'cli' });
+      expect(ctx.hostContext).toEqual({ host: 'cli', argv: ['test'], flags: {} });
+      cleanup();
+    });
+
+    it('should generate REST host context', () => {
+      const { ctx, cleanup } = createTestContext({ host: 'rest' });
+      expect(ctx.hostContext.host).toBe('rest');
+      cleanup();
+    });
+
+    it('should generate workflow host context', () => {
+      const { ctx, cleanup } = createTestContext({ host: 'workflow' });
+      expect(ctx.hostContext.host).toBe('workflow');
+      cleanup();
+    });
+
+    it('should accept custom host context', () => {
+      const custom = { host: 'cli' as const, argv: ['custom'], flags: { verbose: true } };
+      const { ctx, cleanup } = createTestContext({ hostContext: custom });
+      expect(ctx.hostContext).toEqual(custom);
+      cleanup();
+    });
+  });
+});

package/packages/shared-testing/src/__tests__/mock-cache.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect } from 'vitest';
+import { mockCache } from '../mock-cache.js';
+
+describe('mockCache', () => {
+  describe('basic operations', () => {
+    it('should store and retrieve values', async () => {
+      const cache = mockCache();
+      await cache.set('key', { name: 'Alice' });
+
+      const result = await cache.get<{ name: string }>('key');
+      expect(result).toEqual({ name: 'Alice' });
+    });
+
+    it('should return null for missing keys', async () => {
+      const cache = mockCache();
+      expect(await cache.get('missing')).toBeNull();
+    });
+
+    it('should delete values', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'value');
+      await cache.delete('key');
+      expect(await cache.get('key')).toBeNull();
+    });
+
+    it('should clear all values', async () => {
+      const cache = mockCache();
+      await cache.set('a', 1);
+      await cache.set('b', 2);
+      await cache.clear();
+      expect(await cache.get('a')).toBeNull();
+      expect(await cache.get('b')).toBeNull();
+    });
+
+    it('should clear by prefix pattern', async () => {
+      const cache = mockCache();
+      await cache.set('user:1', 'Alice');
+      await cache.set('user:2', 'Bob');
+      await cache.set('post:1', 'Hello');
+
+      await cache.clear('user:*');
+
+      expect(await cache.get('user:1')).toBeNull();
+      expect(await cache.get('user:2')).toBeNull();
+      expect(await cache.get('post:1')).toBe('Hello');
+    });
+  });
+
+  describe('TTL', () => {
+    it('should expire entries after TTL', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'value', 50); // 50ms TTL
+
+      // Still alive
+      expect(await cache.get('key')).toBe('value');
+
+      // Wait for expiry
+      await new Promise(r => { setTimeout(r, 100); });
+      expect(await cache.get('key')).toBeNull();
+    });
+
+    it('should not expire entries without TTL', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'value'); // no TTL
+
+      await new Promise(r => { setTimeout(r, 50); });
+      expect(await cache.get('key')).toBe('value');
+    });
+  });
+
+  describe('setIfNotExists', () => {
+    it('should set value if key does not exist', async () => {
+      const cache = mockCache();
+      const result = await cache.setIfNotExists('key', 'value');
+      expect(result).toBe(true);
+      expect(await cache.get('key')).toBe('value');
+    });
+
+    it('should not overwrite existing value', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'original');
+      const result = await cache.setIfNotExists('key', 'new');
+      expect(result).toBe(false);
+      expect(await cache.get('key')).toBe('original');
+    });
+  });
+
+  describe('sorted sets', () => {
+    it('should add and retrieve by score range', async () => {
+      const cache = mockCache();
+      await cache.zadd('myset', 1, 'a');
+      await cache.zadd('myset', 3, 'c');
+      await cache.zadd('myset', 2, 'b');
+
+      const result = await cache.zrangebyscore('myset', 1, 2);
+      expect(result).toEqual(['a', 'b']);
+    });
+
+    it('should remove members', async () => {
+      const cache = mockCache();
+      await cache.zadd('myset', 1, 'a');
+      await cache.zadd('myset', 2, 'b');
+
+      await cache.zrem('myset', 'a');
+
+      const result = await cache.zrangebyscore('myset', 0, 10);
+      expect(result).toEqual(['b']);
+    });
+
+    it('should update score for existing member', async () => {
+      const cache = mockCache();
+      await cache.zadd('myset', 1, 'a');
+      await cache.zadd('myset', 5, 'a'); // update score
+
+      const result = await cache.zrangebyscore('myset', 4, 6);
+      expect(result).toEqual(['a']);
+    });
+  });
+
+  describe('initial data', () => {
+    it('should accept pre-populated data', async () => {
+      const cache = mockCache({
+        'user:1': { name: 'Alice' },
+        'config': 'debug',
+      });
+
+      expect(await cache.get('user:1')).toEqual({ name: 'Alice' });
+      expect(await cache.get('config')).toBe('debug');
+    });
+  });
+
+  describe('spy tracking', () => {
+    it('all methods should be vi.fn() spies', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'value');
+      await cache.get('key');
+
+      expect(cache.set).toHaveBeenCalledWith('key', 'value');
+      expect(cache.get).toHaveBeenCalledWith('key');
+    });
+  });
+
+  describe('internal state access', () => {
+    it('should expose .store for assertions', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'value');
+
+      expect(cache.store.size).toBe(1);
+      expect(cache.store.has('key')).toBe(true);
+    });
+
+    it('should expose .sortedSets for assertions', async () => {
+      const cache = mockCache();
+      await cache.zadd('myset', 1, 'a');
+
+      expect(cache.sortedSets.size).toBe(1);
+      expect(cache.sortedSets.get('myset')).toHaveLength(1);
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear all data and spy history', async () => {
+      const cache = mockCache();
+      await cache.set('key', 'value');
+      await cache.zadd('myset', 1, 'a');
+
+      cache.reset();
+
+      expect(cache.store.size).toBe(0);
+      expect(cache.sortedSets.size).toBe(0);
+      expect(cache.set).not.toHaveBeenCalled();
+    });
+  });
+});

package/packages/shared-testing/src/__tests__/mock-llm.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect } from 'vitest';
+import { mockLLM } from '../mock-llm.js';
+
+describe('mockLLM', () => {
+  describe('basic usage', () => {
+    it('should return default response', async () => {
+      const llm = mockLLM();
+      const res = await llm.complete('hello');
+
+      expect(res.content).toBe('mock response');
+      expect(res.model).toBe('mock');
+      expect(res.usage).toEqual({ promptTokens: 0, completionTokens: 0 });
+    });
+
+    it('should track calls with vi.fn() spy', async () => {
+      const llm = mockLLM();
+      await llm.complete('hello');
+      await llm.complete('world');
+
+      expect(llm.complete).toHaveBeenCalledTimes(2);
+      expect(llm.complete).toHaveBeenCalledWith('hello');
+      expect(llm.complete).toHaveBeenCalledWith('world');
+    });
+
+    it('should record calls in .calls array', async () => {
+      const llm = mockLLM();
+      await llm.complete('hello');
+
+      expect(llm.calls).toHaveLength(1);
+      expect(llm.calls[0]!.prompt).toBe('hello');
+      expect(llm.calls[0]!.response.content).toBe('mock response');
+    });
+
+    it('should expose lastCall', async () => {
+      const llm = mockLLM();
+      await llm.complete('first');
+      await llm.complete('second');
+
+      expect(llm.lastCall?.prompt).toBe('second');
+    });
+  });
+
+  describe('onComplete() with string matcher', () => {
+    it('should match substring and return specific response', async () => {
+      const llm = mockLLM()
+        .onComplete('commit').respondWith('feat: add feature')
+        .onAnyComplete().respondWith('default');
+
+      const res1 = await llm.complete('Generate commit message');
+      expect(res1.content).toBe('feat: add feature');
+
+      const res2 = await llm.complete('something else');
+      expect(res2.content).toBe('default');
+    });
+  });
+
+  describe('onComplete() with regex matcher', () => {
+    it('should match regex pattern', async () => {
+      const llm = mockLLM()
+        .onComplete(/explain/i).respondWith('This code does X');
+
+      const res = await llm.complete('Please explain this function');
+      expect(res.content).toBe('This code does X');
+    });
+  });
+
+  describe('onComplete() with function matcher', () => {
+    it('should use custom matcher function', async () => {
+      const llm = mockLLM()
+        .onComplete((p) => p.length > 100).respondWith('long prompt handled');
+
+      const shortRes = await llm.complete('short');
+      expect(shortRes.content).toBe('mock response'); // default
+
+      const longRes = await llm.complete('a'.repeat(101));
+      expect(longRes.content).toBe('long prompt handled');
+    });
+  });
+
+  describe('onComplete() with function response', () => {
+    it('should accept a response factory function', async () => {
+      const llm = mockLLM()
+        .onAnyComplete().respondWith((prompt) => `Echo: ${prompt}`);
+
+      const res = await llm.complete('hello');
+      expect(res.content).toBe('Echo: hello');
+    });
+  });
+
+  describe('onComplete() with LLMResponse object', () => {
+    it('should accept full LLMResponse', async () => {
+      const llm = mockLLM()
+        .onAnyComplete().respondWith({
+          content: 'custom',
+          usage: { promptTokens: 10, completionTokens: 5 },
+          model: 'gpt-4',
+        });
+
+      const res = await llm.complete('test');
+      expect(res.content).toBe('custom');
+      expect(res.usage.promptTokens).toBe(10);
+      expect(res.model).toBe('gpt-4');
+    });
+  });
+
+  describe('onAnyComplete()', () => {
+    it('should set default response', async () => {
+      const llm = mockLLM()
+        .onAnyComplete().respondWith('always this');
+
+      const res = await llm.complete('anything');
+      expect(res.content).toBe('always this');
+    });
+  });
+
+  describe('rule priority', () => {
+    it('should match first matching rule', async () => {
+      const llm = mockLLM()
+        .onComplete('commit').respondWith('first')
+        .onComplete('commit').respondWith('second');
+
+      const res = await llm.complete('commit');
+      expect(res.content).toBe('first');
+    });
+  });
+
+  describe('streaming', () => {
+    it('should yield configured chunks', async () => {
+      const llm = mockLLM().streaming(['hello', ' ', 'world']);
+
+      const chunks: string[] = [];
+      for await (const chunk of llm.stream('test')) {
+        chunks.push(chunk);
+      }
+
+      expect(chunks).toEqual(['hello', ' ', 'world']);
+      expect(llm.stream).toHaveBeenCalledWith('test');
+    });
+  });
+
+  describe('failing', () => {
+    it('should throw on complete()', async () => {
+      const error = new Error('rate limit exceeded');
+      const llm = mockLLM().failing(error);
+
+      await expect(llm.complete('test')).rejects.toThrow('rate limit exceeded');
+    });
+
+    it('should throw on stream()', async () => {
+      const llm = mockLLM().failing(new Error('down'));
+
+      await expect(async () => {
+        for await (const _ of llm.stream('test')) { /* consume */ }
+      }).rejects.toThrow('down');
+    });
+
+    it('should throw on chatWithTools()', async () => {
+      const llm = mockLLM().failing(new Error('fail'));
+
+      await expect(
+        llm.chatWithTools!(
+          [{ role: 'user', content: 'test' }],
+          { tools: [] },
+        ),
+      ).rejects.toThrow('fail');
+    });
+  });
+
+  describe('chatWithTools', () => {
+    it('should return configured tool calls', async () => {
+      const llm = mockLLM().withToolCalls([
+        { id: 'call-1', name: 'search', input: { query: 'test' } },
+      ]);
+
+      const res = await llm.chatWithTools!(
+        [{ role: 'user', content: 'find something' }],
+        { tools: [{ name: 'search', description: 'Search', inputSchema: {} }] },
+      );
+
+      expect(res.toolCalls).toHaveLength(1);
+      expect(res.toolCalls![0]!.name).toBe('search');
+      expect(res.toolCalls![0]!.input).toEqual({ query: 'test' });
+    });
+
+    it('should record tool call history', async () => {
+      const llm = mockLLM();
+      await llm.chatWithTools!(
+        [{ role: 'user', content: 'test' }],
+        { tools: [] },
+      );
+
+      expect(llm.toolCalls).toHaveLength(1);
+      expect(llm.toolCalls[0]!.messages[0]!.content).toBe('test');
+    });
+  });
+
+  describe('resetCalls', () => {
+    it('should clear all recorded calls and spies', async () => {
+      const llm = mockLLM();
+      await llm.complete('test');
+
+      expect(llm.calls).toHaveLength(1);
+      expect(llm.complete).toHaveBeenCalledOnce();
+
+      llm.resetCalls();
+
+      expect(llm.calls).toHaveLength(0);
+      expect(llm.complete).not.toHaveBeenCalled();
+      expect(llm.lastCall).toBeUndefined();
+    });
+  });
+});