mock-mcp 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,10 +1,472 @@
-#!/usr/bin/env node
-import { TestMockMCPServer, type TestMockMCPServerOptions } from "./server/test-mock-mcp-server.js";
-import { BatchMockCollector, type BatchMockCollectorOptions, type RequestMockOptions } from "./client/batch-mock-collector.js";
-import { connect, type ConnectOptions } from "./client/connect.js";
-export { TestMockMCPServer };
-export type { TestMockMCPServerOptions };
-export { BatchMockCollector };
-export type { BatchMockCollectorOptions, RequestMockOptions };
-export { connect };
-export type { ConnectOptions };
+/**
+ * Mock Bridge Daemon - The core singleton process for mock-mcp.
+ *
+ * Responsibilities:
+ * - Listen on IPC (Unix Domain Socket / Windows Named Pipe)
+ * - Accept test process connections via WebSocket /test
+ * - Accept adapter connections via HTTP /control (JSON-RPC)
+ * - Manage runs, batches, claims with lease-based concurrency control
+ * - Clean up expired claims and disconnected runs
+ */
+type Logger$2 = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface MockMcpDaemonOptions {
+    projectRoot: string;
+    token: string;
+    version: string;
+    cacheDir?: string;
+    logger?: Logger$2;
+    /** Default lease time for batch claims (ms). Default: 30000 */
+    defaultLeaseMs?: number;
+    /** Interval for sweeping expired claims (ms). Default: 5000 */
+    sweepIntervalMs?: number;
+    /** Auto-shutdown after this many ms of inactivity (no runs/adapters). Default: 600000 (10min) */
+    idleShutdownMs?: number;
+}
+declare class MockMcpDaemon {
+    private readonly logger;
+    private readonly opts;
+    private server?;
+    private wss?;
+    private sweepTimer?;
+    private idleTimer?;
+    private startedAt?;
+    private readonly runs;
+    private readonly batches;
+    private readonly pendingQueue;
+    private batchSeq;
+    constructor(options: MockMcpDaemonOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleHttp;
+    private readBody;
+    private handleWsConnection;
+    private handleBatchRequest;
+    private cleanupRun;
+    private handleRpc;
+    private getErrorCode;
+    private rpcSuccess;
+    private rpcError;
+    private getStatus;
+    private listRuns;
+    private claimNextBatch;
+    private provideBatch;
+    private validateMocks;
+    private releaseBatch;
+    private getBatch;
+    private sweepExpiredClaims;
+    private resetIdleTimer;
+}
+
+/**
+ * MCP Adapter - The MCP stdio server that bridges AI clients to the Daemon.
+ *
+ * Each MCP client (Cursor, Claude Desktop, etc.) spawns one Adapter process.
+ * The Adapter:
+ * - Exposes MCP tools (claim_next_batch, provide_batch_mock_data, get_status)
+ * - Connects to the Daemon via IPC
+ * - Does NOT bind any ports (avoids conflicts)
+ */
+type Logger$1 = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface AdapterOptions {
+    logger?: Logger$1;
+    version?: string;
+}
+declare function runAdapter(opts?: AdapterOptions): Promise<void>;
+
+/**
+ * Core types for mock-mcp.
+ */
+/**
+ * Shape of a mock request emitted by the test process.
+ */
+interface MockRequestDescriptor {
+    requestId: string;
+    endpoint: string;
+    method: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Shape of the mock data that needs to be returned for a request.
+ */
+interface MockResponseDescriptor {
+    requestId: string;
+    data: unknown;
+    status?: number;
+    headers?: Record<string, string>;
+    delayMs?: number;
+}
+/**
+ * Resolved mock with typed data.
+ */
+interface ResolvedMock<T = unknown> extends Omit<MockResponseDescriptor, "data"> {
+    data: T;
+}
+
+/**
+ * Protocol definitions for mock-mcp Daemon communication.
+ *
+ * Defines message types for:
+ * - Test channel (WebSocket /test): Test process ↔ Daemon
+ * - Control channel (HTTP /control): Adapter ↔ Daemon (JSON-RPC)
+ */
+
+/**
+ * Result of claimNextBatch RPC.
+ */
+interface ClaimNextBatchResult {
+    batchId: string;
+    runId: string;
+    requests: MockRequestDescriptor[];
+    claimToken: string;
+    leaseUntil: number;
+}
+/**
+ * Result of provideBatch RPC.
+ */
+interface ProvideBatchResult {
+    ok: boolean;
+    message?: string;
+}
+/**
+ * Result of getStatus RPC.
+ */
+interface GetStatusResult {
+    version: string;
+    projectId: string;
+    projectRoot: string;
+    pid: number;
+    uptime: number;
+    runs: number;
+    pending: number;
+    claimed: number;
+    totalBatches: number;
+}
+/**
+ * Result of listRuns RPC.
+ */
+interface ListRunsResult {
+    runs: RunInfo[];
+}
+interface RunInfo {
+    runId: string;
+    pid: number;
+    cwd: string;
+    startedAt: string;
+    lastSeen: number;
+    pendingBatches: number;
+    testMeta?: {
+        testFile?: string;
+        testName?: string;
+    };
+}
+/**
+ * Result of getBatch RPC.
+ */
+interface GetBatchResult {
+    batchId: string;
+    runId: string;
+    requests: MockRequestDescriptor[];
+    status: BatchStatus;
+    createdAt: number;
+    claim?: {
+        adapterId: string;
+        leaseUntil: number;
+    };
+}
+type BatchStatus = "pending" | "claimed" | "fulfilled" | "expired";
+
+/**
+ * Daemon Client - HTTP/JSON-RPC client for communicating with the Daemon.
+ *
+ * Used by the MCP Adapter to call daemon RPC methods.
+ */
+
+declare class DaemonClient {
+    private readonly ipcPath;
+    private readonly token;
+    private readonly adapterId;
+    constructor(ipcPath: string, token: string, adapterId: string);
+    getStatus(): Promise<GetStatusResult>;
+    listRuns(): Promise<ListRunsResult>;
+    claimNextBatch(args: {
+        runId?: string;
+        leaseMs?: number;
+    }): Promise<ClaimNextBatchResult | null>;
+    provideBatch(args: {
+        batchId: string;
+        claimToken: string;
+        mocks: MockResponseDescriptor[];
+    }): Promise<ProvideBatchResult>;
+    releaseBatch(args: {
+        batchId: string;
+        claimToken: string;
+        reason?: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    getBatch(batchId: string): Promise<GetBatchResult>;
+    private rpc;
+}
+
+/**
+ * Discovery module for mock-mcp Daemon + Adapter architecture.
+ *
+ * Provides:
+ * - Project root resolution (up-search for .git / package.json)
+ * - Project ID computation (sha256 of realpath)
+ * - Registry/lock file path management
+ * - IPC path (Unix Domain Socket / Windows Named Pipe)
+ * - ensureDaemonRunning() - atomic daemon startup with lock
+ */
+
+interface DaemonRegistry {
+    projectId: string;
+    projectRoot: string;
+    ipcPath: string;
+    token: string;
+    pid: number;
+    startedAt: string;
+    version: string;
+}
+interface EnsureDaemonOptions {
+    projectRoot?: string;
+    timeoutMs?: number;
+    /** For testing: override cache directory */
+    cacheDir?: string;
+}
+/**
+ * Resolve the project root by searching upward for .git or package.json.
+ * Falls back to the starting directory if nothing is found.
+ */
+declare function resolveProjectRoot(startDir?: string): string;
+/**
+ * Compute a stable project ID from the project root path.
+ * Uses sha256 of the realpath, truncated to 16 characters.
+ */
+declare function computeProjectId(projectRoot: string): string;
+/**
+ * Ensure the daemon is running for the given project.
+ *
+ * This function:
+ * 1. Checks if a daemon is already running (via registry + health check)
+ * 2. If not, acquires a lock and spawns a new daemon
+ * 3. Waits for the daemon to become healthy
+ * 4. Returns the registry information
+ *
+ * Thread-safe: multiple processes calling this concurrently will only start one daemon.
+ */
+declare function ensureDaemonRunning(opts?: EnsureDaemonOptions): Promise<DaemonRegistry>;
+
+/**
+ * BatchMockCollector - Collects HTTP requests and sends them to the daemon for mock generation.
+ *
+ * Features:
+ * - Connects to daemon via IPC (Unix Domain Socket / Named Pipe)
+ * - Automatically discovers and starts daemon if needed
+ * - Uses runId for multi-run isolation
+ * - Sends HELLO handshake on connection
+ * - Batches concurrent requests for efficient processing
+ */
+
+type Logger = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface BatchMockCollectorOptions {
+    /**
+     * Timeout for individual mock requests in milliseconds.
+     * @default 60000
+     */
+    timeout?: number;
+    /**
+     * Delay (in milliseconds) before flushing the current batch.
+     * Setting to 0 flushes on the next macrotask.
+     * @default 0
+     */
+    batchDebounceMs?: number;
+    /**
+     * Maximum number of requests that may be included in a single batch.
+     * @default 50
+     */
+    maxBatchSize?: number;
+    /**
+     * Optional custom logger. Defaults to console.
+     */
+    logger?: Logger;
+    /**
+     * Interval for WebSocket heartbeats in milliseconds. Set to 0 to disable.
+     * @default 15000
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Automatically attempt to reconnect when the WebSocket closes unexpectedly.
+     * @default true
+     */
+    enableReconnect?: boolean;
+    /**
+     * Optional project root override. By default, auto-detected from process.cwd().
+     * Use this when you want to explicitly specify the project root directory.
+     */
+    projectRoot?: string;
+    /**
+     * Path to the current test file. The project root will be auto-detected
+     * by searching upward for .git or package.json from this file's directory.
+     *
+     * This is useful in test frameworks like Jest/Vitest:
+     * @example
+     * ```typescript
+     * // Jest
+     * const mockMcpClient = await connect({
+     *   filePath: expect.getState().testPath,
+     * });
+     *
+     * // Vitest
+     * const mockMcpClient = await connect({
+     *   filePath: import.meta.url,
+     * });
+     * ```
+     *
+     * Note: If both `filePath` and `projectRoot` are provided, `projectRoot` takes precedence.
+     */
+    filePath?: string;
+    /**
+     * Optional test metadata to include in the HELLO message.
+     */
+    testMeta?: {
+        testFile?: string;
+        testName?: string;
+    };
+}
+interface RequestMockOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Collects HTTP requests and forwards them to the daemon for AI-assisted mock generation.
+ *
+ * New architecture:
+ * - Connects to daemon via IPC (not TCP port)
+ * - Sends HELLO handshake with runId
+ * - Uses the new protocol (BATCH_MOCK_REQUEST → BATCH_MOCK_RESULT)
+ */
+declare class BatchMockCollector {
+    private ws?;
+    private registry?;
+    private readonly runId;
+    private readonly pendingRequests;
+    private readonly queuedRequestIds;
+    private readonly timeout;
+    private readonly batchDebounceMs;
+    private readonly maxBatchSize;
+    private readonly logger;
+    private readonly heartbeatIntervalMs;
+    private readonly enableReconnect;
+    private readonly projectRoot?;
+    private readonly testMeta?;
+    private batchTimer;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private requestIdCounter;
+    private closed;
+    private authed;
+    private readyResolve?;
+    private readyReject?;
+    private readyPromise;
+    constructor(options?: BatchMockCollectorOptions);
+    /**
+     * Resolve projectRoot from options.
+     * Priority: projectRoot > filePath > undefined (auto-detect)
+     */
+    private resolveProjectRootFromOptions;
+    /**
+     * Ensures the underlying connection is ready for use.
+     */
+    waitUntilReady(): Promise<void>;
+    /**
+     * Request mock data for a specific endpoint/method pair.
+     */
+    requestMock<T = unknown>(endpoint: string, method: string, options?: RequestMockOptions): Promise<ResolvedMock<T>>;
+    /**
+     * Wait for all currently pending requests to settle.
+     */
+    waitForPendingRequests(): Promise<void>;
+    /**
+     * Close the connection and fail all pending requests.
+     */
+    close(code?: number): Promise<void>;
+    private initConnection;
+    private createWebSocket;
+    private setupWebSocket;
+    private sendHello;
+    private handleMessage;
+    private isHelloAck;
+    private isBatchMockResult;
+    private resolveRequest;
+    private rejectRequest;
+    private failAllPending;
+    private enqueueRequest;
+    private flushQueue;
+    private sendBatch;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private resetReadyPromise;
+    private buildResolvedMock;
+    /**
+     * Get the run ID for this collector instance.
+     */
+    getRunId(): string;
+    /**
+     * Get the daemon registry information (after connection).
+     */
+    getRegistry(): DaemonRegistry | undefined;
+}
+
+/**
+ * Options for connecting to the mock-mcp daemon.
+ */
+type ConnectOptions = BatchMockCollectorOptions | undefined;
+/**
+ * Interface for the mock client returned by connect().
+ */
+interface MockClient {
+    waitUntilReady(): Promise<void>;
+    requestMock<T = unknown>(endpoint: string, method: string, options?: RequestMockOptions): Promise<ResolvedMock<T>>;
+    waitForPendingRequests(): Promise<void>;
+    close(code?: number): Promise<void>;
+    /** Get the unique run ID for this connection */
+    getRunId(): string;
+}
+/**
+ * Connect to the mock-mcp daemon for AI-assisted mock generation.
+ *
+ * This function:
+ * 1. Automatically discovers or starts the daemon for your project
+ * 2. Establishes a WebSocket connection via IPC
+ * 3. Returns a MockClient for requesting mocks
+ *
+ * The daemon uses Unix Domain Sockets (macOS/Linux) or Named Pipes (Windows)
+ * instead of TCP ports, eliminating port conflicts when multiple MCP clients
+ * are running simultaneously.
+ *
+ * @example
+ * ```typescript
+ * import { connect } from 'mock-mcp';
+ *
+ * const client = await connect();
+ *
+ * const mock = await client.requestMock<User>('/api/users/1', 'GET');
+ * console.log(mock.data); // AI-generated mock data
+ *
+ * await client.close();
+ * ```
+ */
+declare const connect: (options?: ConnectOptions) => Promise<MockClient>;
+
+export { type AdapterOptions, BatchMockCollector, type BatchMockCollectorOptions, type ConnectOptions, DaemonClient, type DaemonRegistry, type MockClient, MockMcpDaemon, type MockMcpDaemonOptions, type MockRequestDescriptor, type MockResponseDescriptor, type RequestMockOptions, type ResolvedMock, computeProjectId, connect, ensureDaemonRunning, resolveProjectRoot, runAdapter };