@selvakumaresra/specship 0.1.0

package/dist/mcp/engine.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link SpecShip} 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+exports.parseDebounceEnv = parseDebounceEnv;
+const directory_1 = require("../directory");
+const sync_1 = require("../sync");
+const tools_1 = require("./tools");
+// Lazy-load the heavy SpecShip chain (sqlite + query/graph/context layers) OFF
+// the MCP startup path. It's only needed once a tool actually opens a project —
+// not to answer initialize/tools-list — so deferring it lets `serve --mcp` (and
+// the daemon it spawns) bind + register tools in ~Node-startup time instead of
+// ~800ms, closing the "No such tool available" cold-start race that made headless
+// agents flounder. require() is sync + cached on the CommonJS build.
+const loadSpecShip = () => require('../index').default;
+/**
+ * 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.
+ */
+class MCPEngine {
+    cg = null;
+    toolHandler;
+    // Project root we resolved to. Null until `ensureInitialized` succeeds
+    // (or null forever if no .specship/ ever turned up — that's a valid
+    // state for the engine, since cross-project queries still work).
+    projectPath = null;
+    // Set on first `ensureInitialized` so subsequent sessions don't redo work.
+    initPromise = null;
+    watcherStarted = false;
+    opts;
+    closed = false;
+    constructor(opts = {}) {
+        this.opts = { watch: opts.watch ?? true };
+        this.toolHandler = new tools_1.ToolHandler(null);
+    }
+    /**
+     * 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) {
+        this.projectPath = projectPath;
+        this.toolHandler.setDefaultProjectHint(projectPath);
+    }
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath() {
+        return this.projectPath;
+    }
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler() {
+        return this.toolHandler;
+    }
+    /** Whether the default project's SpecShip is open. */
+    hasDefaultSpecShip() {
+        return this.toolHandler.hasDefaultSpecShip();
+    }
+    /**
+     * Walk up from `searchFrom` to find the nearest `.specship/` 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).
+     */
+    async ensureInitialized(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultSpecShip())
+            return;
+        if (this.initPromise) {
+            try {
+                await this.initPromise;
+            }
+            catch { /* let caller retry */ }
+            return;
+        }
+        this.initPromise = this.doInitialize(searchFrom).finally(() => {
+            this.initPromise = null;
+        });
+        try {
+            await this.initPromise;
+        }
+        catch {
+            // Init errors are logged inside `doInitialize`; falling through here
+            // matches MCPServer's previous "retry on next tool call" behavior.
+        }
+    }
+    /**
+     * 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) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultSpecShip())
+            return;
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestSpecShipRoot)(searchFrom);
+        if (!resolvedRoot)
+            return;
+        try {
+            // Close any previously failed instance to avoid leaking resources.
+            if (this.cg) {
+                try {
+                    this.cg.close();
+                }
+                catch { /* ignore */ }
+                this.cg = null;
+            }
+            this.cg = loadSpecShip().openSync(resolvedRoot);
+            this.projectPath = resolvedRoot;
+            this.toolHandler.setDefaultSpecShip(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+        }
+        catch {
+            // Still failing — caller will try again on the next tool call.
+        }
+    }
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.toolHandler.closeAll();
+        if (this.cg) {
+            try {
+                this.cg.close();
+            }
+            catch { /* ignore */ }
+            this.cg = null;
+        }
+    }
+    async doInitialize(searchFrom) {
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestSpecShipRoot)(searchFrom);
+        if (!resolvedRoot) {
+            // No .specship/ above searchFrom. Sessions may still discover one later via roots/list
+            this.projectPath = searchFrom;
+            return;
+        }
+        this.projectPath = resolvedRoot;
+        try {
+            this.cg = await loadSpecShip().open(resolvedRoot);
+            this.toolHandler.setDefaultSpecShip(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[SpecShip MCP] Failed to open project at ${resolvedRoot}: ${msg}\n`);
+        }
+    }
+    /**
+     * Start file watching on the active SpecShip 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.
+     */
+    startWatching() {
+        if (!this.cg || this.watcherStarted || !this.opts.watch)
+            return;
+        const disabledReason = (0, sync_1.watchDisabledReason)(this.projectPath ?? process.cwd());
+        if (disabledReason) {
+            process.stderr.write(`[SpecShip MCP] File watcher disabled — ${disabledReason}. ` +
+                `The graph will not auto-update; run \`specship sync\` (or install the git sync hooks via \`specship init\`) to refresh.\n`);
+            this.watcherStarted = true;
+            return;
+        }
+        // Optional override for the debounce window via env var (issue #403).
+        // Useful for workspaces with bursty writes (formatter-on-save chains,
+        // large generated outputs) where the 2s default fires too often. Clamped
+        // to [100ms, 60s]; out-of-range / non-numeric values fall back to the
+        // FileWatcher default. We log the active value so it's discoverable.
+        const debounceMs = parseDebounceEnv(process.env.SPECSHIP_WATCH_DEBOUNCE_MS);
+        if (debounceMs !== undefined) {
+            process.stderr.write(`[SpecShip MCP] File watcher debounce: ${debounceMs}ms (SPECSHIP_WATCH_DEBOUNCE_MS)\n`);
+        }
+        const started = this.cg.watch({
+            debounceMs,
+            onSyncComplete: (result) => {
+                if (result.filesChanged > 0) {
+                    process.stderr.write(`[SpecShip MCP] Auto-synced ${result.filesChanged} file(s) in ${result.durationMs}ms\n`);
+                }
+            },
+            onSyncError: (err) => {
+                process.stderr.write(`[SpecShip MCP] Auto-sync error: ${err.message}\n`);
+            },
+        });
+        this.watcherStarted = true;
+        if (started) {
+            process.stderr.write('[SpecShip MCP] File watcher active — graph will auto-sync on changes\n');
+        }
+        else {
+            process.stderr.write('[SpecShip MCP] File watcher unavailable on this platform — run `specship sync` to refresh the graph after changes.\n');
+        }
+    }
+    /**
+     * 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. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    catchUpSync() {
+        const cg = this.cg;
+        if (!cg)
+            return;
+        const p = cg
+            .sync()
+            .then((result) => {
+            const changed = result.filesAdded + result.filesModified + result.filesRemoved;
+            if (changed > 0) {
+                process.stderr.write(`[SpecShip MCP] Caught up ${changed} file(s) changed since last run\n`);
+            }
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[SpecShip MCP] Catch-up sync failed: ${msg}\n`);
+        });
+        this.toolHandler.setCatchUpGate(p);
+    }
+}
+exports.MCPEngine = MCPEngine;
+/**
+ * Parse and clamp the SPECSHIP_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.
+ */
+function parseDebounceEnv(raw) {
+    if (!raw || !raw.trim())
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return undefined;
+    if (n < 100 || n > 60000)
+        return undefined;
+    return n;
+}
+//# sourceMappingURL=engine.js.map

package/dist/mcp/engine.js.map

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * SpecShip MCP Server
+ *
+ * Model Context Protocol server that exposes SpecShip functionality
+ * as tools for AI assistants like Claude.
+ *
+ * @module mcp
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer } from 'specship';
+ *
+ * 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 (`SPECSHIP_NO_DAEMON=1`), no
+ *   `.specship/` 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 SpecShip + 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).
+ */
+/**
+ * MCP Server for SpecShip
+ *
+ * Implements the Model Context Protocol to expose SpecShip
+ * 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 originalPpid;
+    private hostPpid;
+    private stopped;
+    private mode;
+    constructor(projectPath?: string);
+    /**
+     * Start the MCP server.
+     *
+     * Decision order:
+     *   1. `SPECSHIP_NO_DAEMON=1` → direct mode (unchanged pre-#411 behavior).
+     *   2. `SPECSHIP_DAEMON_INTERNAL=1` → we ARE the detached daemon; listen.
+     *   3. No `.specship/` reachable → direct mode (the daemon's lockfile and
+     *      socket both live under `.specship/`).
+     *   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
+     * `SPECSHIP_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 { SpecShipPackageVersion } 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;AAsKH;;;;;;;;;;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,YAAY,CAAwB;IAC5C,OAAO,CAAC,QAAQ,CAA4D;IAE5E,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAA4D;gBAE5D,WAAW,CAAC,EAAE,MAAM;IAIhC;;;;;;;;;;;;OAYG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC5B;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAuBZ,uEAAuE;YACzD,WAAW;IA4BzB;;;;;;;;OAQG;YACW,kBAAkB;IAiChC;;;;;;;OAOG;YACW,0BAA0B;IAoBxC,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,sBAAsB,EAAE,MAAM,WAAW,CAAC"}