llmist 1.1.0 → 1.3.0

package/dist/testing/index.d.cts

@@ -1,6 +1,7 @@
-import { B as BaseGadget } from '../mock-stream-DKF5yatf.cjs';
-export { a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-DKF5yatf.cjs';
+import { B as BaseGadget, L as LLMStream, a as LLMStreamChunk, b as LLMMessage, I as IConversationManager } from '../mock-stream-DNt-HBTn.cjs';
+export { d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-DNt-HBTn.cjs';
 import { ZodType } from 'zod';
+import { PassThrough, Readable, Writable } from 'node:stream';
 import 'tslog';
 
 /**
@@ -271,4 +272,437 @@ declare class MockGadgetBuilder {
  */
 declare function mockGadget(): MockGadgetBuilder;
 
-export { type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type RecordedCall, type TestGadgetOptions, type TestGadgetResult, createMockGadget, mockGadget, testGadget, testGadgetBatch };
+/**
+ * Stream testing utilities for llmist.
+ * Provides helpers for creating and consuming test streams.
+ */
+
+/**
+ * Create an async iterable stream from an array of chunks.
+ * Useful for creating deterministic test streams.
+ *
+ * @param chunks - Array of chunks to yield
+ * @returns An async iterable that yields the chunks in order
+ *
+ * @example
+ * ```typescript
+ * const stream = createTestStream([
+ *   { text: "Hello " },
+ *   { text: "world", finishReason: "stop", usage: { inputTokens: 10, outputTokens: 5 } }
+ * ]);
+ * ```
+ */
+declare function createTestStream(chunks: LLMStreamChunk[]): LLMStream;
+/**
+ * Create a stream that yields text in specified chunks.
+ * Automatically adds finishReason and usage to the final chunk.
+ *
+ * @param text - The full text to stream
+ * @param options - Configuration options
+ * @returns An async iterable stream
+ *
+ * @example
+ * ```typescript
+ * const stream = createTextStream("Hello, world!", { chunkSize: 5 });
+ * // Yields: "Hello", ", wor", "ld!"
+ * ```
+ */
+declare function createTextStream(text: string, options?: {
+    /** Size of each chunk (default: entire text as one chunk) */
+    chunkSize?: number;
+    /** Delay before starting the stream in ms */
+    delayMs?: number;
+    /** Delay between chunks in ms */
+    chunkDelayMs?: number;
+    /** Custom usage stats */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /** Custom finish reason (default: "stop") */
+    finishReason?: string;
+}): LLMStream;
+/**
+ * Collect all chunks from a stream into an array.
+ * Useful for asserting on stream output in tests.
+ *
+ * @param stream - The stream to collect from
+ * @returns Array of all chunks from the stream
+ *
+ * @example
+ * ```typescript
+ * const chunks = await collectStream(myStream);
+ * expect(chunks).toHaveLength(3);
+ * expect(chunks[2].finishReason).toBe("stop");
+ * ```
+ */
+declare function collectStream(stream: LLMStream): Promise<LLMStreamChunk[]>;
+/**
+ * Collect all text from a stream into a single string.
+ *
+ * @param stream - The stream to collect from
+ * @returns Concatenated text from all chunks
+ *
+ * @example
+ * ```typescript
+ * const text = await collectStreamText(myStream);
+ * expect(text).toBe("Hello, world!");
+ * ```
+ */
+declare function collectStreamText(stream: LLMStream): Promise<string>;
+/**
+ * Get the final chunk from a stream (containing finishReason and usage).
+ *
+ * @param stream - The stream to consume
+ * @returns The final chunk from the stream
+ */
+declare function getStreamFinalChunk(stream: LLMStream): Promise<LLMStreamChunk | undefined>;
+/**
+ * Create an empty stream that yields nothing.
+ * Useful for testing edge cases.
+ */
+declare function createEmptyStream(): LLMStream;
+/**
+ * Create a stream that throws an error after yielding some chunks.
+ * Useful for testing error handling.
+ *
+ * @param chunksBeforeError - Chunks to yield before throwing
+ * @param error - The error to throw
+ */
+declare function createErrorStream(chunksBeforeError: LLMStreamChunk[], error: Error): LLMStream;
+
+/**
+ * Conversation fixture generators for testing.
+ * Provides utilities for creating test conversation data.
+ */
+
+/**
+ * Create a conversation with a specified number of turns.
+ * Each turn consists of a user message and an assistant response.
+ *
+ * @param turnCount - Number of conversation turns to generate
+ * @param options - Configuration options
+ * @returns Array of LLMMessages representing the conversation
+ *
+ * @example
+ * ```typescript
+ * const messages = createConversation(5);
+ * // Creates 10 messages: 5 user + 5 assistant
+ * ```
+ */
+declare function createConversation(turnCount: number, options?: {
+    /** Prefix for user messages (default: "User message") */
+    userPrefix?: string;
+    /** Prefix for assistant messages (default: "Assistant response") */
+    assistantPrefix?: string;
+    /** Base content length per message (default: 100 chars) */
+    contentLength?: number;
+}): LLMMessage[];
+/**
+ * Create a conversation with gadget calls interspersed.
+ * Simulates an agent conversation with tool usage.
+ *
+ * @param turnCount - Number of conversation turns
+ * @param gadgetCallsPerTurn - Number of gadget calls per assistant turn
+ * @returns Array of LLMMessages including gadget call/result pairs
+ *
+ * @example
+ * ```typescript
+ * const messages = createConversationWithGadgets(3, 2);
+ * // Creates: user, assistant+gadget, gadget-result, assistant+gadget, gadget-result, assistant (per turn)
+ * ```
+ */
+declare function createConversationWithGadgets(turnCount: number, gadgetCallsPerTurn?: number, options?: {
+    /** Gadget names to cycle through (default: ["search", "calculate", "read"]) */
+    gadgetNames?: string[];
+    /** Content length for messages */
+    contentLength?: number;
+}): LLMMessage[];
+/**
+ * Estimate token count for a message array.
+ * Uses a simple 4-characters-per-token heuristic.
+ *
+ * @param messages - Messages to estimate tokens for
+ * @returns Estimated token count
+ *
+ * @example
+ * ```typescript
+ * const messages = createConversation(10);
+ * const tokens = estimateTokens(messages);
+ * // Returns approximate token count
+ * ```
+ */
+declare function estimateTokens(messages: LLMMessage[]): number;
+/**
+ * Create a single user message.
+ */
+declare function createUserMessage(content: string): LLMMessage;
+/**
+ * Create a single assistant message.
+ */
+declare function createAssistantMessage(content: string): LLMMessage;
+/**
+ * Create a system message.
+ */
+declare function createSystemMessage(content: string): LLMMessage;
+/**
+ * Create a minimal conversation for quick tests.
+ * Returns a single turn: one user message and one assistant response.
+ */
+declare function createMinimalConversation(): LLMMessage[];
+/**
+ * Create a conversation that exceeds a target token count.
+ * Useful for testing compaction triggers.
+ *
+ * @param targetTokens - Minimum token count to exceed
+ * @param options - Configuration options
+ * @returns Conversation with at least targetTokens tokens
+ */
+declare function createLargeConversation(targetTokens: number, options?: {
+    /** Average tokens per turn (default: 200) */
+    tokensPerTurn?: number;
+}): LLMMessage[];
+
+/**
+ * Mock ConversationManager for testing compaction and agent components.
+ * Implements IConversationManager interface with test-friendly features.
+ */
+
+/**
+ * A mock implementation of IConversationManager for testing.
+ * Tracks all operations and allows inspection of state changes.
+ *
+ * @example
+ * ```typescript
+ * const mockConvo = new MockConversationManager([
+ *   { role: "user", content: "Hello" },
+ *   { role: "assistant", content: "Hi!" }
+ * ]);
+ *
+ * // Use in compaction tests
+ * compactionManager.checkAndCompact(mockConvo, 1);
+ *
+ * // Assert on state changes
+ * expect(mockConvo.wasReplaceHistoryCalled()).toBe(true);
+ * expect(mockConvo.getReplacementHistory()).toHaveLength(2);
+ * ```
+ */
+declare class MockConversationManager implements IConversationManager {
+    private history;
+    private readonly baseMessages;
+    private replacementHistory;
+    private replaceHistoryCallCount;
+    private addedMessages;
+    constructor(history?: LLMMessage[], baseMessages?: LLMMessage[]);
+    addUserMessage(content: string): void;
+    addAssistantMessage(content: string): void;
+    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
+    getMessages(): LLMMessage[];
+    getHistoryMessages(): LLMMessage[];
+    getBaseMessages(): LLMMessage[];
+    replaceHistory(newHistory: LLMMessage[]): void;
+    /**
+     * Check if replaceHistory was called.
+     */
+    wasReplaceHistoryCalled(): boolean;
+    /**
+     * Get the number of times replaceHistory was called.
+     */
+    getReplaceHistoryCallCount(): number;
+    /**
+     * Get the most recent history passed to replaceHistory.
+     * Returns undefined if replaceHistory was never called.
+     */
+    getReplacementHistory(): LLMMessage[] | undefined;
+    /**
+     * Get all messages that were added via add* methods.
+     */
+    getAddedMessages(): LLMMessage[];
+    /**
+     * Reset all tracking state while preserving the conversation.
+     */
+    resetTracking(): void;
+    /**
+     * Completely reset the mock to initial state.
+     * Note: baseMessages cannot be changed after construction.
+     */
+    reset(history?: LLMMessage[]): void;
+    /**
+     * Set the history directly (for test setup).
+     */
+    setHistory(messages: LLMMessage[]): void;
+    /**
+     * Get the current history length.
+     */
+    getHistoryLength(): number;
+    /**
+     * Get total message count (base + history).
+     */
+    getTotalMessageCount(): number;
+}
+/**
+ * Create a mock conversation manager with a pre-populated conversation.
+ *
+ * @param turnCount - Number of conversation turns
+ * @param baseMessages - Optional base messages (system prompts)
+ * @returns Configured MockConversationManager
+ */
+declare function createMockConversationManager(turnCount: number, baseMessages?: LLMMessage[]): MockConversationManager;
+
+/**
+ * CLI testing utilities for llmist.
+ * Provides helpers for testing CLI commands without real I/O.
+ */
+
+/**
+ * Options for creating a test environment.
+ */
+interface TestEnvironmentOptions {
+    /** Input to provide via stdin (string or line array) */
+    stdin?: string | string[];
+    /** Whether stdin is a TTY (default: false) */
+    isTTY?: boolean;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+    /** Command line arguments (default: ["node", "llmist"]) */
+    argv?: string[];
+}
+/**
+ * A test environment with captured I/O streams.
+ */
+interface TestEnvironment {
+    /** Stdin readable stream */
+    stdin: Readable;
+    /** Stdout writable stream (PassThrough for capturing) */
+    stdout: PassThrough;
+    /** Stderr writable stream (PassThrough for capturing) */
+    stderr: PassThrough;
+    /** Whether stdin is TTY */
+    isTTY: boolean;
+    /** Command line arguments */
+    argv: string[];
+    /** Environment variables */
+    env: Record<string, string>;
+    /** Exit code if set */
+    exitCode?: number;
+    /** Function to set exit code */
+    setExitCode: (code: number) => void;
+}
+/**
+ * Create a test environment with mocked I/O streams.
+ *
+ * @param options - Configuration options
+ * @returns A test environment with captured streams
+ *
+ * @example
+ * ```typescript
+ * const env = createTestEnvironment({
+ *   stdin: '{"param": "value"}',
+ *   isTTY: false
+ * });
+ *
+ * // Pass to CLI command
+ * await executeCommand(env);
+ *
+ * // Check output
+ * const output = await collectOutput(env.stdout);
+ * expect(output).toContain("Success");
+ * ```
+ */
+declare function createTestEnvironment(options?: TestEnvironmentOptions): TestEnvironment;
+/**
+ * Create a readable stream from a string or array of lines.
+ *
+ * @param input - String content or array of lines
+ * @returns A Readable stream
+ *
+ * @example
+ * ```typescript
+ * const stream = createMockReadable("line1\nline2\n");
+ * // or
+ * const stream = createMockReadable(["line1", "line2"]);
+ * ```
+ */
+declare function createMockReadable(input?: string | string[]): Readable;
+/**
+ * Create a writable stream that collects all written data.
+ *
+ * @returns A writable stream with getData() method
+ */
+declare function createMockWritable(): Writable & {
+    getData(): string;
+};
+/**
+ * Collect all output from a PassThrough stream.
+ * Waits for the stream to end before returning.
+ *
+ * @param stream - The stream to collect from
+ * @param timeout - Maximum time to wait in ms (default: 5000)
+ * @returns All data written to the stream
+ *
+ * @example
+ * ```typescript
+ * const output = await collectOutput(env.stdout);
+ * expect(output).toContain("Expected text");
+ * ```
+ */
+declare function collectOutput(stream: PassThrough, timeout?: number): Promise<string>;
+/**
+ * Collect output without waiting for stream end.
+ * Returns immediately with whatever has been written.
+ *
+ * @param stream - The stream to read from
+ * @returns Currently buffered data
+ */
+declare function getBufferedOutput(stream: PassThrough): string;
+/**
+ * Create a mock prompt function for testing interactive input.
+ *
+ * @param responses - Array of responses to return in order
+ * @returns A prompt function that returns the next response
+ *
+ * @example
+ * ```typescript
+ * const prompt = createMockPrompt(["yes", "no", "maybe"]);
+ * expect(await prompt("Question 1?")).toBe("yes");
+ * expect(await prompt("Question 2?")).toBe("no");
+ * ```
+ */
+declare function createMockPrompt(responses: string[]): (question: string) => Promise<string>;
+/**
+ * Mock prompt that records questions and returns configured responses.
+ */
+declare class MockPromptRecorder {
+    private responses;
+    private index;
+    private questions;
+    constructor(responses: string[]);
+    /**
+     * The prompt function to use in tests.
+     */
+    prompt: (question: string) => Promise<string>;
+    /**
+     * Get all questions that were asked.
+     */
+    getQuestions(): string[];
+    /**
+     * Get the number of questions asked.
+     */
+    getQuestionCount(): number;
+    /**
+     * Reset the recorder state.
+     */
+    reset(newResponses?: string[]): void;
+}
+/**
+ * Wait for a condition to be true, with timeout.
+ * Useful for async testing scenarios.
+ *
+ * @param condition - Function that returns true when condition is met
+ * @param timeout - Maximum time to wait in ms (default: 5000)
+ * @param interval - Check interval in ms (default: 50)
+ */
+declare function waitFor(condition: () => boolean, timeout?: number, interval?: number): Promise<void>;
+
+export { MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, MockPromptRecorder, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getStreamFinalChunk, mockGadget, testGadget, testGadgetBatch, waitFor };