@esankhan3/code-search-mcp 1.0.6 → 1.1.0

package/dist/__tests__/server-lifecycle.test.js

@@ -0,0 +1,108 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import {
+  BIN,
+  tmp,
+  makeWorkspace,
+  baseEnv,
+  spawnProc,
+  getJson,
+  waitFor,
+  exitWithin,
+  startFakeEmbedder
+} from "./_harness.js";
+const PKG_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8")).version;
+let root;
+let ws;
+let slow;
+let fast;
+before(async () => {
+  root = tmp("cs-life-");
+  ws = makeWorkspace(root);
+  slow = await startFakeEmbedder(47391, { delayMs: 2500 });
+  fast = await startFakeEmbedder(47392);
+});
+after(async () => {
+  await slow.close();
+  await fast.close();
+  rmSync(root, { recursive: true, force: true });
+});
+describe("HTTP server lifecycle", () => {
+  it("answers /health and /ready during the startup index, then serves", async () => {
+    const env = baseEnv({ home: join(root, "home"), dataDir: join(root, "data1"), embedderUrl: slow.url });
+    const p = spawnProc(BIN.mcp, ["--local", ws, "--serve", "--port", "47383"], env);
+    const base = "http://127.0.0.1:47383";
+    try {
+      await waitFor(async () => (await getJson(`${base}/health`)).status === 200, 2e4, `health
+${p.stderr()}`);
+      const early = await getJson(`${base}/ready`);
+      assert.equal(early.status, 503, "not ready while the first index is still embedding");
+      assert.equal(early.body.ready, false);
+      await waitFor(async () => (await getJson(`${base}/ready`)).status === 200, 6e4, `ready
+${p.stderr()}`);
+      const version = await getJson(`${base}/version`);
+      assert.equal(version.body.version, PKG_VERSION);
+      const admin = await getJson(`${base}/admin/api/status`);
+      assert.equal(admin.body.version, PKG_VERSION);
+      const client = new Client({ name: "lifecycle-test", version: "1.0.0" });
+      await client.connect(new StreamableHTTPClientTransport(new URL(`${base}/mcp`)));
+      assert.equal(client.getServerVersion()?.version, PKG_VERSION);
+      const templates = (await client.listResourceTemplates()).resourceTemplates.map((t) => t.uriTemplate).sort();
+      assert.deepEqual(templates, ["code-search://repo/{name}/graph", "code-search://repo/{name}/profile"]);
+      await client.close();
+      const metrics = await (await fetch(`${base}/metrics`)).text();
+      const age = metrics.match(/^code_search_index_age_seconds\{project="default"\} (\d+)$/m);
+      assert.ok(age, `index_age missing:
+${metrics}`);
+      assert.ok(Number(age[1]) < 120, `index_age=${age[1]}`);
+      assert.doesNotMatch(metrics, /phase=/);
+      assert.match(metrics, /^code_search_index_chunks_total\{project="default",repo="orders"\} [1-9]\d*$/m);
+      p.child.kill("SIGTERM");
+      const exit = await exitWithin(p, 5e3);
+      assert.notEqual(exit, "timeout", "SIGTERM must terminate the HTTP server");
+    } finally {
+      p.kill();
+      await p.exited;
+    }
+  });
+  it("structured logs + reindex interval from the config file", async () => {
+    const env = baseEnv({
+      home: join(root, "home"),
+      dataDir: join(root, "data2"),
+      embedderUrl: fast.url,
+      extra: { CODE_SEARCH_STRUCTURED_LOGS: "1" }
+    });
+    const p = spawnProc(BIN.mcp, ["--serve", ws, "--port", "47384", "--indexing.reindex-interval-ms", "1h"], env);
+    try {
+      await waitFor(async () => (await getJson("http://127.0.0.1:47384/ready")).status === 200, 6e4, `ready
+${p.stderr()}`);
+      const lines = p.stderr().split("\n").filter(Boolean);
+      assert.ok(!lines.some((l) => l.startsWith("[code-search-mcp]")), `plain-text server lines:
+${p.stderr()}`);
+      const json = lines.filter((l) => l.startsWith("{")).map((l) => JSON.parse(l));
+      assert.ok(json.some((e) => e.component === "code-search-mcp" && e.msg === "Auto-reindex every 60m"), p.stderr());
+      assert.ok(json.some((e) => e.component === "auto-index" && e.level === "info"), "index progress goes through the logger");
+    } finally {
+      p.kill();
+      await p.exited;
+    }
+  });
+});
+describe("stdio server lifecycle", () => {
+  it("SIGTERM terminates --local stdio mode", async () => {
+    const env = baseEnv({ home: join(root, "home"), dataDir: join(root, "data3"), embedderUrl: fast.url });
+    const p = spawnProc(BIN.mcp, ["--local", ws], env);
+    try {
+      await p.waitForStderr(/Server running for "ws" \(stdio\)/, 6e4);
+      p.child.kill("SIGTERM");
+      const exit = await exitWithin(p, 5e3);
+      assert.notEqual(exit, "timeout", "SIGTERM must terminate the stdio server");
+    } finally {
+      p.kill();
+      await p.exited;
+    }
+  });
+});

package/dist/__tests__/tool-inputs.test.js

@@ -0,0 +1,178 @@
+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 { VectorStore, invalidateRetriever, resetLlmConfig } from "@esankhan3/anvil-knowledge-core";
+import { handleGraphTool, registerGraphTools } from "../tools/graph.js";
+import { handleSearchTool, registerSearchTools } from "../tools/search.js";
+import { handleProfileTool } from "../tools/profile.js";
+import { resetServerConfig } from "../core/env-config.js";
+import { registry } from "../observability/metrics.js";
+const PROJECT = "inputs";
+let tmp = "";
+const ENV_KEYS = [
+  "CODE_SEARCH_DATA_DIR",
+  "CODE_SEARCH_EMBEDDING_PROVIDER",
+  "CODE_SEARCH_OLLAMA_HOST",
+  "CODE_SEARCH_EMBEDDING_DIMENSIONS",
+  "CODE_SEARCH_RERANKER_PROVIDER",
+  "ANVIL_LLM_MODE",
+  "CODE_SEARCH_LLM_MODE"
+];
+const stash = {};
+function ctx(indexReady = true) {
+  return {
+    projectName: PROJECT,
+    directoryPath: null,
+    indexReady,
+    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 ?? "";
+function chunk(id, entityName, content) {
+  return {
+    id,
+    filePath: `src/${id}.ts`,
+    repoName: "app",
+    project: PROJECT,
+    startLine: 1,
+    endLine: 3,
+    content,
+    contextPrefix: "",
+    contextualizedContent: content,
+    language: "typescript",
+    entityType: "function",
+    entityName,
+    tokens: 10,
+    imports: [],
+    exports: [],
+    embedding: [1, 0, 0, 0]
+  };
+}
+before(async () => {
+  for (const k of ENV_KEYS) stash[k] = process.env[k];
+  tmp = mkdtempSync(join(tmpdir(), "cs-inputs-"));
+  process.env.CODE_SEARCH_DATA_DIR = tmp;
+  process.env.CODE_SEARCH_EMBEDDING_PROVIDER = "ollama";
+  process.env.CODE_SEARCH_OLLAMA_HOST = "http://127.0.0.1:47361";
+  process.env.CODE_SEARCH_EMBEDDING_DIMENSIONS = "4";
+  process.env.CODE_SEARCH_RERANKER_PROVIDER = "none";
+  process.env.ANVIL_LLM_MODE = "none";
+  process.env.CODE_SEARCH_LLM_MODE = "none";
+  resetServerConfig();
+  resetLlmConfig();
+  mkdirSync(join(tmp, PROJECT), { recursive: true });
+  const store = new VectorStore(join(tmp, PROJECT, "lancedb"));
+  await store.init();
+  await store.upsertChunks([
+    chunk("a", "chargeCustomer", "export function chargeCustomer(amount: number) { return gateway.charge(amount); }"),
+    chunk("b", "refundCustomer", "export function refundCustomer(id: string) { return gateway.refund(id); }")
+  ]);
+  await store.ensureFtsIndex();
+});
+after(async () => {
+  await invalidateRetriever();
+  rmSync(tmp, { recursive: true, force: true });
+  for (const k of ENV_KEYS) {
+    if (stash[k] === void 0) delete process.env[k];
+    else process.env[k] = stash[k];
+  }
+  resetServerConfig();
+  resetLlmConfig();
+});
+describe("input validation", () => {
+  const cases = [
+    ["search", "search_code", {}, /query/],
+    ["search", "search_code", { query: "   " }, /query/],
+    ["search", "search_code", { query: 5 }, /query.*string/],
+    ["search", "search_code", { query: "x", maxResults: 0 }, /maxResults/],
+    ["search", "search_exact", { query: "x", repos: 5 }, /"repos" must be a non-empty array of strings or a non-empty string/],
+    ["search", "search_exact", { query: "x", repos: { app: true } }, /repos/],
+    ["search", "search_exact", { query: "x", repos: [] }, /repos/],
+    ["search", "search_exact", { query: "x", repos: "" }, /repos/],
+    ["search", "search_exact", { query: "x", repos: " , " }, /repos.*at least one/],
+    ["search", "get_code_snippet", {}, /id|repo/],
+    ["graph", "detect_changes", {}, /repo/],
+    ["graph", "trace_path", { from: "a", direction: "sideways" }, /direction.*callees, callers, both/],
+    ["graph", "trace_path", { from: "a", maxDepth: 0 }, /maxDepth/],
+    ["graph", "trace_path", { from: "a", maxDepth: 11 }, /maxDepth/],
+    ["graph", "find_callers", { function: "a", relations: ["friends"] }, /relations/],
+    ["graph", "impact_analysis", { repo: "app" }, /file/],
+    ["graph", "search_graph", { limit: "ten" }, /limit/],
+    ["graph", "find_dead_code", { repo: "app", limit: -1 }, /limit/]
+  ];
+  for (const [kind, name, args, re] of cases) {
+    it(`${name} ${JSON.stringify(args)} \u2192 isError`, async () => {
+      const r = kind === "search" ? await handleSearchTool(name, args, ctx()) : await handleGraphTool(name, args, ctx());
+      assert.equal(r?.isError, true, text(r));
+      assert.match(text(r), re);
+    });
+  }
+  it("get_repo_profile without repo \u2192 isError", async () => {
+    const r = await handleProfileTool("get_repo_profile", {}, ctx());
+    assert.equal(r?.isError, true);
+  });
+});
+describe("search_exact without an embedder", () => {
+  it("serves BM25 even while the index is not ready", async () => {
+    const r = await handleSearchTool("search_exact", { query: "refundCustomer" }, ctx(false));
+    assert.notEqual(r.isError, true, text(r));
+    assert.match(text(r), /refundCustomer/);
+  });
+  it("accepts repos as an array, one name, or a comma-separated list \u2014 and applies it", async () => {
+    for (const repos of [["app"], "app", "other, app"]) {
+      const r = await handleSearchTool("search_exact", { query: "refundCustomer", repos }, ctx());
+      assert.notEqual(r.isError, true, `${JSON.stringify(repos)}: ${text(r)}`);
+      assert.match(text(r), /refundCustomer/, JSON.stringify(repos));
+    }
+    assert.match(text(await handleSearchTool("search_exact", { query: "refundCustomer", repos: "other" }, ctx())), /No results/);
+  });
+  it("records the query metrics", async () => {
+    await handleSearchTool("search_exact", { query: "chargeCustomer" }, ctx());
+    const body = registry.render();
+    assert.match(body, /code_search_queries_total\{[^}]*mode="bm25"[^}]*\} \d+/);
+    assert.match(body, /code_search_query_duration_seconds_count\{mode="bm25"\} \d+/);
+  });
+  it("hybrid search reports an embedder failure as an error and counts it", async () => {
+    const r = await handleSearchTool("search_code", { query: "charge customer" }, ctx());
+    assert.equal(r.isError, true);
+    assert.match(registry.render(), /code_search_errors_total\{kind="search"\} \d+/);
+  });
+});
+describe("hints", () => {
+  it("index-not-ready does not point at a reindex tool", async () => {
+    const t = text(await handleSearchTool("search_semantic", { query: "x" }, ctx(false)));
+    assert.match(t, /not ready/i);
+    assert.doesNotMatch(t, /reindex tool/);
+  });
+  it("missing profile with LLM off says profiles need an LLM", async () => {
+    const t = text(await handleProfileTool("get_repo_profile", { repo: "app" }, ctx()));
+    assert.match(t, /LLM/);
+    assert.doesNotMatch(t, /Run reindex/);
+  });
+});
+describe("descriptors match behaviour", () => {
+  const search = Object.fromEntries(registerSearchTools().map((t) => [t.name, t]));
+  const graph = Object.fromEntries(registerGraphTools().map((t) => [t.name, t]));
+  it("search_semantic / search_exact advertise repos", () => {
+    assert.ok(search.search_semantic.inputSchema.properties.repos);
+    assert.ok(search.search_exact.inputSchema.properties.repos);
+  });
+  it("trace_path is not described as confidence-weighted; search_graph name is a regex", () => {
+    assert.doesNotMatch(graph.trace_path.description, /confidence-weighted/);
+    assert.match(graph.search_graph.inputSchema.properties.name.description, /regex/i);
+    assert.ok(graph.find_callers.inputSchema.properties.relations);
+  });
+});

package/dist/backends/in-process.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { existsSync } from "node:fs";
 import {
   getRetriever,
+  invalidateRetriever,
   indexFromPath,
   getKnowledgeBasePath,
   KnowledgeIndexer,
@@ -60,7 +61,7 @@ class InProcessBackend {
   }
   async status() {
     const indexer = new KnowledgeIndexer();
-    const stats = await indexer.getStats(this.project);
+    const stats = await indexer.getStats(this.project, this.knowledge);
     return {
       totalChunks: stats.totalChunks,
       repos: stats.repos,
@@ -79,6 +80,7 @@ class InProcessBackend {
       force: opts?.force,
       config: this.knowledge
     });
+    await invalidateRetriever(this.project);
     return this.status();
   }
   async invalidate(paths) {
@@ -91,10 +93,11 @@ class InProcessBackend {
     const stats = await store.getStats();
     if (!stats || stats.rowCount === 0) return;
     const indexer = new KnowledgeIndexer();
-    const summary = await indexer.getStats(this.project);
+    const summary = await indexer.getStats(this.project, this.knowledge);
     for (const r of summary.repos) {
       await store.deleteFileChunks(this.project, r.name, paths);
     }
+    await invalidateRetriever(this.project);
   }
   async close() {
   }

package/dist/backends/index.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { InProcessBackend } from "./in-process.js";
 import { DaemonBackend } from "./daemon-client.js";
+import { getComponentLogger } from "../observability/logger.js";
 export * from "./types.js";
 import { InProcessBackend as InProcessBackend2 } from "./in-process.js";
 import { DaemonBackend as DaemonBackend2 } from "./daemon-client.js";
@@ -16,8 +17,7 @@ async function pickBackend(cfg) {
   if (cfg.preferDaemon && socketPath && existsSync(socketPath)) {
     const daemon = new DaemonBackend({ ...cfg, socketPath });
     if (await daemon.ping()) return daemon;
-    process.stderr.write(`[code-search-mcp] daemon socket exists at ${socketPath} but ping failed; using in-process backend
-`);
+    getComponentLogger("code-search").warn(`daemon socket exists at ${socketPath} but ping failed; using in-process backend`);
   }
   return new InProcessBackend(cfg);
 }

package/dist/cli/index.js

@@ -1,20 +1,28 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
-import { join, resolve as resolvePath } from "node:path";
+import { constants as osConstants } from "node:os";
+import { dirname, join, resolve as resolvePath, basename } from "node:path";
 import {
   resolveCodeSearchConfig,
   parseCliFlags,
   printConfig,
-  toKnowledgeConfig
+  redactSecrets,
+  toKnowledgeConfig,
+  exportDataDir
 } from "../core/config.js";
+import { validateProjectName } from "../core/project-name.js";
 import {
   indexFromPath,
   KnowledgeIndexer,
+  getBlobStore,
   getKnowledgeBasePath,
   loadProfile
 } from "@esankhan3/anvil-knowledge-core";
-import { pickBackend, daemonSocketPath } from "../backends/index.js";
+import { pickBackend, daemonSocketPath, DaemonBackend } from "../backends/index.js";
+import { configureLogger, getComponentLogger } from "../observability/logger.js";
+const log = getComponentLogger("code-search");
+const FORMATS = /* @__PURE__ */ new Set(["text", "json", "jsonl"]);
 const HELP_TEXT = `code-search \u2014 multi-repo code intelligence
 
 USAGE:
@@ -26,9 +34,14 @@ COMMANDS:
   query <text>                     hybrid search; print top-K
   status                           show index + daemon health
   reset [--project <name>]         drop the project's index
-  daemon --workspace <path>        spawn the long-running daemon
-  serve [--port N] [--auth mode]   HTTP MCP server
-  mcp                              stdio MCP server (Claude Desktop)
+  daemon --workspace <path>        run the long-running daemon
+  serve [path] [--port N] [--auth mode]   HTTP MCP server
+  mcp [path]                       stdio MCP server over local repos (default: cwd)
+  mcp --remote <url>               stdio proxy to a remote code-search server
+
+INDEX OPTIONS:
+  --project <name>                 project namespace (default: path basename)
+  --force                          full re-index
 
 QUERY OPTIONS:
   --mode hybrid|vector|bm25        retrieval mode (default: hybrid)
@@ -36,6 +49,7 @@ QUERY OPTIONS:
   --repo <name>                    restrict to a repo (repeatable)
   --format text|json|jsonl         output format (default: text)
   --project <name>                 project namespace (default: cwd basename)
+  --no-daemon                      search in-process even if a daemon is running
 
 CONFIG:
   Every leaf in CodeSearchConfig is settable via --<dotted-path>.
@@ -44,6 +58,11 @@ CONFIG:
     --retrieval.max-chunks 20
     --no-indexing.auto-index
 `;
+function usageError(msg) {
+  process.stderr.write(`code-search: ${msg}
+`);
+  process.exit(2);
+}
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
@@ -51,8 +70,7 @@ async function main() {
     process.exit(0);
   }
   if (argv[0] === "--print-config") {
-    const { patch } = parseCliFlags(argv.slice(1));
-    const cfg = resolveCodeSearchConfig({ cli: patch });
+    const { cfg } = parseCommand("--print-config", argv.slice(1), {}, process.cwd());
     process.stdout.write(printConfig(cfg) + "\n");
     process.exit(0);
   }
@@ -79,68 +97,100 @@ ${HELP_TEXT}`);
       process.exit(2);
   }
 }
-function takeFlag(rest, name) {
-  const idx = rest.indexOf(name);
-  if (idx < 0) return void 0;
-  return rest[idx + 1];
+function parseCommand(cmd, argv, spec, workspaceDir) {
+  const { patch, rest, unknown } = parseCliFlags(argv);
+  if (unknown.length) usageError(`${cmd}: unknown flag(s): ${unknown.join(", ")}`);
+  const values = /* @__PURE__ */ new Map();
+  const bools = /* @__PURE__ */ new Set();
+  const positionals = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--help" || a === "-h") {
+      process.stdout.write(HELP_TEXT);
+      process.exit(0);
+    }
+    if (spec.values?.includes(a)) {
+      const v = rest[i + 1];
+      if (v === void 0 || v.startsWith("--")) usageError(`${cmd}: ${a} needs a value`);
+      values.set(a, [...values.get(a) ?? [], v]);
+      i++;
+    } else if (spec.bools?.includes(a)) {
+      bools.add(a);
+    } else if (a.startsWith("-") && a.length > 1 && Number.isNaN(Number(a))) {
+      usageError(`${cmd}: unknown flag ${a}`);
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (spec.maxPositionals !== void 0 && positionals.length > spec.maxPositionals) {
+    usageError(`${cmd}: unexpected argument(s): ${positionals.slice(spec.maxPositionals).join(" ")}`);
+  }
+  const cfg = resolveCodeSearchConfig({ cli: patch, workspaceDir: workspaceDir ?? positionals[0] ?? process.cwd() });
+  configureLogger({ structured: cfg.telemetry.structuredLogs });
+  return { cfg, values, bools, positionals };
 }
-function projectFromPath(p) {
-  return resolvePath(p).split("/").filter(Boolean).pop() || "project";
+function flag(p, name) {
+  const v = p.values.get(name);
+  return v?.[v.length - 1];
+}
+function projectArg(p, fallbackDir) {
+  const name = flag(p, "--project") ?? basename(resolvePath(fallbackDir));
+  try {
+    return validateProjectName(name);
+  } catch (err) {
+    usageError(err.message);
+  }
 }
 async function cmdIndex(rest) {
-  const { patch, rest: positional } = parseCliFlags(rest);
-  const path = positional.find((a) => !a.startsWith("--")) ?? process.cwd();
-  const cfg = resolveCodeSearchConfig({ cli: patch, workspaceDir: path });
-  const project = takeFlag(positional, "--project") ?? projectFromPath(path);
-  const force = positional.includes("--force");
-  process.stderr.write(`[code-search] indexing ${path} as project "${project}"...
-`);
-  const stats = await indexFromPath(project, resolvePath(path), {
-    force,
-    config: toKnowledgeConfig(cfg),
-    onProgress: (m) => process.stderr.write(`[code-search] ${m}
-`)
+  const p = parseCommand("index", rest, { values: ["--project"], bools: ["--force"], maxPositionals: 1 });
+  const path = resolvePath(p.positionals[0] ?? process.cwd());
+  exportDataDir(p.cfg);
+  const project = projectArg(p, path);
+  const knowledge = toKnowledgeConfig(p.cfg);
+  log.info(`indexing ${path} as project "${project}"...`);
+  const stats = await indexFromPath(project, path, {
+    force: p.bools.has("--force"),
+    config: knowledge,
+    onProgress: (m) => log.info(m)
   });
+  const rollup = await new KnowledgeIndexer().getStats(project, knowledge);
   process.stdout.write(JSON.stringify({
     project,
     chunks: stats.totalChunks,
     repos: stats.repos.length,
-    crossRepoEdges: stats.crossRepoEdges,
+    crossRepoEdges: rollup.crossRepoEdges,
     durationMs: stats.indexDurationMs
   }, null, 2) + "\n");
 }
 const VALID_MODES = /* @__PURE__ */ new Set(["hybrid", "vector", "bm25"]);
 async function cmdQuery(rest) {
-  const { patch, rest: positional } = parseCliFlags(rest);
-  const queryText = positional.find((a) => !a.startsWith("--") && !a.startsWith("-"));
-  if (!queryText) {
-    process.stderr.write("code-search query: missing <text>\n");
-    process.exit(2);
-  }
-  const rawMode = takeFlag(positional, "--mode") ?? "hybrid";
+  const p = parseCommand("query", rest, {
+    values: ["--project", "--mode", "--top-k", "--format", "--repo"],
+    bools: ["--no-daemon"]
+  }, process.cwd());
+  const queryText = p.positionals.join(" ");
+  if (!queryText) usageError("query: missing <text>");
+  const rawMode = flag(p, "--mode") ?? "hybrid";
   if (!VALID_MODES.has(rawMode)) {
-    process.stderr.write(
-      `code-search query: invalid --mode "${rawMode}". Valid modes: ${[...VALID_MODES].join(", ")}.
-`
-    );
-    process.exit(2);
+    usageError(`query: invalid --mode "${rawMode}". Valid modes: ${[...VALID_MODES].join(", ")}.`);
   }
   const mode = rawMode;
-  const topK = parseInt(takeFlag(positional, "--top-k") ?? "10", 10);
-  const repos = positional.reduce((acc, a, i) => {
-    if (a === "--repo" && positional[i + 1]) acc.push(positional[i + 1]);
-    return acc;
-  }, []);
-  const format = takeFlag(positional, "--format") ?? "text";
-  const project = takeFlag(positional, "--project") ?? projectFromPath(process.cwd());
-  const cfg = resolveCodeSearchConfig({ cli: patch });
-  const socketPath = daemonSocketPath(cfg.storage.dataDir, project);
+  const rawTopK = flag(p, "--top-k") ?? "10";
+  if (!/^\d+$/.test(rawTopK) || parseInt(rawTopK, 10) < 1) {
+    usageError(`query: invalid --top-k "${rawTopK}" (a positive integer).`);
+  }
+  const topK = parseInt(rawTopK, 10);
+  const format = flag(p, "--format") ?? "text";
+  if (!FORMATS.has(format)) usageError(`query: invalid --format "${format}". Valid formats: ${[...FORMATS].join(", ")}.`);
+  const repos = p.values.get("--repo") ?? [];
+  exportDataDir(p.cfg);
+  const project = projectArg(p, process.cwd());
   const backend = await pickBackend({
     project,
     workspaceDir: process.cwd(),
-    knowledge: toKnowledgeConfig(cfg),
-    preferDaemon: !cfg.daemon.disabled,
-    socketPath
+    knowledge: toKnowledgeConfig(p.cfg),
+    preferDaemon: !p.cfg.daemon.disabled && !p.bools.has("--no-daemon"),
+    socketPath: daemonSocketPath(p.cfg.storage.dataDir, project)
   });
   const result = await backend.search(queryText, {
     mode,
@@ -174,37 +224,44 @@ function printSearchResult(result, format) {
   }
 }
 async function cmdStatus(rest) {
-  const { patch } = parseCliFlags(rest);
-  const cfg = resolveCodeSearchConfig({ cli: patch });
-  const project = takeFlag(rest, "--project") ?? projectFromPath(process.cwd());
-  const indexer = new KnowledgeIndexer();
-  const stats = await indexer.getStats(project);
-  const socketPath = daemonSocketPath(cfg.storage.dataDir, project);
-  const profilesAvailable = await Promise.all(
-    stats.repos.map(async (r) => ({ name: r.name, hasProfile: !!await loadProfile(project, r.name) }))
-  );
+  const p = parseCommand("status", rest, { values: ["--project"], maxPositionals: 0 }, process.cwd());
+  exportDataDir(p.cfg);
+  const project = projectArg(p, process.cwd());
+  const knowledge = toKnowledgeConfig(p.cfg);
+  const socketPath = daemonSocketPath(p.cfg.storage.dataDir, project);
+  const daemonAlive = await new DaemonBackend({ project, workspaceDir: null, knowledge, preferDaemon: true, socketPath }).ping();
+  const blobs = getBlobStore(project, knowledge);
+  const indexed = await blobs.exists("index_stats.json") || await blobs.exists("lancedb");
+  const stats = indexed ? await new KnowledgeIndexer().getStats(project, knowledge) : null;
+  const profilesAvailable = stats ? await Promise.all(stats.repos.map(async (r) => ({ name: r.name, hasProfile: !!await loadProfile(project, r.name, knowledge) }))) : [];
   process.stdout.write(JSON.stringify({
     project,
-    dataDir: cfg.storage.dataDir,
+    dataDir: p.cfg.storage.dataDir,
+    ...p.cfg.storage.backends ? { storageBackends: redactSecrets(p.cfg.storage.backends) } : { kbPath: getKnowledgeBasePath(project) },
+    indexed,
     daemonSocket: socketPath,
-    daemonAlive: existsSync(socketPath),
-    totalChunks: stats.totalChunks,
-    embeddingProvider: stats.embeddingProvider,
-    lastIndexedAt: stats.lastIndexed || null,
-    repos: stats.repos,
+    daemonAlive,
+    totalChunks: stats?.totalChunks ?? 0,
+    embeddingProvider: stats?.embeddingProvider ?? null,
+    lastIndexedAt: stats?.lastIndexed || null,
+    repos: stats?.repos ?? [],
     profilesAvailable
   }, null, 2) + "\n");
 }
 async function cmdReset(rest) {
-  const project = takeFlag(rest, "--project") ?? projectFromPath(process.cwd());
-  const basePath = getKnowledgeBasePath(project);
+  const p = parseCommand("reset", rest, { values: ["--project"], maxPositionals: 0 }, process.cwd());
+  exportDataDir(p.cfg);
+  const project = projectArg(p, process.cwd());
+  const dataDir = p.cfg.storage.dataDir;
+  const basePath = resolvePath(getKnowledgeBasePath(project));
+  if (dirname(basePath) !== dataDir) {
+    usageError(`reset: refusing to remove ${basePath} \u2014 not a project directory inside ${dataDir}`);
+  }
   if (existsSync(basePath)) {
     rmSync(basePath, { recursive: true, force: true });
-    process.stderr.write(`[code-search] removed ${basePath}
-`);
+    log.info(`removed ${basePath}`);
   } else {
-    process.stderr.write(`[code-search] nothing to remove at ${basePath}
-`);
+    log.info(`nothing to remove at ${basePath}`);
   }
 }
 async function cmdDaemon(rest) {
@@ -214,18 +271,28 @@ async function cmdDaemon(rest) {
     stdio: "inherit",
     detached: false
   });
-  child.on("exit", (code) => process.exit(code ?? 0));
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(sig, () => {
+      try {
+        child.kill(sig);
+      } catch {
+      }
+    });
+  }
+  child.on("exit", (code, signal) => {
+    process.exit(code ?? 128 + (signal ? osConstants.signals[signal] ?? 0 : 0));
+  });
 }
 async function cmdServe(rest) {
   process.argv = [process.argv[0], process.argv[1], "--serve", ...rest];
   await import("../index.js");
 }
 async function cmdMcp(rest) {
-  process.argv = [process.argv[0], process.argv[1], ...rest];
+  const remote = rest.includes("--remote") || rest.some((a) => /^https?:\/\//.test(a));
+  process.argv = [process.argv[0], process.argv[1], ...remote ? [] : ["--local"], ...rest];
   await import("../index.js");
 }
 main().catch((err) => {
-  process.stderr.write(`code-search fatal: ${err instanceof Error ? err.stack : err}
-`);
+  log.error(`fatal: ${err instanceof Error ? err.stack : err}`);
   process.exit(1);
 });