@jagilber-org/index-server 1.19.1

package/dist/server/thin-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Index Server - Thin Client Entry Point
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * Lightweight stdio-to-HTTP bridge for MCP hosts.
+ * Instead of loading the full index and handler registry, this process
+ * reads JSON-RPC frames from stdin and forwards them to the leader server
+ * over HTTP.
+ *
+ * Usage:
+ *   node dist/server/thin-client.js
+ *
+ * Environment:
+ *   INDEX_SERVER_STATE_DIR    - State directory to discover leader (default: ./data/state)
+ *   INDEX_SERVER_LEADER_URL   - Explicit leader URL (e.g., http://127.0.0.1:9090/mcp)
+ *
+ * The thin client auto-discovers the leader from the lock file in INDEX_SERVER_STATE_DIR,
+ * or connects to INDEX_SERVER_LEADER_URL if provided. On leader failover, it re-discovers
+ * and reconnects automatically.
+ */
+export {};

package/dist/server/thin-client.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Index Server - Thin Client Entry Point
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * Lightweight stdio-to-HTTP bridge for MCP hosts.
+ * Instead of loading the full index and handler registry, this process
+ * reads JSON-RPC frames from stdin and forwards them to the leader server
+ * over HTTP.
+ *
+ * Usage:
+ *   node dist/server/thin-client.js
+ *
+ * Environment:
+ *   INDEX_SERVER_STATE_DIR    - State directory to discover leader (default: ./data/state)
+ *   INDEX_SERVER_LEADER_URL   - Explicit leader URL (e.g., http://127.0.0.1:9090/mcp)
+ *
+ * The thin client auto-discovers the leader from the lock file in INDEX_SERVER_STATE_DIR,
+ * or connects to INDEX_SERVER_LEADER_URL if provided. On leader failover, it re-discovers
+ * and reconnects automatically.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const ThinClient_js_1 = require("../dashboard/server/ThinClient.js");
+const stateDir = process.env.INDEX_SERVER_STATE_DIR || path_1.default.join(process.cwd(), 'data', 'state');
+const leaderUrl = process.env.INDEX_SERVER_LEADER_URL || undefined;
+const client = new ThinClient_js_1.ThinClient({
+    leaderUrl,
+    stateDir,
+    maxRetries: 5,
+    retryDelayMs: 500,
+});
+process.stderr.write(`[thin-client] Starting stdio bridge (pid=${process.pid})\n`);
+process.stderr.write(`[thin-client] State dir: ${stateDir}\n`);
+if (leaderUrl) {
+    process.stderr.write(`[thin-client] Explicit leader URL: ${leaderUrl}\n`);
+}
+else {
+    const discovered = client.discoverLeader();
+    process.stderr.write(`[thin-client] Discovered leader: ${discovered || '(none yet — will retry on first request)'}\n`);
+}
+// Read JSON-RPC frames from stdin (Content-Length delimited or newline-delimited)
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    // Try Content-Length framing first (standard MCP protocol)
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const headerMatch = buffer.match(/^Content-Length:\s*(\d+)\r?\n\r?\n/);
+        if (headerMatch) {
+            const contentLength = parseInt(headerMatch[1], 10);
+            const headerEnd = headerMatch[0].length;
+            if (buffer.length >= headerEnd + contentLength) {
+                const frame = buffer.slice(headerEnd, headerEnd + contentLength);
+                buffer = buffer.slice(headerEnd + contentLength);
+                handleFrame(frame);
+                continue;
+            }
+            break; // Wait for more data
+        }
+        // Fallback: newline-delimited JSON
+        const newlineIdx = buffer.indexOf('\n');
+        if (newlineIdx >= 0) {
+            const line = buffer.slice(0, newlineIdx).trim();
+            buffer = buffer.slice(newlineIdx + 1);
+            if (line.length > 0 && line.startsWith('{')) {
+                handleFrame(line);
+            }
+            continue;
+        }
+        break; // Wait for more data
+    }
+});
+async function handleFrame(frame) {
+    try {
+        const response = await client.processFrame(frame);
+        const responseBytes = Buffer.from(response, 'utf8');
+        process.stdout.write(`Content-Length: ${responseBytes.length}\r\n\r\n`);
+        process.stdout.write(responseBytes);
+    }
+    catch (err) {
+        const errorResponse = JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32603, message: err instanceof Error ? err.message : 'Internal error' },
+            id: null,
+        });
+        const errorBytes = Buffer.from(errorResponse, 'utf8');
+        process.stdout.write(`Content-Length: ${errorBytes.length}\r\n\r\n`);
+        process.stdout.write(errorBytes);
+    }
+}
+process.stdin.on('end', () => {
+    process.stderr.write('[thin-client] stdin closed, shutting down\n');
+    client.stop();
+    process.exit(0);
+});
+process.on('SIGINT', () => {
+    process.stderr.write('[thin-client] SIGINT received, shutting down\n');
+    client.stop();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    process.stderr.write('[thin-client] SIGTERM received, shutting down\n');
+    client.stop();
+    process.exit(0);
+});

package/dist/server/transport.d.ts

@@ -0,0 +1,41 @@
+export type Handler<TParams = unknown> = (params: TParams) => Promise<unknown> | unknown;
+interface MetricRecord {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+/** Return the in-memory per-method metrics map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by method name
+ */
+export declare function getMetrics(): Record<string, MetricRecord>;
+/**
+ * Register a method handler in the stdio transport's handler table.
+ * Unlike the SDK registry, this does not add wrapping (metrics, audit, etc.).
+ * @param method - JSON-RPC method name
+ * @param handler - Handler function invoked with the parsed params
+ */
+export declare function registerHandler<TParams = unknown>(method: string, handler: Handler<TParams>): void;
+/**
+ * Return a sorted list of all registered method names in the stdio transport.
+ * @returns Array of method name strings in alphabetical order
+ */
+export declare function listRegisteredMethods(): string[];
+/**
+ * Look up a registered handler by method name.
+ * @param method - JSON-RPC method name to look up
+ * @returns The handler function, or `undefined` if not registered
+ */
+export declare function getHandler(method: string): Handler | undefined;
+export interface TransportOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Start the stdio JSON-RPC 2.0 transport, reading requests from stdin and writing responses to stdout.
+ * Registers built-in handlers for `initialize`, `notifications/initialized`, `shutdown`, and `exit`.
+ * @param opts - Optional stream overrides (input, output, stderr) and environment; defaults to process streams
+ */
+export declare function startTransport(opts?: TransportOptions): void;
+export {};

package/dist/server/transport.js

@@ -0,0 +1,312 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetrics = getMetrics;
+exports.registerHandler = registerHandler;
+exports.listRegisteredMethods = listRegisteredMethods;
+exports.getHandler = getHandler;
+exports.startTransport = startTransport;
+/**
+ * MCP Transport Layer - stdio JSON-RPC 2.0 Only
+ *
+ * This module implements the primary MCP server transport over stdin/stdout.
+ * All MCP clients (VS Code, Claude, etc.) communicate exclusively through this stdio transport.
+ *
+ * Security: Process-isolated communication with no network exposure.
+ * Protocol: JSON-RPC 2.0 line-delimited over stdin/stdout streams.
+ *
+ * Note: The optional HTTP dashboard is implemented separately and is for admin use only.
+ */
+const readline_1 = require("readline");
+const validationService_1 = require("../services/validationService");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// Robust version resolution: attempt cwd + relative to compiled dist location
+const versionCandidates = [
+    path_1.default.join(process.cwd(), 'package.json'),
+    path_1.default.join(__dirname, '..', '..', 'package.json')
+];
+let VERSION = '0.0.0';
+for (const p of versionCandidates) {
+    try {
+        if (fs_1.default.existsSync(p)) {
+            const raw = JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+            if (raw?.version) {
+                VERSION = raw.version;
+                break;
+            }
+        }
+    }
+    catch { /* ignore */ }
+}
+const handlers = {
+    'health_check': () => {
+        // Minimal fallback health; enriched version registered by handlers.metrics.ts overwrites this
+        let instances = [];
+        try {
+            // Dynamic require avoids circular dependency at module load time
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { getActiveInstances } = require('../dashboard/server/InstanceManager');
+            instances = getActiveInstances().map(i => ({ pid: i.pid, port: i.port, host: i.host, startedAt: i.startedAt, current: i.current }));
+        }
+        catch { /* fail-open */ }
+        return { status: 'ok', timestamp: new Date().toISOString(), version: VERSION, pid: process.pid, uptime: Math.round(process.uptime()), instances };
+    }
+};
+const metrics = {};
+/** Return the in-memory per-method metrics map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by method name
+ */
+function getMetrics() { return metrics; }
+const handlerMeta = {};
+/**
+ * Register a method handler in the stdio transport's handler table.
+ * Unlike the SDK registry, this does not add wrapping (metrics, audit, etc.).
+ * @param method - JSON-RPC method name
+ * @param handler - Handler function invoked with the parsed params
+ */
+function registerHandler(method, handler) {
+    handlers[method] = handler;
+    handlerMeta[method] = { method };
+}
+/**
+ * Return a sorted list of all registered method names in the stdio transport.
+ * @returns Array of method name strings in alphabetical order
+ */
+function listRegisteredMethods() {
+    return Object.keys(handlerMeta).sort();
+}
+/**
+ * Look up a registered handler by method name.
+ * @param method - JSON-RPC method name to look up
+ * @returns The handler function, or `undefined` if not registered
+ */
+function getHandler(method) {
+    return handlers[method];
+}
+function makeError(id, code, message, data) {
+    return { jsonrpc: '2.0', id: id ?? null, error: { code, message, data } };
+}
+/**
+ * Start the stdio JSON-RPC 2.0 transport, reading requests from stdin and writing responses to stdout.
+ * Registers built-in handlers for `initialize`, `notifications/initialized`, `shutdown`, and `exit`.
+ * @param opts - Optional stream overrides (input, output, stderr) and environment; defaults to process streams
+ */
+function startTransport(opts = {}) {
+    const runtimeConfig = (0, runtimeConfig_1.getRuntimeConfig)();
+    const verbose = runtimeConfig.logging.verbose;
+    const protocolLog = runtimeConfig.logging.protocol; // raw frames (parsed) logging
+    const diag = runtimeConfig.logging.diagnostics || verbose; // banner + environment snapshot
+    const log = (level, msg, extra) => {
+        if (level === 'debug' && !verbose)
+            return;
+        const ts = new Date().toISOString();
+        const line = `[${ts}] [${level}] ${msg}`;
+        try {
+            (opts.stderr || process.stderr).write(line + (extra ? ` ${JSON.stringify(extra)}` : '') + '\n');
+        }
+        catch { /* ignore */ }
+    };
+    if (diag) {
+        log('info', 'startup', {
+            version: VERSION,
+            pid: process.pid,
+            node: process.version,
+            cwd: process.cwd(),
+            mutationEnabled: runtimeConfig.mutationEnabled,
+            verbose,
+            protocolLog,
+            diagnosticsEnabled: runtimeConfig.logging.diagnostics
+        });
+    }
+    // Global crash / rejection safety net to aid diagnostics in host clients that only see silent exits.
+    // Note: process.exit() is handled by the unified shutdownGuard in index.ts (Issue #36 fix).
+    // This handler only logs — the guard prevents duplicate exit() races.
+    process.on('uncaughtException', (err) => {
+        log('error', 'uncaughtException', { message: err.message, stack: err.stack });
+    });
+    process.on('unhandledRejection', (reason) => {
+        const msg = typeof reason === 'object' && reason && 'message' in reason ? reason.message : String(reason);
+        log('error', 'unhandledRejection', { reason: msg });
+    });
+    // Handshake state & helpers (deterministic: initialize result flushes, then server/ready)
+    let initialized = false;
+    let readyEmitted = false;
+    function emitReady(reason) {
+        if (readyEmitted)
+            return;
+        readyEmitted = true;
+        try {
+            (opts.output || process.stdout).write(JSON.stringify({ jsonrpc: '2.0', method: 'server/ready', params: { version: VERSION, reason } }) + '\n');
+            (opts.output || process.stdout).write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/tools/list_changed', params: {} }) + '\n');
+        }
+        catch { /* ignore */ }
+    }
+    // Replace initialize handler with direct interception below to control write callback ordering.
+    registerHandler('initialize', (params) => {
+        // This body will be bypassed by explicit fast-path in line reader (kept for compatibility if called indirectly)
+        const p = params;
+        return {
+            protocolVersion: p?.protocolVersion || '2025-06-18',
+            serverInfo: { name: 'index', version: VERSION },
+            capabilities: { roots: { listChanged: true }, tools: { listChanged: true } }
+        };
+    });
+    // Accept notification some clients send post-initialize; respond benignly (single registration)
+    registerHandler('notifications/initialized', () => ({ acknowledged: true }));
+    registerHandler('shutdown', () => ({ shuttingDown: true }));
+    registerHandler('exit', () => { setTimeout(() => process.exit(0), 0); return { exiting: true }; });
+    // Use readline only for input parsing; do NOT set output to avoid echoing client-sent
+    // JSON-RPC request lines back to stdout (which confused tests expecting only server
+    // responses and caused false negatives when matching initialize/result frames).
+    const rl = (0, readline_1.createInterface)({ input: opts.input || process.stdin });
+    const respondFn = (obj) => {
+        if (protocolLog) {
+            const base = { id: obj.id ?? null };
+            if ('error' in obj)
+                base.error = obj.error.code;
+            else
+                base.ok = true;
+            log('debug', 'send', base);
+        }
+        (opts.output || process.stdout).write(JSON.stringify(obj) + '\n');
+    };
+    // NOTE: Unlike earlier versions we DO NOT emit server/ready until after initialize response.
+    // This matches stricter clients (and reference PowerShell server) that expect handshake ordering.
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        if (trimmed === 'quit') {
+            process.exit(0);
+        }
+        let req;
+        try {
+            req = JSON.parse(trimmed);
+            if (protocolLog) {
+                log('debug', 'recv', { id: req.id ?? null, method: req.method });
+            }
+        }
+        catch (err) {
+            log('error', 'parse_error', { raw: trimmed.slice(0, 200) });
+            respondFn(makeError(null, -32700, 'Parse error'));
+            return;
+        }
+        if (req.jsonrpc !== '2.0' || !req.method) {
+            respondFn(makeError(req.id ?? null, -32600, 'Invalid Request'));
+            return;
+        }
+        // Fast-path initialize for deterministic ordering: respond immediately with write callback then schedule ready.
+        if (req.method === 'initialize') {
+            const p = req.params;
+            if (initialized) {
+                respondFn(makeError(req.id ?? null, -32600, 'Already initialized'));
+                return;
+            }
+            initialized = true;
+            // Reuse registered initialize handler so future shared logic (capability changes, root listing, etc.) stays centralized.
+            const initHandler = handlers['initialize'];
+            const start = Date.now();
+            let resultPayload;
+            try {
+                resultPayload = initHandler ? initHandler(req.params) : {
+                    protocolVersion: p?.protocolVersion || '2025-06-18',
+                    serverInfo: { name: 'index', version: VERSION },
+                    capabilities: { roots: { listChanged: true }, tools: { listChanged: true } }
+                };
+            }
+            catch (e) {
+                respondFn(makeError(req.id ?? null, -32603, 'Initialize handler failure', { message: e?.message }));
+                return;
+            }
+            // Support promise return from handler
+            Promise.resolve(resultPayload).then(resolved => {
+                const dur = Date.now() - start;
+                const rec = metrics['initialize'] || (metrics['initialize'] = { count: 0, totalMs: 0, maxMs: 0 });
+                rec.count++;
+                rec.totalMs += dur;
+                if (dur > rec.maxMs)
+                    rec.maxMs = dur;
+                const initResult = { jsonrpc: '2.0', id: req.id ?? 1, result: resolved };
+                try {
+                    if (protocolLog) {
+                        log('debug', 'respond_success', { id: req.id ?? 1, method: 'initialize' });
+                    }
+                    (opts.output || process.stdout).write(JSON.stringify(initResult) + '\n', () => {
+                        // Primary ready emission via macrotask after write flush
+                        setTimeout(() => emitReady('post-initialize'), 0);
+                        // Microtask fallback (parity with minimal server) for extreme scheduler edge cases
+                        queueMicrotask(() => { if (!readyEmitted)
+                            emitReady('post-initialize-microtask'); });
+                    });
+                }
+                catch {
+                    respondFn(makeError(req.id ?? null, -32603, 'Failed to write initialize result'));
+                }
+            });
+            return;
+        }
+        const handler = handlers[req.method];
+        if (!handler) {
+            // Provide richer context for missing method to help client authors.
+            const available = listRegisteredMethods();
+            log('debug', 'method_not_found', { requested: req.method, availableCount: available.length });
+            respondFn(makeError(req.id ?? null, -32601, 'Method not found', { method: req.method, available }));
+            return;
+        }
+        // Pre-dispatch parameter validation using registry input schemas (when available)
+        try {
+            const validation = (0, validationService_1.validateParams)(req.method, req.params);
+            if (!validation.ok) {
+                respondFn(makeError(req.id ?? null, -32602, 'Invalid params', { method: req.method, errors: validation.errors }));
+                return;
+            }
+        }
+        catch (e) { /* fail-open on validator issues */ }
+        const start = Date.now();
+        Promise.resolve()
+            .then(() => handler(req.params))
+            .then(result => {
+            if (!initialized) {
+                log('debug', 'call_before_initialize', { method: req.method });
+            }
+            const dur = Date.now() - start;
+            const rec = metrics[req.method] || (metrics[req.method] = { count: 0, totalMs: 0, maxMs: 0 });
+            rec.count++;
+            rec.totalMs += dur;
+            if (dur > rec.maxMs)
+                rec.maxMs = dur;
+            if (req.id !== undefined && req.id !== null) {
+                try {
+                    if (protocolLog || verbose)
+                        log('debug', 'respond_success', { id: req.id, method: req.method });
+                }
+                catch { /* ignore */ }
+                respondFn({ jsonrpc: '2.0', id: req.id, result });
+            }
+        })
+            .catch(e => {
+            const dur = Date.now() - start;
+            const rec = metrics[req.method] || (metrics[req.method] = { count: 0, totalMs: 0, maxMs: 0 });
+            rec.count++;
+            rec.totalMs += dur;
+            if (dur > rec.maxMs)
+                rec.maxMs = dur;
+            const maybeErr = e;
+            if (maybeErr && typeof maybeErr === 'object' && Number.isSafeInteger(maybeErr.code)) {
+                log('error', 'handler_error', { method: req.method, message: maybeErr.message, code: maybeErr.code });
+                respondFn(makeError(req.id ?? null, maybeErr.code, maybeErr.message || 'Error', { method: req.method, ...(maybeErr.data || {}) }));
+                return;
+            }
+            const errObj = e instanceof Error ? { message: e.message, stack: e.stack } : { message: 'Unknown error', value: e };
+            log('error', 'handler_error', { method: req.method, ...errObj });
+            respondFn(makeError(req.id ?? null, -32603, 'Internal error', { method: req.method, ...errObj }));
+        });
+    });
+}
+if (require.main === module) {
+    startTransport();
+}

package/dist/server/transportFactory.d.ts

@@ -0,0 +1,21 @@
+export declare const dynamicImport: (specifier: string) => any;
+/**
+ * Set up stdout diagnostics wrapper for backpressure monitoring.
+ * Enabled via INDEX_SERVER_TRACE=healthMixed.
+ */
+export declare function setupStdoutDiagnostics(): Promise<void>;
+/**
+ * Override the internal request dispatcher to retain error.data & emit diagnostics.
+ * The upstream SDK has used both `_onRequest` (camel) and `_onrequest` (lower) across versions;
+ * we defensively hook whichever exists and assign our wrapper to BOTH names.
+ */
+export declare function setupDispatcherOverride(server: any): void;
+/**
+ * Wrap transport.send to detect initialize response flush and emit ready.
+ */
+export declare function wrapTransportSend(server: any, transport: any): void;
+/**
+ * Explicit keepalive to avoid premature process exit before first client request.
+ * @param label - Optional label for diagnostic log messages (e.g. 'secondary')
+ */
+export declare function setupKeepalive(label?: string): void;