pi-gitnexus-fork 0.7.0

package/dist/mcp-client-stdio.js

@@ -0,0 +1,186 @@
+import spawn from 'cross-spawn';
+import { gitnexusCmd, MAX_OUTPUT_CHARS, spawnEnv } from './gitnexus';
+import { createMcpError } from './mcp-client';
+// ── StdioMcpClient ────────────────────────────────────────────────────────────
+/**
+ * Thin stdio JSON-RPC 2.0 client for `gitnexus mcp`.
+ *
+ * Communication is exclusively over the spawned process's stdin/stdout pipe —
+ * no network socket, no port. Only our process can write to the pipe.
+ *
+ * The MCP process is started lazily on the first callTool() invocation and
+ * kept alive for the session lifetime. stop() terminates it; the next callTool()
+ * re-spawns with the new cwd.
+ */
+export class StdioMcpClient {
+    proc = null;
+    buffer = '';
+    pending = new Map();
+    nextId = 2; // id 1 is reserved for the initialize handshake
+    startPromise = null;
+    /**
+     * Probe the local gitnexus binary. Returns true if it responds to --version.
+     * Static method for use by AutoMcpClient without instantiating.
+     */
+    static async probeLocalBinary() {
+        return new Promise((resolve) => {
+            const [bin, ...baseArgs] = gitnexusCmd;
+            const proc = spawn(bin, [...baseArgs, '--version'], {
+                stdio: 'ignore',
+                env: spawnEnv,
+            });
+            proc.on('close', (code) => resolve(code === 0));
+            proc.on('error', () => resolve(false));
+        });
+    }
+    /**
+     * Lazily spawn `gitnexus mcp` and complete the MCP initialize handshake.
+     * Idempotent — concurrent calls await the same promise; only one process spawns.
+     */
+    ensureStarted(cwd) {
+        if (this.proc)
+            return Promise.resolve();
+        if (this.startPromise)
+            return this.startPromise;
+        this.startPromise = new Promise((resolve_, reject) => {
+            const [bin, ...baseArgs] = gitnexusCmd;
+            const proc = spawn(bin, [...baseArgs, 'mcp'], {
+                cwd,
+                stdio: ['pipe', 'pipe', 'ignore'],
+                env: spawnEnv,
+            });
+            proc.on('error', (err) => {
+                this.startPromise = null;
+                reject(err);
+            });
+            proc.stdout.setEncoding('utf8');
+            proc.stdout.on('data', (chunk) => {
+                this.buffer += chunk;
+                const lines = this.buffer.split('\n');
+                this.buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        if (msg.id !== undefined) {
+                            const p = this.pending.get(msg.id);
+                            if (p) {
+                                this.pending.delete(msg.id);
+                                p.resolve(line);
+                            }
+                        }
+                    }
+                    catch { /* ignore malformed lines */ }
+                }
+            });
+            proc.on('close', () => {
+                this.proc = null;
+                this.startPromise = null;
+                for (const p of this.pending.values()) {
+                    p.reject(new Error('gitnexus mcp process exited'));
+                }
+                this.pending.clear();
+            });
+            // MCP initialize handshake
+            const initMsg = JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: { name: 'pi-gitnexus', version: '0.1.0' },
+                },
+            });
+            this.pending.set(1, {
+                resolve: () => {
+                    proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+                    this.proc = proc;
+                    resolve_();
+                },
+                reject: (err) => {
+                    this.startPromise = null;
+                    reject(err);
+                },
+            });
+            proc.stdin.write(initMsg + '\n');
+        });
+        return this.startPromise;
+    }
+    /**
+     * Call a gitnexus MCP tool and return its formatted text response.
+     * Starts the MCP process lazily if not already running.
+     */
+    async callTool(name, args, cwd) {
+        try {
+            await this.ensureStarted(cwd);
+        }
+        catch (error) {
+            throw createMcpError(error, 'Failed to start gitnexus mcp');
+        }
+        if (!this.proc)
+            throw createMcpError('GitNexus MCP is not running.');
+        const id = this.nextId++;
+        return new Promise((resolve_, reject_) => {
+            this.pending.set(id, {
+                resolve: (raw) => {
+                    try {
+                        const msg = JSON.parse(raw);
+                        if (msg.error) {
+                            reject_(createMcpError(msg.error.message));
+                            return;
+                        }
+                        const result = msg.result;
+                        if (!result?.content) {
+                            reject_(createMcpError('No response content returned from GitNexus MCP.'));
+                            return;
+                        }
+                        const text = result.content
+                            .filter((c) => c.type === 'text' && c.text)
+                            .map((c) => c.text)
+                            .join('\n');
+                        if (result.isError) {
+                            reject_(createMcpError(text || 'GitNexus MCP reported an error with no text payload.'));
+                            return;
+                        }
+                        if (!text) {
+                            reject_(createMcpError('GitNexus MCP returned an empty response.'));
+                            return;
+                        }
+                        resolve_('[GitNexus]\n' + text.slice(0, MAX_OUTPUT_CHARS));
+                    }
+                    catch (error) {
+                        reject_(createMcpError(error, 'Malformed response from GitNexus MCP.'));
+                    }
+                },
+                reject: (error) => reject_(createMcpError(error)),
+            });
+            const msg = JSON.stringify({
+                jsonrpc: '2.0',
+                id,
+                method: 'tools/call',
+                params: { name, arguments: args },
+            });
+            try {
+                this.proc.stdin.write(msg + '\n');
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reject_(createMcpError(error, 'Failed to write request to GitNexus MCP.'));
+            }
+        });
+    }
+    /** Terminate the MCP process. Called on session_start so the next session gets a fresh process. */
+    stop() {
+        if (this.proc) {
+            this.proc.kill('SIGTERM');
+            this.proc = null;
+        }
+        this.startPromise = null;
+        for (const p of this.pending.values()) {
+            p.reject(new Error('MCP client stopped'));
+        }
+        this.pending.clear();
+    }
+}

package/dist/mcp-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Abstraction over MCP transport mechanisms (stdio, remote HTTP).
+ * Implementations must be safe for concurrent `callTool()` invocations.
+ */
+export interface McpClient {
+    /** Call a named MCP tool with the given arguments, scoped to `cwd`. Returns formatted text. */
+    callTool(name: string, args: Record<string, unknown>, cwd: string): Promise<string>;
+    /** Terminate any open connections / processes. Idempotent. */
+    stop(): void;
+}
+/** Create a consistently-prefixed error from an unknown value. */
+export declare function createMcpError(error: unknown, fallback?: string): Error;
+export { StdioMcpClient } from "./mcp-client-stdio";
+import type { McpMode } from "./gitnexus";
+/**
+ * Auto-detecting MCP client that probes the local binary on first use.
+ * Falls back to remote HTTP if the local binary fails.
+ * Once selected, the chosen transport is cached for the session.
+ */
+export declare class AutoMcpClient implements McpClient {
+    private delegate;
+    private probePromise;
+    /**
+     * Probe the local gitnexus binary. Returns true if it responds to --version.
+     */
+    static probeLocalBinary(): Promise<boolean>;
+    /** Resolve the transport. Probes local binary once, then caches the result. */
+    private resolveClient;
+    callTool(name: string, args: Record<string, unknown>, cwd: string): Promise<string>;
+    stop(): void;
+}
+/**
+ * Create an McpClient based on the configured mode.
+ *
+ * @param mode     - Transport mode from config.
+ * @param serverUrl - Remote server URL (required for 'remote', optional for 'auto').
+ */
+export declare function createMcpClient(mode: McpMode, serverUrl: string): McpClient;
+/**
+ * Singleton MCP client. Reads config on first use and selects transport:
+ * - mode=remote → RemoteMcpClient
+ * - mode=auto → AutoMcpClient (probe local, fallback remote)
+ * - mode=local (or missing) → StdioMcpClient
+ */
+export declare const mcpClient: McpClient;

package/dist/mcp-client.js

@@ -0,0 +1,145 @@
+// ── JSON-RPC / MCP types ──────────────────────────────────────────────────────
+// ── Error helper ──────────────────────────────────────────────────────────────
+/** Create a consistently-prefixed error from an unknown value. */
+export function createMcpError(error, fallback = "GitNexus MCP request failed.") {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : fallback;
+    return new Error(`[GitNexus] ${message || fallback}`);
+}
+// ── Re-exports (lazy — avoids circular dependency) ─────────────────────────────
+export { StdioMcpClient } from "./mcp-client-stdio";
+import { RemoteMcpClient } from "./remote-mcp-client";
+/**
+ * Auto-detecting MCP client that probes the local binary on first use.
+ * Falls back to remote HTTP if the local binary fails.
+ * Once selected, the chosen transport is cached for the session.
+ */
+export class AutoMcpClient {
+    delegate = null;
+    probePromise = null;
+    /**
+     * Probe the local gitnexus binary. Returns true if it responds to --version.
+     */
+    static async probeLocalBinary() {
+        const { StdioMcpClient } = await import("./mcp-client-stdio");
+        return StdioMcpClient.probeLocalBinary();
+    }
+    /** Resolve the transport. Probes local binary once, then caches the result. */
+    async resolveClient() {
+        if (this.delegate)
+            return this.delegate;
+        if (this.probePromise)
+            return this.probePromise;
+        this.probePromise = (async () => {
+            const { McpClientFactory } = await import("./mcp-client-factory");
+            const { serverUrl } = McpClientFactory.loadConfig();
+            const localWorks = await AutoMcpClient.probeLocalBinary();
+            const client = localWorks
+                ? await McpClientFactory.createClient({ mode: "local" })
+                : new RemoteMcpClient({ serverUrl: serverUrl });
+            this.delegate = client;
+            return client;
+        })();
+        return this.probePromise;
+    }
+    async callTool(name, args, cwd) {
+        const client = await this.resolveClient();
+        return client.callTool(name, args, cwd);
+    }
+    stop() {
+        if (this.delegate) {
+            this.delegate.stop();
+            this.delegate = null;
+        }
+        this.probePromise = null;
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Create an McpClient based on the configured mode.
+ *
+ * @param mode     - Transport mode from config.
+ * @param serverUrl - Remote server URL (required for 'remote', optional for 'auto').
+ */
+export function createMcpClient(mode, serverUrl) {
+    switch (mode) {
+        case "remote":
+            return new RemoteMcpClient({ serverUrl });
+        case "auto":
+            return new AutoMcpClient();
+        default:
+            // Return a lazy proxy that defers StdioMcpClient instantiation.
+            // This avoids circular dependency: mcp-client-stdio imports from this module,
+            // so we can't eagerly import it here.
+            return createLazyStdioClient();
+    }
+}
+/**
+ * Create a lazy proxy McpClient that defers StdioMcpClient instantiation
+ * until the first method call. Avoids circular dependency issues.
+ */
+function createLazyStdioClient() {
+    let _instance = null;
+    let _pending = null;
+    const getInstance = async () => {
+        if (_instance)
+            return _instance;
+        if (_pending)
+            return _pending;
+        _pending = import("./mcp-client-stdio").then((mod) => {
+            _instance = new mod.StdioMcpClient();
+            return _instance;
+        });
+        return _pending;
+    };
+    return new Proxy({}, {
+        get(_, prop) {
+            if (prop === "stop") {
+                return () => {
+                    _instance?.stop();
+                };
+            }
+            if (prop === "callTool") {
+                return (name, args, cwd) => getInstance().then((c) => c.callTool(name, args, cwd));
+            }
+            return undefined;
+        },
+    });
+}
+// ── Singleton (config-aware, lazy) ─────────────────────────────────────────────
+/**
+ * Singleton MCP client. Reads config on first use and selects transport:
+ * - mode=remote → RemoteMcpClient
+ * - mode=auto → AutoMcpClient (probe local, fallback remote)
+ * - mode=local (or missing) → StdioMcpClient
+ */
+export const mcpClient = new Proxy({}, {
+    get(_, prop) {
+        if (prop === "stop") {
+            return () => {
+                _singletonInstance?.stop();
+            };
+        }
+        if (prop === "callTool") {
+            return (name, args, cwd) => getSingletonClient().then((c) => c.callTool(name, args, cwd));
+        }
+        return undefined;
+    },
+});
+let _singletonInstance = null;
+let _singletonPending = null;
+function getSingletonClient() {
+    if (_singletonInstance)
+        return Promise.resolve(_singletonInstance);
+    if (_singletonPending)
+        return _singletonPending;
+    _singletonPending = import("./mcp-client-factory").then((mod) => {
+        const { mode, serverUrl } = mod.McpClientFactory.loadConfig();
+        _singletonInstance = createMcpClient(mode, serverUrl ?? "");
+        return _singletonInstance;
+    });
+    return _singletonPending;
+}

package/dist/remote-mcp-client.d.ts

@@ -0,0 +1,43 @@
+export interface RemoteMcpClientConfig {
+    serverUrl: string;
+    timeout?: number;
+}
+/**
+ * RemoteMcpClient — StreamableHTTP transport to a GitNexus MCP server.
+ *
+ * Uses native fetch() for all communication. Completes the MCP initialize
+ * handshake on the first callTool() invocation and reuses the session.
+ */
+export declare class RemoteMcpClient {
+    private serverUrl;
+    private initialized;
+    private stopped;
+    private timeoutMs;
+    private initPromise;
+    private sessionId;
+    /**
+     * @param configOrUrl - Either a config object `{ serverUrl, timeout? }` or a plain URL string.
+     */
+    constructor(configOrUrl: RemoteMcpClientConfig | string);
+    /** Returns the configured server URL. */
+    getServerUrl(): string;
+    /** Returns whether the MCP initialize handshake has been completed. */
+    isInitialized(): boolean;
+    /**
+     * POST a JSON-RPC message and return the parsed response.
+     * Throws on network errors, timeouts, or MCP-level errors.
+     */
+    private rpcSend;
+    /**
+     * Complete MCP initialize handshake (idempotent for concurrent callers).
+     * Only runs once per client lifetime until stop() is called.
+     */
+    private ensureInitialized;
+    /**
+     * Call an MCP tool by name and return its formatted text response.
+     * Handles text content extraction, truncation, and error mapping.
+     */
+    callTool(name: string, args: Record<string, unknown>, _cwd?: string): Promise<string>;
+    /** Mark as stopped. Resets initialization state so next call re-initializes. */
+    stop(): void;
+}

package/dist/remote-mcp-client.js

@@ -0,0 +1,181 @@
+import { MAX_OUTPUT_CHARS } from "./gitnexus";
+const PREFIX = "[GitNexus]\n";
+/** Default timeout for a single MCP request (ms). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * RemoteMcpClient — StreamableHTTP transport to a GitNexus MCP server.
+ *
+ * Uses native fetch() for all communication. Completes the MCP initialize
+ * handshake on the first callTool() invocation and reuses the session.
+ */
+export class RemoteMcpClient {
+    serverUrl;
+    initialized = false;
+    stopped = false;
+    timeoutMs;
+    initPromise = null;
+    sessionId = null;
+    /**
+     * @param configOrUrl - Either a config object `{ serverUrl, timeout? }` or a plain URL string.
+     */
+    constructor(configOrUrl) {
+        if (typeof configOrUrl === "string") {
+            this.serverUrl = configOrUrl.replace(/\/+$/, "");
+            this.timeoutMs = DEFAULT_TIMEOUT_MS;
+        }
+        else {
+            this.serverUrl = (configOrUrl.serverUrl ?? "").replace(/\/+$/, "");
+            this.timeoutMs = configOrUrl.timeout ?? DEFAULT_TIMEOUT_MS;
+        }
+    }
+    /** Returns the configured server URL. */
+    getServerUrl() {
+        return this.serverUrl;
+    }
+    /** Returns whether the MCP initialize handshake has been completed. */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * POST a JSON-RPC message and return the parsed response.
+     * Throws on network errors, timeouts, or MCP-level errors.
+     */
+    async rpcSend(method, params) {
+        if (this.stopped)
+            throw new Error("[GitNexus] Remote MCP client is stopped.");
+        const body = {
+            jsonrpc: "2.0",
+            id: 1,
+            method,
+            ...(params !== undefined ? { params } : {}),
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+            };
+            if (this.sessionId)
+                headers["Mcp-Session-Id"] = this.sessionId;
+            const res = await Promise.race([
+                fetch(this.serverUrl, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                }),
+                new Promise((_, reject) => setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`[GitNexus] Remote MCP request timed out after ${this.timeoutMs}ms`));
+                }, this.timeoutMs)),
+            ]);
+            if (!res.ok) {
+                throw new Error(`[GitNexus] HTTP ${res.status}`);
+            }
+            // Capture session ID for StreamableHTTP session stickiness
+            const sid = res.headers.get("mcp-session-id");
+            if (sid)
+                this.sessionId = sid;
+            let data;
+            try {
+                data = (await res.json());
+            }
+            catch {
+                throw new Error("[GitNexus] Malformed JSON response from remote MCP.");
+            }
+            if (data.error) {
+                throw new Error(`[GitNexus] ${data.error.message || `MCP error ${data.error.code}`}`);
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("timed out"))
+                throw err;
+            if (err instanceof Error && err.message.startsWith("[GitNexus]"))
+                throw err;
+            throw new Error(`[GitNexus] ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Complete MCP initialize handshake (idempotent for concurrent callers).
+     * Only runs once per client lifetime until stop() is called.
+     */
+    ensureInitialized() {
+        if (this.initialized)
+            return Promise.resolve();
+        if (this.stopped)
+            return Promise.reject(new Error("[GitNexus] Remote MCP client is stopped."));
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            try {
+                await this.rpcSend("initialize", {
+                    protocolVersion: "2024-11-05",
+                    capabilities: {},
+                    clientInfo: { name: "pi-gitnexus", version: "0.1.0" },
+                });
+                // Send initialized notification (fire-and-forget)
+                try {
+                    await fetch(this.serverUrl, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            jsonrpc: "2.0",
+                            method: "notifications/initialized",
+                        }),
+                    });
+                }
+                catch {
+                    /* best-effort */
+                }
+                this.initialized = true;
+            }
+            catch (err) {
+                this.initPromise = null;
+                throw new Error(`[GitNexus] Remote MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        })();
+        return this.initPromise;
+    }
+    /**
+     * Call an MCP tool by name and return its formatted text response.
+     * Handles text content extraction, truncation, and error mapping.
+     */
+    async callTool(name, args, _cwd) {
+        await this.ensureInitialized();
+        if (this.stopped)
+            throw new Error("[GitNexus] Remote MCP client is stopped.");
+        const response = await this.rpcSend("tools/call", {
+            name,
+            arguments: args,
+        });
+        const result = response.result;
+        if (!result?.content) {
+            throw new Error("[GitNexus] No response content returned from remote MCP.");
+        }
+        const text = result.content
+            .filter((c) => c.type === "text" && c.text)
+            .map((c) => c.text)
+            .join("\n");
+        if (result.isError) {
+            throw new Error(`[GitNexus] ${text || "Remote MCP reported an error with no text payload."}`);
+        }
+        if (!text) {
+            throw new Error("[GitNexus] Remote MCP returned an empty response.");
+        }
+        // Truncate including the prefix so total stays within MAX_OUTPUT_CHARS
+        const available = MAX_OUTPUT_CHARS - PREFIX.length;
+        return PREFIX + text.slice(0, Math.max(0, available));
+    }
+    /** Mark as stopped. Resets initialization state so next call re-initializes. */
+    stop() {
+        this.stopped = false; // Allow re-use after stop
+        this.initialized = false;
+        this.initPromise = null;
+        this.sessionId = null;
+    }
+}

package/dist/repo-resolver.d.ts

@@ -0,0 +1,47 @@
+export interface RepoEntry {
+    name: string;
+    path: string;
+    remoteUrl?: string | null;
+}
+export interface RepoResolverConfig {
+    serverUrl: string;
+}
+/**
+ * RepoResolver — maps a host cwd to a server-side repo path.
+ *
+ * Strategy:
+ *  1. Fetch registry from GET <serverUrl>/api/repos
+ *  2. Match by git remote URL (most reliable)
+ *  3. Match by basename of cwd vs basename of server path
+ *  4. Fallback: return findGitNexusRoot(cwd)
+ *
+ * Uses instance-level cache so separate resolver instances don't share state.
+ */
+export declare class RepoResolver {
+    private serverUrl;
+    private registry;
+    private registryFetched;
+    private resolutionCache;
+    constructor(config: RepoResolverConfig);
+    /**
+     * Fetch the repo registry from the server.
+     * Only fetches once per instance; subsequent calls return cached data.
+     */
+    private fetchRegistry;
+    /** Clear cached registry and resolution cache. Re-fetches on next resolveRepo. */
+    refreshRegistry(): Promise<void>;
+    /** Return the currently cached registry entries. */
+    getRegistry(): RepoEntry[];
+    /**
+     * Resolve a host cwd to a server-side repo path (string).
+     * Uses instance-level resolution cache.
+     */
+    resolveRepo(cwd: string): Promise<string | null>;
+    private doResolve;
+    private getGitRemoteUrl;
+}
+/**
+ * Normalize a git remote URL for comparison.
+ * Strips trailing .git, protocol prefixes, and user@host: prefixes.
+ */
+export declare function normalizeGitUrl(url: string): string;