@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/mcp/server.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_ENFORCED_TOOLS = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const spec_store_1 = require("../spec/spec-store");
+const handlers_1 = require("./handlers");
+const tool_schemas_1 = require("./tool-schemas");
+Object.defineProperty(exports, "HOOK_ENFORCED_TOOLS", { enumerable: true, get: function () { return tool_schemas_1.HOOK_ENFORCED_TOOLS; } });
+const validate_args_1 = require("./validate-args");
+// @implements A-SPEC-100.2
+const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS ?? '.ax/specs');
+const handlers = (0, handlers_1.makeHandlers)(store);
+const server = new index_js_1.Server({ name: 'holmes-kit', version: '0.1.0' }, { capabilities: { tools: {} } });
+const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
+// Register each handler as a tool with its real typed inputSchema so MCP
+// clients can marshal complex (array/object) arguments; fall back to a
+// permissive stub only if a handler somehow lacks a schema (tool-schemas.test.ts
+// pins full 1:1 coverage, so the fallback should never fire in practice).
+const TOOLS = Object.keys(handlers)
+    .filter((name) => fullProfile || !tool_schemas_1.HOOK_ENFORCED_TOOLS.has(name))
+    .map((name) => {
+    const def = tool_schemas_1.TOOL_SCHEMAS[name];
+    return def
+        ? { name, description: def.description, inputSchema: def.inputSchema }
+        : { name, description: name, inputSchema: { type: 'object', properties: {} } };
+});
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+    // @implements A-SPEC-189
+    // The server is the first consumer of its own advertised schemas. Before this check, 15 of 26
+    // handlers threw raw internal errors at `{}` over the wire, and a one-key typo in reverse_anchor
+    // produced a wrong diagnosis or a success-shaped no-op. Judged against the SAME object ListTools
+    // serves — a separate copy would be a second truth that drifts. In-process callers (makeHandlers)
+    // are authors of these schemas, not consumers; the wire is where enforcement belongs.
+    // Own-property lookups: 'constructor'/'__proto__' as a tool name would otherwise resolve through
+    // the prototype chain to a truthy non-handler and crash the new validation path (round-2 probe) —
+    // pre-enforcement it silently "succeeded" by invoking Object. Both are wrong; unknown tool is true.
+    const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined;
+    const fn = own(handlers, req.params.name);
+    const def = own(tool_schemas_1.TOOL_SCHEMAS, req.params.name);
+    const args = req.params.arguments ?? {};
+    const check = fn && def ? (0, validate_args_1.validateArgs)(req.params.name, def.inputSchema, args) : { ok: true };
+    // @implements A-SPEC-189 §6 — a handler's REFUSAL must arrive in the refusal shape. Round-9
+    // measured the seam: review_record's pointed guidance ('send it as summary') left the wire as a
+    // raw JSON-RPC -32603, i.e. this REQ closed 15 raw-error paths and opened one. A deliberate
+    // refusal is a plain `Error` thrown by a handler; a programming fault (TypeError, RangeError…)
+    // keeps failing loudly, because dressing a crash as an orderly refusal is how a bug becomes a
+    // policy decision in the caller's log.
+    let out;
+    if (!fn)
+        out = { error: 'unknown tool' };
+    else if (!check.ok)
+        out = check;
+    else {
+        try {
+            out = await fn(args);
+        }
+        catch (e) {
+            // Round-10: only a refusal the handler CHOSE is dressed as a refusal. Everything else —
+            // fs/exec failures included — keeps failing loudly, because a crash wearing `{ok:false}` is
+            // how a broken gate reads as a passed one.
+            if (!(0, handlers_1.isHandlerRefusal)(e))
+                throw e;
+            out = { ok: false, reason: `${req.params.name}: ${e.message}` };
+        }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(out) }] };
+});
+void server.connect(new stdio_js_1.StdioServerTransport());

package/dist/holmes/mcp/stdio-client.js

@@ -0,0 +1,165 @@
+"use strict";
+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.StdioClient = exports.OMITTED_FROM_COMPARISON = void 0;
+exports.comparable = comparable;
+exports.parseToolResult = parseToolResult;
+// @implements A-SPEC-159
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Keys excluded from surface comparison.
+ *
+ * `basis` legitimately differs: two processes observe the world at different moments, so the spec
+ * fingerprint can move between the two calls. Excluding it is correct — but the exclusion is named
+ * and asserted, because an agreement claim whose exceptions are invisible is stronger-sounding than
+ * it is.
+ */
+exports.OMITTED_FROM_COMPARISON = ['basis'];
+/** Strips the excluded keys so two answers can be compared for the part that must match. */
+function comparable(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return v;
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (exports.OMITTED_FROM_COMPARISON.includes(k))
+            continue;
+        out[k] = val;
+    }
+    return out;
+}
+/**
+ * Extracts a tool's payload from an MCP result.
+ *
+ * Pure and exported because the failure it guards — a surface that answers with no text at all —
+ * cannot be produced by the real server (an unknown tool comes back as a perfectly well-formed
+ * `{"error":"unknown tool"}`), so the branch is unreachable from an end-to-end test. Left inline it
+ * would be an untested guard, and an untested guard is one a later change deletes for free: with it
+ * gone, a silent surface yields `undefined`, `undefined` compares equal to `undefined`, and the
+ * conformance suite reports agreement between two answers that contain nothing.
+ */
+function parseToolResult(name, result, error) {
+    // A JSON-RPC error carries no `content`, so without this the next check would report "no text
+    // content" and hide what actually went wrong. Measured: this server answers an unknown tool with a
+    // well-formed `{"error":"unknown tool"}` result rather than a protocol error, so the branch is
+    // unreachable end-to-end and has to be pinned here or not at all.
+    if (error !== undefined)
+        throw new Error(`tool ${name} failed: ${JSON.stringify(error)}`);
+    const text = result?.content?.[0]?.text;
+    if (typeof text !== 'string')
+        throw new Error(`tool ${name} returned no text content`);
+    return JSON.parse(text);
+}
+/**
+ * A minimal MCP client that SPAWNS the shipped entry point.
+ *
+ * Importing the handler module — what every other test does — cannot see the boundary where the
+ * 2026-08-08 defect lived: a server process running a three-day-old build answered `impactedSpecs:
+ * []` for a commit touching 39 specs, while the same handler in a fresh process answered correctly,
+ * and 1,370 tests stayed green throughout. Anything that does not cross a process boundary is blind
+ * to that entire class.
+ *
+ * One server is started per suite and reused, so conformance costs one spawn rather than one per
+ * tool.
+ */
+class StdioClient {
+    child;
+    buf = '';
+    nextId = 1;
+    pending = new Map();
+    constructor(child) {
+        this.child = child;
+        this.child.stdout.on('data', (d) => {
+            this.buf += d.toString();
+            let nl;
+            while ((nl = this.buf.indexOf('\n')) >= 0) {
+                const line = this.buf.slice(0, nl).trim();
+                this.buf = this.buf.slice(nl + 1);
+                if (!line.startsWith('{'))
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const resolve = msg.id !== undefined ? this.pending.get(msg.id) : undefined;
+                if (resolve && msg.id !== undefined) {
+                    this.pending.delete(msg.id);
+                    resolve(msg);
+                }
+            }
+        });
+    }
+    /**
+     * @param specsDir  Overrides `HOLMES_SPECS` for the child. Needed because the server binds its
+     *   spec store at start-up from that variable and ignores the `root` argument a tool receives
+     *   (REQ-169) — without this, a write tool driven for conformance lands in the server's own
+     *   project. Measured: it wrote REQ-901.md into this repository.
+     */
+    static async start(repoRoot, specsDir = '.ax/specs') {
+        // A conformance suite that skips when it cannot spawn reports green for exactly the situation it
+        // exists to detect, so an unusable root is an error rather than a quiet no-op.
+        const entry = path.join(repoRoot, 'bin', 'holmes-mcp.js');
+        if (!fs.existsSync(entry))
+            throw new Error(`no MCP entry point at ${entry}`);
+        const child = (0, node_child_process_1.spawn)('node', ['bin/holmes-mcp.js'], {
+            cwd: repoRoot, stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, HOLMES_SPECS: specsDir },
+        });
+        const client = new StdioClient(child);
+        await client.send('initialize', {
+            protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'conformance', version: '0' },
+        });
+        child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);
+        return client;
+    }
+    send(method, params) {
+        return new Promise((resolve) => {
+            const id = this.nextId++;
+            this.pending.set(id, resolve);
+            this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        });
+    }
+    async call(name, args) {
+        const res = await this.send('tools/call', { name, arguments: args });
+        return parseToolResult(name, res.result, res.error);
+    }
+    stop() {
+        this.child.kill();
+    }
+}
+exports.StdioClient = StdioClient;

package/dist/holmes/mcp/supervisor.js

@@ -0,0 +1,178 @@
+"use strict";
+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.Supervisor = exports.AUTORELOAD_ENV = void 0;
+exports.autoreloadEnabled = autoreloadEnabled;
+exports.shouldSwap = shouldSwap;
+// @implements A-SPEC-162
+const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
+const basis_1 = require("./basis");
+/** Opt-in switch. Absent means the entry point behaves exactly as it did before this existed. */
+exports.AUTORELOAD_ENV = 'HOLMES_MCP_AUTORELOAD';
+function autoreloadEnabled(env) {
+    const v = env[exports.AUTORELOAD_ENV];
+    return typeof v === 'string' && v.trim() !== '';
+}
+/**
+ * Whether the child may be replaced right now.
+ *
+ * Pure, so the three ways this can be wrong are testable without spawning anything.
+ *
+ * An unknown disk build never swaps: not knowing is not divergence, the same posture A-SPEC-160 took
+ * for the digest marker. Reading absence as change would restart continuously on any install whose
+ * build is unstamped.
+ *
+ * An in-flight request never swaps. Each child starts its JSON-RPC id counter at 1, so a mid-request
+ * swap lets the new child's reply match an id the old one issued — an answer delivered to the wrong
+ * question, which is worse than the staleness it was fixing.
+ */
+function shouldSwap(loaded, disk, inflight) {
+    if (disk === undefined || disk === 'unknown')
+        return false;
+    if (disk === loaded)
+        return false;
+    return inflight === 0;
+}
+/**
+ * Runs the real server as a child and relays stdio, replacing the child when the build changes.
+ *
+ * A child process rather than `require.cache` surgery: this package depends on nine native addons
+ * (better-sqlite3 plus eight tree-sitter grammars), and re-requiring a `.node` either crashes the
+ * process or leaks the handles it still owns — better-sqlite3 holds open database handles. A fresh
+ * child loads them cleanly, and the client never sees the connection drop.
+ *
+ * This is a CONVENIENCE, not a correctness mechanism. If a swap fails, REQ-156's basis and ART-6
+ * still expose the divergence; making the supervisor responsible for correctness would turn it into
+ * a new single point of failure for the property it was meant to help with.
+ */
+class Supervisor {
+    repoRoot;
+    onSwap;
+    child;
+    inflight = 0;
+    loaded;
+    /**
+     * The client's opening exchange, replayed into every replacement child. Without it the first call
+     * after a swap hits an uninitialised server and fails — which would break the one promise the
+     * supervisor makes, that the connection does not drop.
+     */
+    handshake = [];
+    constructor(repoRoot, onSwap) {
+        this.repoRoot = repoRoot;
+        this.onSwap = onSwap;
+        this.loaded = (0, basis_1.loadedBuildId)(repoRoot);
+    }
+    start(stdin, stdout) {
+        this.spawnChild(stdout);
+        let buf = '';
+        stdin.on('data', (d) => {
+            buf += d.toString();
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl + 1);
+                buf = buf.slice(nl + 1);
+                this.forward(line, stdout);
+            }
+        });
+    }
+    forward(line, stdout) {
+        const trimmed = line.trim();
+        let isRequest = false;
+        if (trimmed.startsWith('{')) {
+            try {
+                const msg = JSON.parse(trimmed);
+                if (msg.method === 'initialize' || msg.method === 'notifications/initialized')
+                    this.handshake.push(line);
+                isRequest = msg.id !== undefined;
+            }
+            catch { /* unparseable input is relayed untouched; the child owns protocol errors */ }
+        }
+        // Decide BEFORE counting this request in. Measured: incrementing first made `inflight` at least
+        // 1 for every request-carrying line, so the swap check never saw zero and the child was never
+        // replaced — the live probe caught it while the pure-function unit tests all passed, because
+        // they test the predicate and this is the caller.
+        const disk = (0, basis_1.loadedBuildId)(this.repoRoot);
+        if (shouldSwap(this.loaded, disk, this.inflight))
+            this.swap(disk, stdout);
+        if (isRequest)
+            this.inflight++;
+        this.child?.stdin.write(line);
+    }
+    swap(to, stdout) {
+        const from = this.loaded;
+        this.child?.kill();
+        this.loaded = to;
+        this.spawnChild(stdout);
+        // Counted as WRITTEN, not as captured. Reporting `handshake.length` looked like an observation
+        // but described the capture step, so deleting the replay left the number unchanged and the test
+        // kept passing — the same "crediting the wrong layer" mistake in a new place.
+        let replayed = 0;
+        for (const line of this.handshake) {
+            if (this.child?.stdin.write(line))
+                replayed++;
+            else if (this.child)
+                replayed++; // buffered rather than flushed is still sent
+        }
+        // Measured: this server answers `tools/call` without a prior `initialize`, so the replay's
+        // absence cannot be detected downstream — asserting "the call would fail without it" would be
+        // asserting something untrue. The contract is that the opening exchange is re-sent; a
+        // spec-compliant server is entitled to require it.
+        this.onSwap?.(from, to, replayed);
+    }
+    spawnChild(stdout) {
+        // `stdio: ['pipe','pipe','pipe']` keeps the typed streams non-null; the child's stderr is
+        // forwarded rather than inherited so a supervised run logs identically to an unsupervised one.
+        const child = (0, node_child_process_1.spawn)('node', [path.join('dist', 'holmes', 'mcp', 'server.js')], {
+            cwd: this.repoRoot, stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        child.stderr.on('data', (d) => process.stderr.write(d));
+        this.child = child;
+        child.stdout.on('data', (d) => {
+            const text = d.toString();
+            // Count replies out so `inflight` returns to zero; the id itself does not matter here, only
+            // that a response arrived for something that was counted in.
+            for (const line of text.split('\n')) {
+                if (line.trim().startsWith('{') && line.includes('"id"') && this.inflight > 0)
+                    this.inflight--;
+            }
+            stdout.write(text);
+        });
+    }
+    stop() {
+        this.child?.kill();
+    }
+}
+exports.Supervisor = Supervisor;