@esankhan3/code-search-mcp 1.0.5 → 1.1.0

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"]);
   });
 });

package/dist/__tests__/remote-proxy.test.js

@@ -0,0 +1,105 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { rmSync } from "node:fs";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { BIN, tmp, baseEnv } from "./_harness.js";
+const PORT = 47389;
+const GOOD_KEY = "good-key-1234";
+let remote;
+let root;
+before(async () => {
+  root = tmp("cs-proxy-");
+  remote = createServer((req, res) => {
+    if (req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", project: "remote", indexReady: true }));
+      return;
+    }
+    let body = "";
+    req.on("data", (c) => {
+      body += c.toString();
+    });
+    req.on("end", () => {
+      if (req.headers.authorization !== `Bearer ${GOOD_KEY}`) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid API key" }));
+        return;
+      }
+      const msg = JSON.parse(body);
+      if (msg.method === "initialize") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: { protocolVersion: "2024-11-05", capabilities: {}, serverInfo: { name: "fake", version: "0" } } }));
+        return;
+      }
+      if (msg.method === "resources/list") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "Method not found: resources/list" } }));
+        return;
+      }
+      const reply = JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: { tools: [{ name: "remote_tool", inputSchema: { type: "object" } }] } });
+      const half = Math.floor(reply.length / 2);
+      res.writeHead(200, { "Content-Type": "text/event-stream" });
+      res.end(
+        `event: message
+data: ${JSON.stringify({ jsonrpc: "2.0", method: "notifications/message", params: { level: "info", data: "hi" } })}
+
+event: message
+data: ${JSON.stringify({ jsonrpc: "2.0", id: 999, result: { tools: [] } })}
+
+event: message
+data: ${reply.slice(0, half)}
+data: ${reply.slice(half)}
+
+`
+      );
+    });
+  });
+  await new Promise((r) => remote.listen(PORT, "127.0.0.1", () => r()));
+});
+after(async () => {
+  remote.closeAllConnections();
+  await new Promise((r) => remote.close(r));
+  rmSync(root, { recursive: true, force: true });
+});
+async function proxyClient(key) {
+  const client = new Client({ name: "proxy-test", version: "1.0.0" });
+  const env = baseEnv({ home: join(root, "home") });
+  await client.connect(new StdioClientTransport({
+    command: process.execPath,
+    args: [BIN.mcp, "--remote", `http://127.0.0.1:${PORT}`, "--api-key", key],
+    env,
+    stderr: "pipe"
+  }));
+  return client;
+}
+describe("remote proxy", () => {
+  it("surfaces upstream auth failures as JSON-RPC errors", async () => {
+    const client = await proxyClient("wrong-key");
+    try {
+      await assert.rejects(() => client.listTools(), /401/);
+      await assert.rejects(() => client.listResources(), /401/);
+    } finally {
+      await client.close();
+    }
+  });
+  it("relays a remote JSON-RPC error", async () => {
+    const client = await proxyClient(GOOD_KEY);
+    try {
+      await assert.rejects(() => client.listResources(), /Method not found: resources\/list/);
+    } finally {
+      await client.close();
+    }
+  });
+  it("picks the SSE event answering its request id", async () => {
+    const client = await proxyClient(GOOD_KEY);
+    try {
+      const { tools } = await client.listTools();
+      assert.deepEqual(tools.map((t) => t.name), ["remote_tool"]);
+    } finally {
+      await client.close();
+    }
+  });
+});

package/dist/__tests__/server-cli-args.test.js

@@ -0,0 +1,146 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import {
+  BIN,
+  tmp,
+  makeWorkspace,
+  baseEnv,
+  spawnProc,
+  run,
+  getJson,
+  waitFor,
+  startFakeEmbedder
+} from "./_harness.js";
+let root;
+let ws;
+let embedder;
+let env;
+before(async () => {
+  root = tmp("cs-args-");
+  ws = makeWorkspace(root);
+  embedder = await startFakeEmbedder(47390);
+  env = baseEnv({ home: join(root, "home"), dataDir: join(root, "data"), embedderUrl: embedder.url });
+});
+after(async () => {
+  await embedder.close();
+  rmSync(root, { recursive: true, force: true });
+});
+async function printConfig(args, cwd, extra = {}) {
+  const r = await run(BIN.mcp, ["--print-config", ...args], { ...env, ...extra }, cwd);
+  assert.equal(r.code, 0, r.stderr);
+  return { cfg: JSON.parse(r.stdout), stderr: r.stderr };
+}
+describe("code-search-mcp argv", () => {
+  it("--print-config reports dotted flags and --port under server.port", async () => {
+    const { cfg } = await printConfig(["--serve", "--port", "47381", "--retrieval.max-chunks", "12"]);
+    assert.equal(cfg.server.port, 47381);
+    assert.equal(cfg.retrieval.maxChunks, 12);
+    assert.equal(cfg.port, void 0);
+  });
+  it("--print-config flags an invalid reindex interval as disabled", async () => {
+    const { cfg, stderr } = await printConfig([], void 0, { CODE_SEARCH_REINDEX_INTERVAL: "90s" });
+    assert.equal(cfg.indexing.reindexIntervalMs, 0);
+    assert.match(stderr, /invalid reindex interval "90s"/i);
+  });
+  it("--print-config applies the cwd .code-search.yaml layer", async () => {
+    const dir = tmp("cs-wsy-");
+    writeFileSync(join(dir, ".code-search.yaml"), "retrieval:\n  max_chunks: 17\n");
+    const { cfg } = await printConfig([], dir);
+    assert.equal(cfg.retrieval.maxChunks, 17);
+    const cli = await run(BIN.cli, ["--print-config"], env, dir);
+    assert.equal(JSON.parse(cli.stdout).retrieval.maxChunks, 17);
+  });
+  it("serve mode accepts dotted flags, --serve <path>, and any mode-flag order", async () => {
+    const variants = [
+      ["--serve", ws, "--port", "47381", "--retrieval.max-chunks", "12"],
+      ["--serve", "--local", ws, "--port", "47381"],
+      ["--local", ws, "--serve", "--port", "47381"]
+    ];
+    for (const args of variants) {
+      const p = spawnProc(BIN.mcp, args, env);
+      try {
+        await waitFor(async () => (await getJson("http://127.0.0.1:47381/health")).status === 200, 2e4, `health for ${args.join(" ")}
+${p.stderr()}`);
+        const status = await getJson("http://127.0.0.1:47381/status");
+        assert.equal(status.body.directoryPath, ws, args.join(" "));
+        assert.match(p.stderr(), /LLM: disabled/);
+      } finally {
+        p.kill();
+        await p.exited;
+      }
+    }
+  });
+  it("--transport sse fails clearly instead of starting another transport", async () => {
+    const r = await run(BIN.mcp, ["--serve", "--port", "47382", "--transport", "sse"], env);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /SSE transport is not supported/);
+  });
+  it("unknown flags exit 2", async () => {
+    const r = await run(BIN.mcp, ["--serve", "--retrieval.max-chunkz", "3"], env);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /unknown flag.*--retrieval\.max-chunkz/i);
+  });
+});
+describe("code-search subcommands", () => {
+  it("index --project p <dir> indexes <dir> as p and reports cross-repo edges", async () => {
+    const r = await run(BIN.cli, ["index", "--project", "wsx", ws], env);
+    assert.equal(r.code, 0, r.stderr);
+    const out = JSON.parse(r.stdout);
+    assert.equal(out.project, "wsx");
+    assert.equal(out.repos, 2);
+    assert.ok(out.crossRepoEdges >= 1, `crossRepoEdges=${out.crossRepoEdges}`);
+  });
+  it("query takes the positional text even after flags", async () => {
+    const r = await run(BIN.cli, ["query", "--project", "wsx", "--mode", "bm25", "--format", "json", "--no-daemon", "welcome email"], env);
+    assert.equal(r.code, 0, r.stderr);
+    assert.equal(JSON.parse(r.stdout).query, "welcome email");
+  });
+  it("rejects unknown flags and invalid --format / --top-k with exit 2", async () => {
+    for (const args of [
+      ["query", "--retrieval.max-chunkz", "3", "x"],
+      ["query", "--format", "xml", "x"],
+      ["query", "--top-k", "abc", "x"],
+      ["query", "--top-k", "0", "x"],
+      ["index", "--top-k", "3", ws],
+      ["status", "--bogus"]
+    ]) {
+      const r = await run(BIN.cli, args, env);
+      assert.equal(r.code, 2, `${args.join(" ")} \u2192 ${r.code}
+${r.stderr}`);
+    }
+  });
+  it("status reports where the KB lives and never creates dirs for unknown projects", async () => {
+    const r = await run(BIN.cli, ["status", "--project", "nope"], env);
+    assert.equal(r.code, 0, r.stderr);
+    const s = JSON.parse(r.stdout);
+    assert.equal(s.indexed, false);
+    assert.equal(s.daemonAlive, false);
+    assert.equal(existsSync(join(root, "data", "nope")), false);
+    const ok = JSON.parse((await run(BIN.cli, ["status", "--project", "wsx"], env)).stdout);
+    assert.equal(ok.indexed, true);
+    assert.equal(ok.kbPath, join(root, "data", "wsx"));
+  });
+  it("storage.dataDir from the CLI moves the KB", async () => {
+    const { CODE_SEARCH_DATA_DIR: _drop, ...noDataDir } = env;
+    const dd = join(root, "dd2");
+    const r = await run(BIN.cli, ["index", ws, "--project", "moved", "--storage.data-dir", dd], noDataDir);
+    assert.equal(r.code, 0, r.stderr);
+    assert.ok(existsSync(join(dd, "moved", "index_stats.json")), "KB written under --storage.data-dir");
+    assert.equal(existsSync(join(root, "home", ".anvil", "knowledge-base", "moved")), false);
+    const s = JSON.parse((await run(BIN.cli, ["status", "--project", "moved", "--storage.data-dir", dd], noDataDir)).stdout);
+    assert.equal(s.dataDir, dd);
+    assert.equal(s.indexed, true);
+  });
+  it("bare `code-search mcp` serves the cwd over stdio (as its help says)", async () => {
+    const p = spawnProc(BIN.cli, ["mcp", "--project", "wsx"], env, ws);
+    try {
+      await p.waitForStderr(/Server running for "wsx" \(stdio\)/);
+      assert.doesNotMatch(p.stderr(), /No remote server configured/);
+    } finally {
+      p.kill();
+      await p.exited;
+    }
+  });
+});