llmist 2.5.0 → 2.6.0

package/dist/testing/index.d.cts

@@ -1,9 +1,256 @@
-import { B as BaseGadget, L as LLMStream, a as LLMStreamChunk, b as LLMMessage, I as IConversationManager } from '../mock-stream-ga4KIiwX.cjs';
-export { j as MockAudioData, d as MockBuilder, k as MockImageData, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-ga4KIiwX.cjs';
-import { ZodType } from 'zod';
 import { PassThrough, Readable, Writable } from 'node:stream';
+import { L as LLMMessage, B as BaseGadget, I as IConversationManager, a as LLMStream, b as LLMStreamChunk } from '../mock-stream-Jgg5u6Uf.cjs';
+export { j as MockAudioData, d as MockBuilder, k as MockImageData, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-Jgg5u6Uf.cjs';
+import { ZodType } from 'zod';
 import 'tslog';
 
+/**
+ * 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>;
+
+/**
+ * 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[];
+
 /**
  * Testing utilities for gadgets.
  *
@@ -104,13 +351,99 @@ declare function testGadget(gadget: BaseGadget, params: Record<string, unknown>,
 declare function testGadgetBatch(gadget: BaseGadget, paramSets: Record<string, unknown>[], options?: TestGadgetOptions): Promise<TestGadgetResult[]>;
 
 /**
- * Mock gadget utilities for testing.
- *
- * Provides helpers for creating mock gadgets with configurable behavior
- * and call tracking.
- *
- * @module testing/mock-gadget
- */
+ * 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;
+
+/**
+ * Mock gadget utilities for testing.
+ *
+ * Provides helpers for creating mock gadgets with configurable behavior
+ * and call tracking.
+ *
+ * @module testing/mock-gadget
+ */
 
 /**
  * Recorded gadget call for tracking.
@@ -374,337 +707,4 @@ declare function createEmptyStream(): LLMStream;
  */
 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 };