@zuvia-software-solutions/code-mapper 1.4.0

package/dist/mcp/compatible-stdio-transport.js

@@ -0,0 +1,209 @@
+// code-mapper/src/mcp/compatible-stdio-transport.ts
+/** @file compatible-stdio-transport.ts
+ *  @description MCP stdio transport that auto-detects content-length vs newline framing
+ *  Handles both official MCP SDK clients and simpler newline-delimited JSON clients */
+import process from 'node:process';
+import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+function deserializeMessage(raw) {
+    return JSONRPCMessageSchema.parse(JSON.parse(raw));
+}
+function serializeNewlineMessage(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+function serializeContentLengthMessage(message) {
+    const body = JSON.stringify(message);
+    return `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
+}
+function findHeaderEnd(buffer) {
+    const crlfEnd = buffer.indexOf('\r\n\r\n');
+    if (crlfEnd !== -1) {
+        return { index: crlfEnd, separatorLength: 4 };
+    }
+    const lfEnd = buffer.indexOf('\n\n');
+    if (lfEnd !== -1) {
+        return { index: lfEnd, separatorLength: 2 };
+    }
+    return null;
+}
+function looksLikeContentLength(buffer) {
+    if (buffer.length < 14) {
+        return false;
+    }
+    const probe = buffer.toString('utf8', 0, Math.min(buffer.length, 32));
+    return /^content-length\s*:/i.test(probe);
+}
+const MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10 MB — generous for JSON-RPC
+export class CompatibleStdioServerTransport {
+    _stdin;
+    _stdout;
+    _readBuffer;
+    _started = false;
+    _framing = null;
+    /** Direct reference to the real write function, captured at construction time.
+     *  Immune to process.stdout.write being replaced (e.g. embedder.ts silences
+     *  stdout during ONNX model load, which would swallow MCP responses). */
+    _directWrite;
+    onmessage;
+    onerror;
+    onclose;
+    constructor(_stdin = process.stdin, _stdout = process.stdout) {
+        this._stdin = _stdin;
+        this._stdout = _stdout;
+        this._directWrite = this._stdout.write.bind(this._stdout);
+    }
+    _ondata = (chunk) => {
+        this._readBuffer = this._readBuffer ? Buffer.concat([this._readBuffer, chunk]) : chunk;
+        if (this._readBuffer.length > MAX_BUFFER_SIZE) {
+            this.onerror?.(new Error(`Read buffer exceeded maximum size (${MAX_BUFFER_SIZE} bytes)`));
+            this.discardBufferedInput();
+            return;
+        }
+        this.processReadBuffer();
+    };
+    _onerror = (error) => {
+        this.onerror?.(error);
+    };
+    async start() {
+        if (this._started) {
+            throw new Error('CompatibleStdioServerTransport already started!');
+        }
+        this._started = true;
+        this._stdin.on('data', this._ondata);
+        this._stdin.on('error', this._onerror);
+    }
+    detectFraming() {
+        if (!this._readBuffer || this._readBuffer.length === 0) {
+            return null;
+        }
+        const firstByte = this._readBuffer[0];
+        if (firstByte === 0x7b || firstByte === 0x5b) {
+            return 'newline';
+        }
+        if (looksLikeContentLength(this._readBuffer)) {
+            return 'content-length';
+        }
+        return null;
+    }
+    discardBufferedInput() {
+        this._readBuffer = undefined;
+        this._framing = null;
+    }
+    readContentLengthMessage() {
+        if (!this._readBuffer) {
+            return null;
+        }
+        const header = findHeaderEnd(this._readBuffer);
+        if (header === null) {
+            return null;
+        }
+        const headerText = this._readBuffer
+            .toString('utf8', 0, header.index)
+            .replace(/\r\n/g, '\n')
+            .replace(/\r/g, '\n');
+        const match = headerText.match(/(?:^|\n)content-length\s*:\s*(\d+)/i);
+        if (!match) {
+            this.discardBufferedInput();
+            throw new Error('Missing Content-Length header from MCP client');
+        }
+        const contentLength = Number.parseInt(match[1], 10);
+        if (!Number.isFinite(contentLength) || contentLength < 0) {
+            this.discardBufferedInput();
+            throw new Error('Invalid Content-Length header from MCP client');
+        }
+        if (contentLength > MAX_BUFFER_SIZE) {
+            this.discardBufferedInput();
+            throw new Error(`Content-Length ${contentLength} exceeds maximum allowed size (${MAX_BUFFER_SIZE} bytes)`);
+        }
+        const bodyStart = header.index + header.separatorLength;
+        const bodyEnd = bodyStart + contentLength;
+        if (this._readBuffer.length < bodyEnd) {
+            return null;
+        }
+        const body = this._readBuffer.toString('utf8', bodyStart, bodyEnd);
+        this._readBuffer = this._readBuffer.subarray(bodyEnd);
+        return deserializeMessage(body);
+    }
+    readNewlineMessage() {
+        if (!this._readBuffer) {
+            return null;
+        }
+        while (true) {
+            const newlineIndex = this._readBuffer.indexOf('\n');
+            if (newlineIndex === -1) {
+                return null;
+            }
+            const line = this._readBuffer.toString('utf8', 0, newlineIndex).replace(/\r$/, '');
+            this._readBuffer = this._readBuffer.subarray(newlineIndex + 1);
+            if (line.trim().length === 0) {
+                continue;
+            }
+            return deserializeMessage(line);
+        }
+    }
+    readMessage() {
+        if (!this._readBuffer || this._readBuffer.length === 0) {
+            return null;
+        }
+        if (this._framing === null) {
+            this._framing = this.detectFraming();
+            if (this._framing === null) {
+                return null;
+            }
+        }
+        return this._framing === 'content-length'
+            ? this.readContentLengthMessage()
+            : this.readNewlineMessage();
+    }
+    processReadBuffer() {
+        while (true) {
+            try {
+                const message = this.readMessage();
+                if (message === null) {
+                    break;
+                }
+                this.onmessage?.(message);
+            }
+            catch (error) {
+                this.onerror?.(error);
+                break;
+            }
+        }
+    }
+    async close() {
+        this._stdin.off('data', this._ondata);
+        this._stdin.off('error', this._onerror);
+        const remainingDataListeners = this._stdin.listenerCount('data');
+        if (remainingDataListeners === 0) {
+            this._stdin.pause();
+        }
+        this._started = false;
+        this._readBuffer = undefined;
+        this.onclose?.();
+    }
+    send(message, _options) {
+        return new Promise((resolve, reject) => {
+            if (!this._started) {
+                reject(new Error('Transport is closed'));
+                return;
+            }
+            const payload = this._framing === 'newline'
+                ? serializeNewlineMessage(message)
+                : serializeContentLengthMessage(message);
+            const onError = (error) => {
+                this._stdout.removeListener('error', onError);
+                reject(error);
+            };
+            this._stdout.on('error', onError);
+            if (this._directWrite(payload)) {
+                this._stdout.removeListener('error', onError);
+                resolve();
+            }
+            else {
+                this._stdout.once('drain', () => {
+                    this._stdout.removeListener('error', onError);
+                    resolve();
+                });
+            }
+        });
+    }
+}

package/dist/mcp/core/embedder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file embedder.ts
+ * @description MLX-accelerated query embedder for MCP semantic search
+ *
+ * Spawns a persistent Python subprocess running Jina Code 1.5B on Metal.
+ * Query embeddings use task="nl2code" with prompt_type="query" for optimal
+ * natural-language-to-code matching. Includes LRU cache.
+ *
+ * Fail-fast — requires Python 3 + MLX + the downloaded model.
+ */
+/** Initialize the MLX embedder */
+export declare function initEmbedder(): Promise<any>;
+/** Check if embedder is ready */
+export declare function isEmbedderReady(): boolean;
+/** Embed a query text for semantic search (cached, uses "query" prompt type) */
+export declare function embedQuery(query: string): Promise<number[]>;
+/**
+ * Embed multiple texts in a single batch (for incremental embedding refresh)
+ */
+export declare function embedBatch(texts: string[]): Promise<number[][]>;
+/** Get embedding dimensions */
+export declare function getEmbeddingDims(): number;
+/** Cleanup embedder subprocess */
+export declare function disposeEmbedder(): Promise<void>;

package/dist/mcp/core/embedder.js

@@ -0,0 +1,168 @@
+// code-mapper/src/mcp/core/embedder.ts
+/**
+ * @file embedder.ts
+ * @description MLX-accelerated query embedder for MCP semantic search
+ *
+ * Spawns a persistent Python subprocess running Jina Code 1.5B on Metal.
+ * Query embeddings use task="nl2code" with prompt_type="query" for optimal
+ * natural-language-to-code matching. Includes LRU cache.
+ *
+ * Fail-fast — requires Python 3 + MLX + the downloaded model.
+ */
+import { spawn, execFileSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { queryEmbeddingCache } from '../../core/search/query-cache.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Path to MLX embedder script
+const MLX_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'models', 'mlx-embedder.py');
+// Embedding dimensions — must match what was used at index time
+const EMBEDDING_DIMS = 256;
+// Singleton subprocess
+let mlxProcess = null;
+let pendingResolve = null;
+let pendingReject = null;
+let lineBuffer = '';
+let ready = false;
+function ensureProcess() {
+    if (mlxProcess && !mlxProcess.killed)
+        return mlxProcess;
+    // Check prerequisites
+    try {
+        execFileSync('python3', ['-c', 'import mlx; import tokenizers'], {
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        throw new Error('MLX embedder requires Python 3 + MLX on Apple Silicon.\n' +
+            'Install: pip3 install mlx tokenizers huggingface_hub\n' +
+            'The embedding model will download automatically on first use (~3GB).');
+    }
+    mlxProcess = spawn('python3', [MLX_SCRIPT], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, TOKENIZERS_PARALLELISM: 'false' },
+    });
+    lineBuffer = '';
+    mlxProcess.stdout.on('data', (chunk) => {
+        lineBuffer += chunk.toString();
+        const lines = lineBuffer.split('\n');
+        lineBuffer = lines.pop() || '';
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const msg = JSON.parse(line);
+                if (msg.status === 'ready' && !ready) {
+                    ready = true;
+                    console.error(`Code Mapper: MLX query embedder ready (${msg.device})`);
+                }
+                if (pendingResolve) {
+                    const resolve = pendingResolve;
+                    pendingResolve = null;
+                    pendingReject = null;
+                    resolve(msg);
+                }
+            }
+            catch { }
+        }
+    });
+    mlxProcess.stderr.on('data', (chunk) => {
+        // Suppress stderr during MCP stdio to avoid corrupting the protocol
+        // Only log in non-MCP contexts
+    });
+    mlxProcess.on('exit', (code) => {
+        ready = false;
+        mlxProcess = null;
+        if (pendingReject) {
+            const reject = pendingReject;
+            pendingResolve = null;
+            pendingReject = null;
+            reject(new Error(`MLX embedder exited with code ${code}`));
+        }
+    });
+    return mlxProcess;
+}
+function sendAndReceive(request) {
+    return new Promise((resolve, reject) => {
+        const proc = ensureProcess();
+        pendingResolve = resolve;
+        pendingReject = reject;
+        proc.stdin.write(JSON.stringify(request) + '\n');
+    });
+}
+/** Initialize the MLX embedder */
+export async function initEmbedder() {
+    if (ready)
+        return;
+    ensureProcess();
+    const msg = await sendAndReceive({ cmd: 'ping' });
+    if (msg.error)
+        throw new Error(`MLX embedder failed: ${msg.error}`);
+    return msg;
+}
+/** Check if embedder is ready */
+export function isEmbedderReady() {
+    return ready;
+}
+/** Embed a query text for semantic search (cached, uses "query" prompt type) */
+export async function embedQuery(query) {
+    // Check cache first
+    const cached = queryEmbeddingCache.get(query);
+    if (cached)
+        return cached;
+    if (!ready)
+        await initEmbedder();
+    const result = await sendAndReceive({
+        texts: [query],
+        task: 'nl2code',
+        type: 'query', // query prompt type for natural-language-to-code matching
+        dims: EMBEDDING_DIMS,
+    });
+    if (result.error)
+        throw new Error(`Query embedding failed: ${result.error}`);
+    const embedding = result.embeddings[0];
+    // Cache for future lookups
+    queryEmbeddingCache.set(query, embedding);
+    return embedding;
+}
+/**
+ * Embed multiple texts in a single batch (for incremental embedding refresh)
+ */
+export async function embedBatch(texts) {
+    if (texts.length === 0)
+        return [];
+    if (!ready)
+        await initEmbedder();
+    const result = await sendAndReceive({
+        texts,
+        task: 'nl2code',
+        type: 'passage',
+        dims: EMBEDDING_DIMS,
+    });
+    if (result.error)
+        throw new Error(`Batch embedding failed: ${result.error}`);
+    return result.embeddings;
+}
+/** Get embedding dimensions */
+export function getEmbeddingDims() {
+    return EMBEDDING_DIMS;
+}
+/** Cleanup embedder subprocess */
+export async function disposeEmbedder() {
+    if (mlxProcess && !mlxProcess.killed) {
+        try {
+            mlxProcess.stdin.write(JSON.stringify({ cmd: 'quit' }) + '\n');
+            await new Promise(resolve => setTimeout(resolve, 500));
+        }
+        catch { }
+        try {
+            mlxProcess.kill();
+        }
+        catch { }
+        mlxProcess = null;
+    }
+    ready = false;
+    queryEmbeddingCache.clear();
+}

package/dist/mcp/core/lbug-adapter.d.ts

@@ -0,0 +1,29 @@
+/** @file lbug-adapter.ts
+ *  @description LadybugDB connection pool adapter keyed by repoId
+ *  Provides checkout/return pool so each concurrent query gets its own Connection
+ *  from the same Database (Connections are NOT thread-safe)
+ *  @see https://docs.ladybugdb.com/concurrency */
+import lbug from '@ladybugdb/core';
+/**
+ * Initialize (or reuse) a Database + connection pool for a specific repo
+ * Retries on lock errors (e.g., when `code-mapper analyze` is running)
+ */
+export declare const initLbug: (repoId: string, dbPath: string) => Promise<void>;
+export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
+/** Execute a parameterized query using prepare/execute to prevent Cypher injection */
+export declare const executeParameterized: (repoId: string, cypher: string, params: Record<string, any>) => Promise<any[]>;
+/** Close one or all repo pools (provide repoId for single, omit for all) */
+export declare const closeLbug: (repoId?: string) => Promise<void>;
+/** Invalidate a repo's pool and shared DB cache, forcing fresh connections on next init.
+ *  Closes the native Database handle to release the file lock so a child process
+ *  can open the DB in read-write mode for incremental refresh.
+ *  Used before AND after the incremental refresh child process writes to the DB. */
+export declare const invalidateAndReopen: (repoId: string) => Promise<void>;
+/** Check if a specific repo's pool is active */
+export declare const isLbugReady: (repoId: string) => boolean;
+/**
+ * Open a short-lived read-write connection, execute the callback, then close.
+ * The read-only pool must be invalidated BEFORE calling this to avoid lock
+ * conflicts. Retries on lock errors (e.g., concurrent `code-mapper analyze`).
+ */
+export declare const withWriteConnection: <T>(dbPath: string, fn: (conn: lbug.Connection) => Promise<T>) => Promise<T>;