mock-mcp 0.3.1 → 0.5.1

package/dist/types-bEGXLBF0.d.ts

@@ -0,0 +1,190 @@
+import fssync from 'node:fs';
+
+/**
+ * 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;
+/**
+ * Get the cache directory for mock-mcp files.
+ * Priority: override > MOCK_MCP_CACHE_DIR env > XDG_CACHE_HOME > LOCALAPPDATA (Windows) > ~/.cache
+ */
+declare function getCacheDir(override?: string): string;
+interface DaemonPaths {
+    base: string;
+    registryPath: string;
+    lockPath: string;
+    ipcPath: string;
+}
+/**
+ * Get all relevant paths for a given project ID.
+ */
+declare function getPaths(projectId: string, cacheDir?: string): DaemonPaths;
+/**
+ * Read the daemon registry file.
+ */
+declare function readRegistry(registryPath: string): Promise<DaemonRegistry | null>;
+/**
+ * Write the daemon registry file with restricted permissions.
+ */
+declare function writeRegistry(registryPath: string, registry: DaemonRegistry): Promise<void>;
+/**
+ * Check if the daemon is healthy by making an HTTP request to /health.
+ */
+declare function healthCheck(ipcPath: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Try to acquire an exclusive lock file.
+ * Returns the file handle if successful, null otherwise.
+ */
+declare function tryAcquireLock(lockPath: string): Promise<fssync.promises.FileHandle | null>;
+/**
+ * Release the lock file.
+ */
+declare function releaseLock(lockPath: string, fh: fssync.promises.FileHandle): Promise<void>;
+/**
+ * Generate a random token for daemon authentication.
+ */
+declare function randomToken(): string;
+/**
+ * Get the path to the daemon entry point.
+ *
+ * This function handles multiple scenarios:
+ * 1. Direct execution from source (development)
+ * 2. Execution from dist (production)
+ * 3. When re-bundled by another tool (Vitest, esbuild, webpack)
+ *
+ * We use require.resolve to reliably find the mock-mcp package location,
+ * which works even when the code is re-bundled by another tool.
+ */
+declare function getDaemonEntryPath(): 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>;
+declare function sleep(ms: number): Promise<void>;
+/**
+ * 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;
+}
+/**
+ * Get the path to the global active daemons index file.
+ */
+declare function getGlobalIndexPath(cacheDir?: string): string;
+/**
+ * Read the global active daemons index.
+ */
+declare function readGlobalIndex(cacheDir?: string): Promise<ActiveDaemonsIndex>;
+/**
+ * Write the global active daemons index.
+ */
+declare function writeGlobalIndex(index: ActiveDaemonsIndex, cacheDir?: string): Promise<void>;
+/**
+ * Register a daemon in the global index.
+ * Called when a daemon starts.
+ */
+declare function registerDaemonGlobally(entry: ActiveDaemonEntry, cacheDir?: string): Promise<void>;
+/**
+ * Unregister a daemon from the global index.
+ * Called when a daemon stops.
+ */
+declare function unregisterDaemonGlobally(projectId: string, cacheDir?: string): Promise<void>;
+/**
+ * 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;
+}[]>;
+
+/**
+ * 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;
+}
+
+export { type ActiveDaemonEntry as A, type DaemonRegistry as D, type EnsureDaemonOptions as E, type MockResponseDescriptor as M, type ResolvedMock as R, type MockRequestDescriptor as a, getPaths as b, computeProjectId as c, readRegistry as d, releaseLock as e, randomToken as f, getCacheDir as g, healthCheck as h, getDaemonEntryPath as i, ensureDaemonRunning as j, getGlobalIndexPath as k, readGlobalIndex as l, writeGlobalIndex as m, registerDaemonGlobally as n, cleanupGlobalIndex as o, discoverAllDaemons as p, type DaemonPaths as q, resolveProjectRoot as r, sleep as s, tryAcquireLock as t, unregisterDaemonGlobally as u, type ActiveDaemonsIndex as v, writeRegistry as w };

package/package.json

@@ -1,12 +1,46 @@
 {
   "name": "mock-mcp",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "description": "An MCP server enabling LLMs to write integration tests through live test environment interaction",
-  "main": "./dist/connect.cjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "type": "module",
   "bin": {
     "mock-mcp": "./dist/index.js"
   },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
+    "./connect": {
+      "import": {
+        "types": "./dist/client/connect.d.ts",
+        "default": "./dist/client/connect.js"
+      },
+      "require": {
+        "types": "./dist/client/connect.d.cts",
+        "default": "./dist/client/connect.cjs"
+      }
+    }
+  },
   "files": [
     "dist"
   ],
@@ -17,12 +51,17 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc && tsup src/client/connect.ts --dts",
+    "build": "tsup",
+    "clean": "rimraf dist",
     "start": "node dist/index.js",
+    "start:adapter": "node dist/index.js adapter",
     "dev": "tsx src/index.ts",
+    "dev:adapter": "tsx src/index.ts adapter",
     "lint": "eslint . --ext .ts",
     "test": "vitest run",
     "test:watch": "vitest --watch",
+    "test:concurrency": "vitest run test/concurrency.test.ts",
+    "test:inspector": "vitest run test/inspector-integration.test.ts",
     "prepublishOnly": "npm run build",
     "link": "npm link",
     "unlink": "npm unlink",
@@ -55,7 +94,9 @@
     "@vitest/coverage-v8": "^3.2.4",
     "commitizen": "^4.3.1",
     "eslint": "^9.31.0",
+    "fetch-mock": "^12.6.0",
     "node-fetch": "^3.3.2",
+    "rimraf": "^6.1.2",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
@@ -70,4 +111,4 @@
       "path": "cz-conventional-changelog"
     }
   }
-}
+}

package/dist/client/batch-mock-collector.d.ts

@@ -1,111 +0,0 @@
-import { type ResolvedMock } from "../types.js";
-type Logger = Pick<Console, "log" | "warn" | "error"> & {
-    debug?: (...args: unknown[]) => void;
-};
-export interface BatchMockCollectorOptions {
-    /**
-     * TCP port exposed by {@link TestMockMCPServer}.
-     *
-     * @default 3002
-     */
-    port?: number;
-    /**
-     * Timeout for individual mock requests in milliseconds.
-     *
-     * @default 60000
-     */
-    timeout?: number;
-    /**
-     * Delay (in milliseconds) that determines how long the collector waits before
-     * flushing the current batch. Setting this to 0 mirrors the "flush on the next
-     * macrotask" approach described in the technical design document.
-     *
-     * @default 0
-     */
-    batchDebounceMs?: number;
-    /**
-     * Maximum number of requests that may be included in a single batch payload.
-     * Requests that exceed this limit will be split into multiple batches.
-     *
-     * @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;
-}
-export interface RequestMockOptions {
-    body?: unknown;
-    headers?: Record<string, string>;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Collects HTTP requests issued during a single macrotask and forwards them to
- * the MCP server as a batch for AI-assisted mock generation.
- */
-export declare class BatchMockCollector {
-    private ws;
-    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 port;
-    private batchTimer;
-    private heartbeatTimer;
-    private reconnectTimer;
-    private requestIdCounter;
-    private closed;
-    private readyResolve?;
-    private readyReject?;
-    private readyPromise;
-    constructor(options?: BatchMockCollectorOptions);
-    /**
-     * Ensures the underlying WebSocket 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 requests that are currently pending to settle. Requests
-     * created after this method is called are not included.
-     */
-    waitForPendingRequests(): Promise<void>;
-    /**
-     * Close the underlying connection and fail all pending requests.
-     */
-    close(code?: number): Promise<void>;
-    private setupWebSocket;
-    private createWebSocket;
-    private resetReadyPromise;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private scheduleReconnect;
-    private handleMessage;
-    private resolveRequest;
-    private enqueueRequest;
-    private flushQueue;
-    private sendBatch;
-    private buildResolvedMock;
-    private rejectRequest;
-    private failAllPending;
-}
-export {};

package/dist/client/batch-mock-collector.js

@@ -1,308 +0,0 @@
-import WebSocket from "ws";
-import { BATCH_MOCK_REQUEST, BATCH_MOCK_RESPONSE, } from "../types.js";
-import { isEnabled } from "./util.js";
-const DEFAULT_TIMEOUT = 60_000;
-const DEFAULT_BATCH_DEBOUNCE_MS = 0;
-const DEFAULT_MAX_BATCH_SIZE = 50;
-const DEFAULT_PORT = 3002;
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
-/**
- * Collects HTTP requests issued during a single macrotask and forwards them to
- * the MCP server as a batch for AI-assisted mock generation.
- */
-export class BatchMockCollector {
-    ws;
-    pendingRequests = new Map();
-    queuedRequestIds = new Set();
-    timeout;
-    batchDebounceMs;
-    maxBatchSize;
-    logger;
-    heartbeatIntervalMs;
-    enableReconnect;
-    port;
-    batchTimer = null;
-    heartbeatTimer = null;
-    reconnectTimer = null;
-    requestIdCounter = 0;
-    closed = false;
-    readyResolve;
-    readyReject;
-    readyPromise = Promise.resolve();
-    constructor(options = {}) {
-        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
-        this.batchDebounceMs = options.batchDebounceMs ?? DEFAULT_BATCH_DEBOUNCE_MS;
-        this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
-        this.logger = options.logger ?? console;
-        this.heartbeatIntervalMs =
-            options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
-        this.enableReconnect = options.enableReconnect ?? true;
-        this.port = options.port ?? DEFAULT_PORT;
-        this.resetReadyPromise();
-        this.ws = this.createWebSocket();
-        this.setupWebSocket();
-    }
-    /**
-     * Ensures the underlying WebSocket connection is ready for use.
-     */
-    async waitUntilReady() {
-        return this.readyPromise;
-    }
-    /**
-     * Request mock data for a specific endpoint/method pair.
-     */
-    async requestMock(endpoint, method, options = {}) {
-        if (this.closed) {
-            throw new Error("BatchMockCollector has been closed");
-        }
-        await this.waitUntilReady();
-        const requestId = `req-${++this.requestIdCounter}`;
-        const request = {
-            requestId,
-            endpoint,
-            method,
-            body: options.body,
-            headers: options.headers,
-            metadata: options.metadata,
-        };
-        let settleCompletion;
-        const completion = new Promise((resolve) => {
-            settleCompletion = resolve;
-        });
-        return new Promise((resolve, reject) => {
-            const timeoutId = setTimeout(() => {
-                this.rejectRequest(requestId, new Error(`Mock request timed out after ${this.timeout}ms: ${method} ${endpoint}`));
-            }, this.timeout);
-            this.pendingRequests.set(requestId, {
-                request,
-                resolve: (mock) => {
-                    settleCompletion({ status: "fulfilled", value: undefined });
-                    resolve(this.buildResolvedMock(mock));
-                },
-                reject: (error) => {
-                    settleCompletion({ status: "rejected", reason: error });
-                    reject(error);
-                },
-                timeoutId,
-                completion,
-            });
-            this.enqueueRequest(requestId);
-        });
-    }
-    /**
-     * Wait for all requests that are currently pending to settle. Requests
-     * created after this method is called are not included.
-     */
-    async waitForPendingRequests() {
-        if (!isEnabled()) {
-            return;
-        }
-        const pendingCompletions = Array.from(this.pendingRequests.values()).map((pending) => pending.completion);
-        const results = await Promise.all(pendingCompletions);
-        const rejected = results.find((result) => result.status === "rejected");
-        if (rejected) {
-            throw rejected.reason;
-        }
-    }
-    /**
-     * Close the underlying connection and fail all pending requests.
-     */
-    async close(code) {
-        if (this.closed) {
-            return;
-        }
-        this.closed = true;
-        if (this.batchTimer) {
-            clearTimeout(this.batchTimer);
-            this.batchTimer = null;
-        }
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = null;
-        }
-        this.queuedRequestIds.clear();
-        const closePromise = new Promise((resolve) => {
-            this.ws.once("close", () => resolve());
-        });
-        this.ws.close(code);
-        this.failAllPending(new Error("BatchMockCollector has been closed"));
-        await closePromise;
-    }
-    setupWebSocket() {
-        this.ws.on("open", () => {
-            this.logger.log("🔌 Connected to mock MCP WebSocket endpoint");
-            this.readyResolve?.();
-            this.startHeartbeat();
-        });
-        this.ws.on("message", (data) => this.handleMessage(data));
-        this.ws.on("error", (error) => {
-            this.logger.error("❌ WebSocket error:", error);
-            this.readyReject?.(error instanceof Error ? error : new Error(String(error)));
-            this.failAllPending(error instanceof Error ? error : new Error(String(error)));
-        });
-        this.ws.on("close", () => {
-            this.logger.warn("🔌 WebSocket connection closed");
-            this.stopHeartbeat();
-            this.failAllPending(new Error("WebSocket connection closed"));
-            if (!this.closed && this.enableReconnect) {
-                this.scheduleReconnect();
-            }
-        });
-    }
-    createWebSocket() {
-        const wsUrl = `ws://localhost:${this.port}`;
-        return new WebSocket(wsUrl);
-    }
-    resetReadyPromise() {
-        this.readyPromise = new Promise((resolve, reject) => {
-            this.readyResolve = resolve;
-            this.readyReject = reject;
-        });
-    }
-    startHeartbeat() {
-        if (this.heartbeatIntervalMs <= 0 || this.heartbeatTimer) {
-            return;
-        }
-        let lastPong = Date.now();
-        this.ws.on("pong", () => {
-            lastPong = Date.now();
-        });
-        this.heartbeatTimer = setInterval(() => {
-            if (this.ws.readyState !== WebSocket.OPEN) {
-                return;
-            }
-            const now = Date.now();
-            if (now - lastPong > this.heartbeatIntervalMs * 2) {
-                this.logger.warn("Heartbeat missed; closing socket to trigger reconnect...");
-                this.ws.close();
-                return;
-            }
-            this.ws.ping();
-        }, this.heartbeatIntervalMs);
-        this.heartbeatTimer.unref?.();
-    }
-    stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-    }
-    scheduleReconnect() {
-        if (this.reconnectTimer || this.closed) {
-            return;
-        }
-        this.reconnectTimer = setTimeout(() => {
-            this.reconnectTimer = null;
-            this.logger.warn("🔄 Reconnecting to mock MCP WebSocket endpoint...");
-            this.stopHeartbeat();
-            this.resetReadyPromise();
-            this.ws = this.createWebSocket();
-            this.setupWebSocket();
-        }, 1_000);
-        this.reconnectTimer.unref?.();
-    }
-    handleMessage(data) {
-        let parsed;
-        try {
-            parsed = JSON.parse(data.toString());
-        }
-        catch (error) {
-            this.logger.error("Failed to parse server message:", error);
-            return;
-        }
-        if (parsed.type !== BATCH_MOCK_RESPONSE) {
-            this.logger.warn("Received unsupported message type", parsed.type);
-            return;
-        }
-        this.logger.debug?.(`📦 Received mock data for ${parsed.mocks.length} requests (batch ${parsed.batchId})`);
-        for (const mock of parsed.mocks) {
-            this.resolveRequest(mock);
-        }
-    }
-    resolveRequest(mock) {
-        const pending = this.pendingRequests.get(mock.requestId);
-        if (!pending) {
-            this.logger.warn(`Received mock for unknown request: ${mock.requestId}`);
-            return;
-        }
-        clearTimeout(pending.timeoutId);
-        this.pendingRequests.delete(mock.requestId);
-        const resolve = () => pending.resolve(mock);
-        if (mock.delayMs && mock.delayMs > 0) {
-            setTimeout(resolve, mock.delayMs);
-        }
-        else {
-            resolve();
-        }
-    }
-    enqueueRequest(requestId) {
-        this.queuedRequestIds.add(requestId);
-        if (this.batchTimer) {
-            return;
-        }
-        this.batchTimer = setTimeout(() => {
-            this.batchTimer = null;
-            this.flushQueue();
-        }, this.batchDebounceMs);
-    }
-    flushQueue() {
-        const queuedIds = Array.from(this.queuedRequestIds);
-        this.queuedRequestIds.clear();
-        if (queuedIds.length === 0) {
-            return;
-        }
-        for (let i = 0; i < queuedIds.length; i += this.maxBatchSize) {
-            const chunkIds = queuedIds.slice(i, i + this.maxBatchSize);
-            const requests = [];
-            for (const id of chunkIds) {
-                const pending = this.pendingRequests.get(id);
-                if (pending) {
-                    requests.push(pending.request);
-                }
-            }
-            if (requests.length > 0) {
-                this.sendBatch(requests);
-            }
-        }
-    }
-    sendBatch(requests) {
-        if (this.ws.readyState !== WebSocket.OPEN) {
-            const error = new Error("WebSocket is not open");
-            requests.forEach((request) => this.rejectRequest(request.requestId, error));
-            return;
-        }
-        const payload = {
-            type: BATCH_MOCK_REQUEST,
-            requests,
-        };
-        this.logger.debug?.(`📤 Sending batch with ${requests.length} request(s) to MCP server`);
-        this.ws.send(JSON.stringify(payload));
-    }
-    buildResolvedMock(mock) {
-        return {
-            requestId: mock.requestId,
-            data: mock.data,
-            status: mock.status,
-            headers: mock.headers,
-            delayMs: mock.delayMs,
-        };
-    }
-    rejectRequest(requestId, error) {
-        const pending = this.pendingRequests.get(requestId);
-        if (!pending) {
-            return;
-        }
-        clearTimeout(pending.timeoutId);
-        this.pendingRequests.delete(requestId);
-        pending.reject(error);
-    }
-    failAllPending(error) {
-        for (const requestId of Array.from(this.pendingRequests.keys())) {
-            this.rejectRequest(requestId, error);
-        }
-    }
-}

package/dist/client/util.d.ts

@@ -1 +0,0 @@
-export declare const isEnabled: () => boolean;

package/dist/client/util.js

@@ -1,3 +0,0 @@
-export const isEnabled = () => {
-    return process.env.MOCK_MCP !== undefined && process.env.MOCK_MCP !== "0";
-};