codedeep-mcp 0.1.0

package/dist/git/runner.js

@@ -0,0 +1,204 @@
+// GitRunner — the project's only subprocess boundary. Wraps execFile('git')
+// with a timeout, an output cap, an AbortController per call (so shutdown
+// can kill every in-flight child), and an error taxonomy that callers
+// branch on:
+//
+//   'git-missing'  spawn ENOENT — git isn't installed. Disables the runner
+//                  for the whole session (one warn, zero further spawns).
+//   'disabled'     a call made after disableForSession; never spawned.
+//   'aborted'      killed via abortAll() (shutdown) — log at debug only.
+//   'timeout'      exceeded timeoutMs and was SIGTERM'd by execFile.
+//   'maxbuffer'    output exceeded maxBuffer — skip this result, do NOT
+//                  disable the session.
+//   'exit'         git RAN and exited non-zero (numeric exit code). exit
+//                  128 is *normal* for "not a git repository" / "no
+//                  commits yet" — callers decide log level, the runner
+//                  never warns on 'exit'. This is the ONLY kind callers
+//                  may treat as an authoritative negative answer.
+//   'spawn-failed' the child never ran or died abnormally: spawn errors
+//                  other than ENOENT (EACCES/EMFILE/EAGAIN), external
+//                  signal kills, anything unexplained. Transient — must
+//                  never be read as "not a repository".
+//
+// Git failures must never surface to a tool response: callers degrade by
+// omitting sections. The runner is also the warn-dedup point (warnOnce) so
+// a failing command logs once per session, not once per tool call.
+import { execFile } from 'node:child_process';
+import { errMsg, log } from '../logger.js';
+export class GitError extends Error {
+    kind;
+    exitCode;
+    stderr;
+    constructor(kind, message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = 'GitError';
+        this.kind = kind;
+        if (opts.exitCode !== undefined)
+            this.exitCode = opts.exitCode;
+        if (opts.stderr !== undefined)
+            this.stderr = opts.stderr;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024;
+// Keep GitError.stderr bounded — git can echo whole pathspecs into stderr.
+const STDERR_CAP = 500;
+// Prepended to every invocation — pins of user-config settings that
+// would otherwise corrupt parsing or behavior:
+// - core.quotepath=false: without it git %-escapes non-ASCII bytes in
+//   --name-only output ("\303\251"-style), which would never match the
+//   raw POSIX paths used as index keys.
+// - log.showSignature=false: a user-level log.showSignature=true would
+//   inject GPG status lines into every log output, which the analyzer
+//   would otherwise parse as file paths.
+// - log.follow=false: a user-level log.follow=true silently turns the
+//   single-pathspec recentCommits query into a full-history rename walk
+//   (the documented no---follow decision).
+// - diff.relative=false: a user-level diff.relative=true makes the bulk
+//   `log --name-only` emit cwd-relative paths and DROP paths outside the
+//   cwd subtree — in monorepo-subdirectory mode that zeroes the whole
+//   analysis. The branch diff's explicit --relative flag still wins.
+const GIT_ARGS_PREFIX = [
+    '-c', 'core.quotepath=false',
+    '-c', 'log.showSignature=false',
+    '-c', 'log.follow=false',
+    '-c', 'diff.relative=false',
+];
+// Inherited git environment would silently override cwd-based repo
+// discovery (GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE/GIT_COMMON_DIR/
+// GIT_OBJECT_DIRECTORY), block upward discovery entirely
+// (GIT_CEILING_DIRECTORIES — fatal for monorepo-subdirectory roots,
+// where the clean exit-128 would read as "no repo" and wipe the cache),
+// or inject parent-process config (GIT_CONFIG_PARAMETERS /
+// GIT_CONFIG_COUNT, set by hooks). Strip them all so discovery is
+// always anchored to the project root passed as cwd.
+function sanitizedEnv() {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_COMMON_DIR;
+    delete env.GIT_OBJECT_DIRECTORY;
+    delete env.GIT_CEILING_DIRECTORIES;
+    delete env.GIT_CONFIG_PARAMETERS;
+    delete env.GIT_CONFIG_COUNT;
+    return env;
+}
+export class GitRunner {
+    cwd;
+    gitBin;
+    execFileImpl;
+    controllers = new Set();
+    warned = new Set();
+    disabledReason = null;
+    constructor(cwd, opts = {}) {
+        this.cwd = cwd;
+        this.gitBin = opts.gitBin ?? 'git';
+        this.execFileImpl = opts.execFileImpl ?? execFile;
+    }
+    get disabled() {
+        return this.disabledReason !== null;
+    }
+    // Permanent for the session (git missing or gitEnabled=false). Later
+    // run()/tryRun() calls fail fast without spawning.
+    disableForSession(reason) {
+        if (this.disabledReason !== null)
+            return;
+        this.disabledReason = reason;
+        this.warnOnce('disabled', `git: disabled for this session: ${reason}`);
+    }
+    warnOnce(key, msg) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        log.warn(msg);
+    }
+    // Shutdown path: abort every in-flight child. Their promises reject with
+    // kind 'aborted'; callers log those at debug.
+    abortAll() {
+        for (const controller of this.controllers)
+            controller.abort();
+    }
+    async run(args, opts = {}) {
+        if (this.disabledReason !== null) {
+            throw new GitError('disabled', `git disabled: ${this.disabledReason}`);
+        }
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        try {
+            return await new Promise((resolvePromise, rejectPromise) => {
+                this.execFileImpl(this.gitBin, [...GIT_ARGS_PREFIX, ...args], {
+                    cwd: this.cwd,
+                    env: sanitizedEnv(),
+                    encoding: 'utf8',
+                    timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                    maxBuffer: opts.maxBuffer ?? DEFAULT_MAX_BUFFER,
+                    signal: controller.signal,
+                    windowsHide: true,
+                }, (err, stdout, stderr) => {
+                    if (err === null) {
+                        resolvePromise(stdout);
+                        return;
+                    }
+                    rejectPromise(this.classify(err, stderr ?? '', controller, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS));
+                });
+            });
+        }
+        finally {
+            this.controllers.delete(controller);
+        }
+    }
+    // null on any failure; logs at debug. For call sites where the caller
+    // doesn't branch on the failure kind (cheap per-call queries).
+    async tryRun(args, opts = {}) {
+        try {
+            return await this.run(args, opts);
+        }
+        catch (err) {
+            log.debug(`git: ${args[0] ?? '?'} failed: ${errMsg(err)}`);
+            return null;
+        }
+    }
+    classify(err, stderr, controller, timeoutMs) {
+        const stderrCapped = stderr.trim().slice(0, STDERR_CAP);
+        // Our own abort also reports killed/ABORT_ERR — check the signal first
+        // so shutdown never masquerades as a timeout.
+        if (controller.signal.aborted) {
+            return new GitError('aborted', 'git call aborted', { cause: err });
+        }
+        if (err.code === 'ENOENT') {
+            this.disableForSession(`'${this.gitBin}' not found on PATH`);
+            return new GitError('git-missing', `git executable not found: ${this.gitBin}`, {
+                cause: err,
+            });
+        }
+        if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            return new GitError('maxbuffer', 'git output exceeded maxBuffer', {
+                stderr: stderrCapped,
+                cause: err,
+            });
+        }
+        if (err.killed === true) {
+            return new GitError('timeout', `git timed out after ${timeoutMs}ms`, {
+                stderr: stderrCapped,
+                cause: err,
+            });
+        }
+        if (typeof err.code === 'number') {
+            return new GitError('exit', `git exited with code ${err.code}`, {
+                exitCode: err.code,
+                stderr: stderrCapped,
+                cause: err,
+            });
+        }
+        // Anything left never produced a numeric exit: spawn errors with
+        // string errno codes (EACCES/EMFILE/EAGAIN), external signal kills
+        // (code null, signal set), or unknown shapes. These are transient —
+        // classifying them as 'exit' would let the detection probe read an
+        // fd-pressure blip as "not a repository" and wipe the cache.
+        return new GitError('spawn-failed', errMsg(err), {
+            stderr: stderrCapped,
+            cause: err,
+        });
+    }
+}

package/dist/index.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig, resolveCacheDir } from "./config.js";
+import { GitService } from "./git/git-service.js";
+import { CodeIndex } from "./indexer/code-index.js";
+import { Indexer } from "./indexer/pipeline.js";
+import { Watcher } from "./indexer/watcher.js";
+import { errMsg, log } from "./logger.js";
+import { createServer } from "./server.js";
+let initial;
+try {
+    initial = loadConfig();
+}
+catch (err) {
+    log.error(`codedeep-mcp: invalid config: ${errMsg(err)}`);
+    process.exit(1);
+}
+let cacheDir;
+try {
+    cacheDir = await resolveCacheDir(initial);
+}
+catch (err) {
+    log.error(`codedeep-mcp: failed to resolve cache directory: ${errMsg(err)}`);
+    process.exit(1);
+}
+const config = Object.freeze({ ...initial, cacheDir });
+const index = new CodeIndex(config.projectRoot);
+const indexer = new Indexer(config, index);
+const indexingPromise = (async () => {
+    const loaded = await index.load(indexer.cachePath);
+    log.debug(loaded
+        ? "Indexer: cache loaded; running indexChanged"
+        : "Indexer: no cache; running indexAll");
+    // The run guard drops (not queues) concurrent requests. Nothing else can
+    // hold it this early — the watcher defers until `ready`, which only the
+    // startup run sets — so a refusal here means a code change broke that
+    // invariant; surface it loudly rather than papering over it with retries.
+    const ran = loaded ? await indexer.indexChanged() : await indexer.indexAll();
+    if (!ran) {
+        log.error("Indexer: startup indexing refused by run guard; index is stale");
+    }
+})();
+// Attach .catch synchronously so a rejection during indexing can't crash the
+// process under --unhandled-rejections=throw. The server stays up either way.
+indexingPromise.catch((err) => {
+    log.error(`Indexer top-level failure: ${errMsg(err)}`);
+});
+// Safe to start while the cache load / background index runs: the watcher
+// defers its flushes until `indexer.ready`, so it can neither race the
+// load's Map swap nor steal the startup run's concurrency guard.
+let watcher = null;
+if (config.watch) {
+    watcher = new Watcher(indexer, index, config);
+    watcher.start();
+}
+// Git enrichment starts strictly AFTER the startup index resolves: the
+// analyzer filters to fileByPath membership, so running against a
+// cold/empty index would persist an EMPTY analysis whose gitMeta marks
+// it fresh for a day. The .catch(() => {}) keeps git alive when
+// indexChanged fails over a successfully loaded cache. Tool calls served
+// before the first analysis simply omit git sections (warm starts get
+// them instantly from the v5 cache).
+// git.start() never throws (it catches internally), and the leading
+// .catch makes the chain unrejectable — one line, one error path.
+const git = new GitService(config, index, indexer.cachePath);
+void indexingPromise.catch(() => { }).then(() => git.start());
+// Flush-on-shutdown — the watcher's per-flush saves bound the loss window,
+// but exiting between flushes shouldn't discard the last debounce batch.
+// watcher.close() drains that batch and persists through its normal save
+// path (and refuses to touch the index before the startup run completes),
+// so no separate save is needed here.
+//
+// The graceful work is raced against a watchdog — a save wedged on a
+// dead network mount must not orphan the process after the client is
+// gone. Exit codes are honest: 0 only when the flush completed; 1 when
+// the watchdog cut it, it failed, or a signal escalated past it.
+const SHUTDOWN_WATCHDOG_MS = 10_000;
+let shuttingDown = false;
+function shutdown(reason, waitForStartup, 
+// Signals escalate an in-flight graceful shutdown to an immediate
+// exit. Duplicate stdin events ('end' then 'close' fire back-to-back
+// on EOF) must NOT — they'd cut the flush they themselves started.
+escalateIfShuttingDown = false) {
+    if (shuttingDown) {
+        if (escalateIfShuttingDown) {
+            log.debug("codedeep-mcp: signal during shutdown; exiting immediately");
+            process.exit(1);
+        }
+        return;
+    }
+    shuttingDown = true;
+    log.debug(`codedeep-mcp: ${reason}; flushing watcher before exit`);
+    void (async () => {
+        let code = 1;
+        try {
+            const work = (async () => {
+                // Client disconnect is not urgent — let an in-flight startup
+                // index finish (it persists internally) as the pre-watcher
+                // server did. Signals skip the wait: the user wants out now.
+                if (waitForStartup)
+                    await indexingPromise.catch(() => { });
+                // Sync-fast: aborts in-flight git children. Never awaits the
+                // analysis — the watchdog must not ride on a git subprocess.
+                git.close();
+                await watcher?.close();
+            })();
+            const watchdog = new Promise((resolve) => {
+                const t = setTimeout(() => resolve("timeout"), SHUTDOWN_WATCHDOG_MS);
+                t.unref();
+            });
+            const outcome = await Promise.race([
+                work.then(() => "done"),
+                watchdog,
+            ]);
+            if (outcome === "done")
+                code = 0;
+            else
+                log.warn("codedeep-mcp: shutdown watchdog fired; exiting with flush incomplete");
+        }
+        catch (err) {
+            log.warn(`codedeep-mcp: shutdown flush failed: ${errMsg(err)}`);
+        }
+        finally {
+            process.exit(code);
+        }
+    })();
+}
+// `on`, not `once`: a REPEATED signal must reach the escalate path above
+// instead of falling back to default disposition (uncontrolled kill).
+process.on("SIGINT", () => shutdown("SIGINT received", false, true));
+process.on("SIGTERM", () => shutdown("SIGTERM received", false, true));
+// The PRIMARY MCP shutdown path is the client closing stdin — without
+// this hook the unref'd watcher timer never fires again and the process
+// exits with the last debounce batch unflushed and unsaved.
+process.stdin.once("end", () => shutdown("stdin closed", true));
+process.stdin.once("close", () => shutdown("stdin closed", true));
+const server = createServer({ index, indexer, config, git });
+await server.connect(new StdioServerTransport());