@oomkapwn/enquire-mcp 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -2,6 +2,163 @@
 
 All notable changes to this project will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.12.0] — 2026-05-09
+
+**Sprint 12 — built-in retrieval-quality evaluation harness.** Closes the "you can't tune what you can't measure" gap. Before this, anyone trying to A/B test retrieval changes (graph_boost on/off, reranker on/off, different `min_signals` / `limit` values) had to write a custom script. Now there's a first-class `enquire-mcp eval` subcommand. **No other Obsidian-MCP currently ships a built-in retrieval evaluation harness.**
+
+### Added — `enquire-mcp eval --vault <path> --queries <file>`
+
+Reads a JSONL file of queries with known-relevant doc paths, runs `obsidian_search` for each, computes standard IR metrics, reports per-query + aggregate scores.
+
+**Input format** (one JSON object per line; tolerates blank lines and `//` comments):
+
+```jsonl
+{"id": "rkt", "query": "Apollo program rocket", "relevant": ["apollo.md", "saturn.md"]}
+{"id": "food", "query": "carbonara recipe", "relevant": ["pasta.md"]}
+```
+
+**Metrics** (from Manning et al, "Introduction to Information Retrieval", Chapter 8):
+- **NDCG@K** (Normalized Discounted Cumulative Gain) — penalizes relevant docs found low in the ranking; 1.0 perfect, 0.0 worst.
+- **Recall@K** — fraction of relevant docs found in top-K.
+- **MRR** (Mean Reciprocal Rank) — 1/rank of the first relevant doc; 0 if none.
+
+Binary-relevance ground truth (each path in `relevant` is gain=1, others gain=0) — most users won't label graded relevance, so this is the practical default.
+
+**Flags:**
+- `--k <n>` — top-K cutoff (default 10)
+- `--matrix` — 2×2 sweep of (graph_boost ± reranker), printed as a comparison table with the best-NDCG config highlighted
+- `--reranker` — enable cross-encoder reranking (same as `serve --enable-reranker`)
+- `--reranker-model <alias>` / `--reranker-top-n <n>` — pass-through reranker config
+- `--persistent-index` — open the FTS5 BM25 index for the eval (recommended; without it, the eval runs over TF-IDF only)
+- `--per-query` — print per-query scores in addition to aggregates
+- `--json` — emit machine-readable JSON (useful for piping into a comparison tool, dashboard, or CI gate)
+
+**Example output:**
+
+```
+enquire eval — default
+  12 queries · k=10 · wall=2483ms
+
+aggregate:
+  mean NDCG@10   = 0.7621
+  mean Recall@10 = 0.8333
+  mean MRR        = 0.8125
+  mean latency    = 187ms (per query)
+```
+
+**Matrix mode example:**
+
+```
+enquire eval matrix (4 configs)
+
+label                      NDCG@10  Recall@10  MRR     latency
+baseline (RRF only)        0.6420   0.7500     0.6250  142ms
++graph-boost               0.7150   0.8333     0.7083  148ms
++reranker                  0.8210   0.8333     0.9583  421ms
++graph-boost +reranker     0.8345   0.9167     0.9583  428ms
+
+best NDCG@10: +graph-boost +reranker (0.8345)
+```
+
+### Implementation
+
+`src/eval.ts` (~340 lines):
+- Pure-function metrics (`ndcgAtK`, `recallAtK`, `reciprocalRank`) — exact log2-based formulas, fully testable without I/O.
+- `readQueriesJsonl(file)` — tolerates blank lines + `//` comments, throws with line numbers on malformed input.
+- `runEval(opts)` — orchestrates per-query searchHybrid calls with per-query latency tracking and per-query failure isolation (one bad query doesn't sink the eval).
+- `formatEvalResult` / `formatEvalMatrix` — TTY-aware ANSI rendering, plain text on pipes.
+
+### Surface delta vs v2.11.0
+
+- **+1 CLI subcommand** (`eval`)
+- **+1 source module** (`src/eval.ts`)
+- **No new MCP tools, no new prompts, no schema changes, no new prod deps.**
+
+### Tests
+
+547 unit tests pass (was 522 in v2.11.0, +25 new):
+- **Pure metrics (+11):** ndcgAtK / recallAtK / reciprocalRank — empty relevant set, no overlap, perfect ranking, partial overlap, K-cutoff truncation, first-relevant-only MRR semantics.
+- **readQueriesJsonl (+5):** valid input, blank lines + comments tolerated, malformed JSON throws with line number, missing required fields throws with field name, type-incorrect `relevant` rejected.
+- **runEval end-to-end (+3):** single-query scoring against real FtsIndex, multi-query aggregation, per-query failure isolation.
+- **format helpers (+6):** non-empty output, per-query mode includes table, matrix highlights best NDCG, empty matrix handles gracefully.
+
+### Migration
+
+**No-op for default users.** Eval is opt-in via the new subcommand. Existing `serve` / `serve-http` / `setup` / `doctor` behavior is unchanged.
+
+### Strategic position
+
+v2.12.0 is the **measurement** sprint that pairs with v2.11.0's onboarding sprint. Together they form a "tune-while-you-build" feedback loop: `setup` indexes your vault, `eval` scores your retrieval, you adjust flags + re-eval until NDCG plateaus. Karpathy-style LLM Wiki users get systematic quality tuning for free. The retrieval-quality moat (hybrid RRF, graph-boost, PDF blending, cross-encoder reranking, OCR) gets a quantitative ruler bundled in the box.
+
+### Bonus (PR #31)
+
+Patched 3 fresh `hono` advisories that landed in the GHSA database overnight (CSS injection in JSX SSR, JWT NumericDate validation, Cache Middleware Vary handling). Transitive via `@modelcontextprotocol/sdk → @hono/node-server → hono`. Lockfile-only diff via `npm audit fix`.
+
+## [2.11.0] — 2026-05-08
+
+**Sprint 11 — zero-touch onboarding (`doctor` + `setup`).** Closes the biggest UX gap in the project: setup friction. Before this, getting full hybrid retrieval required 3 separate commands (`install-model` → `build-embeddings` → `serve --persistent-index`), and there was no quick way to see "is everything ready?" without triggering each codepath.
+
+### Added — `enquire-mcp doctor --vault <path>`
+
+Read-only health check. Verifies every prerequisite for full hybrid retrieval:
+- Vault path exists + is readable, with note/PDF/canvas counts (privacy filter applied)
+- All 5 optional deps load cleanly: `better-sqlite3` (FTS5 + embed-db), `@huggingface/transformers` (ML embeddings + reranker), `pdfjs-dist` (PDF read + indexing), `tesseract.js` + `@napi-rs/canvas` (OCR for scanned PDFs)
+- Embedding model cache — probes 5+ candidate paths (transformers.js v3 default `node_modules/@huggingface/transformers/.cache/Xenova/`, HF_HOME, TRANSFORMERS_CACHE env vars, `~/.cache/huggingface/`, macOS XDG `~/Library/Caches/huggingface/`)
+- FTS5 BM25 index existence + per-vault file/chunk counts
+- Embed-db existence + size
+
+Color-coded ✓ / ⚠ / ✗ output (auto-detects TTY so piped output stays clean). Returns 0 if everything is ready, 1 if any critical piece is missing. `--json` flag for machine-readable output (useful for CI / scripted setup checks).
+
+### Added — `enquire-mcp setup --vault <path>`
+
+Zero-touch onboarding. Runs the install + build sequence in one command:
+
+1. **Step 1/3:** Cold-build FTS5 BM25 index (`syncFtsIndex` + optional `syncPdfFtsIndex` if `--include-pdfs`)
+2. **Step 2/3:** Install embedding model (downloads ~120 MB for `multilingual` default, cached for reuse)
+3. **Step 3/3:** Build embedding index (`syncEmbedDb` + optional `syncPdfEmbedDb`)
+
+Idempotent — re-running on a fully set-up vault is a fast no-op pass that just reports the existing state. `--skip-embeddings` for users who only want BM25. `--include-pdfs` for vaults with PDFs.
+
+After successful setup, prints the exact `serve` command to run.
+
+### Surface delta vs v2.10.0
+
+- **+2 CLI subcommands** (`doctor`, `setup`)
+- **+1 source module** (`src/doctor.ts`, ~310 lines)
+- **No new tools, no new prompts, no schema changes, no new deps.**
+
+### Tests
+
+522 unit tests pass (was 509 in v2.10.0, +13 new):
+- **runDoctor (+8):** result shape contract, vault check ok-vs-error, optional-dep checks (5 deps), model-cache check missing-vs-ok with synthetic Xenova dir, FTS5 + embed-db checks not-built status, ready boolean correctness against summary tally.
+- **formatCheck + formatDoctorResult (+5):** non-empty output for each status, detail + hint inclusion, hint omission for ok status, banner shape, NOT-READY verdict on failures.
+
+### Migration
+
+**No-op for default users.** Both new subcommands are opt-in. Existing `serve` / `serve-http` / `index` / `build-embeddings` behavior unchanged.
+
+### Strategic position
+
+v2.11.0 is a UX-focused sprint, not a capability sprint. The retrieval moats (hybrid RRF, graph-boost, PDF + OCR, cross-encoder reranking) all stayed put. What changed: the **time-to-first-useful-result** drops from ~5 minutes (figure out 3 commands, paste them, wait) to ~30 seconds (`enquire-mcp setup --vault <path>` and you're done).
+
+Demo flow:
+
+```bash
+$ enquire-mcp doctor --vault ~/Obsidian
+NOT READY — 1 missing/error, 0 warnings, 7 ok
+   ✗ Embedding model cache → enquire-mcp install-model multilingual
+
+$ enquire-mcp setup --vault ~/Obsidian
+>> Step 1/3: Cold-build FTS5 index ...
+>> Step 2/3: Install embedding model ...
+>> Step 3/3: Build embedding index ...
+✓ Setup complete. Now run:
+   enquire-mcp serve --vault ~/Obsidian --persistent-index
+
+$ enquire-mcp doctor --vault ~/Obsidian
+READY — all critical checks pass (8 ok, 0 warnings)
+```
+
 ## [2.10.0] — 2026-05-08
 
 **Sprint 10 — OCR for image-only / scanned PDFs.** Closes the v2.7-v2.8-v2.9 PDF retrieval story. v2.7.0 added text-extraction tools; v2.8.0 blended PDF chunks into hybrid search; v2.9.0 added cross-encoder reranking. v2.10.0 makes the **scanned / camera-captured** PDFs in your vault searchable too — Tesseract.js OCR over each page bitmap.

package/README.md

@@ -42,14 +42,19 @@ That's it. Your AI now has structured access to wikilinks, backlinks, frontmatte
 }
 ```
 
-**Want hybrid retrieval at full power?** One-time setup, ~10 min for a 100-note vault:
+**Want hybrid retrieval at full power?** One command (v2.11.0):
 
 ```bash
-enquire-mcp install-model multilingual          # ~120MB, 50+ languages
-enquire-mcp build-embeddings --vault <path>     # ~30ms/chunk on M1
+enquire-mcp setup --vault <path>      # downloads model, builds FTS5 + embed indexes
 # then: serve --persistent-index for BM25 + --enable-reranker for cross-encoder
 ```
 
+Already set up? Check status anytime:
+
+```bash
+enquire-mcp doctor --vault <path>     # color-coded ✓/⚠/✗ health check
+```
+
 ---
 
 ## 🎯 The only Obsidian-MCP with…
@@ -58,6 +63,7 @@ enquire-mcp build-embeddings --vault <path>     # ~30ms/chunk on M1
 - ✅ **Cross-encoder reranking** on top of RRF (+5-10 NDCG@10) — `v2.9.0`
 - ✅ **PDFs blended into hybrid search** with `[page: N]` citation markers — `v2.8.0`
 - ✅ **OCR for scanned / image-only PDFs** (Tesseract.js, multilingual) — `v2.10.0`
+- ✅ **Built-in retrieval-quality eval** (`enquire-mcp eval` — NDCG@K, Recall@K, MRR, A/B matrix) — `v2.12.0`
 - ✅ **Wikilink graph-boost** as a retrieval signal (1-step personalised PageRank seeded by RRF top-K)
 - ✅ **Remote MCP** over HTTP with bearer auth + rate-limit + CORS — `v2.6.0`
 - ✅ **Multilingual** semantic search (50+ languages, runs on CPU, free)
@@ -113,13 +119,14 @@ graph LR
 | **PDFs blended into hybrid search** | ❌ | ❌ | ✅ **only here** |
 | **OCR for scanned / image-only PDFs** | ❌ | ❌ | ✅ **only here** |
 | **Cross-encoder reranking** | ❌ | ❌ | ✅ **only here** |
+| **Built-in retrieval-quality eval** (NDCG@K + matrix) | ❌ | ❌ | ✅ **only here** |
 | **Remote MCP (HTTP + bearer auth)** | ❌ | ❌ | ✅ **only here** |
 | Per-signal observability per hit | ❌ | ❌ | ✅ |
 | Privacy filter (exclude/allow globs) | ❌ | n/a | ✅ verified at search + write paths |
 | Standalone (no Obsidian plugin) | varies | ❌ requires Obsidian | ✅ direct vault read |
 | MCP-native (any agent) | varies | ❌ Obsidian-only | ✅ stdio + HTTP |
 | SLSA-3 release provenance | ❌ | n/a | ✅ |
-| Test suite | rare | n/a | ✅ 507 unit tests |
+| Test suite | rare | n/a | ✅ 547 unit tests |
 
 > **Strategic claim:** enquire is the open-source backend for [Karpathy-style LLM Wikis](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) on top of your existing Obsidian vault. The `vault_synth` / `vault_wiki_compile` / `vault_lint_extended` prompts implement the ingest → query → lint → compile workflow natively over `.md` + `[[wikilinks]]`. Knowledge that compounds, traceable to sources.
 
@@ -172,7 +179,7 @@ The flags you'll actually use:
 | `--watch` | off | Live invalidation on `.md` add/change/unlink |
 | `--persistent-cache` | off | Survive cold starts |
 
-Subcommands: `serve` · `serve-http` · `gen-token` · `clear-cache` · `clear-index` · `clear-embeddings` · `index` · `install-model` · `build-embeddings`.
+Subcommands: `serve` · `serve-http` · `gen-token` · `doctor` (v2.11) · `setup` (v2.11) · `eval` (v2.12) · `clear-cache` · `clear-index` · `clear-embeddings` · `index` · `install-model` · `build-embeddings`.
 
 **Remote MCP** for Claude.ai web / ChatGPT / Cursor HTTP / mobile:
 
@@ -200,7 +207,7 @@ enquire-mcp serve-http \
 
 | Surface | Posture |
 |---|---|
-| Tests | 507 unit tests across 25 files, 8 required CI gates per PR |
+| Tests | 547 unit tests across 27 files, 8 required CI gates per PR |
 | Coverage | Lines ≥86%, statements ≥82%, functions ≥75%, branches ≥73% (gated) |
 | Audit | `npm audit --audit-level=moderate` for prod; high for dev |
 | CI | Ubuntu × {Node 20, 22, 24} required + macOS advisory job |

package/dist/doctor.d.ts

@@ -0,0 +1,54 @@
+import type { EmbeddingModel } from "./embeddings.js";
+/** Severity buckets surfaced in the diagnostic UI. */
+export type CheckStatus = "ok" | "warn" | "missing" | "error";
+export interface DoctorCheck {
+    /** Stable id for programmatic consumers (e.g. JSON output). */
+    id: string;
+    /** Human-readable label (rendered next to the status icon). */
+    label: string;
+    status: CheckStatus;
+    /** Optional detail line printed below the label. */
+    detail?: string;
+    /** Optional hint — usually the command that fixes it. */
+    hint?: string;
+}
+export interface DoctorResult {
+    vault: string;
+    /** True iff every `missing`/`error` check is absent (`warn` is OK). */
+    ready: boolean;
+    checks: DoctorCheck[];
+    /** Tally for quick consumer reporting. */
+    summary: {
+        ok: number;
+        warn: number;
+        missing: number;
+        error: number;
+    };
+}
+/** Render one DoctorCheck to a multi-line string. */
+export declare function formatCheck(check: DoctorCheck): string;
+/** Render a full DoctorResult to a banner string. */
+export declare function formatDoctorResult(result: DoctorResult): string;
+export interface RunDoctorOptions {
+    vault: string;
+    /** Override default cache root (mostly for tests). */
+    modelCacheRoot?: string;
+    /** Override default embed-db location. */
+    embedFile?: string;
+    /** Override default FTS5 index location. */
+    indexFile?: string;
+    /** Default model alias to check for (matches DEFAULT_MODEL_ALIAS). */
+    modelAlias?: string;
+    /**
+     * Embedding-model catalog entry — passed in to avoid pulling
+     * `@huggingface/transformers` into this module. Caller resolves it via
+     * `resolveModel(alias)` from src/embeddings.ts.
+     */
+    modelEntry?: EmbeddingModel;
+}
+/**
+ * Run all the diagnostic checks. Pure data — caller decides how to
+ * render (CLI banner, JSON, MCP tool response).
+ */
+export declare function runDoctor(opts: RunDoctorOptions): Promise<DoctorResult>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,0CAA0C;IAC1C,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE;AAYD,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAatD;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAY/D;AA4DD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAwO7E"}

package/dist/doctor.js

@@ -0,0 +1,369 @@
+// Diagnostic + auto-setup for enquire-mcp.
+//
+// v2.11.0 — closes the biggest UX gap in the project: setup friction.
+// Before this, getting full hybrid retrieval required 3 separate commands
+// (`install-model` → `build-embeddings` → `serve --persistent-index`),
+// and there was no quick way to see "is everything ready?" without
+// triggering each codepath.
+//
+// Two new subcommands:
+//
+//   enquire-mcp doctor --vault <path>
+//      Read-only health check. Lists every prerequisite for full hybrid
+//      retrieval (vault path, optional deps, embedding model cache, FTS5
+//      index, embed.db). Color-coded ✓ / ⚠ / ✗. Returns 0 if everything
+//      is ready, 1 if any critical piece is missing.
+//
+//   enquire-mcp setup --vault <path>
+//      Runs the install + build sequence in order, with progress messages
+//      at each stage. Calls install-model + cold-build FTS5 + build-
+//      embeddings under the hood. Idempotent — re-running on a fully
+//      set-up vault is a no-op pass.
+//
+// Both are pure orchestration over existing CLI/library code — no new
+// runtime deps, no schema changes. Same privacy filter applies (the
+// doctor walks the vault via Vault.listMarkdown so excluded paths are
+// hidden from its counts).
+import { existsSync, promises as fs, statSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { defaultIndexFile, FtsIndex } from "./fts5.js";
+import { Vault } from "./vault.js";
+/** Simple ANSI color helpers — autodetect TTY so piped output stays clean. */
+const isTty = process.stdout.isTTY === true;
+const c = {
+    green: (s) => (isTty ? `\x1b[32m${s}\x1b[0m` : s),
+    yellow: (s) => (isTty ? `\x1b[33m${s}\x1b[0m` : s),
+    red: (s) => (isTty ? `\x1b[31m${s}\x1b[0m` : s),
+    dim: (s) => (isTty ? `\x1b[2m${s}\x1b[0m` : s),
+    bold: (s) => (isTty ? `\x1b[1m${s}\x1b[0m` : s)
+};
+/** Render one DoctorCheck to a multi-line string. */
+export function formatCheck(check) {
+    const icon = check.status === "ok"
+        ? c.green("✓")
+        : check.status === "warn"
+            ? c.yellow("⚠")
+            : check.status === "missing"
+                ? c.red("✗")
+                : c.red("✗");
+    const lines = [`${icon}  ${check.label}`];
+    if (check.detail)
+        lines.push(c.dim(`   ${check.detail}`));
+    if (check.hint && check.status !== "ok")
+        lines.push(c.dim(`   → ${check.hint}`));
+    return lines.join("\n");
+}
+/** Render a full DoctorResult to a banner string. */
+export function formatDoctorResult(result) {
+    const lines = [];
+    lines.push(c.bold(`enquire-mcp doctor — ${result.vault}`));
+    lines.push("");
+    for (const check of result.checks)
+        lines.push(formatCheck(check));
+    lines.push("");
+    const { ok, warn, missing, error } = result.summary;
+    const verdict = result.ready
+        ? c.green(`READY — all critical checks pass (${ok} ok, ${warn} warnings)`)
+        : c.red(`NOT READY — ${missing + error} missing/error, ${warn} warnings, ${ok} ok`);
+    lines.push(verdict);
+    return lines.join("\n");
+}
+/**
+ * Candidate locations where transformers.js may have cached embedding model
+ * weights. We probe all of them and report `ok` if any contains data.
+ *
+ * Why multiple paths:
+ *   - transformers.js v3+ default: `<package>/.cache/Xenova/...` (lives
+ *     inside `node_modules/@huggingface/transformers/.cache`, the
+ *     library's own cache dir relative to its install location).
+ *   - Older HuggingFace Hub convention: `~/.cache/huggingface/...`.
+ *   - macOS XDG override: `~/Library/Caches/huggingface/...`.
+ *   - Custom env var: HF_HOME or TRANSFORMERS_CACHE if the user set them.
+ *
+ * We don't try to load transformers.js to read `env.cacheDir` — that
+ * would defeat the doctor's "fast read-only health check" promise on
+ * users who haven't installed the optional dep at all.
+ */
+function candidateModelCacheRoots() {
+    const candidates = [];
+    // 1. transformers.js v3+ default (lives inside the package itself).
+    // Find the @huggingface/transformers install directory.
+    // require.resolve doesn't exist in ESM; we walk node_modules ourselves
+    // from cwd. If transformers.js isn't installed, this candidate just
+    // won't exist on disk and gets filtered out.
+    candidates.push(path.join(process.cwd(), "node_modules", "@huggingface", "transformers", ".cache"));
+    // 2. HuggingFace Hub conventions.
+    if (process.env.HF_HOME)
+        candidates.push(path.join(process.env.HF_HOME, "hub"));
+    if (process.env.TRANSFORMERS_CACHE)
+        candidates.push(process.env.TRANSFORMERS_CACHE);
+    candidates.push(path.join(os.homedir(), ".cache", "huggingface", "transformers.js"));
+    candidates.push(path.join(os.homedir(), ".cache", "huggingface"));
+    // 3. macOS XDG-ish convention.
+    if (process.platform === "darwin") {
+        candidates.push(path.join(os.homedir(), "Library", "Caches", "huggingface"));
+    }
+    return candidates;
+}
+/**
+ * Default `.embed.db` location for a given vault root — same convention as
+ * the rest of the codebase. Mirrors `embedDbPath` in src/index.ts.
+ */
+function defaultEmbedDbFile(vaultRoot) {
+    return defaultIndexFile(vaultRoot).replace(/\.fts5\.db$/, ".embed.db");
+}
+/**
+ * Probe whether an optional dep is loadable in this process. Uses a
+ * dynamic import inside a try/catch so we never crash the diagnostic
+ * on a missing or broken native binding.
+ */
+async function probeOptionalDep(spec) {
+    try {
+        await import(spec);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run all the diagnostic checks. Pure data — caller decides how to
+ * render (CLI banner, JSON, MCP tool response).
+ */
+export async function runDoctor(opts) {
+    const checks = [];
+    const vault = new Vault(opts.vault);
+    // 1. Vault path exists + is readable.
+    let vaultExists = false;
+    try {
+        await vault.ensureExists();
+        vaultExists = true;
+        const noteCount = (await vault.listMarkdown()).length;
+        const pdfCount = (await vault.listFilesByExtension(".pdf")).length;
+        const canvasCount = (await vault.listFilesByExtension(".canvas")).length;
+        checks.push({
+            id: "vault",
+            label: `Vault accessible at ${opts.vault}`,
+            status: "ok",
+            detail: `${noteCount} markdown · ${pdfCount} pdf · ${canvasCount} canvas (privacy filter applied)`
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        checks.push({
+            id: "vault",
+            label: `Vault path ${opts.vault}`,
+            status: "error",
+            detail: msg,
+            hint: "Check the path exists and is a directory"
+        });
+    }
+    // 2. better-sqlite3 — gates --persistent-index + ML embed-db.
+    const hasSqlite = await probeOptionalDep("better-sqlite3");
+    checks.push({
+        id: "dep:better-sqlite3",
+        label: "better-sqlite3 (FTS5 BM25 + embedding store)",
+        status: hasSqlite ? "ok" : "missing",
+        detail: hasSqlite ? "loaded; native binding works" : undefined,
+        hint: hasSqlite ? undefined : "npm install better-sqlite3 (or remove --omit=optional from your install)"
+    });
+    // 3. @huggingface/transformers — gates ML embeddings + reranker.
+    const hasTransformers = await probeOptionalDep("@huggingface/transformers");
+    checks.push({
+        id: "dep:transformers",
+        label: "@huggingface/transformers (ML embeddings + cross-encoder reranker)",
+        status: hasTransformers ? "ok" : "missing",
+        detail: hasTransformers ? "loaded; ONNX runtime available" : undefined,
+        hint: hasTransformers ? undefined : "npm install @huggingface/transformers"
+    });
+    // 4. pdfjs-dist — gates obsidian_read_pdf + PDF retrieval.
+    const hasPdfjs = await probeOptionalDep("pdfjs-dist/legacy/build/pdf.mjs");
+    checks.push({
+        id: "dep:pdfjs",
+        label: "pdfjs-dist (PDF read + indexing)",
+        status: hasPdfjs ? "ok" : "warn",
+        detail: hasPdfjs ? "loaded" : "PDFs in vault won't be indexable",
+        hint: hasPdfjs ? undefined : "npm install pdfjs-dist@^4.10.38 (skip if you have no PDFs)"
+    });
+    // 5. tesseract.js + @napi-rs/canvas — gates obsidian_ocr_pdf.
+    const [hasTesseract, hasCanvas] = await Promise.all([
+        probeOptionalDep("tesseract.js"),
+        probeOptionalDep("@napi-rs/canvas")
+    ]);
+    if (hasTesseract && hasCanvas) {
+        checks.push({
+            id: "dep:ocr",
+            label: "tesseract.js + @napi-rs/canvas (OCR for scanned PDFs)",
+            status: "ok",
+            detail: "both loaded; PDF OCR ready"
+        });
+    }
+    else {
+        checks.push({
+            id: "dep:ocr",
+            label: "tesseract.js + @napi-rs/canvas (OCR for scanned PDFs)",
+            status: "warn",
+            detail: `tesseract.js=${hasTesseract ? "ok" : "missing"} · canvas=${hasCanvas ? "ok" : "missing"}`,
+            hint: "npm install tesseract.js @napi-rs/canvas (skip if you have no scanned PDFs)"
+        });
+    }
+    // 6. Embedding model cache — does the user have weights downloaded?
+    // Probe every candidate path; whichever has Xenova-style model dirs
+    // wins. Fall back to "missing" only if every candidate is empty/absent.
+    const cacheRoots = opts.modelCacheRoot ? [opts.modelCacheRoot] : candidateModelCacheRoots();
+    let foundCacheRoot = null;
+    let cachedCount = 0;
+    let cacheBytes = 0;
+    for (const cacheRoot of cacheRoots) {
+        if (!existsSync(cacheRoot))
+            continue;
+        try {
+            // Look for at least one Xenova/* directory or any direct model dir
+            // (transformers.js stores models as `Xenova/<model-id>`).
+            const xenovaPath = path.join(cacheRoot, "Xenova");
+            if (existsSync(xenovaPath)) {
+                const sub = await fs.readdir(xenovaPath, { withFileTypes: true });
+                const models = sub.filter((e) => e.isDirectory());
+                if (models.length > 0) {
+                    foundCacheRoot = cacheRoot;
+                    cachedCount = models.length;
+                    // Best-effort size sum — bounded per model dir.
+                    for (const m of models) {
+                        try {
+                            const files = await fs.readdir(path.join(xenovaPath, m.name));
+                            for (const f of files) {
+                                try {
+                                    cacheBytes += statSync(path.join(xenovaPath, m.name, f)).size;
+                                }
+                                catch {
+                                    /* skip */
+                                }
+                            }
+                        }
+                        catch {
+                            /* skip */
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    if (foundCacheRoot && cachedCount > 0) {
+        checks.push({
+            id: "model:cache",
+            label: "Embedding model cache",
+            status: "ok",
+            detail: `${cachedCount} model(s) cached under ${foundCacheRoot}/Xenova/ (~${Math.round(cacheBytes / 1024 / 1024)} MB)`
+        });
+    }
+    else {
+        checks.push({
+            id: "model:cache",
+            label: "Embedding model cache",
+            status: "missing",
+            detail: "no Xenova model weights found in any standard cache location",
+            hint: opts.modelEntry
+                ? `enquire-mcp install-model ${opts.modelEntry.alias}  (~${opts.modelEntry.approxSizeMB} MB)`
+                : "enquire-mcp install-model multilingual"
+        });
+    }
+    // 7. FTS5 index — does the persistent index exist for this vault?
+    if (vaultExists) {
+        const indexFile = opts.indexFile ?? defaultIndexFile(vault.root);
+        if (existsSync(indexFile) && hasSqlite) {
+            // Open + close to count files/chunks. If something's off, surface it
+            // as a warn (not missing — caller can still serve without the index).
+            try {
+                const idx = new FtsIndex({ file: indexFile, vaultRoot: vault.root });
+                await idx.open();
+                const totalFiles = idx.totalFiles();
+                const totalChunks = idx.totalChunks();
+                idx.close();
+                checks.push({
+                    id: "index:fts5",
+                    label: "FTS5 BM25 index",
+                    status: "ok",
+                    detail: `${indexFile} — ${totalFiles} files / ${totalChunks} chunks`
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                checks.push({
+                    id: "index:fts5",
+                    label: "FTS5 BM25 index",
+                    status: "warn",
+                    detail: `${indexFile} present but failed to open: ${msg}`,
+                    hint: `enquire-mcp clear-index --vault ${opts.vault} && enquire-mcp index --vault ${opts.vault}`
+                });
+            }
+        }
+        else {
+            checks.push({
+                id: "index:fts5",
+                label: "FTS5 BM25 index",
+                status: "warn",
+                detail: hasSqlite ? `${indexFile} not built` : "needs better-sqlite3 first",
+                hint: hasSqlite ? `enquire-mcp index --vault ${opts.vault}` : "install better-sqlite3 first"
+            });
+        }
+    }
+    // 8. Embedding index — does the .embed.db exist for this vault?
+    if (vaultExists) {
+        const embedFile = opts.embedFile ?? defaultEmbedDbFile(vault.root);
+        if (existsSync(embedFile) && hasSqlite && hasTransformers) {
+            // Don't open the file (loading the model is expensive); just stat it
+            // and rely on the existence + size check.
+            try {
+                const sz = statSync(embedFile).size;
+                checks.push({
+                    id: "index:embed",
+                    label: "Embedding index (.embed.db)",
+                    status: "ok",
+                    detail: `${embedFile} — ${(sz / 1024 / 1024).toFixed(1)} MB`
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                checks.push({
+                    id: "index:embed",
+                    label: "Embedding index (.embed.db)",
+                    status: "warn",
+                    detail: msg,
+                    hint: `enquire-mcp clear-embeddings --vault ${opts.vault} && enquire-mcp build-embeddings --vault ${opts.vault}`
+                });
+            }
+        }
+        else {
+            const blockers = [];
+            if (!hasSqlite)
+                blockers.push("better-sqlite3");
+            if (!hasTransformers)
+                blockers.push("@huggingface/transformers");
+            checks.push({
+                id: "index:embed",
+                label: "Embedding index (.embed.db)",
+                status: "warn",
+                detail: blockers.length > 0
+                    ? `blocked on: ${blockers.join(", ")}`
+                    : `${embedFile} not built — semantic-search-only path will use TF-IDF cosine`,
+                hint: blockers.length > 0
+                    ? `npm install ${blockers.join(" ")}`
+                    : `enquire-mcp build-embeddings --vault ${opts.vault}`
+            });
+        }
+    }
+    // Tally the summary.
+    const summary = { ok: 0, warn: 0, missing: 0, error: 0 };
+    for (const ch of checks)
+        summary[ch.status] += 1;
+    // "ready" means: no missing or error. Warnings are advisory — you can
+    // still serve a useful subset of the surface (e.g. without ML embeddings).
+    const ready = summary.missing === 0 && summary.error === 0;
+    return { vault: opts.vault, ready, checks, summary };
+}
+//# sourceMappingURL=doctor.js.map