@esankhan3/code-search-mcp 1.0.6 → 1.1.1

package/dist/__tests__/graph-traversal.test.js

@@ -0,0 +1,262 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createSystemGraphSqliteWriter, getGraphStore, invalidateRetriever } from "@esankhan3/anvil-knowledge-core";
+import { handleGraphTool } from "../tools/graph.js";
+const MAX_NODES = 5e4;
+let tmp = "";
+let stashDataDir;
+function ctx(projectName) {
+  return {
+    projectName,
+    directoryPath: null,
+    indexReady: true,
+    startedAt: 0,
+    indexing: {
+      status: "idle",
+      phase: null,
+      message: null,
+      percent: 0,
+      startedAt: null,
+      error: null,
+      lastSuccess: null,
+      lastDurationMs: 0,
+      history: []
+    }
+  };
+}
+const text = (r) => r?.content?.[0]?.text ?? "";
+const call = async (project, name, args) => text(await handleGraphTool(name, args, ctx(project)));
+const key = (name, file = "f.ts") => `r::${file}::${name}`;
+async function writeGraph(project, nodes, edges, fileOf = (_n) => "f.ts") {
+  const kb = join(tmp, project);
+  mkdirSync(kb, { recursive: true });
+  const w = await createSystemGraphSqliteWriter(kb);
+  assert.ok(w, "no sqlite driver");
+  w.addRepoGraph("r", {
+    nodes: nodes.map((n) => ({ id: `${n.file ?? "f.ts"}::${n.name}`, label: n.name, type: "function", file: n.file ?? "f.ts" })),
+    links: edges.map((e) => ({ source: `${fileOf(e.s)}::${e.s}`, target: `${fileOf(e.t)}::${e.t}`, type: e.type, confidence: e.confidence }))
+  });
+  w.finalize();
+}
+async function instrument(project, methods, onRead = () => {
+}) {
+  const store = await getGraphStore(project);
+  const nodes = /* @__PURE__ */ new Set();
+  for (const m of methods) {
+    const orig = store[m];
+    if (typeof orig !== "function") continue;
+    store[m] = (...a) => {
+      const r = orig.apply(store, a);
+      if (Array.isArray(r)) for (const x of r) for (const k of Array.isArray(x) ? x : [x]) nodes.add(k);
+      onRead();
+      return r;
+    };
+  }
+  return { nodes, restore: () => {
+    for (const m of methods) delete store[m];
+  } };
+}
+function expireClock() {
+  const real = Date.now;
+  Date.now = () => real() + 6e4;
+  return () => {
+    Date.now = real;
+  };
+}
+before(() => {
+  stashDataDir = process.env.CODE_SEARCH_DATA_DIR;
+  tmp = mkdtempSync(join(tmpdir(), "cs-trav-"));
+  process.env.CODE_SEARCH_DATA_DIR = tmp;
+});
+after(async () => {
+  await invalidateRetriever();
+  rmSync(tmp, { recursive: true, force: true });
+  if (stashDataDir === void 0) delete process.env.CODE_SEARCH_DATA_DIR;
+  else process.env.CODE_SEARCH_DATA_DIR = stashDataDir;
+});
+function rng(seed) {
+  return () => {
+    seed = seed + 1831565813 | 0;
+    let t = Math.imul(seed ^ seed >>> 15, 1 | seed);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function steps(edges, direction, types) {
+  const adj = /* @__PURE__ */ new Map();
+  const add = (a, b) => {
+    if (!adj.has(a)) adj.set(a, /* @__PURE__ */ new Set());
+    adj.get(a).add(b);
+  };
+  for (const e of edges) {
+    if (e.confidence < 0.7 || types && !types.includes(e.type)) continue;
+    if (direction !== "callers") add(e.s, e.t);
+    if (direction !== "callees") add(e.t, e.s);
+  }
+  return adj;
+}
+function bfsHops(adj, from, to) {
+  if (from === to) return null;
+  const dist = /* @__PURE__ */ new Map([[from, 0]]);
+  let frontier = [from];
+  while (frontier.length > 0) {
+    const next = [];
+    for (const k of frontier) {
+      for (const n of adj.get(k) ?? []) {
+        if (dist.has(n)) continue;
+        dist.set(n, dist.get(k) + 1);
+        if (n === to) return dist.get(n);
+        next.push(n);
+      }
+    }
+    frontier = next;
+  }
+  return null;
+}
+const pathKeys = (t) => [...t.matchAll(/^- `([^`]+)`$/gm)].map((m) => m[1]);
+describe("trace_path \u2014 shortest path", () => {
+  it("matches a plain BFS on random graphs: hop count, a real path, maxDepth", async () => {
+    const rand = rng(7);
+    const pick = (xs) => xs[Math.floor(rand() * xs.length)];
+    let paths = 0;
+    let none = 0;
+    for (let g = 0; g < 25; g++) {
+      const n = 8 + Math.floor(rand() * 20);
+      const names = Array.from({ length: n }, (_, i) => `n${i}`);
+      const edges = Array.from({ length: Math.floor(n * (1 + rand() * 1.5)) }, () => ({
+        s: pick(names),
+        t: pick(names),
+        type: rand() < 0.75 ? "calls" : "imports",
+        confidence: rand() < 0.85 ? 0.9 : 0.5
+      }));
+      const project = `rnd${g}`;
+      await writeGraph(project, names.map((name) => ({ name })), edges);
+      for (let q = 0; q < 16; q++) {
+        const from = pick(names);
+        const to = pick(names);
+        const direction = pick(["callees", "callers", "both"]);
+        const relations = pick([void 0, ["imports"], ["all"]]);
+        const maxDepth = 1 + Math.floor(rand() * 6);
+        const adj = steps(edges, direction, relations === void 0 ? ["calls"] : relations[0] === "all" ? null : relations);
+        const want = bfsHops(adj, from, to);
+        const t = await call(project, "trace_path", { from: key(from), to: key(to), direction, maxDepth, ...relations ? { relations } : {} });
+        const label = `${project}: ${from} \u2192 ${to} (${direction}, ${relations ?? "calls"}, maxDepth ${maxDepth})
+${t}`;
+        if (want === null || want > maxDepth) {
+          assert.match(t, new RegExp(`^No path from .* within ${maxDepth} hops`), label);
+          none++;
+          continue;
+        }
+        assert.equal(Number(/^# Path \((\d+) hops\)/.exec(t)?.[1]), want, label);
+        const keys = pathKeys(t);
+        assert.equal(keys.length, want + 1, label);
+        assert.equal(keys[0], key(from), label);
+        assert.equal(keys[keys.length - 1], key(to), label);
+        for (let i = 1; i < keys.length; i++) {
+          assert.ok(adj.get(keys[i - 1].split("::")[2])?.has(keys[i].split("::")[2]), `no step ${keys[i - 1]} \u2192 ${keys[i]} in ${label}`);
+        }
+        paths++;
+      }
+    }
+    assert.ok(paths >= 60 && none >= 60, `sample covers both outcomes (${paths} paths, ${none} none)`);
+  });
+  it("picks the shorter of two routes and honours maxDepth exactly", async () => {
+    const e = (s, t2) => ({ s, t: t2, type: "calls", confidence: 0.9 });
+    await writeGraph("routes", ["a", "b", "c", "d", "e", "x", "y"].map((name) => ({ name })), [
+      e("a", "b"),
+      e("b", "c"),
+      e("c", "d"),
+      e("d", "e"),
+      // 4 hops
+      e("a", "x"),
+      e("x", "y"),
+      e("y", "e")
+      // 3 hops
+    ]);
+    const t = await call("routes", "trace_path", { from: "a", to: "e" });
+    assert.match(t, /# Path \(3 hops\)\n\na → x → y → e/);
+    assert.match(await call("routes", "trace_path", { from: "a", to: "e", maxDepth: 3 }), /3 hops/);
+    assert.match(await call("routes", "trace_path", { from: "a", to: "e", maxDepth: 2 }), /^No path from "a" to "e" within 2 hops/);
+    assert.match(await call("routes", "trace_path", { from: "e", to: "a", direction: "callers" }), /# Path \(3 hops\)\n\ne ← y ← x ← a/);
+    assert.match(await call("routes", "trace_path", { from: "e", to: "a" }), /^No path from "e" to "a"/);
+  });
+});
+describe("traversal budget on a high-fan-out graph", () => {
+  const FAN = 250;
+  before(async () => {
+    const nodes = [{ name: "src" }, { name: "dst" }, { name: "sink", file: "sink.ts" }];
+    const edges = [];
+    const calls = (s, t) => edges.push({ s, t, type: "calls", confidence: 0.9 });
+    for (let i = 0; i < FAN; i++) {
+      nodes.push({ name: `c${i}` }, { name: `k${i}` });
+      calls("src", `c${i}`);
+      calls(`k${i}`, "dst");
+      for (let j = 0; j < FAN; j++) {
+        nodes.push({ name: `g${i}_${j}` });
+        calls(`c${i}`, `g${i}_${j}`);
+        calls(`g${i}_${j}`, "sink");
+      }
+    }
+    await writeGraph("fan", nodes, edges, (n) => n === "sink" ? "sink.ts" : "f.ts");
+  });
+  it('trace_path stops at the node cap and says so instead of "No path"', async () => {
+    const reads = await instrument("fan", ["neighborsOf", "neighborEdges"]);
+    try {
+      const t = await call("fan", "trace_path", { from: "src", to: "dst", maxDepth: 10 });
+      assert.match(t, /^No path from "src" to "dst" found within the traversal budget \(explored \d+ nodes, depth \d+ of 10/);
+      assert.match(t, /narrow the search .* or lower maxDepth/);
+      assert.ok(Number(/explored (\d+) nodes/.exec(t)?.[1]) <= MAX_NODES, t);
+      assert.ok(reads.nodes.size <= MAX_NODES, `read ${reads.nodes.size} distinct nodes`);
+    } finally {
+      reads.restore();
+    }
+  });
+  it("trace_path stops when the wall-clock budget runs out", async () => {
+    let restoreClock = () => {
+    };
+    let queries = 0;
+    const reads = await instrument("fan", ["neighborsOf", "neighborEdges"], () => {
+      if (++queries === 1) restoreClock = expireClock();
+    });
+    try {
+      const t = await call("fan", "trace_path", { from: "src", to: "dst", maxDepth: 10 });
+      assert.match(t, /found within the traversal budget \(explored \d+ nodes, depth 1 of 10/);
+      assert.equal(queries, 1);
+    } finally {
+      restoreClock();
+      reads.restore();
+    }
+  });
+  it("trace_path still finds a path into a hub within the budget", async () => {
+    const t = await call("fan", "trace_path", { from: "c0", to: "sink", maxDepth: 10 });
+    assert.match(t, /# Path \(2 hops\)\n\nc0 → g0_\d+ → sink/);
+  });
+  it("impact_analysis caps the dependents scanned per hop and marks the count as a lower bound", async () => {
+    const t = await call("fan", "impact_analysis", { repo: "r", file: "sink.ts", depth: 1 });
+    assert.match(t, new RegExp(`## Dependents: ${MAX_NODES}\\+ edges`));
+    assert.match(t, new RegExp(`### Hop 1 \\(${MAX_NODES}\\+\\)`));
+  });
+  it("impact_analysis stops between hops when the wall-clock budget runs out", async () => {
+    let restoreClock = () => {
+    };
+    let expired = false;
+    const reads = await instrument("fan", ["dependents"], () => {
+      if (!expired) {
+        expired = true;
+        restoreClock = expireClock();
+      }
+    });
+    try {
+      const t = await call("fan", "impact_analysis", { repo: "r", file: "sink.ts", depth: 3 });
+      assert.match(t, /### Hop 1/);
+      assert.doesNotMatch(t, /### Hop 2/);
+      assert.match(t, /traversal budget/);
+    } finally {
+      restoreClock();
+      reads.restore();
+    }
+  });
+});

package/dist/__tests__/http-auth.test.js

@@ -0,0 +1,180 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createHmac } from "node:crypto";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { request as httpRequest } from "node:http";
+import { Server } from "@modelcontextprotocol/server";
+import { startHttpTransport } from "../transports/http-transport.js";
+import { SlidingWindow } from "../middleware/rate-limit.js";
+import { BIN, tmp, baseEnv, spawnProc, getJson, waitFor } from "./_harness.js";
+const PORT = 47386;
+const BASE = `http://127.0.0.1:${PORT}`;
+const SECRET = "s3cr3t-hs256";
+const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
+function jwt(payload, secret = SECRET) {
+  const data = `${b64({ alg: "HS256", typ: "JWT" })}.${b64(payload)}`;
+  return `${data}.${createHmac("sha256", secret).update(data).digest("base64url")}`;
+}
+const now = () => Math.floor(Date.now() / 1e3);
+function config(over) {
+  return {
+    port: PORT,
+    host: "127.0.0.1",
+    transport: "streamable-http",
+    authEnabled: true,
+    authMode: "api-key",
+    authApiKeys: [],
+    authJwtSecret: void 0,
+    authJwtIssuer: "code-search-mcp",
+    rateLimitPerMinute: 100,
+    ...over
+  };
+}
+async function withServer(cfg, fn) {
+  const http = await startHttpTransport({
+    config: cfg,
+    createMcpServer: async () => ({ server: new Server({ name: "t", version: "0" }, { capabilities: {} }) }),
+    getStatus: () => ({ directoryPath: "/secret/path" })
+  });
+  try {
+    await fn();
+  } finally {
+    http.closeAllConnections();
+    await new Promise((r) => http.close(r));
+  }
+}
+function adminStatus(token) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest(`${BASE}/admin/api/status`, {
+      agent: false,
+      headers: token ? { Authorization: `Bearer ${token}` } : {}
+    }, (res) => {
+      let text = "";
+      res.on("data", (c) => {
+        text += c.toString();
+      });
+      res.on("end", () => {
+        let body = text;
+        try {
+          body = JSON.parse(text);
+        } catch {
+        }
+        resolve({ status: res.statusCode ?? 0, body, headers: { get: (h) => res.headers[h.toLowerCase()] } });
+      });
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+describe("sliding-window limiter", () => {
+  it("admits at most `limit` hits in any trailing window (no boundary burst)", () => {
+    let t = 0;
+    const w = new SlidingWindow(6e4, () => t);
+    assert.equal(w.hit("k", 2).ok, true);
+    t = 59e3;
+    assert.equal(w.hit("k", 2).ok, true);
+    t = 59500;
+    const denied = w.hit("k", 2);
+    assert.equal(denied.ok, false);
+    assert.equal(denied.retryAfterSec, 1);
+    t = 60100;
+    assert.equal(w.hit("k", 2).ok, true, "the t=0 hit left the window");
+    t = 60200;
+    assert.equal(w.hit("k", 2).ok, false, "a fixed window would have reset here");
+    assert.equal(w.hit("other", 2).ok, true);
+  });
+});
+describe("JWT", () => {
+  it("rejects tokens without exp and before nbf; accepts a valid one", async () => {
+    await withServer(config({ authMode: "jwt", authJwtSecret: SECRET }), async () => {
+      assert.equal((await adminStatus(jwt({ sub: "a", iss: "code-search-mcp", exp: now() + 600 }))).status, 200);
+      assert.equal((await adminStatus(jwt({ sub: "b", iss: "code-search-mcp" }))).status, 401, "no exp");
+      assert.equal((await adminStatus(jwt({ sub: "c", iss: "code-search-mcp", exp: now() + 600, nbf: now() + 3600 }))).status, 401, "nbf in future");
+      assert.equal((await adminStatus(jwt({ sub: "d", iss: "code-search-mcp", exp: now() - 5 }))).status, 401, "expired");
+    });
+  });
+  it("refuses to start in jwt mode without a secret", async () => {
+    await assert.rejects(
+      () => startHttpTransport({
+        config: config({ authMode: "jwt", authJwtSecret: void 0 }),
+        createMcpServer: async () => ({ server: new Server({ name: "t", version: "0" }, { capabilities: {} }) })
+      }),
+      /CODE_SEARCH_AUTH_JWT_SECRET/
+    );
+  });
+});
+describe("API-key rate limiting + admin auth", () => {
+  it("limits per full key and sends Retry-After", async () => {
+    const keyA = "sharedprefix-AAAA-0001";
+    const keyB = "sharedprefix-BBBB-0002";
+    await withServer(config({ authApiKeys: [keyA, keyB], rateLimitPerMinute: 2 }), async () => {
+      assert.equal((await adminStatus(keyA)).status, 200);
+      assert.equal((await adminStatus(keyA)).status, 200);
+      const limited = await adminStatus(keyA);
+      assert.equal(limited.status, 429);
+      assert.ok(Number(limited.headers.get("retry-after")) >= 1, `Retry-After=${limited.headers.get("retry-after")}`);
+      assert.equal((await adminStatus(keyB)).status, 200, "a key sharing the prefix has its own bucket");
+    });
+  });
+  it("/admin/api/status requires auth when auth is enabled", async () => {
+    await withServer(config({ authApiKeys: ["k-1234567890"] }), async () => {
+      const r = await adminStatus();
+      assert.equal(r.status, 401);
+      assert.doesNotMatch(JSON.stringify(r.body), /secret\/path/);
+    });
+  });
+});
+describe("P8 registry on /mcp", () => {
+  let root;
+  before(() => {
+    root = tmp("cs-reg-");
+    const dir = join(root, "data", "projects", "proj");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "project.yaml"), [
+      `workspace: ${root}`,
+      "scopes: [team-a]",
+      "quotas:",
+      "  max_queries_per_minute: 2",
+      ""
+    ].join("\n"));
+  });
+  after(() => rmSync(root, { recursive: true, force: true }));
+  it("enforces project scopes and the per-(identity, project) quota", async () => {
+    const env = baseEnv({
+      home: join(root, "home"),
+      dataDir: join(root, "data"),
+      extra: { CODE_SEARCH_AUTH_MODE: "jwt", CODE_SEARCH_AUTH_JWT_SECRET: SECRET, CODE_SEARCH_HOST: "127.0.0.1" }
+    });
+    const p = spawnProc(BIN.mcp, ["--serve", "--project", "proj", "--port", String(PORT)], env);
+    try {
+      await waitFor(async () => (await getJson(`${BASE}/health`)).status === 200, 2e4, `health
+${p.stderr()}`);
+      const mcp = (token) => fetch(`${BASE}/mcp`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream"
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} })
+      });
+      const teamB = jwt({ sub: "bob", iss: "code-search-mcp", exp: now() + 600, scope: "team-b" });
+      assert.equal((await mcp(teamB)).status, 403);
+      const noScope = jwt({ sub: "eve", iss: "code-search-mcp", exp: now() + 600 });
+      assert.equal((await mcp(noScope)).status, 403, "a token without a scope claim is not admin");
+      const teamA = jwt({ sub: "alice", iss: "code-search-mcp", exp: now() + 600, scope: "team-a" });
+      for (let i = 0; i < 2; i++) {
+        const r = await mcp(teamA);
+        assert.ok(r.status !== 403 && r.status !== 429, `request ${i} \u2192 ${r.status}`);
+        await r.text();
+      }
+      const over = await mcp(teamA);
+      assert.equal(over.status, 429);
+      assert.ok(Number(over.headers.get("retry-after")) >= 1);
+    } finally {
+      p.kill();
+      await p.exited;
+    }
+  });
+});

package/dist/__tests__/http-index.test.js

@@ -0,0 +1,125 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import {
+  BIN,
+  tmp,
+  makeWorkspace,
+  baseEnv,
+  spawnProc,
+  getJson,
+  waitFor,
+  exitWithin,
+  startFakeEmbedder
+} from "./_harness.js";
+let root;
+let ws;
+let slow;
+before(async () => {
+  root = tmp("cs-idx-");
+  ws = makeWorkspace(root);
+  slow = await startFakeEmbedder(47393, { delayMs: 2e3 });
+});
+after(async () => {
+  await slow.close();
+  rmSync(root, { recursive: true, force: true });
+});
+const post = (base, body, headers = {}) => getJson(`${base}/index`, { method: "POST", headers: { "Content-Type": "application/json", ...headers }, body });
+describe("POST /index", () => {
+  it("validates, refuses overlap and other projects, reports real edges", async () => {
+    const env = baseEnv({ home: join(root, "home"), dataDir: join(root, "data1"), embedderUrl: slow.url });
+    const p = spawnProc(BIN.mcp, ["--serve", "--port", "47387"], env);
+    const base = "http://127.0.0.1:47387";
+    try {
+      await waitFor(async () => (await getJson(`${base}/health`)).status === 200, 2e4, `health
+${p.stderr()}`);
+      assert.equal((await post(base, "")).status, 400, "empty body");
+      assert.equal((await post(base, "not json")).status, 400, "invalid JSON");
+      assert.equal((await post(base, "[]")).status, 400, "no path");
+      assert.equal((await post(base, JSON.stringify({ path: join(root, "missing") }))).status, 400, "missing dir");
+      assert.equal((await post(base, JSON.stringify({ path: ws, pad: "x".repeat(2e5) }))).status, 413, "huge body");
+      const other = await post(base, JSON.stringify({ path: ws, project: "other" }));
+      assert.equal(other.status, 400);
+      assert.match(other.body.error, /serves project "default"/);
+      assert.equal((await getJson(`${base}/status`)).body.project, "default");
+      const first = post(base, JSON.stringify({ path: ws }));
+      await waitFor(async () => (await getJson(`${base}/status`)).body.indexing.status === "indexing", 1e4, "indexing to start");
+      const overlap = await post(base, JSON.stringify({ path: ws }));
+      assert.equal(overlap.status, 409);
+      const done = await first;
+      assert.equal(done.status, 200, JSON.stringify(done.body));
+      assert.equal(done.body.project, "default");
+      assert.equal(done.body.repos, 2);
+      assert.ok(done.body.crossRepoEdges >= 1, `crossRepoEdges=${done.body.crossRepoEdges}`);
+      const status = (await getJson(`${base}/status`)).body;
+      assert.equal(status.project, "default");
+      assert.equal(status.directoryPath, ws);
+      assert.equal(status.indexReady, true);
+    } finally {
+      p.kill();
+      await p.exited;
+    }
+  });
+});
+describe("cluster mode", () => {
+  it("workers report the primary's indexing state", async () => {
+    const env = baseEnv({
+      home: join(root, "home"),
+      dataDir: join(root, "data2"),
+      embedderUrl: slow.url,
+      extra: { CODE_SEARCH_WORKERS: "2" }
+    });
+    const p = spawnProc(BIN.mcp, ["--serve", "--port", "47397"], env);
+    const base = "http://127.0.0.1:47397";
+    try {
+      await waitFor(async () => (await getJson(`${base}/health`)).status === 200, 2e4, `health
+${p.stderr()}`);
+      const indexed = post(base, JSON.stringify({ path: ws }));
+      await waitFor(async () => (await getJson(`${base}/status`)).body.indexing.status === "indexing", 1e4, `worker sees indexing
+${p.stderr()}`);
+      const done = await indexed;
+      assert.equal(done.status, 200, JSON.stringify(done.body));
+      await waitFor(async () => {
+        for (let i = 0; i < 6; i++) {
+          const s = (await getJson(`${base}/status`)).body;
+          if (s.indexing.status !== "idle" || !s.indexReady || !s.indexing.lastSuccess) return false;
+        }
+        return true;
+      }, 5e3, "every worker to report the finished index");
+      assert.equal((await getJson(`${base}/admin/api/status`)).body.indexing.status, "idle");
+    } finally {
+      p.child.kill("SIGTERM");
+      await exitWithin(p, 5e3);
+    }
+  });
+  it("enforces one rate limit for the whole server", async () => {
+    const env = baseEnv({
+      home: join(root, "home"),
+      dataDir: join(root, "data3"),
+      extra: {
+        CODE_SEARCH_WORKERS: "2",
+        CODE_SEARCH_AUTH_MODE: "api-key",
+        CODE_SEARCH_AUTH_API_KEYS: "cluster-key-0001",
+        CODE_SEARCH_RATE_LIMIT_PER_MINUTE: "4",
+        CODE_SEARCH_HOST: "127.0.0.1"
+      }
+    });
+    const p = spawnProc(BIN.mcp, ["--serve", "--port", "47398"], env);
+    const base = "http://127.0.0.1:47398";
+    try {
+      await waitFor(async () => (await getJson(`${base}/health`)).status === 200, 2e4, `health
+${p.stderr()}`);
+      await waitFor(() => (p.stderr().match(/Server running for/g) ?? []).length >= 2, 2e4, "two workers");
+      const statuses = [];
+      for (let i = 0; i < 10; i++) {
+        statuses.push((await getJson(`${base}/admin/api/status`, { headers: { Authorization: "Bearer cluster-key-0001" } })).status);
+      }
+      assert.equal(statuses.filter((s) => s === 200).length, 4, statuses.join(","));
+      assert.equal(statuses.filter((s) => s === 429).length, 6, statuses.join(","));
+    } finally {
+      p.child.kill("SIGTERM");
+      await exitWithin(p, 5e3);
+    }
+  });
+});

package/dist/__tests__/metrics-collect.test.js

@@ -0,0 +1,48 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { rmSync } from "node:fs";
+import { getBlobStore } from "@esankhan3/anvil-knowledge-core";
+import { collectIndexMetrics } from "../server.js";
+import { registry } from "../observability/metrics.js";
+import { tmp } from "./_harness.js";
+let dataDir;
+before(() => {
+  dataDir = tmp("cs-metrics-");
+  process.env.CODE_SEARCH_DATA_DIR = dataDir;
+});
+after(() => rmSync(dataDir, { recursive: true, force: true }));
+const KC = { embedding: { provider: "ollama" }, chunking: { maxTokens: 500 }, retrieval: { maxChunks: 8, maxTokens: 12e3 } };
+describe("collectIndexMetrics", () => {
+  it("reports real index age + chunks and clears gauges whose blob vanished", async () => {
+    const blobs = getBlobStore("p", KC);
+    await blobs.putJson("index_stats.json", {
+      repos: [{ name: "a", chunkCount: 3, language: "ts" }, { name: "b", chunkCount: 5, language: "ts" }],
+      lastIndexed: new Date(Date.now() - 42e3).toISOString()
+    });
+    await blobs.putJson("vector_index.json", { rowsAddedSinceTrain: 5, trainedRows: 10, numUnindexedRows: 7, checkedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    await collectIndexMetrics("p", KC);
+    let out = registry.render();
+    const age = Number(out.match(/^code_search_index_age_seconds\{project="p"\} (\d+)$/m)?.[1]);
+    assert.ok(age >= 42 && age < 60, `age=${age}`);
+    assert.match(out, /^code_search_index_chunks_total\{project="p",repo="a"\} 3$/m);
+    assert.match(out, /^code_search_index_chunks_total\{project="p",repo="b"\} 5$/m);
+    assert.match(out, /^code_search_vector_index_unindexed_rows\{project="p"\} 7$/m);
+    assert.match(out, /^code_search_vector_index_growth_ratio\{project="p"\} 0\.5$/m);
+    await collectIndexMetrics("p", KC, new Date(Date.now() - 2e3).toISOString());
+    assert.ok(Number(registry.render().match(/^code_search_index_age_seconds\{project="p"\} (\d+)$/m)?.[1]) < 10);
+    await blobs.delete("vector_index.json");
+    await blobs.putJson("index_stats.json", { repos: [{ name: "a", chunkCount: 4, language: "ts" }], lastIndexed: (/* @__PURE__ */ new Date()).toISOString() });
+    await collectIndexMetrics("p", KC);
+    out = registry.render();
+    assert.doesNotMatch(out, /code_search_vector_index_unindexed_rows\{/);
+    assert.doesNotMatch(out, /code_search_vector_index_growth_ratio\{/);
+    assert.doesNotMatch(out, /repo="b"/);
+    assert.match(out, /^code_search_index_chunks_total\{project="p",repo="a"\} 4$/m);
+  });
+  it("declares no metric that nothing records", () => {
+    const out = registry.render();
+    for (const dead of ["embeddings_calls_total", "llm_calls_total", "reranker_cache_hits_total"]) {
+      assert.doesNotMatch(out, new RegExp(`code_search_${dead}`));
+    }
+  });
+});

package/dist/__tests__/observability.test.js

@@ -58,12 +58,11 @@ describe("Logger (P7)", () => {
     assert.equal(lines.length, 1);
     assert.match(lines[0], /"kept"/);
   });
-  it("falls back to text mode when structured=false", () => {
+  it("passes text through unchanged when structured=false", () => {
     const lines = [];
     const log = new Logger({ structured: false, write: (l) => lines.push(l) });
     log.error("boom");
-    assert.equal(lines.length, 1);
-    assert.match(lines[0], /ERROR/);
-    assert.match(lines[0], /boom/);
+    log.info("ready", { component: "code-search-mcp" });
+    assert.deepEqual(lines, ["boom", "[code-search-mcp] ready"]);
   });
 });