@kb-labs/shared-testing 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,545 @@
+import { platform } from '@kb-labs/core-runtime';
+import { ILLM, ICache, IEmbeddings, IVectorStore, IStorage, IAnalytics, ILogger, IEventBus, LLMOptions, LLMResponse, LLMMessage, LLMToolCallOptions, LLMToolCallResponse, LLMToolCall } from '@kb-labs/core-platform';
+import { HostContext, PlatformServices, UIFacade, PluginContextV3, PluginAPI, EnvironmentAPI, WorkspaceAPI, SnapshotAPI, RuntimeAPI, TraceContext } from '@kb-labs/plugin-contracts';
+
+/**
+ * @module @kb-labs/shared-testing/setup-platform
+ *
+ * Solves the "singleton gap" problem: composables (useLLM, useCache, etc.)
+ * read from the global platform singleton, but createTestContext() only
+ * populates ctx.platform. This module bridges the gap by setting test mocks
+ * directly into the global singleton.
+ */
+
+/**
+ * Options for setting up the test platform.
+ * Only adapters that are provided will be registered.
+ * Omitted adapters will use the PlatformContainer's built-in fallbacks.
+ */
+interface TestPlatformOptions {
+    llm?: ILLM;
+    cache?: ICache;
+    embeddings?: IEmbeddings;
+    vectorStore?: IVectorStore;
+    storage?: IStorage;
+    analytics?: IAnalytics;
+    logger?: ILogger;
+    eventBus?: IEventBus;
+}
+interface TestPlatformResult {
+    /** The global platform singleton (with test mocks applied) */
+    platform: typeof platform;
+    /** Call in afterEach() to reset the singleton to a clean state */
+    cleanup: () => void;
+}
+/**
+ * Setup the global platform singleton with test mocks.
+ *
+ * This ensures that useLLM(), useCache() and other composables
+ * return the test mocks instead of uninitialized/stale adapters.
+ *
+ * @example
+ * ```typescript
+ * import { setupTestPlatform, mockLLM } from '@kb-labs/shared-testing';
+ *
+ * describe('my handler', () => {
+ *   let cleanup: () => void;
+ *
+ *   beforeEach(() => {
+ *     const result = setupTestPlatform({
+ *       llm: mockLLM().onAnyComplete().respondWith('hello'),
+ *     });
+ *     cleanup = result.cleanup;
+ *   });
+ *
+ *   afterEach(() => cleanup());
+ *
+ *   it('uses LLM', async () => {
+ *     const llm = useLLM(); // Returns the test mock!
+ *     const res = await llm!.complete('test');
+ *     expect(res.content).toBe('hello');
+ *   });
+ * });
+ * ```
+ */
+declare function setupTestPlatform(options?: TestPlatformOptions): TestPlatformResult;
+
+/**
+ * @module @kb-labs/shared-testing/mock-llm
+ *
+ * LLM mock builder with fluent API and call tracking.
+ *
+ * @example
+ * ```typescript
+ * const llm = mockLLM()
+ *   .onComplete('Generate commit').respondWith('feat: add login')
+ *   .onComplete(/explain/i).respondWith('This function does X')
+ *   .onAnyComplete().respondWith('default answer');
+ *
+ * const res = await llm.complete('Generate commit message');
+ * expect(res.content).toBe('feat: add login');
+ * expect(llm.complete).toHaveBeenCalledOnce();
+ * ```
+ */
+
+/** Recorded call to complete() */
+interface LLMCall {
+    prompt: string;
+    options?: LLMOptions;
+    response: LLMResponse;
+}
+/** Recorded call to chatWithTools() */
+interface LLMToolCallRecord {
+    messages: LLMMessage[];
+    options: LLMToolCallOptions;
+    response: LLMToolCallResponse;
+}
+type PromptMatcher = string | RegExp | ((prompt: string) => boolean);
+/**
+ * Mock LLM instance with call tracking and fluent API.
+ * All methods are vi.fn() spies.
+ */
+interface MockLLMInstance extends ILLM {
+    /** All recorded complete() calls */
+    calls: LLMCall[];
+    /** Last complete() call (or undefined) */
+    lastCall: LLMCall | undefined;
+    /** All recorded chatWithTools() calls */
+    toolCalls: LLMToolCallRecord[];
+    /** Reset all recorded calls and spies */
+    resetCalls: () => void;
+}
+/** Public type returned by mockLLM() — builder fluent API + ILLM spy instance */
+interface MockLLM extends MockLLMInstance {
+    onComplete(matcher: PromptMatcher): {
+        respondWith: (response: string | LLMResponse | ((prompt: string) => string | LLMResponse)) => MockLLM;
+    };
+    onAnyComplete(): {
+        respondWith: (response: string | LLMResponse | ((prompt: string) => string | LLMResponse)) => MockLLM;
+    };
+    streaming(chunks: string[]): MockLLM;
+    failing(error: Error): MockLLM;
+    withToolCalls(calls: LLMToolCall[], content?: string): MockLLM;
+}
+/**
+ * Create a mock LLM with fluent builder API.
+ *
+ * @example
+ * ```typescript
+ * // Simple: always returns same response
+ * const llm = mockLLM();
+ *
+ * // With specific responses
+ * const llm = mockLLM()
+ *   .onComplete('generate commit').respondWith('feat: add feature')
+ *   .onComplete(/explain/i).respondWith('This code does...')
+ *   .onAnyComplete().respondWith('default');
+ *
+ * // Streaming
+ * const llm = mockLLM().streaming(['chunk1', 'chunk2', 'chunk3']);
+ *
+ * // Error simulation
+ * const llm = mockLLM().failing(new Error('rate limit exceeded'));
+ *
+ * // Tool calling
+ * const llm = mockLLM().withToolCalls([
+ *   { id: 'call-1', name: 'search', input: { query: 'test' } },
+ * ]);
+ * ```
+ */
+declare function mockLLM(): MockLLM;
+
+/**
+ * @module @kb-labs/shared-testing/mock-cache
+ *
+ * In-memory cache mock that actually stores data (unlike noop mocks).
+ * All methods are vi.fn() spies for assertion.
+ *
+ * @example
+ * ```typescript
+ * const cache = mockCache();
+ * await cache.set('key', { data: 42 }, 5000);
+ * expect(await cache.get('key')).toEqual({ data: 42 });
+ * expect(cache.set).toHaveBeenCalledWith('key', { data: 42 }, 5000);
+ * ```
+ */
+
+interface CacheEntry {
+    value: unknown;
+    expiresAt: number | null;
+}
+interface SortedSetMember {
+    score: number;
+    member: string;
+}
+/**
+ * Mock cache instance with working in-memory storage.
+ * All methods are vi.fn() spies.
+ */
+interface MockCacheInstance extends ICache {
+    /** Direct access to the internal store (for assertions) */
+    readonly store: Map<string, CacheEntry>;
+    /** Direct access to sorted sets (for assertions) */
+    readonly sortedSets: Map<string, SortedSetMember[]>;
+    /** Reset all data and spy call history */
+    reset: () => void;
+}
+/**
+ * Create a mock cache with working in-memory storage.
+ *
+ * Unlike noop mocks, this cache actually stores and retrieves data,
+ * respects TTL, and supports sorted set operations.
+ *
+ * @param initial - Optional initial data to populate the cache
+ *
+ * @example
+ * ```typescript
+ * // Empty cache
+ * const cache = mockCache();
+ *
+ * // Pre-populated cache
+ * const cache = mockCache({ 'user:1': { name: 'Alice' } });
+ *
+ * // TTL works
+ * await cache.set('temp', 'value', 100); // expires in 100ms
+ * await new Promise(r => setTimeout(r, 150));
+ * expect(await cache.get('temp')).toBeNull(); // expired
+ * ```
+ */
+declare function mockCache(initial?: Record<string, unknown>): MockCacheInstance;
+
+/**
+ * @module @kb-labs/shared-testing/mock-storage
+ *
+ * Virtual filesystem mock for IStorage interface.
+ * All methods are vi.fn() spies.
+ *
+ * @example
+ * ```typescript
+ * const storage = mockStorage({
+ *   'config.json': '{"key": "value"}',
+ *   'data/file.txt': 'hello world',
+ * });
+ *
+ * const content = await storage.read('config.json');
+ * expect(content?.toString()).toBe('{"key": "value"}');
+ * expect(storage.read).toHaveBeenCalledWith('config.json');
+ * ```
+ */
+
+/**
+ * Mock storage instance with in-memory virtual filesystem.
+ */
+interface MockStorageInstance extends IStorage {
+    /** Direct access to the virtual filesystem (for assertions) */
+    readonly files: Map<string, Buffer>;
+    /** Reset all files and spy call history */
+    reset: () => void;
+}
+/**
+ * Create a mock storage with in-memory virtual filesystem.
+ *
+ * @param initial - Optional initial files. Keys are paths, values are content (string or Buffer).
+ *
+ * @example
+ * ```typescript
+ * const storage = mockStorage({
+ *   'data.json': JSON.stringify({ items: [] }),
+ *   'binary.dat': Buffer.from([0x00, 0x01]),
+ * });
+ *
+ * // Write and read
+ * await storage.write('new.txt', Buffer.from('hello'));
+ * expect(await storage.exists('new.txt')).toBe(true);
+ *
+ * // List files
+ * const files = await storage.list('');
+ * expect(files).toContain('new.txt');
+ * ```
+ */
+declare function mockStorage(initial?: Record<string, string | Buffer>): MockStorageInstance;
+
+/**
+ * @module @kb-labs/shared-testing/mock-logger
+ *
+ * Logger mock with message recording and vi.fn() spies.
+ *
+ * @example
+ * ```typescript
+ * const logger = mockLogger();
+ * logger.info('hello', { extra: 'data' });
+ * logger.error('oops', new Error('fail'));
+ *
+ * expect(logger.messages).toEqual([
+ *   { level: 'info', msg: 'hello', meta: { extra: 'data' } },
+ *   { level: 'error', msg: 'oops', error: expect.any(Error), meta: undefined },
+ * ]);
+ * expect(logger.info).toHaveBeenCalledWith('hello', { extra: 'data' });
+ * ```
+ */
+
+/** Recorded log entry */
+interface LogEntry {
+    level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    msg: string;
+    error?: Error;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Mock logger instance with message recording.
+ */
+interface MockLoggerInstance extends ILogger {
+    /** All recorded log messages */
+    readonly messages: LogEntry[];
+    /** Reset messages and spy call history */
+    reset: () => void;
+}
+/**
+ * Create a mock logger with message recording.
+ *
+ * All log methods are vi.fn() spies. Messages are collected
+ * into a `.messages` array for easy assertion.
+ *
+ * Child loggers share the same messages array.
+ *
+ * @example
+ * ```typescript
+ * const logger = mockLogger();
+ * const child = logger.child({ module: 'auth' });
+ *
+ * child.info('user logged in');
+ * expect(logger.messages).toHaveLength(1);
+ * expect(logger.messages[0].msg).toBe('user logged in');
+ * ```
+ */
+declare function mockLogger(sharedMessages?: LogEntry[]): MockLoggerInstance;
+
+/**
+ * @module @kb-labs/shared-testing/create-test-context
+ *
+ * Enhanced test context factory that bridges ctx.platform and the global singleton.
+ *
+ * Unlike the original createTestContext() from SDK, this version:
+ * - Uses mockLLM/mockCache/mockLogger with vi.fn() spies (not noop functions)
+ * - Syncs ctx.platform adapters with the global singleton via setupTestPlatform()
+ * - Provides a cleanup function to reset the singleton in afterEach()
+ *
+ * @example
+ * ```typescript
+ * import { createTestContext, mockLLM } from '@kb-labs/shared-testing';
+ *
+ * const llm = mockLLM().onAnyComplete().respondWith('hello');
+ * const { ctx, cleanup } = createTestContext({ platform: { llm } });
+ *
+ * // Both work — ctx.platform and useLLM() return the same mock
+ * await handler.execute(ctx, args);
+ * expect(llm.complete).toHaveBeenCalled();
+ *
+ * cleanup(); // Reset singleton in afterEach
+ * ```
+ */
+
+interface CreateTestContextOptions {
+    pluginId?: string;
+    pluginVersion?: string;
+    host?: 'cli' | 'rest' | 'workflow' | 'webhook';
+    hostContext?: HostContext;
+    config?: unknown;
+    cwd?: string;
+    outdir?: string;
+    tenantId?: string;
+    signal?: AbortSignal;
+    /** Override platform services. Also synced to global singleton. */
+    platform?: Partial<PlatformServices>;
+    /** Override UI facade */
+    ui?: Partial<UIFacade>;
+    /**
+     * If true, sync platform adapters to the global singleton
+     * so that useLLM(), useCache(), etc. return the test mocks.
+     * @default true
+     */
+    syncSingleton?: boolean;
+}
+interface TestContextResult<TConfig = unknown> {
+    /** The plugin context with test mocks */
+    ctx: PluginContextV3<TConfig>;
+    /** Call in afterEach() to reset the global singleton */
+    cleanup: () => void;
+}
+declare function createMockTrace(): TraceContext;
+declare function createMockUI(): UIFacade;
+declare function createMockRuntime(): RuntimeAPI;
+declare function createMockEnvironmentAPI(): EnvironmentAPI;
+declare function createMockWorkspaceAPI(): WorkspaceAPI;
+declare function createMockSnapshotAPI(): SnapshotAPI;
+declare function createInfraApiMocks(): Pick<PluginAPI, 'environment' | 'workspace' | 'snapshot'>;
+declare function createMockPluginAPI(): PluginAPI;
+declare const createMockPlatformApi: typeof createMockPluginAPI;
+declare function createMockPluginContextV3<TConfig = unknown>(options?: CreateTestContextOptions): TestContextResult<TConfig>;
+/**
+ * Create a test context for plugin development.
+ *
+ * Unlike the original SDK version, this:
+ * - Uses mock builders with vi.fn() spies (not noop functions)
+ * - Syncs platform adapters to the global singleton by default
+ * - Returns a cleanup function for afterEach()
+ *
+ * @example
+ * ```typescript
+ * import { createTestContext, mockLLM } from '@kb-labs/shared-testing';
+ *
+ * describe('my handler', () => {
+ *   let cleanup: () => void;
+ *
+ *   beforeEach(() => {
+ *     const llm = mockLLM().onAnyComplete().respondWith('ok');
+ *     const result = createTestContext({ platform: { llm } });
+ *     cleanup = result.cleanup;
+ *     // Use result.ctx in your tests
+ *   });
+ *
+ *   afterEach(() => cleanup());
+ * });
+ * ```
+ */
+declare function createTestContext<TConfig = unknown>(options?: CreateTestContextOptions): TestContextResult<TConfig>;
+
+/**
+ * @module @kb-labs/shared-testing/test-command
+ *
+ * Single-function test runner for plugin command handlers.
+ *
+ * Eliminates boilerplate: no manual context creation, no descriptor setup,
+ * no mock wiring. Import your handler, call testCommand(), assert on result.
+ *
+ * @example
+ * ```typescript
+ * import { testCommand, mockLLM } from '@kb-labs/shared-testing';
+ * import handler from '../src/commands/greet.js';
+ *
+ * it('greets the user', async () => {
+ *   const result = await testCommand(handler, {
+ *     flags: { name: 'Alice' },
+ *   });
+ *
+ *   expect(result.exitCode).toBe(0);
+ *   expect(result.result).toEqual({ message: 'Hello, Alice!' });
+ *   expect(result.ui.success).toHaveBeenCalledWith('Hello, Alice!');
+ * });
+ * ```
+ */
+
+/**
+ * Any handler that has an execute(ctx, input) method.
+ * Covers CommandHandlerV3, RouteHandler, Handler, and raw objects.
+ */
+interface TestableHandler<TConfig = unknown, TInput = unknown, TResult = unknown> {
+    execute(context: PluginContextV3<TConfig>, input: TInput): Promise<TResult> | TResult;
+    cleanup?(): Promise<void> | void;
+}
+/**
+ * Options for testCommand().
+ *
+ * Provide only what you need — everything else gets sensible defaults.
+ */
+interface TestCommandOptions<TConfig = unknown> {
+    /** CLI flags (sugar for input: { flags, argv }) */
+    flags?: Record<string, unknown>;
+    /** CLI positional arguments (default: []) */
+    argv?: string[];
+    /** REST query params (sugar for input: { query }) */
+    query?: Record<string, unknown>;
+    /** REST request body (sugar for input: { body }) */
+    body?: unknown;
+    /** REST route params (sugar for input: { params }) */
+    params?: Record<string, unknown>;
+    /**
+     * Raw input object. If provided, flags/argv/query/body/params are ignored.
+     * Use this when your handler expects a custom input shape.
+     */
+    input?: unknown;
+    /** Host type (default: 'cli') */
+    host?: 'cli' | 'rest' | 'workflow' | 'webhook';
+    /** Plugin config passed as ctx.config */
+    config?: TConfig;
+    /** Working directory (default: process.cwd()) */
+    cwd?: string;
+    /** Tenant ID */
+    tenantId?: string;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Override platform services (e.g., { llm: mockLLM().onAnyComplete().respondWith('ok') }) */
+    platform?: Partial<PlatformServices>;
+    /** Override UI facade (individual methods are merged with default spy UI) */
+    ui?: Partial<UIFacade>;
+    /**
+     * Sync platform mocks to global singleton for composables (useLLM, useCache, etc.)
+     * @default true
+     */
+    syncSingleton?: boolean;
+}
+/**
+ * Result of testCommand() — everything you need for assertions.
+ */
+interface TestCommandResult<TResult = unknown> {
+    /** Exit code from CommandResult (0 = success). Defaults to 0 if handler returns raw data. */
+    exitCode: number;
+    /** The result data from the handler */
+    result: TResult | undefined;
+    /** Custom metadata from CommandResult.meta */
+    meta: Record<string, unknown> | undefined;
+    /** The raw return value from handler.execute() — useful for non-CommandResult handlers */
+    raw: unknown;
+    /** UI facade with vi.fn() spies — assert on ui.success, ui.error, etc. */
+    ui: UIFacade;
+    /** The full context that was passed to the handler */
+    ctx: PluginContextV3;
+    /** Call in afterEach() to reset the global platform singleton */
+    cleanup: () => void;
+}
+/**
+ * Test a plugin command handler with minimal boilerplate.
+ *
+ * Creates a test context, builds the input object, calls handler.execute(),
+ * and returns a result with UI spies for assertions.
+ *
+ * @example CLI command
+ * ```typescript
+ * import handler from '../src/commands/greet.js';
+ *
+ * const result = await testCommand(handler, {
+ *   flags: { name: 'Alice' },
+ * });
+ * expect(result.exitCode).toBe(0);
+ * expect(result.ui.success).toHaveBeenCalledWith('Hello, Alice!');
+ * ```
+ *
+ * @example REST handler
+ * ```typescript
+ * import handler from '../src/routes/create-plan.js';
+ *
+ * const result = await testCommand(handler, {
+ *   host: 'rest',
+ *   body: { name: 'v2.0' },
+ *   query: { workspace: 'root' },
+ * });
+ * expect(result.result).toMatchObject({ name: 'v2.0' });
+ * ```
+ *
+ * @example With LLM mock
+ * ```typescript
+ * import { testCommand, mockLLM } from '@kb-labs/shared-testing';
+ * import handler from '../src/commands/analyze.js';
+ *
+ * const llm = mockLLM().onAnyComplete().respondWith('looks good');
+ * const result = await testCommand(handler, {
+ *   flags: { file: 'index.ts' },
+ *   platform: { llm },
+ * });
+ * expect(llm.complete).toHaveBeenCalled();
+ * expect(result.exitCode).toBe(0);
+ * ```
+ */
+declare function testCommand<TResult = unknown, TConfig = unknown>(handler: TestableHandler<TConfig, any, any>, options?: TestCommandOptions<TConfig>): Promise<TestCommandResult<TResult>>;
+
+export { type CreateTestContextOptions, type LLMCall, type LLMToolCallRecord, type LogEntry, type MockCacheInstance, type MockLLM, type MockLLMInstance, type MockLoggerInstance, type MockStorageInstance, type TestCommandOptions, type TestCommandResult, type TestContextResult, type TestPlatformOptions, type TestPlatformResult, type TestableHandler, createInfraApiMocks, createMockEnvironmentAPI, createMockPlatformApi, createMockPluginAPI, createMockPluginContextV3, createMockRuntime, createMockSnapshotAPI, createMockTrace, createMockUI, createMockWorkspaceAPI, createTestContext, mockCache, mockLLM, mockLogger, mockStorage, setupTestPlatform, testCommand };