clawvault 3.2.0 → 3.3.0

package/dist/chunk-PTWPPVC7.js

@@ -0,0 +1,972 @@
+import {
+  EmbeddingStore,
+  cosineSimilarity,
+  embedText,
+  resolveEmbeddingConfig
+} from "./chunk-H3JZIB5O.js";
+
+// src/lib/search.ts
+import { execFileSync, spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+// src/lib/hosted-rerank.ts
+var DEFAULT_ENDPOINTS = {
+  jina: "https://api.jina.ai/v1/rerank",
+  voyage: "https://api.voyageai.com/v1/rerank",
+  siliconflow: "https://api.siliconflow.cn/v1/rerank",
+  pinecone: "https://api.pinecone.io/rerank"
+};
+var DEFAULT_MODELS = {
+  jina: "jina-reranker-v2-base-multilingual",
+  voyage: "rerank-2",
+  siliconflow: "BAAI/bge-reranker-v2-m3",
+  pinecone: "bge-reranker-v2-m3"
+};
+function clampWeight(value) {
+  if (!Number.isFinite(value)) return 0.6;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function resolveApiKey(provider, configured) {
+  if (configured?.trim()) return configured.trim();
+  const envKeyByProvider = {
+    jina: ["JINA_API_KEY"],
+    voyage: ["VOYAGE_API_KEY"],
+    siliconflow: ["SILICONFLOW_API_KEY"],
+    pinecone: ["PINECONE_API_KEY"]
+  };
+  for (const key of envKeyByProvider[provider]) {
+    const value = process.env[key]?.trim();
+    if (value) return value;
+  }
+  return process.env.RERANK_API_KEY?.trim();
+}
+function resolveRerankConfig(searchConfig) {
+  const provider = searchConfig?.rerank?.provider ?? "none";
+  if (provider === "none") {
+    return null;
+  }
+  const apiKey = resolveApiKey(provider, searchConfig?.rerank?.apiKey);
+  if (!apiKey) {
+    return null;
+  }
+  const endpoint = (searchConfig?.rerank?.endpoint?.trim() || DEFAULT_ENDPOINTS[provider]).replace(/\/+$/, "");
+  const model = searchConfig?.rerank?.model?.trim() || DEFAULT_MODELS[provider];
+  const weight = clampWeight(searchConfig?.rerank?.weight ?? 0.6);
+  return {
+    provider,
+    endpoint,
+    model,
+    apiKey,
+    weight
+  };
+}
+async function crossEncoderRerank(query, documents, config) {
+  if (!documents.length) return null;
+  try {
+    const response = await fetch(config.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify({
+        model: config.model,
+        query,
+        documents,
+        top_n: documents.length
+      }),
+      signal: AbortSignal.timeout(15e3)
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json();
+    const items = payload.results ?? payload.data;
+    if (!Array.isArray(items)) {
+      return null;
+    }
+    const scores = new Array(documents.length).fill(0);
+    for (const item of items) {
+      const score = Number(item.relevance_score ?? item.score ?? 0);
+      if (Number.isFinite(item.index) && item.index >= 0 && item.index < documents.length) {
+        scores[item.index] = score;
+      }
+    }
+    return scores;
+  } catch {
+    return null;
+  }
+}
+
+// src/lib/in-process-search.ts
+var BM25_K1 = 1.2;
+var BM25_B = 0.75;
+var RRF_K = 60;
+var DEFAULT_CHUNK_SIZE = 700;
+var DEFAULT_CHUNK_OVERLAP = 100;
+function tokenize(text) {
+  return text.toLowerCase().split(/[^\p{L}\p{N}_-]+/u).map((token) => token.trim()).filter((token) => token.length > 1);
+}
+function normalizeScore(value, min, max) {
+  if (!Number.isFinite(value)) return 0;
+  if (max <= min) return value > 0 ? 1 : 0;
+  return (value - min) / (max - min);
+}
+function normalizeCandidateScores(candidates) {
+  if (!candidates.length) return candidates;
+  const values = candidates.map((item) => item.score).filter((value) => Number.isFinite(value));
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  return candidates.map((candidate) => ({
+    ...candidate,
+    score: normalizeScore(candidate.score, min, max)
+  }));
+}
+var InProcessSearchEngine = class {
+  vaultPath = "";
+  config = {};
+  documents = /* @__PURE__ */ new Map();
+  chunks = /* @__PURE__ */ new Map();
+  chunkIdsByDoc = /* @__PURE__ */ new Map();
+  documentFrequency = /* @__PURE__ */ new Map();
+  totalChunkLength = 0;
+  embeddingStore = new EmbeddingStore(process.cwd());
+  embeddingStoreLoaded = false;
+  setVaultPath(vaultPath) {
+    this.vaultPath = vaultPath;
+    this.embeddingStore.setVaultPath(vaultPath);
+    this.embeddingStoreLoaded = false;
+  }
+  setConfig(config) {
+    this.config = config ?? {};
+  }
+  addDocument(doc) {
+    const existing = this.documents.get(doc.id);
+    if (existing) {
+      this.removeDocument(existing.id);
+    }
+    this.documents.set(doc.id, doc);
+    const chunkIds = [];
+    const chunkTexts = this.splitIntoChunks(`${doc.title}
+${doc.content}`);
+    for (let index = 0; index < chunkTexts.length; index += 1) {
+      const text = chunkTexts[index];
+      const terms = tokenize(text);
+      if (!terms.length) continue;
+      const termFreq = /* @__PURE__ */ new Map();
+      for (const term of terms) {
+        termFreq.set(term, (termFreq.get(term) ?? 0) + 1);
+      }
+      const chunkId = `${doc.id}#${index + 1}`;
+      chunkIds.push(chunkId);
+      this.totalChunkLength += terms.length;
+      this.chunks.set(chunkId, {
+        id: chunkId,
+        docId: doc.id,
+        text,
+        termFreq,
+        length: terms.length
+      });
+      for (const term of termFreq.keys()) {
+        this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+      }
+    }
+    this.chunkIdsByDoc.set(doc.id, chunkIds);
+  }
+  removeDocument(docId) {
+    const existingChunkIds = this.chunkIdsByDoc.get(docId) ?? [];
+    for (const chunkId of existingChunkIds) {
+      const chunk = this.chunks.get(chunkId);
+      if (!chunk) continue;
+      this.totalChunkLength = Math.max(0, this.totalChunkLength - chunk.length);
+      for (const term of chunk.termFreq.keys()) {
+        const next = (this.documentFrequency.get(term) ?? 0) - 1;
+        if (next <= 0) {
+          this.documentFrequency.delete(term);
+        } else {
+          this.documentFrequency.set(term, next);
+        }
+      }
+      this.chunks.delete(chunkId);
+    }
+    this.chunkIdsByDoc.delete(docId);
+    this.documents.delete(docId);
+  }
+  clear() {
+    this.documents.clear();
+    this.chunks.clear();
+    this.chunkIdsByDoc.clear();
+    this.documentFrequency.clear();
+    this.totalChunkLength = 0;
+  }
+  getAllDocuments() {
+    return [...this.documents.values()];
+  }
+  get size() {
+    return this.documents.size;
+  }
+  export() {
+    return { documents: this.getAllDocuments() };
+  }
+  import(data) {
+    this.clear();
+    for (const doc of data.documents) {
+      this.addDocument(doc);
+    }
+  }
+  async search(query, options = {}) {
+    if (!query.trim()) return [];
+    const limit = Math.max(1, options.limit ?? 10);
+    const bm25Candidates = this.runBm25(query, options, limit * 5);
+    const semanticRanks = await this.getSemanticRanks(query, options);
+    let fused = this.fuseHybrid(bm25Candidates, semanticRanks, limit * 5);
+    fused = await this.applyCrossEncoderRerank(query, fused);
+    return this.toSearchResults(fused, options, limit);
+  }
+  async vsearch(query, options = {}) {
+    if (!query.trim()) return [];
+    const limit = Math.max(1, options.limit ?? 10);
+    const semanticRanks = await this.getSemanticRanks(query, options);
+    if (semanticRanks.length === 0) {
+      return [];
+    }
+    const candidates = [];
+    for (const { docId, score } of semanticRanks) {
+      const doc = this.documents.get(docId);
+      if (!doc || !this.matchesFilters(doc, options)) continue;
+      candidates.push({
+        id: `${docId}#semantic`,
+        docId,
+        snippet: this.buildSnippet(doc.content, []),
+        score,
+        matchedTerms: []
+      });
+    }
+    const reranked = await this.applyCrossEncoderRerank(query, candidates);
+    return this.toSearchResults(reranked, options, limit);
+  }
+  async query(queryText, options = {}) {
+    return this.search(queryText, options);
+  }
+  splitIntoChunks(content) {
+    const normalized = content.replace(/\r\n/g, "\n").trim();
+    if (!normalized) return [];
+    const chunkSize = Math.max(200, this.config.chunkSize ?? DEFAULT_CHUNK_SIZE);
+    const overlap = Math.max(0, Math.min(chunkSize - 1, this.config.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP));
+    const chunks = [];
+    let start = 0;
+    while (start < normalized.length) {
+      let end = Math.min(normalized.length, start + chunkSize);
+      if (end < normalized.length) {
+        const boundary = normalized.slice(end, Math.min(normalized.length, end + 100)).search(/\s/);
+        if (boundary >= 0) {
+          end += boundary;
+        }
+      }
+      const piece = normalized.slice(start, end).trim();
+      if (piece) {
+        chunks.push(piece);
+      }
+      if (end >= normalized.length) break;
+      start = Math.max(0, end - overlap);
+    }
+    return chunks;
+  }
+  runBm25(query, options, topK) {
+    const queryTerms = tokenize(query);
+    if (!queryTerms.length || this.chunks.size === 0) {
+      return [];
+    }
+    const uniqueTerms = [...new Set(queryTerms)];
+    const chunkCount = this.chunks.size;
+    const avgChunkLength = chunkCount > 0 ? this.totalChunkLength / chunkCount : 1;
+    const candidates = [];
+    for (const chunk of this.chunks.values()) {
+      const doc = this.documents.get(chunk.docId);
+      if (!doc || !this.matchesFilters(doc, options)) continue;
+      let score = 0;
+      const matchedTerms = [];
+      for (const term of uniqueTerms) {
+        const termFreq = chunk.termFreq.get(term) ?? 0;
+        if (termFreq === 0) continue;
+        matchedTerms.push(term);
+        const docFreq = this.documentFrequency.get(term) ?? 0;
+        const idf = Math.log((chunkCount - docFreq + 0.5) / (docFreq + 0.5) + 1);
+        const tfNorm = termFreq * (BM25_K1 + 1) / (termFreq + BM25_K1 * (1 - BM25_B + BM25_B * (chunk.length / Math.max(1, avgChunkLength))));
+        score += idf * tfNorm;
+      }
+      if (score <= 0) continue;
+      candidates.push({
+        id: chunk.id,
+        docId: chunk.docId,
+        snippet: this.buildSnippet(chunk.text, matchedTerms),
+        score,
+        matchedTerms
+      });
+    }
+    return normalizeCandidateScores(
+      candidates.sort((left, right) => right.score - left.score).slice(0, topK)
+    );
+  }
+  async getSemanticRanks(query, options) {
+    const embeddingConfig = resolveEmbeddingConfig(this.config);
+    if (!embeddingConfig) {
+      return [];
+    }
+    if (!this.loadEmbeddingStoreIfNeeded(embeddingConfig.provider, embeddingConfig.model)) {
+      return [];
+    }
+    let queryEmbedding;
+    try {
+      queryEmbedding = await embedText(query, embeddingConfig, { isQuery: true });
+    } catch {
+      return [];
+    }
+    const ranked = Array.from(this.documents.values()).filter((doc) => this.matchesFilters(doc, options)).map((doc) => {
+      const vector = this.embeddingStore.get(doc.id);
+      if (!vector) {
+        return null;
+      }
+      return {
+        docId: doc.id,
+        score: cosineSimilarity(queryEmbedding, vector)
+      };
+    }).filter((entry) => entry !== null).sort((left, right) => right.score - left.score).slice(0, Math.max(20, (options.limit ?? 10) * 5));
+    if (ranked.length === 0) {
+      return [];
+    }
+    const min = Math.min(...ranked.map((entry) => entry.score));
+    const max = Math.max(...ranked.map((entry) => entry.score));
+    return ranked.map((entry, index) => ({
+      docId: entry.docId,
+      rank: index,
+      score: normalizeScore(entry.score, min, max)
+    }));
+  }
+  fuseHybrid(bm25Candidates, semanticRanks, topK) {
+    if (bm25Candidates.length === 0) {
+      return semanticRanks.map((entry) => {
+        const doc = this.documents.get(entry.docId);
+        return {
+          id: `${entry.docId}#semantic`,
+          docId: entry.docId,
+          snippet: this.buildSnippet(doc.content, []),
+          score: 1 / (RRF_K + entry.rank + 1),
+          matchedTerms: []
+        };
+      }).slice(0, topK);
+    }
+    const semanticRankMap = new Map(
+      semanticRanks.map((entry) => [entry.docId, { rank: entry.rank, score: entry.score }])
+    );
+    const fused = [];
+    for (let index = 0; index < bm25Candidates.length; index += 1) {
+      const candidate = bm25Candidates[index];
+      const bm25Rrf = 0.65 / (RRF_K + index + 1);
+      const semantic = semanticRankMap.get(candidate.docId);
+      const semanticRrf = semantic ? 0.35 / (RRF_K + semantic.rank + 1) : 0;
+      fused.push({
+        ...candidate,
+        score: bm25Rrf + semanticRrf
+      });
+    }
+    const seenDocs = new Set(fused.map((entry) => entry.docId));
+    for (const entry of semanticRanks) {
+      if (seenDocs.has(entry.docId)) continue;
+      const doc = this.documents.get(entry.docId);
+      if (!doc) continue;
+      fused.push({
+        id: `${entry.docId}#semantic`,
+        docId: entry.docId,
+        snippet: this.buildSnippet(doc.content, []),
+        matchedTerms: [],
+        score: 0.35 / (RRF_K + entry.rank + 1)
+      });
+    }
+    return normalizeCandidateScores(
+      fused.sort((left, right) => right.score - left.score).slice(0, topK)
+    );
+  }
+  async applyCrossEncoderRerank(query, candidates) {
+    const rerankConfig = resolveRerankConfig(this.config);
+    if (!rerankConfig || candidates.length === 0) {
+      return candidates;
+    }
+    const texts = candidates.map((candidate) => {
+      const doc = this.documents.get(candidate.docId);
+      const title = doc?.title ?? candidate.docId;
+      return `${title}
+${candidate.snippet}`.trim();
+    });
+    const rerankScores = await crossEncoderRerank(query, texts, rerankConfig);
+    if (!rerankScores) {
+      return candidates;
+    }
+    const normalizedRerank = normalizeCandidateScores(
+      candidates.map((candidate, index) => ({
+        ...candidate,
+        score: rerankScores[index] ?? 0
+      }))
+    );
+    const weighted = candidates.map((candidate, index) => ({
+      ...candidate,
+      score: (1 - rerankConfig.weight) * candidate.score + rerankConfig.weight * normalizedRerank[index].score
+    }));
+    return weighted.sort((left, right) => right.score - left.score);
+  }
+  toSearchResults(candidates, options, limit) {
+    const minScore = options.minScore ?? 0;
+    const boosted = candidates.map((candidate) => {
+      const doc = this.documents.get(candidate.docId);
+      if (!doc) return null;
+      const temporal = options.temporalBoost ? this.getRecencyFactor(doc.modified) : 1;
+      return {
+        candidate,
+        doc,
+        score: candidate.score * temporal
+      };
+    }).filter((entry) => entry !== null).filter((entry) => entry.score >= minScore).sort((left, right) => right.score - left.score).slice(0, limit);
+    return boosted.map((entry) => ({
+      document: options.fullContent ? entry.doc : { ...entry.doc, content: "" },
+      score: entry.score,
+      snippet: entry.candidate.snippet,
+      matchedTerms: entry.candidate.matchedTerms
+    }));
+  }
+  matchesFilters(doc, options) {
+    if (options.category && doc.category !== options.category) {
+      return false;
+    }
+    if (options.tags?.length) {
+      const docTags = new Set(doc.tags.map((tag) => tag.toLowerCase()));
+      const hasTag = options.tags.some((tag) => docTags.has(tag.toLowerCase()));
+      if (!hasTag) return false;
+    }
+    return true;
+  }
+  getRecencyFactor(modifiedAt) {
+    const ageMs = Math.max(0, Date.now() - modifiedAt.getTime());
+    const ageDays = ageMs / (24 * 60 * 60 * 1e3);
+    if (ageDays < 1) return 1;
+    if (ageDays <= 7) return 0.9;
+    return 0.7;
+  }
+  buildSnippet(text, matchedTerms) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (!normalized) return "";
+    if (!matchedTerms.length) {
+      return normalized.slice(0, 260);
+    }
+    const lower = normalized.toLowerCase();
+    const firstTerm = matchedTerms.find((term) => lower.includes(term.toLowerCase()));
+    if (!firstTerm) {
+      return normalized.slice(0, 260);
+    }
+    const start = Math.max(0, lower.indexOf(firstTerm.toLowerCase()) - 80);
+    const end = Math.min(normalized.length, start + 260);
+    return normalized.slice(start, end).trim();
+  }
+  loadEmbeddingStoreIfNeeded(provider, model) {
+    if (!this.embeddingStoreLoaded) {
+      this.embeddingStore.load();
+      this.embeddingStoreLoaded = true;
+    }
+    if (!this.embeddingStore.isCompatible(provider, model)) {
+      return false;
+    }
+    this.embeddingStore.setSignature(provider, model);
+    return true;
+  }
+};
+
+// src/lib/search.ts
+var QMD_INSTALL_URL = "https://github.com/tobi/qmd";
+var QMD_INSTALL_COMMAND = "bun install -g github:tobi/qmd";
+var QMD_INDEX_ENV_VAR = "CLAWVAULT_QMD_INDEX";
+var QMD_ERROR_MESSAGES = {
+  NOT_INSTALLED: {
+    code: "NOT_INSTALLED",
+    message: "qmd is not installed",
+    hint: `Install qmd to enable ClawVault search and indexing:
+  ${QMD_INSTALL_COMMAND}
+
+For more information: ${QMD_INSTALL_URL}`
+  },
+  NOT_CONFIGURED: {
+    code: "NOT_CONFIGURED",
+    message: "qmd collection is not configured",
+    hint: "Run `clawvault doctor` to diagnose configuration issues, or `clawvault migrate` to fix common setup problems."
+  },
+  COLLECTION_NOT_FOUND: {
+    code: "COLLECTION_NOT_FOUND",
+    message: "qmd collection not found",
+    hint: "The configured qmd collection does not exist. Run `clawvault migrate` to recreate it, or `qmd collection add <name> <path>` manually."
+  },
+  EXECUTION_FAILED: {
+    code: "EXECUTION_FAILED",
+    message: "qmd command failed",
+    hint: "Run `clawvault doctor` to diagnose qmd issues."
+  }
+};
+var QmdUnavailableError = class extends Error {
+  code;
+  hint;
+  constructor(code = "NOT_INSTALLED", additionalContext) {
+    const details = QMD_ERROR_MESSAGES[code];
+    const fullMessage = additionalContext ? `${details.message}: ${additionalContext}` : details.message;
+    super(fullMessage);
+    this.name = "QmdUnavailableError";
+    this.code = code;
+    this.hint = details.hint;
+  }
+  toUserMessage() {
+    return `Error: ${this.message}
+
+${this.hint}`;
+  }
+};
+function getQmdErrorDetails(code) {
+  return QMD_ERROR_MESSAGES[code];
+}
+var QmdConfigurationError = class extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.hint = hint;
+    this.name = "QmdConfigurationError";
+  }
+};
+function ensureJsonArgs(args) {
+  return args.includes("--json") ? args : [...args, "--json"];
+}
+function resolveQmdIndexName(indexName) {
+  const explicit = indexName?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const fromEnv = process.env[QMD_INDEX_ENV_VAR]?.trim();
+  return fromEnv || void 0;
+}
+function withQmdIndexArgs(args, indexName) {
+  if (args.includes("--index")) {
+    return [...args];
+  }
+  const resolvedIndexName = resolveQmdIndexName(indexName);
+  if (!resolvedIndexName) {
+    return [...args];
+  }
+  return ["--index", resolvedIndexName, ...args];
+}
+function tryParseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function extractJsonPayload(raw) {
+  const start = raw.search(/[\[{]/);
+  if (start === -1) return null;
+  const end = Math.max(raw.lastIndexOf("]"), raw.lastIndexOf("}"));
+  if (end <= start) return null;
+  return raw.slice(start, end + 1);
+}
+function stripQmdNoise(raw) {
+  return raw.split("\n").filter((line) => {
+    const t = line.trim();
+    if (!t) return true;
+    if (t.startsWith("[node-llama-cpp]")) return false;
+    if (t.startsWith("Expanding query")) return false;
+    if (t.startsWith("Searching ") && t.endsWith("queries...")) return false;
+    if (/^[├└─│]/.test(t)) return false;
+    return true;
+  }).join("\n");
+}
+function parseQmdOutput(raw) {
+  const trimmed = stripQmdNoise(raw).trim();
+  if (!trimmed) return [];
+  const direct = tryParseJson(trimmed);
+  const extracted = direct ? null : extractJsonPayload(trimmed);
+  const parsed = direct ?? (extracted ? tryParseJson(extracted) : null);
+  if (!parsed) {
+    throw new Error("qmd returned non-JSON output. Ensure qmd supports --json.");
+  }
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+  if (parsed && typeof parsed === "object") {
+    const candidate = parsed.results ?? parsed.items ?? parsed.data;
+    if (Array.isArray(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error("qmd returned an unexpected JSON shape.");
+}
+function ensureQmdAvailable() {
+  if (!hasQmd()) {
+    throw new QmdUnavailableError("NOT_INSTALLED");
+  }
+}
+function detectQmdError(output, args) {
+  const lowerOutput = output.toLowerCase();
+  if (lowerOutput.includes("missing required arguments") || lowerOutput.includes("unknown option")) {
+    return new QmdConfigurationError(
+      'qmd does not support the search command with the expected arguments. This may indicate an incompatible qmd version or a different tool named "qmd".',
+      `Ensure you have the correct qmd installed: ${QMD_INSTALL_COMMAND}`
+    );
+  }
+  if (lowerOutput.includes("collection not found") || lowerOutput.includes("no collection")) {
+    const collectionArg = args.findIndex((a) => a === "-c");
+    const collectionName = collectionArg >= 0 && args[collectionArg + 1] ? args[collectionArg + 1] : "unknown";
+    return new QmdConfigurationError(
+      `qmd collection "${collectionName}" not found.`,
+      'Run `qmd update -c <collection>` to create the collection, or check your vault\'s .clawvault.json "name" field.'
+    );
+  }
+  if (lowerOutput.includes("no index") || lowerOutput.includes("index not found")) {
+    return new QmdConfigurationError(
+      "qmd index not found. The vault may not be indexed yet.",
+      "Run `clawvault rebuild` or `qmd update` to build the search index."
+    );
+  }
+  if (lowerOutput.includes("embedding") && (lowerOutput.includes("not found") || lowerOutput.includes("missing"))) {
+    return new QmdConfigurationError(
+      "qmd embeddings not found. Vector search requires embeddings to be generated.",
+      "Run `clawvault embed` or `qmd embed` to generate embeddings for semantic search."
+    );
+  }
+  return null;
+}
+function execQmd(args, indexName) {
+  ensureQmdAvailable();
+  const finalArgs = withQmdIndexArgs(ensureJsonArgs(args), indexName);
+  try {
+    const result = execFileSync("qmd", finalArgs, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 10 * 1024 * 1024,
+      // 10MB
+      shell: process.platform === "win32"
+    });
+    return parseQmdOutput(result);
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      throw new QmdUnavailableError("NOT_INSTALLED");
+    }
+    if (err?.status === 1 && err?.stdout) {
+      return parseQmdOutput(err.stdout);
+    }
+    const output = [err?.stdout, err?.stderr].filter(Boolean).join("\n");
+    const detectedError = detectQmdError(output, finalArgs);
+    if (detectedError) {
+      throw detectedError;
+    }
+    if (output) {
+      try {
+        return parseQmdOutput(output);
+      } catch {
+      }
+      if (output.includes("collection not found") || output.includes("no such collection")) {
+        throw new QmdUnavailableError("COLLECTION_NOT_FOUND", output.trim());
+      }
+    }
+    const errorDetail = err?.message || "unknown error";
+    throw new QmdUnavailableError("EXECUTION_FAILED", errorDetail);
+  }
+}
+function hasQmd() {
+  const result = spawnSync("qmd", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+  return !result.error && (result.status === 0 || result.status === 1);
+}
+function qmdUpdate(collection, indexName) {
+  ensureQmdAvailable();
+  const args = ["update"];
+  if (collection) {
+    args.push("-c", collection);
+  }
+  execFileSync("qmd", withQmdIndexArgs(args, indexName), { stdio: "inherit", shell: process.platform === "win32" });
+}
+function qmdEmbed(collection, indexName) {
+  ensureQmdAvailable();
+  const args = ["embed"];
+  if (collection) {
+    args.push("-c", collection);
+  }
+  execFileSync("qmd", withQmdIndexArgs(args, indexName), { stdio: "inherit", shell: process.platform === "win32" });
+}
+var SearchEngine = class {
+  inProcess = new InProcessSearchEngine();
+  collection = "";
+  vaultPath = "";
+  collectionRoot = "";
+  qmdIndexName;
+  searchConfig = {};
+  setSearchConfig(config) {
+    this.searchConfig = config ?? {};
+    this.inProcess.setConfig(this.searchConfig);
+  }
+  /**
+   * Set the collection name (usually vault name)
+   */
+  setCollection(name) {
+    this.collection = name;
+  }
+  /**
+   * Get the current collection name
+   */
+  getCollection() {
+    return this.collection;
+  }
+  /**
+   * Set the vault path for file resolution
+   */
+  setVaultPath(vaultPath) {
+    this.vaultPath = vaultPath;
+    this.inProcess.setVaultPath(vaultPath);
+  }
+  /**
+   * Set the collection root for qmd:// URI resolution
+   */
+  setCollectionRoot(root) {
+    this.collectionRoot = path.resolve(root);
+  }
+  /**
+   * Set qmd index name (defaults to qmd global default when omitted)
+   */
+  setIndexName(indexName) {
+    this.qmdIndexName = indexName;
+  }
+  /**
+   * Add or update a document in the local cache
+   * Note: qmd indexing happens via qmd update command
+   */
+  addDocument(doc) {
+    this.inProcess.addDocument(doc);
+  }
+  /**
+   * Remove a document from the local cache
+   */
+  removeDocument(id) {
+    this.inProcess.removeDocument(id);
+  }
+  /**
+   * No-op for qmd - indexing is managed externally
+   */
+  rebuildIDF() {
+  }
+  /**
+   * BM25 search via qmd
+   */
+  async search(query, options = {}) {
+    if (!query.trim()) return [];
+    return this.runSearchWithFallback("search", query, options);
+  }
+  /**
+   * Vector/semantic search via qmd vsearch
+   */
+  async vsearch(query, options = {}) {
+    if (!query.trim()) return [];
+    return this.runSearchWithFallback("vsearch", query, options);
+  }
+  /**
+   * Combined search with query expansion (qmd query command)
+   */
+  async query(query, options = {}) {
+    if (!query.trim()) return [];
+    return this.runSearchWithFallback("query", query, options);
+  }
+  async runSearchWithFallback(command, query, options) {
+    const preferQmd = this.searchConfig.backend === "qmd";
+    const qmdFallbackEnabled = this.searchConfig.qmdFallback ?? true;
+    if (preferQmd) {
+      if (hasQmd()) {
+        return this.runQmdQuery(command, query, options);
+      }
+      return this.runInProcessQuery(command, query, options);
+    }
+    try {
+      const inProcessResults = await this.runInProcessQuery(command, query, options);
+      if (inProcessResults.length > 0 || command === "search" || !qmdFallbackEnabled || !hasQmd()) {
+        return inProcessResults;
+      }
+      return this.runQmdQuery(command, query, options);
+    } catch (error) {
+      if (qmdFallbackEnabled && hasQmd()) {
+        return this.runQmdQuery(command, query, options);
+      }
+      throw error;
+    }
+  }
+  async runInProcessQuery(command, query, options) {
+    if (command === "vsearch") {
+      return this.inProcess.vsearch(query, options);
+    }
+    if (command === "query") {
+      return this.inProcess.query(query, options);
+    }
+    return this.inProcess.search(query, options);
+  }
+  runQmdQuery(command, query, options) {
+    const { limit = 10, minScore = 0, category, tags, fullContent = false, temporalBoost = false } = options;
+    const args = [command, query, "-n", String(limit * 2), "--json"];
+    if (this.collection) {
+      args.push("-c", this.collection);
+    }
+    return this.convertResults(execQmd(args, this.qmdIndexName), {
+      limit,
+      minScore,
+      category,
+      tags,
+      fullContent,
+      temporalBoost
+    });
+  }
+  /**
+   * Convert qmd results to ClawVault SearchResult format
+   */
+  convertResults(qmdResults, options) {
+    const { limit = 10, minScore = 0, category, tags, fullContent = false, temporalBoost = false } = options;
+    const results = [];
+    const docs = this.inProcess.getAllDocuments();
+    const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+    const maxScore = qmdResults[0]?.score || 1;
+    for (const qr of qmdResults) {
+      const filePath = this.qmdUriToPath(qr.file);
+      const relativePath = this.vaultPath ? path.relative(this.vaultPath, filePath) : filePath;
+      const normalizedRelativePath = relativePath.replace(/\\/g, "/");
+      if (normalizedRelativePath.startsWith("ledger/archive/") || normalizedRelativePath.includes("/ledger/archive/")) {
+        continue;
+      }
+      const docId = normalizedRelativePath.replace(/\.md$/, "");
+      let doc = docsById.get(docId) ?? docsById.get(docId.split("/").join(path.sep));
+      const modifiedAt = this.resolveModifiedAt(doc, filePath);
+      const parts = normalizedRelativePath.split("/");
+      const docCategory = parts.length > 1 ? parts[0] : "root";
+      if (category && docCategory !== category) continue;
+      if (tags && tags.length > 0 && doc) {
+        const docTags = new Set(doc.tags);
+        if (!tags.some((t) => docTags.has(t))) continue;
+      }
+      const normalizedScore = maxScore > 0 ? qr.score / maxScore : 0;
+      const finalScore = temporalBoost ? normalizedScore * this.getRecencyFactor(modifiedAt) : normalizedScore;
+      if (finalScore < minScore) continue;
+      if (!doc) {
+        doc = {
+          id: docId,
+          path: filePath,
+          category: docCategory,
+          title: qr.title || path.basename(relativePath, ".md"),
+          content: "",
+          // Content loaded separately if needed
+          frontmatter: {},
+          links: [],
+          tags: [],
+          modified: modifiedAt
+        };
+      }
+      results.push({
+        document: fullContent ? doc : { ...doc, content: "" },
+        score: finalScore,
+        snippet: this.cleanSnippet(qr.snippet),
+        matchedTerms: []
+        // qmd doesn't provide this
+      });
+    }
+    return results.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+  resolveModifiedAt(doc, filePath) {
+    if (doc) return doc.modified;
+    try {
+      return fs.statSync(filePath).mtime;
+    } catch {
+      return /* @__PURE__ */ new Date(0);
+    }
+  }
+  getRecencyFactor(modifiedAt) {
+    const ageMs = Math.max(0, Date.now() - modifiedAt.getTime());
+    const ageDays = ageMs / (24 * 60 * 60 * 1e3);
+    if (ageDays < 1) return 1;
+    if (ageDays <= 7) return 0.9;
+    return 0.7;
+  }
+  /**
+   * Convert qmd:// URI to file path
+   */
+  qmdUriToPath(uri) {
+    if (uri.startsWith("qmd://")) {
+      const withoutScheme = uri.slice(6);
+      const slashIndex = withoutScheme.indexOf("/");
+      if (slashIndex > -1) {
+        const relativePath = withoutScheme.slice(slashIndex + 1);
+        const root = this.collectionRoot || this.vaultPath;
+        if (root) {
+          return path.join(root, relativePath);
+        }
+        return relativePath;
+      }
+    }
+    return uri;
+  }
+  /**
+   * Clean up qmd snippet format
+   */
+  cleanSnippet(snippet) {
+    if (!snippet) return "";
+    return snippet.replace(/@@ [-+]?\d+,?\d* @@ \([^)]+\)/g, "").trim().split("\n").slice(0, 3).join("\n").slice(0, 300);
+  }
+  /**
+   * Get all cached documents
+   */
+  getAllDocuments() {
+    return this.inProcess.getAllDocuments();
+  }
+  /**
+   * Get document count
+   */
+  get size() {
+    return this.inProcess.size;
+  }
+  /**
+   * Clear the local document cache
+   */
+  clear() {
+    this.inProcess.clear();
+  }
+  /**
+   * Export documents for persistence
+   */
+  export() {
+    return this.inProcess.export();
+  }
+  /**
+   * Import from persisted data
+   */
+  import(data) {
+    this.inProcess.import(data);
+  }
+};
+function extractWikiLinks(content) {
+  const matches = content.match(/\[\[([^\]]+)\]\]/g) || [];
+  return matches.map((m) => m.slice(2, -2).toLowerCase());
+}
+function extractTags(content) {
+  const matches = content.match(/#[\w-]+/g) || [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+
+export {
+  QMD_INSTALL_URL,
+  QMD_INSTALL_COMMAND,
+  QmdUnavailableError,
+  getQmdErrorDetails,
+  QmdConfigurationError,
+  withQmdIndexArgs,
+  hasQmd,
+  qmdUpdate,
+  qmdEmbed,
+  SearchEngine,
+  extractWikiLinks,
+  extractTags
+};