@colbymchenry/codegraph-darwin-x64 0.9.3 → 0.9.5

package/lib/dist/mcp/daemon.js

@@ -0,0 +1,403 @@
+"use strict";
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * One detached `codegraph serve --mcp` daemon process per project root,
+ * accepting N concurrent MCP clients over a Unix-domain socket (or named pipe
+ * on Windows). Each incoming connection gets its own {@link MCPSession}; all
+ * sessions share a single {@link MCPEngine}, which means a single file watcher
+ * (one inotify set), a single SQLite connection (one WAL writer), and a single
+ * tree-sitter warm-up — paid once, amortized across every agent talking to the
+ * project.
+ *
+ * Lifecycle (see also `./index.ts` and `./proxy.ts`):
+ *   - The daemon is spawned **detached** (its own session/process group, stdio
+ *     decoupled) by the first launcher that finds no daemon running. It is NOT
+ *     a child of any MCP host, so closing one terminal / Ctrl-C'ing one session
+ *     can't take it down and sever the others. That's why this process has no
+ *     PPID watchdog: it deliberately outlives every individual client.
+ *   - Every MCP host talks to the daemon through a thin `proxy` process (the
+ *     thing the host actually spawned). The proxy keeps the #277 PPID watchdog,
+ *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
+ *     close then decrements the daemon's refcount.
+ *   - When the last client disconnects the daemon lingers for
+ *     `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
+ *     runs in the same project don't repay startup, then exits cleanly. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *
+ * What this file owns:
+ *   - Listening on the daemon socket and spawning per-connection sessions.
+ *   - The handshake "hello" line that lets a proxy verify it found a
+ *     same-version daemon before piping any JSON-RPC through it.
+ *   - The lockfile (`.codegraph/daemon.pid`) competing daemons arbitrate
+ *     against — atomic `O_EXCL` create with the full record written in the same
+ *     breath (no empty-file window) + cleanup on exit.
+ *   - Reference counting + idle timeout.
+ *   - Graceful shutdown on SIGTERM/SIGINT and idle exit.
+ *
+ * What this file does NOT own:
+ *   - The proxy side (`./proxy.ts`).
+ *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
+ *   - The MCP protocol state machine — that's `./session.ts`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_HELLO_LINE_BYTES = exports.Daemon = void 0;
+exports.tryAcquireDaemonLock = tryAcquireDaemonLock;
+exports.clearStaleDaemonLock = clearStaleDaemonLock;
+exports.isProcessAlive = isProcessAlive;
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const engine_1 = require("./engine");
+const session_1 = require("./session");
+const transport_1 = require("./transport");
+const daemon_paths_1 = require("./daemon-paths");
+const version_1 = require("./version");
+/** Default idle linger after the last client disconnects. */
+const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+/** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
+const MAX_HELLO_LINE_BYTES = 4096;
+exports.MAX_HELLO_LINE_BYTES = MAX_HELLO_LINE_BYTES;
+/**
+ * Run as the shared daemon for `projectRoot`. Resolves once the socket is
+ * listening. The Daemon owns the socket, the engine, and the lockfile until
+ * `stop()` is called or it exits on idle/signal.
+ *
+ * Race-safe: callers must first call `tryAcquireDaemonLock(projectRoot)` and
+ * only construct a Daemon if they got the lock (`kind: 'acquired'`). The atomic
+ * `O_EXCL` create inside the acquire helper — which now also writes the full
+ * record before returning — is the only synchronization between competing
+ * daemons.
+ */
+class Daemon {
+    projectRoot;
+    server = null;
+    clients = new Set();
+    idleTimer = null;
+    idleTimeoutMs;
+    engine;
+    stopping = false;
+    socketPath;
+    pidPath;
+    constructor(projectRoot, opts = {}) {
+        this.projectRoot = projectRoot;
+        this.socketPath = (0, daemon_paths_1.getDaemonSocketPath)(projectRoot);
+        this.pidPath = (0, daemon_paths_1.getDaemonPidPath)(projectRoot);
+        this.idleTimeoutMs = opts.idleTimeoutMs ?? resolveIdleTimeoutMs();
+        this.engine = new engine_1.MCPEngine();
+        this.engine.setProjectPathHint(projectRoot);
+    }
+    /**
+     * Bind the socket, kick off engine init, and register signal handlers. The
+     * lockfile body was already written atomically by `tryAcquireDaemonLock`, so
+     * there is nothing to write here. The promise resolves once the server is
+     * listening — the daemon then sticks around until idle/shutdown.
+     */
+    async start() {
+        // Engine init is deliberately backgrounded — see #172. The first session
+        // to land waits on `ensureInitialized` either way, and unloaded sessions
+        // (cross-project tool calls only) shouldn't pay any open cost.
+        void this.engine.ensureInitialized(this.projectRoot);
+        // Stale socket file (left over from a SIGKILL'd previous daemon) will
+        // wedge `listen` with EADDRINUSE. We arrived here holding the lockfile,
+        // which means there's no live daemon, so it's safe to clear.
+        if (process.platform !== 'win32') {
+            try {
+                fs.unlinkSync(this.socketPath);
+            }
+            catch { /* not-exists is fine */ }
+        }
+        await new Promise((resolve, reject) => {
+            const server = net.createServer((socket) => this.handleConnection(socket));
+            server.once('error', (err) => reject(err));
+            server.listen(this.socketPath, () => {
+                // POSIX: tighten permissions to user-only — the socket lives under
+                // `.codegraph/`, which is git-ignored but may be on a shared FS.
+                if (process.platform !== 'win32') {
+                    try {
+                        fs.chmodSync(this.socketPath, 0o600);
+                    }
+                    catch { /* best-effort */ }
+                }
+                this.server = server;
+                resolve();
+            });
+        });
+        const lock = {
+            pid: process.pid,
+            version: version_1.CodeGraphPackageVersion,
+            socketPath: this.socketPath,
+            startedAt: Date.now(),
+        };
+        process.stderr.write(`[CodeGraph daemon] Listening on ${this.socketPath} (pid ${process.pid}, v${version_1.CodeGraphPackageVersion}). Idle timeout ${this.idleTimeoutMs}ms.\n`);
+        // No clients yet: arm the idle timer immediately so a daemon that nobody
+        // ever connects to (e.g. spawned then abandoned because the launcher died)
+        // doesn't pin resources forever.
+        this.armIdleTimer();
+        process.on('SIGINT', () => this.stop('SIGINT'));
+        process.on('SIGTERM', () => this.stop('SIGTERM'));
+        return { socketPath: this.socketPath, lock };
+    }
+    /** Currently-connected client count. Exposed for tests / status output. */
+    getClientCount() {
+        return this.clients.size;
+    }
+    /** The socket path the daemon is (or will be) listening on. */
+    getSocketPath() {
+        return this.socketPath;
+    }
+    /** Graceful shutdown: close all sessions, the engine, and clean up the lock. */
+    async stop(reason = 'stop') {
+        if (this.stopping)
+            return;
+        this.stopping = true;
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        process.stderr.write(`[CodeGraph daemon] Shutting down (${reason}; clients=${this.clients.size}).\n`);
+        for (const session of [...this.clients]) {
+            try {
+                session.stop();
+            }
+            catch { /* best-effort */ }
+        }
+        this.clients.clear();
+        if (this.server) {
+            await new Promise((resolve) => this.server.close(() => resolve()));
+            this.server = null;
+        }
+        this.engine.stop();
+        this.cleanupLockfile();
+        if (process.platform !== 'win32') {
+            try {
+                fs.unlinkSync(this.socketPath);
+            }
+            catch { /* may already be gone */ }
+        }
+        process.exit(0);
+    }
+    handleConnection(socket) {
+        // Hello first so the proxy can verify versions before piping any
+        // application bytes. The proxy reads exactly one line, then forwards.
+        const hello = {
+            codegraph: version_1.CodeGraphPackageVersion,
+            pid: process.pid,
+            socketPath: this.socketPath,
+            protocol: 1,
+        };
+        socket.write(JSON.stringify(hello) + '\n');
+        const transport = new transport_1.SocketTransport(socket);
+        const session = new session_1.MCPSession(transport, this.engine, {
+            explicitProjectPath: this.projectRoot,
+        });
+        transport.onClose(() => this.dropClient(session));
+        this.clients.add(session);
+        this.disarmIdleTimer();
+        session.start();
+    }
+    dropClient(session) {
+        if (!this.clients.delete(session))
+            return;
+        if (this.clients.size === 0)
+            this.armIdleTimer();
+    }
+    armIdleTimer() {
+        if (this.idleTimer || this.stopping)
+            return;
+        if (this.idleTimeoutMs <= 0)
+            return; // 0 = never idle-exit
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            // Last-second sanity check: if a connection landed between the timer
+            // firing and now, don't exit. (setImmediate-ordering is the only way
+            // this races; cheap to defend against.)
+            if (this.clients.size > 0) {
+                this.armIdleTimer();
+                return;
+            }
+            void this.stop('idle timeout');
+        }, this.idleTimeoutMs);
+        // Don't keep the event loop alive just for this — the net.Server keeps the
+        // loop alive while listening, so the timer still fires; once we stop() the
+        // loop should drain naturally.
+        this.idleTimer.unref?.();
+    }
+    disarmIdleTimer() {
+        if (!this.idleTimer)
+            return;
+        clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+    }
+    cleanupLockfile() {
+        try {
+            if (fs.existsSync(this.pidPath)) {
+                // Only remove if it still belongs to us — another daemon may have
+                // already taken over while we were shutting down (extremely rare).
+                const raw = fs.readFileSync(this.pidPath, 'utf8');
+                const info = (0, daemon_paths_1.decodeLockInfo)(raw);
+                if (info && info.pid === process.pid) {
+                    fs.unlinkSync(this.pidPath);
+                }
+            }
+        }
+        catch { /* best-effort; we're exiting anyway */ }
+    }
+}
+exports.Daemon = Daemon;
+/**
+ * Atomically create the daemon pidfile with its full record already in place.
+ * Returns either an `acquired` result (the caller is the daemon-elect and may
+ * construct a {@link Daemon}) or a `taken` result.
+ *
+ * must-fix 1 (issue #411 review): the lockfile must appear in ONE atomic step,
+ * already complete — never empty, even momentarily. The first attempt at this
+ * (`O_EXCL` create then a separate `writeSync`) left a microsecond window where
+ * the file existed but was empty; under concurrent daemon startup a third
+ * candidate could read that empty file, decode it as `null`, and `unlink` the
+ * winner's lock → two daemons (two watchers, two writers). The window was
+ * normally too small to hit, but the chokidar watcher's extra startup time made
+ * concurrent daemons overlap enough to reproduce it reliably.
+ *
+ * The fix writes the complete record to a private temp file, then hard-links it
+ * into place: `link()` is atomic AND exclusive (EEXIST if the target exists), so
+ * the pidfile becomes visible in one step already containing a full record.
+ * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
+ * There is no empty-file window at all.
+ */
+function tryAcquireDaemonLock(projectRoot) {
+    const pidPath = (0, daemon_paths_1.getDaemonPidPath)(projectRoot);
+    // Make sure the .codegraph/ directory exists — the daemon may be the first
+    // thing to touch it on a fresh-clone-but-already-initialized checkout.
+    fs.mkdirSync(path.dirname(pidPath), { recursive: true });
+    const info = {
+        pid: process.pid,
+        version: version_1.CodeGraphPackageVersion,
+        socketPath: (0, daemon_paths_1.getDaemonSocketPath)(projectRoot),
+        startedAt: Date.now(),
+    };
+    // Temp name is pid-scoped so racing candidates never collide on it.
+    const tmp = `${pidPath}.${process.pid}.tmp`;
+    let acquired = false;
+    try {
+        fs.writeFileSync(tmp, (0, daemon_paths_1.encodeLockInfo)(info), { mode: 0o600 });
+        try {
+            fs.linkSync(tmp, pidPath); // atomic + exclusive
+            acquired = true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* temp already gone */ }
+    }
+    if (acquired)
+        return { kind: 'acquired', pidPath, info };
+    // Taken. Because the pidfile was link'd atomically it always holds a complete
+    // record — `existing` is null only for a genuinely corrupt leftover, never a
+    // mid-write race.
+    let existing = null;
+    try {
+        existing = (0, daemon_paths_1.decodeLockInfo)(fs.readFileSync(pidPath, 'utf8'));
+    }
+    catch { /* unreadable lockfile — treat as malformed */ }
+    return { kind: 'taken', existing, pidPath };
+}
+/**
+ * Remove a stale pidfile, but only if it still names a dead process. Re-reads
+ * the file immediately before unlinking so we never delete a lock that a live
+ * daemon (re)acquired in the meantime.
+ *
+ * must-fix 1 (issue #411 review): the original unconditionally `unlink`'d,
+ * which let a racing candidate delete a healthy daemon's lock. Passing
+ * `expectedDeadPid` (the pid the caller believed was dead) makes the clear a
+ * compare-and-delete: bail if the file now holds a different pid, or any live
+ * pid. Returns true when the stale lock is gone (or was already gone).
+ */
+function clearStaleDaemonLock(pidPath, expectedDeadPid) {
+    try {
+        const raw = fs.readFileSync(pidPath, 'utf8');
+        const info = (0, daemon_paths_1.decodeLockInfo)(raw);
+        if (info) {
+            // A different pid took over since we read it — not ours to clear.
+            if (expectedDeadPid !== undefined && info.pid !== expectedDeadPid)
+                return false;
+            // Holder is actually alive — never clear a live daemon's lock.
+            if (info.pid > 0 && isProcessAlive(info.pid))
+                return false;
+        }
+        fs.unlinkSync(pidPath);
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            return true; // already gone
+        return false;
+    }
+}
+/**
+ * Probe whether `pid` is currently alive (signal-0). Treats EPERM as alive on
+ * every platform (the process exists, it's just not ours to signal) so we never
+ * mistake a live daemon for a dead one and clear its lock.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'EPERM')
+            return true; // exists, just not ours to signal
+        return false;
+    }
+}
+function resolveIdleTimeoutMs() {
+    const raw = process.env.CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_IDLE_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_IDLE_TIMEOUT_MS;
+    return Math.floor(parsed);
+}
+//# sourceMappingURL=daemon.js.map

package/lib/dist/mcp/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../../src/mcp/daemon.ts"],"names":[],"mappings":"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"}

package/lib/dist/mcp/engine.d.ts

@@ -0,0 +1,100 @@
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link CodeGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+import { ToolHandler } from './tools';
+export interface MCPEngineOptions {
+    /**
+     * Whether to start the file watcher when initializing. Daemon and direct
+     * modes both want this true; tests may set it false to keep the engine
+     * cheap. Honors {@link watchDisabledReason} regardless.
+     */
+    watch?: boolean;
+}
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+export declare class MCPEngine {
+    private cg;
+    private toolHandler;
+    private projectPath;
+    private initPromise;
+    private watcherStarted;
+    private opts;
+    private closed;
+    constructor(opts?: MCPEngineOptions);
+    /**
+     * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+     * project path (from the `--path` CLI flag) without yet opening it. This
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath: string): void;
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath(): string | null;
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler(): ToolHandler;
+    /** Whether the default project's CodeGraph is open. */
+    hasDefaultCodeGraph(): boolean;
+    /**
+     * Walk up from `searchFrom` to find the nearest `.codegraph/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    ensureInitialized(searchFrom: string): Promise<void>;
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom: string): void;
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop(): void;
+    private doInitialize;
+    /**
+     * Start file watching on the active CodeGraph instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    private startWatching;
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Background, never awaited.
+     */
+    private catchUpSync;
+}
+/**
+ * Parse and clamp the CODEGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+export declare function parseDebounceEnv(raw: string | undefined): number | undefined;
+//# sourceMappingURL=engine.d.ts.map

package/lib/dist/mcp/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,WAAW,CAAc;IAIjC,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,GAAE,gBAAqB;IAKvC;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK7C,0EAA0E;IAC1E,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,yEAAyE;IACzE,cAAc,IAAI,WAAW;IAI7B,uDAAuD;IACvD,mBAAmB,IAAI,OAAO;IAI9B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAsB7C;;;OAGG;IACH,IAAI,IAAI,IAAI;YAUE,YAAY;IAuB1B;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IA+CrB;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAgBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E"}