@defai.digital/ax-cli 4.4.7 → 4.4.10

package/dist/sdk/testing.d.ts

@@ -1,427 +0,0 @@
-/**
- * Testing utilities for AX CLI SDK
- *
- * This module provides mock implementations and test helpers to make
- * it easy to test code that uses the AX CLI SDK.
- *
- * @packageDocumentation
- */
-import { EventEmitter } from 'events';
-import type { ChatEntry, StreamingChunk } from '../agent/llm-agent.js';
-import type { ToolResult } from '../types/index.js';
-/**
- * Mock agent for testing
- *
- * Implements the same interface as LLMAgent but with predictable,
- * controllable behavior for testing.
- *
- * @example
- * ```typescript
- * import { MockAgent } from '@defai.digital/ax-cli/sdk/testing';
- *
- * test('my integration', async () => {
- *   const agent = new MockAgent({
- *     responses: ['First response', 'Second response']
- *   });
- *
- *   const result = await agent.processUserMessage('Hello');
- *   expect(result[0].content).toBe('First response');
- * });
- * ```
- */
-export declare class MockAgent extends EventEmitter {
-    private responses;
-    private currentResponseIndex;
-    private history;
-    private disposed;
-    /**
-     * Create a new mock agent
-     *
-     * @param options - Configuration for mock behavior
-     */
-    constructor(options?: {
-        /** Predefined responses to return (cycles through) */
-        responses?: string[];
-    });
-    /**
-     * Process a user message (mock implementation)
-     *
-     * Returns the next predefined response and adds it to history.
-     * Cycles through responses if called more times than responses available.
-     *
-     * @param message - User message (stored in history)
-     * @returns Mock chat history
-     */
-    processUserMessage(message: string): Promise<ChatEntry[]>;
-    /**
-     * Process user message with streaming (mock implementation)
-     *
-     * Yields mock stream chunks for the response.
-     */
-    processUserMessageStream(message: string): AsyncGenerator<StreamingChunk>;
-    /**
-     * Get chat history (mock implementation)
-     *
-     * Returns deep copies of chat entries to prevent external mutation.
-     */
-    getChatHistory(): ChatEntry[];
-    /**
-     * Execute bash command (mock implementation)
-     *
-     * Always returns success with predefined output.
-     */
-    executeBashCommand(command: string): Promise<ToolResult>;
-    /**
-     * Get current directory (mock implementation)
-     */
-    getCurrentDirectory(): string;
-    /**
-     * Create checkpoint (mock implementation)
-     */
-    createCheckpoint(_description?: string): Promise<string>;
-    /**
-     * Rewind conversation (mock implementation)
-     */
-    rewindConversation(_checkpointId: string): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    /**
-     * Check if bash is executing (mock implementation)
-     */
-    isBashExecuting(): boolean;
-    /**
-     * Dispose of mock agent
-     * Note: Returns void to match LLMAgent.dispose() signature
-     */
-    dispose(): void;
-    /**
-     * Reset mock agent state
-     *
-     * Clears history and resets response index.
-     * Useful for reusing the same mock across multiple tests.
-     */
-    reset(): void;
-    /**
-     * Set new responses
-     *
-     * @param responses - New responses to use (must have at least one response)
-     * @throws Error if responses array is empty
-     */
-    setResponses(responses: string[]): void;
-    /**
-     * Get number of messages processed
-     */
-    getMessageCount(): number;
-    private checkDisposed;
-    /**
-     * Clean up resources and remove all event listeners.
-     */
-    destroy(): void;
-}
-/**
- * Create a mock agent with predefined responses
- *
- * Convenience function for creating mock agents.
- *
- * @param responses - Predefined responses (optional)
- * @returns Mock agent instance
- *
- * @example
- * ```typescript
- * import { createMockAgent } from '@defai.digital/ax-cli/sdk/testing';
- *
- * const agent = createMockAgent(['Hello!', 'How can I help?']);
- * const result = await agent.processUserMessage('Hi');
- * expect(result[0].content).toBe('Hello!');
- * ```
- */
-export declare function createMockAgent(responses?: string[]): MockAgent;
-/**
- * Mock settings manager for testing
- *
- * Allows tests to control what settings are returned without
- * needing actual config files.
- *
- * @example
- * ```typescript
- * import { MockSettingsManager } from '@defai.digital/ax-cli/sdk/testing';
- *
- * const settings = new MockSettingsManager({
- *   apiKey: 'test-key',
- *   baseURL: 'https://test.api.com',
- *   model: 'glm-4.6'
- * });
- * ```
- */
-interface MockSettings {
-    apiKey?: string;
-    baseURL?: string;
-    model?: string;
-}
-export declare class MockSettingsManager {
-    private settings;
-    constructor(settings?: MockSettings);
-    loadUserSettings(): void;
-    loadProjectSettings(): void;
-    getApiKey(): string | undefined;
-    getBaseURL(): string | undefined;
-    getCurrentModel(): string | undefined;
-    updateUserSetting(key: keyof MockSettings, value: string | undefined): void;
-    saveUserSettings(): void;
-}
-/**
- * Create a mock settings manager
- *
- * @param settings - Settings to return
- * @returns Mock settings manager
- *
- * @example
- * ```typescript
- * import { createMockSettings } from '@defai.digital/ax-cli/sdk/testing';
- *
- * const settings = createMockSettings({
- *   apiKey: 'test-key',
- *   model: 'glm-4.6'
- * });
- * ```
- */
-export declare function createMockSettings(settings?: MockSettings): MockSettingsManager;
-/**
- * Mock MCP Server Options
- */
-export interface MockMCPServerOptions {
-    name: string;
-    version?: string;
-    tools?: Array<{
-        name: string;
-        description: string;
-        inputSchema: {
-            type: 'object';
-            properties: Record<string, unknown>;
-            required?: string[];
-        };
-        handler: (args: Record<string, unknown>) => Promise<unknown>;
-    }>;
-    resources?: Array<{
-        uri: string;
-        name: string;
-        mimeType?: string;
-        handler: () => Promise<string>;
-    }>;
-    prompts?: Array<{
-        name: string;
-        description?: string;
-        handler: (args?: Record<string, unknown>) => Promise<unknown>;
-    }>;
-}
-/**
- * Mock MCP Server for Testing
- *
- * Simplified MCP server that can be used in tests without needing
- * real MCP server infrastructure.
- *
- * @example
- * ```typescript
- * import { createMockMCPServer } from '@defai.digital/ax-cli/sdk/testing';
- *
- * const mockServer = createMockMCPServer({
- *   name: 'test-server',
- *   tools: [{
- *     name: 'test_tool',
- *     description: 'A test tool',
- *     inputSchema: {
- *       type: 'object',
- *       properties: { input: { type: 'string' } },
- *       required: ['input']
- *     },
- *     handler: async (args) => ({ result: `Processed: ${args.input}` })
- *   }]
- * });
- *
- * await mockServer.connect();
- * const tools = await mockServer.listTools();
- * const result = await mockServer.callTool('test_tool', { input: 'test' });
- * ```
- */
-export declare class MockMCPServer {
-    private options;
-    private connected;
-    constructor(options: MockMCPServerOptions);
-    /**
-     * Connect the mock server
-     */
-    connect(): Promise<void>;
-    /**
-     * Disconnect the mock server
-     */
-    disconnect(): Promise<void>;
-    /**
-     * List available tools
-     *
-     * Returns deep copies of tool definitions to prevent external mutation.
-     */
-    listTools(): Promise<Array<{
-        name: string;
-        description: string;
-        inputSchema: Record<string, unknown>;
-    }>>;
-    /**
-     * Call a tool on the mock server
-     *
-     * @param name - Tool name to call
-     * @param args - Arguments to pass to the tool
-     * @throws Error if server not connected, tool not found, or handler throws
-     */
-    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
-    /**
-     * List available resources
-     */
-    listResources(): Promise<Array<{
-        uri: string;
-        name: string;
-        mimeType?: string;
-    }>>;
-    /**
-     * Read a resource from the mock server
-     *
-     * @param uri - Resource URI to read
-     * @throws Error if server not connected, resource not found, or handler throws
-     */
-    readResource(uri: string): Promise<string>;
-    /**
-     * List available prompts
-     */
-    listPrompts(): Promise<Array<{
-        name: string;
-        description?: string;
-    }>>;
-    /**
-     * Execute a prompt
-     *
-     * @param name - Prompt name to execute
-     * @param args - Optional arguments for the prompt
-     * @throws Error if server not connected, prompt not found, or handler throws
-     */
-    executePrompt(name: string, args?: Record<string, unknown>): Promise<unknown>;
-    /**
-     * Check if server is connected
-     */
-    isConnected(): boolean;
-    /**
-     * Get server info
-     */
-    getInfo(): {
-        name: string;
-        version: string;
-        toolCount: number;
-        resourceCount: number;
-        promptCount: number;
-    };
-}
-/**
- * Create a mock MCP server for testing
- *
- * @example
- * ```typescript
- * const mockServer = createMockMCPServer({
- *   name: 'test-server',
- *   tools: [{
- *     name: 'test_tool',
- *     description: 'A test tool',
- *     inputSchema: {
- *       type: 'object',
- *       properties: { input: { type: 'string' } },
- *       required: ['input']
- *     },
- *     handler: async (args) => ({ result: `Processed: ${args.input}` })
- *   }]
- * });
- *
- * await mockServer.connect();
- * const tools = await mockServer.listTools();
- * const result = await mockServer.callTool('test_tool', { input: 'test' });
- * ```
- */
-export declare function createMockMCPServer(options: MockMCPServerOptions): MockMCPServer;
-/**
- * Wait for agent to complete processing
- *
- * Useful in tests when you need to wait for async operations to complete.
- *
- * @example
- * ```typescript
- * const agent = await createAgent();
- *
- * agent.processUserMessage('Hello');
- *
- * // Wait for agent to finish
- * await waitForAgent(agent, { timeout: 5000 });
- *
- * // Now agent is idle
- * ```
- */
-export declare function waitForAgent(agent: EventEmitter, options?: {
-    timeout?: number;
-}): Promise<void>;
-/**
- * Create a mock tool result
- *
- * @param success - Whether the tool execution succeeded
- * @param output - Output message (typically for success cases)
- * @param error - Error message (typically for failure cases)
- * @param data - Additional structured data from the tool
- * @returns ToolResult matching the full interface
- *
- * @example
- * ```typescript
- * // Success result
- * const result = createMockToolResult(true, 'File created');
- *
- * // Failure result
- * const result = createMockToolResult(false, undefined, 'Permission denied');
- *
- * // With data
- * const result = createMockToolResult(true, 'Found 5 files', undefined, { files: ['a.ts', 'b.ts'] });
- * ```
- */
-export declare function createMockToolResult(success: boolean, output?: string, error?: string, data?: Record<string, unknown>): ToolResult;
-/**
- * Assert tool result is successful
- *
- * Note: This only asserts `success: true`. The `output` field may still be undefined
- * even for successful tool results (some tools don't produce output).
- *
- * @example
- * ```typescript
- * const result = await tool.execute();
- * assertToolSuccess(result);
- * // result.success is now true
- * // result.output may still be undefined
- * if (result.output) {
- *   console.log(result.output);
- * }
- * ```
- */
-export declare function assertToolSuccess(result: ToolResult): asserts result is ToolResult & {
-    success: true;
-};
-/**
- * Assert tool result is a failure
- *
- * Note: This only asserts `success: false`. The `error` field may still be undefined
- * even for failed tool results (some tools don't provide error messages).
- *
- * @example
- * ```typescript
- * const result = await tool.execute();
- * assertToolFailure(result);
- * // result.success is now false
- * // result.error may still be undefined
- * console.log(result.error ?? 'Unknown error');
- * ```
- */
-export declare function assertToolFailure(result: ToolResult): asserts result is ToolResult & {
-    success: false;
-};
-export {};