@ltm-alpha/alpha-cs 1.6.0

package/dist/mcp/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Alpha Code Sense MCP Server
+ *
+ * Model Context Protocol server that exposes Alpha Code Sense functionality
+ * as tools for AI assistants like Claude.
+ *
+ * @module mcp
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer } from 'codegraph';
+ *
+ * const server = new MCPServer('/path/to/project');
+ * await server.start();
+ * ```
+ *
+ * Runtime modes (decided in {@link MCPServer.start}):
+ *
+ * - **Direct** — one process serves one MCP client over stdio. The pre-#411
+ *   behavior; used when the user opts out (`CODEGRAPH_NO_DAEMON=1`), no
+ *   `.alpha-cs/` is reachable, or the daemon machinery fails for any reason.
+ * - **Proxy** — what an MCP host actually talks to when sharing is on: a thin
+ *   stdio↔socket pipe to the shared daemon. The proxy carries the #277 PPID
+ *   watchdog, so a SIGKILL'd host reaps its proxy promptly. See {@link ./proxy.ts}.
+ * - **Daemon** — a *detached* background process (its own session/process
+ *   group) that serves N proxies over a Unix-domain socket / named pipe,
+ *   sharing one Alpha Code Sense + watcher + SQLite handle. Spawned on demand; never a
+ *   child of any host, so it survives individual sessions and is reaped by
+ *   client-refcount + idle timeout. See {@link ./daemon.ts} and issue #411.
+ *
+ * The detached-daemon + always-proxy split is the fix for the review finding
+ * that the original in-process daemon (a) was the first host's child, so closing
+ * that terminal severed every other client, and (b) disabled the PPID watchdog,
+ * regressing #277 (orphaned daemons on host SIGKILL).
+ */
+/**
+ * Prefix every `process.stderr.write` chunk with an ISO-8601 timestamp. Called
+ * once, only when this process becomes the detached daemon — whose stderr is
+ * appended to `.alpha-cs/daemon.log`. Before #1431 no log line carried a
+ * timestamp, so watchdog kills and restarts could be counted but never placed
+ * in time. (The watchdog child writes its kill notice through its own
+ * inherited fd 2, bypassing this wrapper — it stamps that line itself.)
+ */
+export declare function timestampStderrLines(): void;
+/** Prepend `[<ISO-8601>] ` to a log chunk; unknown chunk types pass through. */
+export declare function stampLogChunk(chunk: string | Uint8Array): string | Uint8Array;
+/**
+ * Watchdog `progressPaths` for a server keyed on `root`'s index: the SQLite DB
+ * + its WAL. With these, the #850 liveness watchdog only kills on heartbeat
+ * silence when the DB files are NOT advancing — the same slow-disk deferral
+ * the CLI `index`/`init` path got in #1231. Without it, one >timeout
+ * synchronous statement on a big DB (multi-GB index behind Windows Defender)
+ * SIGKILLs a perfectly healthy daemon — and a daemon SIGKILL'd at the end of
+ * nearly every session is what ratcheted the WAL leak in #1431. A true wedge
+ * still dies: a wedged loop writes nothing, so the files stay still.
+ */
+export declare function watchdogProgressPaths(root: string | null): {
+    progressPaths?: string[];
+};
+/**
+ * MCP Server for Alpha Code Sense
+ *
+ * Implements the Model Context Protocol to expose Alpha Code Sense
+ * functionality as tools that can be called by AI assistants.
+ *
+ * Backwards-compatible constructor and `start()` signature with the
+ * pre-issue-#411 implementation: callers continue to do
+ * `new MCPServer(path).start()`. Internally we now pick from direct / proxy /
+ * daemon at start time.
+ */
+export declare class MCPServer {
+    private projectPath;
+    private session;
+    private engine;
+    private daemon;
+    private ppidWatchdog;
+    private livenessWatchdog;
+    private originalPpid;
+    private hostPpid;
+    private stopped;
+    private mode;
+    /** Project root whose writer.pid we hold in direct mode (#1740); released on stop. */
+    private writerLockRoot;
+    constructor(projectPath?: string);
+    /**
+     * Start the MCP server.
+     *
+     * Decision order:
+     *   1. `CODEGRAPH_NO_DAEMON=1` → direct mode (unchanged pre-#411 behavior).
+     *   2. `CODEGRAPH_DAEMON_INTERNAL=1` → we ARE the detached daemon; listen.
+     *   3. No `.alpha-cs/` reachable → direct mode (the daemon's lockfile and
+     *      socket both live under `.alpha-cs/`).
+     *   4. Otherwise connect to (or spawn) the shared daemon and proxy to it.
+     *
+     * On any unexpected failure in step 4 we transparently fall back to direct
+     * mode — a misbehaving daemon must never block a session from starting.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server. In daemon mode this triggers graceful shutdown of every
+     * connected session; in direct mode it mirrors the pre-#411 behavior (close
+     * cg, exit). Proxy mode never routes through here — the proxy exits itself.
+     */
+    stop(): void;
+    /** Single-process stdio MCP session — the pre-issue-#411 code path. */
+    private startDirect;
+    /**
+     * Run as the detached shared daemon (process spawned with
+     * `CODEGRAPH_DAEMON_INTERNAL=1`). Arbitrate the O_EXCL lock, then either
+     * become the daemon (bind the socket, serve forever) or — if a live daemon
+     * already holds the lock — exit so we don't leak a redundant process.
+     *
+     * No PPID watchdog and no stdin handlers: the daemon is detached on purpose
+     * and reaps itself via client-refcount + idle timeout (see {@link Daemon}).
+     */
+    private startDaemonProcess;
+    /**
+     * Proxy mode (the common case). Serve the MCP handshake LOCALLY for instant
+     * tool registration, forwarding tool calls to the shared daemon — which is
+     * connected in the background (probed, then spawned + polled if absent) so the
+     * handshake never waits ~600ms on it. Runs until the host disconnects; the
+     * proxy falls back to an in-process engine if the daemon never binds, so this
+     * never wedges a session.
+     */
+    private runProxyWithLocalHandshake;
+    /** Standard SIGINT/SIGTERM handlers that route to our `stop()` (direct mode). */
+    private installSignalHandlers;
+    /**
+     * PPID watchdog (#277) — direct mode only. Daemon mode is detached on purpose
+     * and reaps via idle timeout; proxy mode installs its own watchdog inside
+     * {@link runProxy}. So this only ever runs for an in-process direct session.
+     */
+    private installPpidWatchdog;
+}
+export { StdioTransport } from './transport';
+export { tools, ToolHandler } from './tools';
+export { Daemon } from './daemon';
+export { AlphaCodeSensePackageVersion } from './version';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAyHH;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAO7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAIvF;AAgFD;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,WAAW,CAAgB;IAGnC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAA+C;IAGnE,OAAO,CAAC,gBAAgB,CAA+B;IAIvD,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAA4D;IAE5E,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAA4D;IACxE,sFAAsF;IACtF,OAAO,CAAC,cAAc,CAAuB;gBAEjC,WAAW,CAAC,EAAE,MAAM;IAIhC;;;;;;;;;;;;OAYG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmD5B;;;;OAIG;IACH,IAAI,IAAI,IAAI;IA+BZ,uEAAuE;YACzD,WAAW;IAwDzB;;;;;;;;OAQG;YACW,kBAAkB;IAmEhC;;;;;;;OAOG;YACW,0BAA0B;IAqCxC,iFAAiF;IACjF,OAAO,CAAC,qBAAqB;IAK7B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAoB5B;AAWD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC"}