mock-mcp 0.3.1 → 0.5.1

package/dist/index.d.cts

@@ -0,0 +1,602 @@
+/**
+ * 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$3 = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface MockMcpDaemonOptions {
+    projectRoot: string;
+    token: string;
+    version: string;
+    cacheDir?: string;
+    logger?: Logger$3;
+    /** 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)
+ * - Discovers and connects to ALL active Daemons via IPC
+ * - Does NOT bind any ports (avoids conflicts)
+ * - Works across projects without requiring --project-root
+ */
+type Logger$2 = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface AdapterOptions {
+    logger?: Logger$2;
+    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>;
+/**
+ * Entry in the global active daemons index.
+ */
+interface ActiveDaemonEntry {
+    projectId: string;
+    projectRoot: string;
+    ipcPath: string;
+    registryPath: string;
+    pid: number;
+    startedAt: string;
+    version: string;
+}
+/**
+ * Global index of all active daemons.
+ */
+interface ActiveDaemonsIndex {
+    daemons: ActiveDaemonEntry[];
+    updatedAt: string;
+}
+/**
+ * Read the global active daemons index.
+ */
+declare function readGlobalIndex(cacheDir?: string): Promise<ActiveDaemonsIndex>;
+/**
+ * Clean up stale entries from the global index.
+ * Removes entries where the daemon is no longer running.
+ */
+declare function cleanupGlobalIndex(cacheDir?: string): Promise<void>;
+/**
+ * Discover all active daemons.
+ * Returns list of daemons with their connection info.
+ */
+declare function discoverAllDaemons(cacheDir?: string): Promise<{
+    registry: DaemonRegistry;
+    healthy: boolean;
+}[]>;
+
+/**
+ * MultiDaemonClient - Aggregates multiple daemon connections for cross-project operation.
+ *
+ * This client discovers all active daemons and can perform operations across them.
+ * It's designed for MCP adapters that need to work without knowing the specific project root.
+ */
+
+type Logger$1 = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface MultiDaemonClientOptions {
+    logger?: Logger$1;
+    cacheDir?: string;
+}
+interface DaemonConnection {
+    registry: DaemonRegistry;
+    healthy: boolean;
+}
+interface ExtendedRunInfo extends RunInfo {
+    projectId: string;
+    projectRoot: string;
+}
+interface AggregatedStatusResult {
+    daemons: (GetStatusResult & {
+        healthy: boolean;
+    })[];
+    totalRuns: number;
+    totalPending: number;
+    totalClaimed: number;
+}
+declare class MultiDaemonClient {
+    private readonly logger;
+    private readonly cacheDir?;
+    private readonly adapterId;
+    constructor(opts?: MultiDaemonClientOptions);
+    /**
+     * Discover all active and healthy daemons.
+     */
+    discoverDaemons(): Promise<DaemonConnection[]>;
+    /**
+     * Get aggregated status from all daemons.
+     */
+    getAggregatedStatus(): Promise<AggregatedStatusResult>;
+    /**
+     * List all runs across all daemons.
+     */
+    listAllRuns(): Promise<ExtendedRunInfo[]>;
+    /**
+     * Claim the next available batch from any daemon.
+     * Searches through all daemons in order until finding one with a pending batch.
+     */
+    claimNextBatch(args: {
+        runId?: string;
+        leaseMs?: number;
+    }): Promise<(ClaimNextBatchResult & {
+        projectId: string;
+        projectRoot: string;
+    }) | null>;
+    /**
+     * Provide mock data for a batch.
+     * Automatically routes to the correct daemon based on batchId.
+     */
+    provideBatch(args: {
+        batchId: string;
+        claimToken: string;
+        mocks: MockResponseDescriptor[];
+    }): Promise<ProvideBatchResult>;
+    /**
+     * Release a batch.
+     */
+    releaseBatch(args: {
+        batchId: string;
+        claimToken: string;
+        reason?: string;
+    }): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    /**
+     * Get a specific batch by ID.
+     */
+    getBatch(batchId: string): Promise<GetBatchResult | null>;
+    private rpc;
+}
+
+/**
+ * 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 (if valid) > filePath > projectRoot (fallback) > undefined (auto-detect)
+     *
+     * A projectRoot is "valid" if it contains .git or package.json. This prevents
+     * accidentally using a wrong directory (e.g., user's home directory) when the
+     * caller mistakenly passes process.cwd() as projectRoot.
+     */
+    private resolveProjectRootFromOptions;
+    /**
+     * Check if a directory contains .git or package.json
+     */
+    private hasGitOrPackageJson;
+    /**
+     * 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 ActiveDaemonEntry, type ActiveDaemonsIndex, type AdapterOptions, type AggregatedStatusResult, BatchMockCollector, type BatchMockCollectorOptions, type ConnectOptions, DaemonClient, type DaemonRegistry, type ExtendedRunInfo, type MockClient, MockMcpDaemon, type MockMcpDaemonOptions, type MockRequestDescriptor, type MockResponseDescriptor, MultiDaemonClient, type MultiDaemonClientOptions, type RequestMockOptions, type ResolvedMock, cleanupGlobalIndex, computeProjectId, connect, discoverAllDaemons, ensureDaemonRunning, readGlobalIndex, resolveProjectRoot, runAdapter };