@kb-labs/shared-testing-platform 2.96.0

package/README.md

@@ -0,0 +1,20 @@
+# @kb-labs/shared-testing-platform
+
+Platform setup utilities for testing KB Labs plugins.
+
+Requires `@kb-labs/core-runtime` (concrete implementation). For pure mocks only, use `@kb-labs/shared-testing`.
+
+## Usage
+
+```typescript
+import { createTestContext, testCommand, mockLLM } from '@kb-labs/sdk/testing';
+
+const llm = mockLLM().onAnyComplete().respondWith('hello');
+const { ctx, cleanup } = createTestContext({ platform: { llm } });
+```
+
+## Exports
+
+- `setupTestPlatform` — sets test mocks into the global platform singleton
+- `createTestContext` — factory for `PluginContextV3` with injected mocks
+- `testCommand` — single-function runner for plugin command handlers

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import { platform } from '@kb-labs/core-runtime';
+import { ILLM, ICache, IEmbeddings, IVectorStore, IStorage, IAnalytics, ILogger, IEventBus } from '@kb-labs/core-platform';
+import { HostContext, PlatformServices, UIFacade, PluginContextV3, PluginAPI, EnvironmentAPI, RuntimeAPI, SnapshotAPI, TraceContext, WorkspaceAPI } from '@kb-labs/plugin-contracts';
+import { IDocumentDatabase, EnsureCollectionOpts, BaseDocument, DocumentFilter, FindOptions, ProjectOpts, SignalOpts, DocumentUpdate, BulkOp, BulkResult, IDocumentTransaction, IKVStore, SetOpts } from '@kb-labs/core-platform/adapters';
+export { LLMCall, LLMToolCallRecord, LogEntry, MockCacheInstance, MockEmbeddings, MockLLM, MockLLMInstance, MockLoggerInstance, MockStorageInstance, mockCache, mockLLM, mockLogger, mockStorage } from '@kb-labs/shared-testing';
+
+/**
+ * @module @kb-labs/shared-testing-platform/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-platform';
+ *
+ * describe('my handler', () => {
+ *   let cleanup: () => void;
+ *
+ *   beforeEach(() => {
+ *     const result = setupTestPlatform({
+ *       llm: mockLLM().onAnyComplete().respondWith('hello'),
+ *     });
+ *     cleanup = result.cleanup;
+ *   });
+ *
+ *   afterEach(() => cleanup());
+ * });
+ * ```
+ */
+declare function setupTestPlatform(options?: TestPlatformOptions): TestPlatformResult;
+
+/**
+ * @module @kb-labs/shared-testing-platform/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-platform';
+ *
+ * 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.
+ *
+ * Uses mock builders with vi.fn() spies and syncs platform adapters
+ * to the global singleton by default so that composables work in tests.
+ */
+declare function createTestContext<TConfig = unknown>(options?: CreateTestContextOptions): TestContextResult<TConfig>;
+
+/**
+ * @module @kb-labs/shared-testing-platform/test-command
+ *
+ * Single-function test runner for plugin command handlers.
+ */
+
+interface TestableHandler<TConfig = unknown, TInput = unknown, TResult = unknown> {
+    execute(context: PluginContextV3<TConfig>, input: TInput): Promise<TResult> | TResult;
+    cleanup?(): Promise<void> | void;
+}
+interface TestCommandOptions<TConfig = unknown> {
+    flags?: Record<string, unknown>;
+    argv?: string[];
+    query?: Record<string, unknown>;
+    body?: unknown;
+    params?: Record<string, unknown>;
+    input?: unknown;
+    host?: 'cli' | 'rest' | 'workflow' | 'webhook';
+    config?: TConfig;
+    cwd?: string;
+    tenantId?: string;
+    signal?: AbortSignal;
+    platform?: Partial<PlatformServices>;
+    ui?: Partial<UIFacade>;
+    syncSingleton?: boolean;
+}
+interface TestCommandResult<TResult = unknown> {
+    exitCode: number;
+    result: TResult | undefined;
+    meta: Record<string, unknown> | undefined;
+    raw: unknown;
+    ui: UIFacade;
+    ctx: PluginContextV3;
+    cleanup: () => void;
+}
+declare function testCommand<TResult = unknown, TConfig = unknown>(handler: TestableHandler<TConfig, any, any>, options?: TestCommandOptions<TConfig>): Promise<TestCommandResult<TResult>>;
+
+/**
+ * In-memory `IDocumentDatabase` for tests.
+ *
+ * Scope: behavioural fidelity sufficient for governance / wrapper tests —
+ * CRUD, filters, updates, atomic bulkWrite, transactions, ensureCollection,
+ * unique indexes. Not optimised, not for production. Sweep-based TTL is
+ * intentionally absent (not exercised by the governance suite).
+ */
+
+interface InMemoryDocumentDatabaseOptions {
+    /** Seed clock value for new documents. Defaults to `Date.now()` at call site. */
+    now?: () => number;
+}
+/**
+ * In-memory `IDocumentDatabase` for tests.
+ *
+ * Storage layout: `Map<collectionName, Collection>`. Each `Collection` holds
+ * a `Map<id, doc>` and a list of declared indexes (used for uniqueness checks).
+ */
+declare class InMemoryDocumentDatabase implements IDocumentDatabase {
+    private readonly collections;
+    private readonly now;
+    private closed;
+    constructor(opts?: InMemoryDocumentDatabaseOptions);
+    private getCollection;
+    private throwIfClosed;
+    ensureCollection(name: string, options?: EnsureCollectionOpts): Promise<void>;
+    find<T extends BaseDocument, P = T>(collection: string, filter: DocumentFilter<T>, options?: FindOptions & ProjectOpts<T, P> & SignalOpts): Promise<P[]>;
+    findStream<T extends BaseDocument, P = T>(collection: string, filter: DocumentFilter<T>, options?: FindOptions & ProjectOpts<T, P> & SignalOpts & {
+        batchSize?: number;
+    }): AsyncIterable<P>;
+    findById<T extends BaseDocument>(collection: string, id: string): Promise<T | null>;
+    count<T extends BaseDocument>(collection: string, filter: DocumentFilter<T>): Promise<number>;
+    insertOne<T extends BaseDocument>(collection: string, doc: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+    insertMany<T extends BaseDocument>(collection: string, docs: Array<Omit<T, 'id' | 'createdAt' | 'updatedAt'>>): Promise<T[]>;
+    updateOne<T extends BaseDocument>(collection: string, filter: DocumentFilter<T>, update: DocumentUpdate<T>, options?: SignalOpts & {
+        upsert?: boolean;
+    }): Promise<T | null>;
+    updateMany<T extends BaseDocument>(collection: string, filter: DocumentFilter<T>, update: DocumentUpdate<T>): Promise<number>;
+    updateById<T extends BaseDocument>(collection: string, id: string, update: DocumentUpdate<T>): Promise<T | null>;
+    deleteMany<T extends BaseDocument>(collection: string, filter: DocumentFilter<T>): Promise<number>;
+    deleteById(collection: string, id: string): Promise<boolean>;
+    bulkWrite<T extends BaseDocument>(collection: string, ops: Array<BulkOp<T>>): Promise<BulkResult>;
+    transaction<T>(fn: (tx: IDocumentTransaction) => Promise<T>): Promise<T>;
+    ping(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+    }>;
+    close(): Promise<void>;
+}
+declare function createInMemoryDocumentDatabase(opts?: InMemoryDocumentDatabaseOptions): InMemoryDocumentDatabase;
+
+/**
+ * In-memory `IKVStore` for tests. Sufficient for governance / wrapper tests:
+ * full method surface, TTL respected on read (lazy expiry), atomic CAS / incr
+ * via the single-threaded event loop. No background sweeper.
+ */
+
+declare class InMemoryKVStore implements IKVStore {
+    private readonly map;
+    private closed;
+    private throwIfClosed;
+    private isExpired;
+    private getLive;
+    get<T = unknown>(key: string): Promise<T | null>;
+    getMany<T = unknown>(keys: string[]): Promise<Array<T | null>>;
+    set<T = unknown>(key: string, value: T, options?: SetOpts): Promise<boolean>;
+    setMany<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        ttlMs?: number;
+    }>): Promise<void>;
+    setIfNotExists<T = unknown>(key: string, value: T, options?: {
+        ttlMs?: number;
+    } & SignalOpts): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    cas<T = unknown>(key: string, expected: T, next: T, options?: {
+        ttlMs?: number;
+    } & SignalOpts): Promise<boolean>;
+    incr(key: string, delta?: number, options?: {
+        ttlMs?: number;
+    } & SignalOpts): Promise<number>;
+    ttl(key: string): Promise<number | null>;
+    expire(key: string, ttlMs: number): Promise<boolean>;
+    persist(key: string): Promise<boolean>;
+    scan(prefix?: string, _options?: {
+        batchSize?: number;
+    } & SignalOpts): AsyncIterable<{
+        key: string;
+        value: unknown;
+    }>;
+    ping(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+    }>;
+    close(): Promise<void>;
+}
+declare function createInMemoryKVStore(): InMemoryKVStore;
+
+export { type CreateTestContextOptions, InMemoryDocumentDatabase, type InMemoryDocumentDatabaseOptions, InMemoryKVStore, type TestCommandOptions, type TestCommandResult, type TestContextResult, type TestPlatformOptions, type TestPlatformResult, type TestableHandler, createInMemoryDocumentDatabase, createInMemoryKVStore, createInfraApiMocks, createMockEnvironmentAPI, createMockPlatformApi, createMockPluginAPI, createMockPluginContextV3, createMockRuntime, createMockSnapshotAPI, createMockTrace, createMockUI, createMockWorkspaceAPI, createTestContext, setupTestPlatform, testCommand };