mock-mcp 0.3.1 → 0.5.1

package/dist/client/connect.d.cts

@@ -0,0 +1,218 @@
+import { R as ResolvedMock, D as DaemonRegistry } from '../types-bEGXLBF0.cjs';
+import 'node:fs';
+
+/**
+ * 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 { BatchMockCollector as B, type ConnectOptions, type MockClient, type RequestMockOptions as R, type BatchMockCollectorOptions as a, connect };

package/dist/client/connect.d.ts

@@ -1,14 +1,218 @@
-import type { BatchMockCollectorOptions, RequestMockOptions } from "./batch-mock-collector.js";
-import type { ResolvedMock } from "../types.js";
-export type ConnectOptions = number | BatchMockCollectorOptions | undefined;
-export interface MockClient {
+import { R as ResolvedMock, D as DaemonRegistry } from '../types-bEGXLBF0.js';
+import 'node:fs';
+
+/**
+ * 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;
 }
 /**
- * Convenience helper that creates a {@link BatchMockCollector} and waits for the
- * underlying WebSocket connection to become ready before resolving.
+ * 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();
+ * ```
  */
-export declare const connect: (options?: ConnectOptions) => Promise<MockClient>;
+declare const connect: (options?: ConnectOptions) => Promise<MockClient>;
+
+export { BatchMockCollector as B, type ConnectOptions, type MockClient, type RequestMockOptions as R, type BatchMockCollectorOptions as a, connect };