@arabold/docs-mcp-server 1.18.0 → 1.20.0

package/dist/DocumentManagementService-BH02TJEe.js

@@ -0,0 +1,1917 @@
+import fs from "node:fs";
+import path from "node:path";
+import envPaths from "env-paths";
+import Fuse from "fuse.js";
+import semver__default from "semver";
+import { RecursiveCharacterTextSplitter } from "langchain/text_splitter";
+import remarkGfm from "remark-gfm";
+import remarkHtml from "remark-html";
+import remarkParse from "remark-parse";
+import TurndownService from "turndown";
+import { unified } from "unified";
+import { l as logger, c as createJSDOM, V as VECTOR_DIMENSION, S as StoreError, D as DimensionError, a as applyMigrations, C as ConnectionError, d as denormalizeVersionName, n as normalizeVersionName, E as EMBEDDING_BATCH_CHARS, b as EMBEDDING_BATCH_SIZE, m as mapDbDocumentToDocument, g as getProjectRoot, e as SPLITTER_PREFERRED_CHUNK_SIZE, f as SPLITTER_MAX_CHUNK_SIZE, L as LibraryNotFoundError, h as VersionNotFoundError, i as SPLITTER_MIN_CHUNK_SIZE } from "./index.js";
+import "cheerio";
+import "node:vm";
+import "jsdom";
+import "playwright";
+import "@joplin/turndown-plugin-gfm";
+import "iconv-lite";
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+class SplitterError extends Error {
+}
+class MinimumChunkSizeError extends SplitterError {
+  constructor(size, maxSize) {
+    super(
+      `Cannot split content any further. Content requires minimum chunk size of ${size} bytes, but maximum allowed is ${maxSize} bytes.`
+    );
+  }
+}
+class ContentSplitterError extends SplitterError {
+}
+class GreedySplitter {
+  baseSplitter;
+  minChunkSize;
+  preferredChunkSize;
+  /**
+   * Combines a base document splitter with size constraints to produce optimally-sized chunks.
+   * The base splitter handles the initial semantic splitting, while this class handles
+   * the concatenation strategy.
+   */
+  constructor(baseSplitter, minChunkSize, preferredChunkSize) {
+    this.baseSplitter = baseSplitter;
+    this.minChunkSize = minChunkSize;
+    this.preferredChunkSize = preferredChunkSize;
+  }
+  /**
+   * Uses a greedy concatenation strategy to build optimally-sized chunks. Small chunks
+   * are combined until they reach the minimum size, but splits are preserved at major
+   * section boundaries to maintain document structure. This balances the need for
+   * context with semantic coherence.
+   */
+  async splitText(markdown) {
+    const initialChunks = await this.baseSplitter.splitText(markdown);
+    const concatenatedChunks = [];
+    let currentChunk = null;
+    for (const nextChunk of initialChunks) {
+      if (currentChunk) {
+        if (this.wouldExceedMaxSize(currentChunk, nextChunk)) {
+          concatenatedChunks.push(currentChunk);
+          currentChunk = this.cloneChunk(nextChunk);
+          continue;
+        }
+        if (currentChunk.content.length >= this.minChunkSize && this.startsNewMajorSection(nextChunk)) {
+          concatenatedChunks.push(currentChunk);
+          currentChunk = this.cloneChunk(nextChunk);
+          continue;
+        }
+        currentChunk.content += `
+${nextChunk.content}`;
+        currentChunk.section = this.mergeSectionInfo(currentChunk, nextChunk);
+        currentChunk.types = this.mergeTypes(currentChunk.types, nextChunk.types);
+      } else {
+        currentChunk = this.cloneChunk(nextChunk);
+      }
+    }
+    if (currentChunk) {
+      concatenatedChunks.push(currentChunk);
+    }
+    return concatenatedChunks;
+  }
+  cloneChunk(chunk) {
+    return {
+      types: [...chunk.types],
+      content: chunk.content,
+      section: {
+        level: chunk.section.level,
+        path: [...chunk.section.path]
+      }
+    };
+  }
+  /**
+   * H1 and H2 headings represent major conceptual breaks in the document.
+   * Preserving these splits helps maintain the document's logical structure.
+   */
+  startsNewMajorSection(chunk) {
+    return chunk.section.level === 1 || chunk.section.level === 2;
+  }
+  /**
+   * Size limit check to ensure chunks remain within embedding model constraints.
+   * Essential for maintaining consistent embedding quality and avoiding truncation.
+   */
+  wouldExceedMaxSize(currentChunk, nextChunk) {
+    if (!currentChunk) {
+      return false;
+    }
+    return currentChunk.content.length + nextChunk.content.length > this.preferredChunkSize;
+  }
+  /**
+   * Checks if one path is a prefix of another path, indicating a parent-child relationship
+   */
+  isPathIncluded(parentPath, childPath) {
+    if (parentPath.length >= childPath.length) return false;
+    return parentPath.every((part, i) => part === childPath[i]);
+  }
+  /**
+   * Merges section metadata when concatenating chunks, following these rules:
+   * 1. Level: Always uses the lowest (most general) level between chunks
+   * 2. Path selection:
+   *    - For parent-child relationships (one path includes the other), uses the child's path
+   *    - For siblings/unrelated sections, uses the common parent path
+   *    - If no common path exists, uses the root path ([])
+   */
+  mergeSectionInfo(currentChunk, nextChunk) {
+    const level = Math.min(currentChunk.section.level, nextChunk.section.level);
+    if (currentChunk.section.level === nextChunk.section.level && currentChunk.section.path.length === nextChunk.section.path.length && currentChunk.section.path.every((p, i) => p === nextChunk.section.path[i])) {
+      return currentChunk.section;
+    }
+    if (this.isPathIncluded(currentChunk.section.path, nextChunk.section.path)) {
+      return {
+        path: nextChunk.section.path,
+        level
+      };
+    }
+    if (this.isPathIncluded(nextChunk.section.path, currentChunk.section.path)) {
+      return {
+        path: currentChunk.section.path,
+        level
+      };
+    }
+    const commonPath = this.findCommonPrefix(
+      currentChunk.section.path,
+      nextChunk.section.path
+    );
+    return {
+      path: commonPath,
+      level
+    };
+  }
+  mergeTypes(currentTypes, nextTypes) {
+    return [.../* @__PURE__ */ new Set([...currentTypes, ...nextTypes])];
+  }
+  /**
+   * Returns longest common prefix between two paths
+   */
+  findCommonPrefix(path1, path2) {
+    const common = [];
+    for (let i = 0; i < Math.min(path1.length, path2.length); i++) {
+      if (path1[i] === path2[i]) {
+        common.push(path1[i]);
+      } else {
+        break;
+      }
+    }
+    return common;
+  }
+}
+const fullTrim = (str) => {
+  return str.replace(/^[\s\r\n\t]+|[\s\r\n\t]+$/g, "");
+};
+class CodeContentSplitter {
+  constructor(options) {
+    this.options = options;
+  }
+  async split(content) {
+    const language = content.match(/^```(\w+)\n/)?.[1];
+    const strippedContent = content.replace(/^```(\w*)\n/, "").replace(/```\s*$/, "");
+    const lines = strippedContent.split("\n");
+    const chunks = [];
+    let currentChunkLines = [];
+    for (const line of lines) {
+      const singleLineSize = this.wrap(line, language).length;
+      if (singleLineSize > this.options.chunkSize) {
+        throw new MinimumChunkSizeError(singleLineSize, this.options.chunkSize);
+      }
+      currentChunkLines.push(line);
+      const newChunkContent = this.wrap(currentChunkLines.join("\n"), language);
+      const newChunkSize = newChunkContent.length;
+      if (newChunkSize > this.options.chunkSize && currentChunkLines.length > 1) {
+        const lastLine = currentChunkLines.pop();
+        chunks.push(this.wrap(currentChunkLines.join("\n"), language));
+        currentChunkLines = [lastLine];
+      }
+    }
+    if (currentChunkLines.length > 0) {
+      chunks.push(this.wrap(currentChunkLines.join("\n"), language));
+    }
+    return chunks;
+  }
+  wrap(content, language) {
+    return `\`\`\`${language || ""}
+${content.replace(/\n+$/, "")}
+\`\`\``;
+  }
+}
+class TableContentSplitter {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Splits table content into chunks while preserving table structure
+   */
+  async split(content) {
+    const parsedTable = this.parseTable(content);
+    if (!parsedTable) {
+      return [content];
+    }
+    const { headers, rows } = parsedTable;
+    const chunks = [];
+    let currentRows = [];
+    for (const row of rows) {
+      const singleRowSize = this.wrap(row, headers).length;
+      if (singleRowSize > this.options.chunkSize) {
+        throw new MinimumChunkSizeError(singleRowSize, this.options.chunkSize);
+      }
+      const newChunkContent = this.wrap([...currentRows, row].join("\n"), headers);
+      const newChunkSize = newChunkContent.length;
+      if (newChunkSize > this.options.chunkSize && currentRows.length > 0) {
+        chunks.push(this.wrap(currentRows.join("\n"), headers));
+        currentRows = [row];
+      } else {
+        currentRows.push(row);
+      }
+    }
+    if (currentRows.length > 0) {
+      chunks.push(this.wrap(currentRows.join("\n"), headers));
+    }
+    return chunks;
+  }
+  wrap(content, headers) {
+    const headerRow = `| ${headers.join(" | ")} |`;
+    const separatorRow = `|${headers.map(() => "---").join("|")}|`;
+    return [headerRow, separatorRow, content].join("\n");
+  }
+  parseTable(content) {
+    const lines = content.trim().split("\n");
+    if (lines.length < 3) return null;
+    const headers = this.parseRow(lines[0]);
+    if (!headers) return null;
+    const separator = lines[1];
+    if (!this.isValidSeparator(separator)) return null;
+    const rows = lines.slice(2).filter((row) => row.trim() !== "");
+    return { headers, separator, rows };
+  }
+  /**
+   * Parses a table row into cells
+   */
+  parseRow(row) {
+    if (!row.includes("|")) return null;
+    return row.split("|").map((cell) => cell.trim()).filter((cell) => cell !== "");
+  }
+  /**
+   * Validates the separator row of the table
+   */
+  isValidSeparator(separator) {
+    return separator.includes("|") && /^\|?[\s-|]+\|?$/.test(separator);
+  }
+}
+class TextContentSplitter {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Splits text content into chunks while trying to preserve semantic boundaries.
+   * Prefers paragraph breaks, then line breaks, finally falling back to word boundaries.
+   */
+  async split(content) {
+    const trimmedContent = fullTrim(content);
+    if (trimmedContent.length <= this.options.chunkSize) {
+      return [trimmedContent];
+    }
+    const words = trimmedContent.split(/\s+/);
+    const longestWord = words.reduce(
+      (max, word) => word.length > max.length ? word : max
+    );
+    if (longestWord.length > this.options.chunkSize) {
+      throw new MinimumChunkSizeError(longestWord.length, this.options.chunkSize);
+    }
+    const paragraphChunks = this.splitByParagraphs(trimmedContent);
+    if (this.areChunksValid(paragraphChunks)) {
+      return paragraphChunks;
+    }
+    const lineChunks = this.splitByLines(trimmedContent);
+    if (this.areChunksValid(lineChunks)) {
+      return this.mergeChunks(lineChunks, "\n");
+    }
+    const wordChunks = await this.splitByWords(trimmedContent);
+    return this.mergeChunks(wordChunks, " ");
+  }
+  /**
+   * Checks if all chunks are within the maximum size limit
+   */
+  areChunksValid(chunks) {
+    return chunks.every((chunk) => chunk.length <= this.options.chunkSize);
+  }
+  /**
+   * Splits text into chunks by paragraph boundaries (double newlines)
+   */
+  splitByParagraphs(text) {
+    const paragraphs = text.split(/\n\s*\n/).map((p) => fullTrim(p)).filter(Boolean);
+    return paragraphs.filter((chunk) => chunk.length > 2);
+  }
+  /**
+   * Splits text into chunks by line boundaries
+   */
+  splitByLines(text) {
+    const lines = text.split(/\n/).map((line) => fullTrim(line)).filter(Boolean);
+    return lines.filter((chunk) => chunk.length > 1);
+  }
+  /**
+   * Uses LangChain's recursive splitter for word-based splitting as a last resort
+   */
+  async splitByWords(text) {
+    const splitter = new RecursiveCharacterTextSplitter({
+      chunkSize: this.options.chunkSize,
+      chunkOverlap: 0
+    });
+    const chunks = await splitter.splitText(text);
+    return chunks;
+  }
+  /**
+   * Attempts to merge small chunks with previous chunks to minimize fragmentation.
+   * Only merges if combined size is within maxChunkSize.
+   */
+  mergeChunks(chunks, separator) {
+    const mergedChunks = [];
+    let currentChunk = null;
+    for (const chunk of chunks) {
+      if (currentChunk === null) {
+        currentChunk = chunk;
+        continue;
+      }
+      const currentChunkSize = this.getChunkSize(currentChunk);
+      const nextChunkSize = this.getChunkSize(chunk);
+      if (currentChunkSize + nextChunkSize + separator.length <= this.options.chunkSize) {
+        currentChunk = `${currentChunk}${separator}${chunk}`;
+      } else {
+        mergedChunks.push(currentChunk);
+        currentChunk = chunk;
+      }
+    }
+    if (currentChunk) {
+      mergedChunks.push(currentChunk);
+    }
+    return mergedChunks;
+  }
+  getChunkSize(chunk) {
+    return chunk.length;
+  }
+  wrap(content) {
+    return content;
+  }
+}
+class SemanticMarkdownSplitter {
+  constructor(preferredChunkSize, maxChunkSize) {
+    this.preferredChunkSize = preferredChunkSize;
+    this.maxChunkSize = maxChunkSize;
+    this.turndownService = new TurndownService({
+      headingStyle: "atx",
+      hr: "---",
+      bulletListMarker: "-",
+      codeBlockStyle: "fenced",
+      emDelimiter: "_",
+      strongDelimiter: "**",
+      linkStyle: "inlined"
+    });
+    this.turndownService.addRule("table", {
+      filter: ["table"],
+      replacement: (_content, node) => {
+        const table = node;
+        const headers = Array.from(table.querySelectorAll("th")).map(
+          (th) => th.textContent?.trim() || ""
+        );
+        const rows = Array.from(table.querySelectorAll("tr")).filter(
+          (tr) => !tr.querySelector("th")
+        );
+        if (headers.length === 0 && rows.length === 0) return "";
+        let markdown = "\n";
+        if (headers.length > 0) {
+          markdown += `| ${headers.join(" | ")} |
+`;
+          markdown += `|${headers.map(() => "---").join("|")}|
+`;
+        }
+        for (const row of rows) {
+          const cells = Array.from(row.querySelectorAll("td")).map(
+            (td) => td.textContent?.trim() || ""
+          );
+          markdown += `| ${cells.join(" | ")} |
+`;
+        }
+        return markdown;
+      }
+    });
+    this.textSplitter = new TextContentSplitter({
+      chunkSize: this.preferredChunkSize
+    });
+    this.codeSplitter = new CodeContentSplitter({
+      chunkSize: this.maxChunkSize
+    });
+    this.tableSplitter = new TableContentSplitter({
+      chunkSize: this.maxChunkSize
+    });
+  }
+  turndownService;
+  textSplitter;
+  codeSplitter;
+  tableSplitter;
+  /**
+   * Main entry point for splitting markdown content
+   */
+  async splitText(markdown) {
+    const html = await this.markdownToHtml(markdown);
+    const dom = await this.parseHtml(html);
+    const sections = await this.splitIntoSections(dom);
+    return this.splitSectionContent(sections);
+  }
+  /**
+   * Step 1: Split document into sections based on H1-H6 headings,
+   * as well as code blocks and tables.
+   */
+  async splitIntoSections(dom) {
+    const body = dom.querySelector("body");
+    if (!body) {
+      throw new Error("Invalid HTML structure: no body element found");
+    }
+    let currentSection = this.createRootSection();
+    const sections = [];
+    const stack = [currentSection];
+    for (const element of Array.from(body.children)) {
+      const headingMatch = element.tagName.match(/H([1-6])/);
+      if (headingMatch) {
+        const level = Number.parseInt(headingMatch[1], 10);
+        const title = fullTrim(element.textContent || "");
+        while (stack.length > 1 && stack[stack.length - 1].level >= level) {
+          stack.pop();
+        }
+        currentSection = {
+          level,
+          path: [
+            ...stack.slice(1).reduce((acc, s) => {
+              const lastPath = s.path[s.path.length - 1];
+              if (lastPath) acc.push(lastPath);
+              return acc;
+            }, []),
+            title
+          ],
+          content: [
+            {
+              type: "heading",
+              text: `${"#".repeat(level)} ${title}`
+            }
+          ]
+        };
+        sections.push(currentSection);
+        stack.push(currentSection);
+      } else if (element.tagName === "PRE") {
+        const code = element.querySelector("code");
+        const language = code?.className.replace("language-", "") || "";
+        const content = code?.textContent || element.textContent || "";
+        const markdown = `${"```"}${language}
+${content}
+${"```"}`;
+        currentSection = {
+          level: currentSection.level,
+          path: currentSection.path,
+          content: [
+            {
+              type: "code",
+              text: markdown
+            }
+          ]
+        };
+        sections.push(currentSection);
+      } else if (element.tagName === "TABLE") {
+        const markdown = fullTrim(this.turndownService.turndown(element.outerHTML));
+        currentSection = {
+          level: currentSection.level,
+          path: currentSection.path,
+          content: [
+            {
+              type: "table",
+              text: markdown
+            }
+          ]
+        };
+        sections.push(currentSection);
+      } else {
+        const markdown = fullTrim(this.turndownService.turndown(element.innerHTML));
+        if (markdown) {
+          currentSection = {
+            level: currentSection.level,
+            path: currentSection.path,
+            content: [
+              {
+                type: "text",
+                text: markdown
+              }
+            ]
+          };
+          sections.push(currentSection);
+        }
+      }
+    }
+    return sections;
+  }
+  /**
+   * Step 2: Split section content into smaller chunks
+   */
+  async splitSectionContent(sections) {
+    const chunks = [];
+    for (const section of sections) {
+      for (const content of section.content) {
+        let splitContent = [];
+        try {
+          switch (content.type) {
+            case "heading":
+            case "text": {
+              splitContent = await this.textSplitter.split(content.text);
+              break;
+            }
+            case "code": {
+              splitContent = await this.codeSplitter.split(content.text);
+              break;
+            }
+            case "table": {
+              splitContent = await this.tableSplitter.split(content.text);
+              break;
+            }
+          }
+        } catch (err) {
+          if (err instanceof MinimumChunkSizeError) {
+            logger.warn(
+              `⚠ Cannot split ${content.type} chunk normally, using RecursiveCharacterTextSplitter: ${err.message}`
+            );
+            const splitter = new RecursiveCharacterTextSplitter({
+              chunkSize: this.maxChunkSize,
+              chunkOverlap: Math.min(20, Math.floor(this.maxChunkSize * 0.1)),
+              // Use more aggressive separators including empty string as last resort
+              separators: [
+                "\n\n",
+                "\n",
+                " ",
+                "	",
+                ".",
+                ",",
+                ";",
+                ":",
+                "-",
+                "(",
+                ")",
+                "[",
+                "]",
+                "{",
+                "}",
+                ""
+              ]
+            });
+            const chunks2 = await splitter.splitText(content.text);
+            if (chunks2.length === 0) {
+              splitContent = [content.text.substring(0, this.maxChunkSize)];
+            } else {
+              splitContent = chunks2;
+            }
+          } else {
+            const errMessage = err instanceof Error ? err.message : String(err);
+            throw new ContentSplitterError(
+              `Failed to split ${content.type} content: ${errMessage}`
+            );
+          }
+        }
+        chunks.push(
+          ...splitContent.map(
+            (text) => ({
+              types: [content.type],
+              content: text,
+              section: {
+                level: section.level,
+                path: section.path
+              }
+            })
+          )
+        );
+      }
+    }
+    return chunks;
+  }
+  /**
+   * Helper to create the root section
+   */
+  createRootSection() {
+    return {
+      level: 0,
+      path: [],
+      content: []
+    };
+  }
+  /**
+   * Convert markdown to HTML using remark
+   */
+  async markdownToHtml(markdown) {
+    const html = await unified().use(remarkParse).use(remarkGfm).use(remarkHtml).process(markdown);
+    return `<!DOCTYPE html>
+      <html>
+        <body>
+          ${String(html)}
+        </body>
+      </html>`;
+  }
+  /**
+   * Parse HTML
+   */
+  async parseHtml(html) {
+    const { window } = createJSDOM(html);
+    return window.document;
+  }
+}
+const CHILD_LIMIT = 5;
+const SIBLING_LIMIT = 2;
+class DocumentRetrieverService {
+  documentStore;
+  constructor(documentStore) {
+    this.documentStore = documentStore;
+  }
+  /**
+   * Collects all related chunk IDs for a given initial hit.
+   * Returns an object with url, hitId, relatedIds (Set), and score.
+   */
+  async getRelatedChunkIds(library, version, doc, siblingLimit = SIBLING_LIMIT, childLimit = CHILD_LIMIT) {
+    const id = doc.id;
+    const url = doc.metadata.url;
+    const score = doc.metadata.score;
+    const relatedIds = /* @__PURE__ */ new Set();
+    relatedIds.add(id);
+    const parent = await this.documentStore.findParentChunk(library, version, id);
+    if (parent) {
+      relatedIds.add(parent.id);
+    }
+    const precedingSiblings = await this.documentStore.findPrecedingSiblingChunks(
+      library,
+      version,
+      id,
+      siblingLimit
+    );
+    for (const sib of precedingSiblings) {
+      relatedIds.add(sib.id);
+    }
+    const childChunks = await this.documentStore.findChildChunks(
+      library,
+      version,
+      id,
+      childLimit
+    );
+    for (const child of childChunks) {
+      relatedIds.add(child.id);
+    }
+    const subsequentSiblings = await this.documentStore.findSubsequentSiblingChunks(
+      library,
+      version,
+      id,
+      siblingLimit
+    );
+    for (const sib of subsequentSiblings) {
+      relatedIds.add(sib.id);
+    }
+    return { url, hitId: id, relatedIds, score };
+  }
+  /**
+   * Groups related chunk info by URL, deduplicates IDs, and finds max score per URL.
+   */
+  groupAndPrepareFetch(relatedInfos) {
+    const urlMap = /* @__PURE__ */ new Map();
+    for (const info of relatedInfos) {
+      let entry = urlMap.get(info.url);
+      if (!entry) {
+        entry = { uniqueChunkIds: /* @__PURE__ */ new Set(), maxScore: info.score };
+        urlMap.set(info.url, entry);
+      }
+      for (const id of info.relatedIds) {
+        entry.uniqueChunkIds.add(id);
+      }
+      if (info.score > entry.maxScore) {
+        entry.maxScore = info.score;
+      }
+    }
+    return urlMap;
+  }
+  /**
+   * Finalizes the merged result for a URL group by fetching, sorting, and joining content.
+   */
+  async finalizeResult(library, version, url, uniqueChunkIds, maxScore) {
+    const ids = Array.from(uniqueChunkIds);
+    const docs = await this.documentStore.findChunksByIds(library, version, ids);
+    const content = docs.map((d) => d.pageContent).join("\n\n");
+    return {
+      url,
+      content,
+      score: maxScore
+    };
+  }
+  /**
+   * Searches for documents and expands the context around the matches.
+   * @param library The library name.
+   * @param version The library version.
+   * @param query The search query.
+   * @param version The library version (optional, defaults to searching documents without a version).
+   * @param query The search query.
+   * @param limit The optional limit for the initial search results.
+   * @returns An array of strings representing the aggregated content of the retrieved chunks.
+   */
+  async search(library, version, query, limit) {
+    const normalizedVersion = (version ?? "").toLowerCase();
+    const initialResults = await this.documentStore.findByContent(
+      library,
+      normalizedVersion,
+      query,
+      limit ?? 10
+    );
+    const relatedInfos = await Promise.all(
+      initialResults.map(
+        (doc) => this.getRelatedChunkIds(library, normalizedVersion, doc)
+      )
+    );
+    const urlMap = this.groupAndPrepareFetch(relatedInfos);
+    const results = [];
+    for (const [url, { uniqueChunkIds, maxScore }] of urlMap.entries()) {
+      const result = await this.finalizeResult(
+        library,
+        normalizedVersion,
+        url,
+        uniqueChunkIds,
+        maxScore
+      );
+      results.push(result);
+    }
+    return results;
+  }
+}
+class DocumentStore {
+  db;
+  embeddings;
+  dbDimension = VECTOR_DIMENSION;
+  modelDimension;
+  statements;
+  /**
+   * Calculates Reciprocal Rank Fusion score for a result
+   */
+  calculateRRF(vecRank, ftsRank, k = 60) {
+    let rrf = 0;
+    if (vecRank !== void 0) {
+      rrf += 1 / (k + vecRank);
+    }
+    if (ftsRank !== void 0) {
+      rrf += 1 / (k + ftsRank);
+    }
+    return rrf;
+  }
+  /**
+   * Assigns ranks to search results based on their scores
+   */
+  assignRanks(results) {
+    const vecRanks = /* @__PURE__ */ new Map();
+    const ftsRanks = /* @__PURE__ */ new Map();
+    results.filter((r) => r.vec_score !== void 0).sort((a, b) => (b.vec_score ?? 0) - (a.vec_score ?? 0)).forEach((result, index) => {
+      vecRanks.set(Number(result.id), index + 1);
+    });
+    results.filter((r) => r.fts_score !== void 0).sort((a, b) => (b.fts_score ?? 0) - (a.fts_score ?? 0)).forEach((result, index) => {
+      ftsRanks.set(Number(result.id), index + 1);
+    });
+    return results.map((result) => ({
+      ...result,
+      vec_rank: vecRanks.get(Number(result.id)),
+      fts_rank: ftsRanks.get(Number(result.id)),
+      rrf_score: this.calculateRRF(
+        vecRanks.get(Number(result.id)),
+        ftsRanks.get(Number(result.id))
+      )
+    }));
+  }
+  constructor(dbPath) {
+    if (!dbPath) {
+      throw new StoreError("Missing required database path");
+    }
+    this.db = new Database(dbPath);
+  }
+  /**
+   * Sets up prepared statements for database queries
+   */
+  prepareStatements() {
+    const statements = {
+      getById: this.db.prepare("SELECT * FROM documents WHERE id = ?"),
+      insertDocument: this.db.prepare(
+        "INSERT INTO documents (library_id, version_id, url, content, metadata, sort_order, indexed_at) VALUES (?, ?, ?, ?, ?, ?, ?)"
+      ),
+      insertEmbedding: this.db.prepare(
+        "INSERT INTO documents_vec (rowid, library_id, version_id, embedding) VALUES (?, ?, ?, ?)"
+      ),
+      insertLibrary: this.db.prepare(
+        "INSERT INTO libraries (name) VALUES (?) ON CONFLICT(name) DO NOTHING"
+      ),
+      getLibraryIdByName: this.db.prepare(
+        "SELECT id FROM libraries WHERE name = ?"
+      ),
+      // New version-related statements
+      insertVersion: this.db.prepare(
+        "INSERT INTO versions (library_id, name, status) VALUES (?, ?, 'not_indexed') ON CONFLICT(library_id, name) DO NOTHING"
+      ),
+      resolveVersionId: this.db.prepare(
+        "SELECT id FROM versions WHERE library_id = ? AND name IS ?"
+      ),
+      getVersionById: this.db.prepare("SELECT * FROM versions WHERE id = ?"),
+      queryVersionsByLibraryId: this.db.prepare(
+        "SELECT * FROM versions WHERE library_id = ? ORDER BY name"
+      ),
+      deleteLibraryDocuments: this.db.prepare(
+        `DELETE FROM documents
+         WHERE library_id = (SELECT id FROM libraries WHERE name = ?)
+         AND version_id = (
+           SELECT v.id FROM versions v 
+           WHERE v.library_id = (SELECT id FROM libraries WHERE name = ?)
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+         )`
+      ),
+      deleteDocuments: this.db.prepare(
+        `DELETE FROM documents
+         WHERE library_id = (SELECT id FROM libraries WHERE name = ?)
+         AND version_id = (
+           SELECT v.id FROM versions v 
+           WHERE v.library_id = (SELECT id FROM libraries WHERE name = ?)
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+         )`
+      ),
+      deleteDocumentsByUrl: this.db.prepare(
+        `DELETE FROM documents
+         WHERE url = ?
+         AND library_id = (SELECT id FROM libraries WHERE name = ?)
+         AND version_id = (
+           SELECT v.id FROM versions v 
+           WHERE v.library_id = (SELECT id FROM libraries WHERE name = ?)
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+         )`
+      ),
+      getDocumentBySort: this.db.prepare(
+        `SELECT d.id
+         FROM documents d
+         JOIN versions v ON d.version_id = v.id
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ?
+         AND COALESCE(v.name, '') = COALESCE(?, '')
+         LIMIT 1`
+      ),
+      queryVersions: this.db.prepare(
+        `SELECT DISTINCT v.name
+         FROM versions v
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ?
+         ORDER BY v.name`
+      ),
+      checkExists: this.db.prepare(
+        `SELECT d.id FROM documents d
+         JOIN versions v ON d.version_id = v.id
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ?
+         AND COALESCE(v.name, '') = COALESCE(?, '')
+         LIMIT 1`
+      ),
+      // Library/version aggregation including versions without documents and status/progress fields
+      queryLibraryVersions: this.db.prepare(
+        `SELECT
+          l.name as library,
+          COALESCE(v.name, '') as version,
+          v.id as versionId,
+          v.status as status,
+          v.progress_pages as progressPages,
+          v.progress_max_pages as progressMaxPages,
+          v.source_url as sourceUrl,
+          MIN(d.indexed_at) as indexedAt,
+          COUNT(d.id) as documentCount,
+          COUNT(DISTINCT d.url) as uniqueUrlCount
+        FROM versions v
+        JOIN libraries l ON v.library_id = l.id
+        LEFT JOIN documents d ON d.version_id = v.id
+        GROUP BY v.id
+        ORDER BY l.name, version`
+      ),
+      getChildChunks: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND json_array_length(json_extract(d.metadata, '$.path')) = ?
+        AND json_extract(d.metadata, '$.path') LIKE ? || '%'
+        AND d.sort_order > (SELECT sort_order FROM documents WHERE id = ?)
+        ORDER BY d.sort_order
+        LIMIT ?
+      `),
+      getPrecedingSiblings: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND d.sort_order < (SELECT sort_order FROM documents WHERE id = ?)
+        AND json_extract(d.metadata, '$.path') = ?
+        ORDER BY d.sort_order DESC
+        LIMIT ?
+      `),
+      getSubsequentSiblings: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND d.sort_order > (SELECT sort_order FROM documents WHERE id = ?)
+        AND json_extract(d.metadata, '$.path') = ?
+        ORDER BY d.sort_order
+        LIMIT ?
+      `),
+      getParentChunk: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND json_extract(d.metadata, '$.path') = ?
+        AND d.sort_order < (SELECT sort_order FROM documents WHERE id = ?)
+        ORDER BY d.sort_order DESC
+        LIMIT 1
+      `),
+      // Status tracking statements
+      updateVersionStatus: this.db.prepare(
+        "UPDATE versions SET status = ?, error_message = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+      ),
+      updateVersionProgress: this.db.prepare(
+        "UPDATE versions SET progress_pages = ?, progress_max_pages = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+      ),
+      getVersionsByStatus: this.db.prepare(
+        "SELECT v.*, l.name as library_name FROM versions v JOIN libraries l ON v.library_id = l.id WHERE v.status IN (SELECT value FROM json_each(?))"
+      ),
+      // Scraper options statements
+      updateVersionScraperOptions: this.db.prepare(
+        "UPDATE versions SET source_url = ?, scraper_options = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+      ),
+      getVersionWithOptions: this.db.prepare(
+        "SELECT * FROM versions WHERE id = ?"
+      ),
+      getVersionsBySourceUrl: this.db.prepare(
+        "SELECT v.*, l.name as library_name FROM versions v JOIN libraries l ON v.library_id = l.id WHERE v.source_url = ? ORDER BY v.created_at DESC"
+      )
+    };
+    this.statements = statements;
+  }
+  /**
+   * Pads a vector to the fixed database dimension by appending zeros.
+   * Throws an error if the input vector is longer than the database dimension.
+   */
+  padVector(vector) {
+    if (vector.length > this.dbDimension) {
+      throw new Error(
+        `Vector dimension ${vector.length} exceeds database dimension ${this.dbDimension}`
+      );
+    }
+    if (vector.length === this.dbDimension) {
+      return vector;
+    }
+    return [...vector, ...new Array(this.dbDimension - vector.length).fill(0)];
+  }
+  /**
+   * Initializes embeddings client using environment variables for configuration.
+   *
+   * The embedding model is configured using DOCS_MCP_EMBEDDING_MODEL environment variable.
+   * Format: "provider:model_name" (e.g., "google:text-embedding-004") or just "model_name"
+   * for OpenAI (default).
+   *
+   * Supported providers and their required environment variables:
+   * - openai: OPENAI_API_KEY (and optionally OPENAI_API_BASE, OPENAI_ORG_ID)
+   * - google: GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)
+   * - aws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (or BEDROCK_AWS_REGION)
+   * - microsoft: Azure OpenAI credentials (AZURE_OPENAI_API_*)
+   */
+  async initializeEmbeddings() {
+    const modelSpec = process.env.DOCS_MCP_EMBEDDING_MODEL || "text-embedding-3-small";
+    const { createEmbeddingModel } = await import("./EmbeddingFactory-CElwVk3X.js");
+    this.embeddings = createEmbeddingModel(modelSpec);
+    const testVector = await this.embeddings.embedQuery("test");
+    this.modelDimension = testVector.length;
+    if (this.modelDimension > this.dbDimension) {
+      throw new DimensionError(modelSpec, this.modelDimension, this.dbDimension);
+    }
+  }
+  /**
+   * Escapes a query string for use with SQLite FTS5 MATCH operator.
+   * Wraps the query in double quotes and escapes internal double quotes.
+   */
+  escapeFtsQuery(query) {
+    const escapedQuotes = query.replace(/"/g, '""');
+    return `"${escapedQuotes}"`;
+  }
+  /**
+   * Initializes database connection and ensures readiness
+   */
+  async initialize() {
+    try {
+      sqliteVec.load(this.db);
+      applyMigrations(this.db);
+      this.prepareStatements();
+      await this.initializeEmbeddings();
+    } catch (error) {
+      if (error instanceof StoreError) {
+        throw error;
+      }
+      throw new ConnectionError("Failed to initialize database connection", error);
+    }
+  }
+  /**
+   * Gracefully closes database connections
+   */
+  async shutdown() {
+    this.db.close();
+  }
+  /**
+   * Resolves a library name and version string to library_id and version_id.
+   * Creates library and version records if they don't exist.
+   */
+  async resolveLibraryAndVersionIds(library, version) {
+    const normalizedLibrary = library.toLowerCase();
+    const normalizedVersion = denormalizeVersionName(version.toLowerCase());
+    this.statements.insertLibrary.run(normalizedLibrary);
+    const libraryIdRow = this.statements.getLibraryIdByName.get(normalizedLibrary);
+    if (!libraryIdRow || typeof libraryIdRow.id !== "number") {
+      throw new StoreError(`Failed to resolve library_id for library: ${library}`);
+    }
+    const libraryId = libraryIdRow.id;
+    this.statements.insertVersion.run(libraryId, normalizedVersion);
+    const versionIdRow = this.statements.resolveVersionId.get(
+      libraryId,
+      normalizedVersion === null ? "" : normalizedVersion
+    );
+    if (!versionIdRow || typeof versionIdRow.id !== "number") {
+      throw new StoreError(
+        `Failed to resolve version_id for library: ${library}, version: ${version}`
+      );
+    }
+    return { libraryId, versionId: versionIdRow.id };
+  }
+  /**
+   * Retrieves all unique versions for a specific library
+   */
+  async queryUniqueVersions(library) {
+    try {
+      const rows = this.statements.queryVersions.all(library.toLowerCase());
+      return rows.map((row) => normalizeVersionName(row.name));
+    } catch (error) {
+      throw new ConnectionError("Failed to query versions", error);
+    }
+  }
+  /**
+   * Updates the status of a version record in the database.
+   * @param versionId The version ID to update
+   * @param status The new status to set
+   * @param errorMessage Optional error message for failed statuses
+   */
+  async updateVersionStatus(versionId, status, errorMessage) {
+    try {
+      this.statements.updateVersionStatus.run(status, errorMessage ?? null, versionId);
+    } catch (error) {
+      throw new StoreError(`Failed to update version status: ${error}`);
+    }
+  }
+  /**
+   * Updates the progress counters for a version being indexed.
+   * @param versionId The version ID to update
+   * @param pages Current number of pages processed
+   * @param maxPages Total number of pages to process
+   */
+  async updateVersionProgress(versionId, pages, maxPages) {
+    try {
+      this.statements.updateVersionProgress.run(pages, maxPages, versionId);
+    } catch (error) {
+      throw new StoreError(`Failed to update version progress: ${error}`);
+    }
+  }
+  /**
+   * Retrieves versions by their status.
+   * @param statuses Array of statuses to filter by
+   * @returns Array of version records matching the statuses
+   */
+  async getVersionsByStatus(statuses) {
+    try {
+      const statusJson = JSON.stringify(statuses);
+      const rows = this.statements.getVersionsByStatus.all(
+        statusJson
+      );
+      return rows;
+    } catch (error) {
+      throw new StoreError(`Failed to get versions by status: ${error}`);
+    }
+  }
+  /**
+   * Stores scraper options for a version to enable reproducible indexing.
+   * @param versionId The version ID to update
+   * @param options Complete scraper options used for indexing
+   */
+  async storeScraperOptions(versionId, options) {
+    try {
+      const { url: source_url, library, version, signal, ...scraper_options } = options;
+      const optionsJson = JSON.stringify(scraper_options);
+      this.statements.updateVersionScraperOptions.run(source_url, optionsJson, versionId);
+    } catch (error) {
+      throw new StoreError(`Failed to store scraper options: ${error}`);
+    }
+  }
+  /**
+   * Retrieves stored scraping configuration (source URL and options) for a version.
+   * Returns null when no source URL is recorded (not re-indexable).
+   */
+  async getScraperOptions(versionId) {
+    try {
+      const row = this.statements.getVersionWithOptions.get(versionId);
+      if (!row?.source_url) {
+        return null;
+      }
+      let parsed = {};
+      if (row.scraper_options) {
+        try {
+          parsed = JSON.parse(row.scraper_options);
+        } catch (e) {
+          logger.warn(`⚠️ Invalid scraper_options JSON for version ${versionId}: ${e}`);
+          parsed = {};
+        }
+      }
+      return { sourceUrl: row.source_url, options: parsed };
+    } catch (error) {
+      throw new StoreError(`Failed to get scraper options: ${error}`);
+    }
+  }
+  /**
+   * Finds versions that were indexed from the same source URL.
+   * Useful for finding similar configurations or detecting duplicates.
+   * @param url Source URL to search for
+   * @returns Array of versions with the same source URL
+   */
+  async findVersionsBySourceUrl(url) {
+    try {
+      const rows = this.statements.getVersionsBySourceUrl.all(
+        url
+      );
+      return rows;
+    } catch (error) {
+      throw new StoreError(`Failed to find versions by source URL: ${error}`);
+    }
+  }
+  /**
+   * Verifies existence of documents for a specific library version
+   */
+  async checkDocumentExists(library, version) {
+    try {
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.checkExists.get(
+        library.toLowerCase(),
+        normalizedVersion
+      );
+      return result !== void 0;
+    } catch (error) {
+      throw new ConnectionError("Failed to check document existence", error);
+    }
+  }
+  /**
+   * Retrieves a mapping of all libraries to their available versions with details.
+   */
+  async queryLibraryVersions() {
+    try {
+      const rows = this.statements.queryLibraryVersions.all();
+      const libraryMap = /* @__PURE__ */ new Map();
+      for (const row of rows) {
+        const library = row.library;
+        if (!libraryMap.has(library)) {
+          libraryMap.set(library, []);
+        }
+        const indexedAtISO = row.indexedAt ? new Date(row.indexedAt).toISOString() : null;
+        libraryMap.get(library)?.push({
+          version: row.version,
+          versionId: row.versionId,
+          // Preserve raw string status here; DocumentManagementService will cast to VersionStatus
+          status: row.status,
+          progressPages: row.progressPages,
+          progressMaxPages: row.progressMaxPages,
+          sourceUrl: row.sourceUrl,
+          documentCount: row.documentCount,
+          uniqueUrlCount: row.uniqueUrlCount,
+          indexedAt: indexedAtISO
+        });
+      }
+      for (const versions of libraryMap.values()) {
+        versions.sort((a, b) => {
+          if (a.version === "" && b.version !== "") {
+            return -1;
+          }
+          if (a.version !== "" && b.version === "") {
+            return 1;
+          }
+          if (a.version === "" && b.version === "") {
+            return 0;
+          }
+          try {
+            return semver__default.compare(a.version, b.version);
+          } catch (_error) {
+            return a.version.localeCompare(b.version);
+          }
+        });
+      }
+      return libraryMap;
+    } catch (error) {
+      throw new ConnectionError("Failed to query library versions", error);
+    }
+  }
+  /**
+   * Stores documents with library and version metadata, generating embeddings
+   * for vector similarity search. Automatically removes any existing documents
+   * for the same URLs before adding new ones to prevent UNIQUE constraint violations.
+   */
+  async addDocuments(library, version, documents) {
+    try {
+      if (documents.length === 0) {
+        return;
+      }
+      const urls = /* @__PURE__ */ new Set();
+      for (const doc of documents) {
+        const url = doc.metadata.url;
+        if (!url || typeof url !== "string" || !url.trim()) {
+          throw new StoreError("Document metadata must include a valid URL");
+        }
+        urls.add(url);
+      }
+      const texts = documents.map((doc) => {
+        const header = `<title>${doc.metadata.title}</title>
+<url>${doc.metadata.url}</url>
+<path>${doc.metadata.path.join(" / ")}</path>
+`;
+        return `${header}${doc.pageContent}`;
+      });
+      const maxBatchChars = Number(process.env.DOCS_MCP_EMBEDDING_BATCH_CHARS) || EMBEDDING_BATCH_CHARS;
+      const rawEmbeddings = [];
+      let currentBatch = [];
+      let currentBatchSize = 0;
+      let batchCount = 0;
+      for (const text of texts) {
+        const textSize = text.length;
+        if (currentBatchSize + textSize > maxBatchChars && currentBatch.length > 0) {
+          batchCount++;
+          logger.debug(
+            `🔄 Processing embedding batch ${batchCount}: ${currentBatch.length} texts, ${currentBatchSize} chars`
+          );
+          const batchEmbeddings = await this.embeddings.embedDocuments(currentBatch);
+          rawEmbeddings.push(...batchEmbeddings);
+          currentBatch = [];
+          currentBatchSize = 0;
+        }
+        currentBatch.push(text);
+        currentBatchSize += textSize;
+        if (currentBatch.length >= EMBEDDING_BATCH_SIZE) {
+          batchCount++;
+          logger.debug(
+            `🔄 Processing embedding batch ${batchCount}: ${currentBatch.length} texts, ${currentBatchSize} chars`
+          );
+          const batchEmbeddings = await this.embeddings.embedDocuments(currentBatch);
+          rawEmbeddings.push(...batchEmbeddings);
+          currentBatch = [];
+          currentBatchSize = 0;
+        }
+      }
+      if (currentBatch.length > 0) {
+        batchCount++;
+        logger.debug(
+          `🔄 Processing final embedding batch ${batchCount}: ${currentBatch.length} texts, ${currentBatchSize} chars`
+        );
+        const batchEmbeddings = await this.embeddings.embedDocuments(currentBatch);
+        rawEmbeddings.push(...batchEmbeddings);
+      }
+      const paddedEmbeddings = rawEmbeddings.map((vector) => this.padVector(vector));
+      const { libraryId, versionId } = await this.resolveLibraryAndVersionIds(
+        library,
+        version
+      );
+      for (const url of urls) {
+        const deletedCount = await this.deleteDocumentsByUrl(library, version, url);
+        if (deletedCount > 0) {
+          logger.debug(`🗑️ Deleted ${deletedCount} existing documents for URL: ${url}`);
+        }
+      }
+      const transaction = this.db.transaction((docs) => {
+        for (let i = 0; i < docs.length; i++) {
+          const doc = docs[i];
+          const url = doc.metadata.url;
+          const result = this.statements.insertDocument.run(
+            BigInt(libraryId),
+            BigInt(versionId),
+            url,
+            doc.pageContent,
+            JSON.stringify(doc.metadata),
+            i,
+            (/* @__PURE__ */ new Date()).toISOString()
+            // Pass current timestamp for indexed_at
+          );
+          const rowId = result.lastInsertRowid;
+          this.statements.insertEmbedding.run(
+            BigInt(rowId),
+            BigInt(libraryId),
+            BigInt(versionId),
+            JSON.stringify(paddedEmbeddings[i])
+          );
+        }
+      });
+      transaction(documents);
+    } catch (error) {
+      throw new ConnectionError("Failed to add documents to store", error);
+    }
+  }
+  /**
+   * Removes documents matching specified library and version
+   * @returns Number of documents deleted
+   */
+  async deleteDocuments(library, version) {
+    try {
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.deleteDocuments.run(
+        library.toLowerCase(),
+        library.toLowerCase(),
+        // library name appears twice in the query
+        normalizedVersion
+      );
+      return result.changes;
+    } catch (error) {
+      throw new ConnectionError("Failed to delete documents", error);
+    }
+  }
+  /**
+   * Removes documents for a specific URL within a library and version
+   * @returns Number of documents deleted
+   */
+  async deleteDocumentsByUrl(library, version, url) {
+    try {
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.deleteDocumentsByUrl.run(
+        url,
+        library.toLowerCase(),
+        library.toLowerCase(),
+        // library name appears twice in the query
+        normalizedVersion
+      );
+      return result.changes;
+    } catch (error) {
+      throw new ConnectionError("Failed to delete documents by URL", error);
+    }
+  }
+  /**
+   * Retrieves a document by its ID.
+   * @param id The ID of the document.
+   * @returns The document, or null if not found.
+   */
+  async getById(id) {
+    try {
+      const row = this.statements.getById.get(BigInt(id));
+      if (!row) {
+        return null;
+      }
+      return mapDbDocumentToDocument(row);
+    } catch (error) {
+      throw new ConnectionError(`Failed to get document by ID ${id}`, error);
+    }
+  }
+  /**
+   * Finds documents matching a text query using hybrid search.
+   * Combines vector similarity search with full-text search using Reciprocal Rank Fusion.
+   */
+  async findByContent(library, version, query, limit) {
+    try {
+      const rawEmbedding = await this.embeddings.embedQuery(query);
+      const embedding = this.padVector(rawEmbedding);
+      const ftsQuery = this.escapeFtsQuery(query);
+      const normalizedVersion = version.toLowerCase();
+      const stmt = this.db.prepare(`
+        WITH vec_distances AS (
+          SELECT
+            dv.rowid as id,
+            dv.distance as vec_distance
+          FROM documents_vec dv
+          JOIN versions v ON dv.version_id = v.id
+          JOIN libraries l ON v.library_id = l.id
+          WHERE l.name = ?
+            AND COALESCE(v.name, '') = COALESCE(?, '')
+            AND dv.embedding MATCH ?
+            AND dv.k = ?
+          ORDER BY dv.distance
+        ),
+        fts_scores AS (
+          SELECT
+            f.rowid as id,
+            bm25(documents_fts, 10.0, 1.0, 5.0, 1.0) as fts_score
+          FROM documents_fts f
+          JOIN documents d ON f.rowid = d.id
+          JOIN versions v ON d.version_id = v.id
+          JOIN libraries l ON v.library_id = l.id
+          WHERE l.name = ?
+            AND COALESCE(v.name, '') = COALESCE(?, '')
+            AND documents_fts MATCH ?
+          ORDER BY fts_score
+          LIMIT ?
+        )
+        SELECT
+          d.id,
+          d.content,
+          d.metadata,
+          COALESCE(1 / (1 + v.vec_distance), 0) as vec_score,
+          COALESCE(-MIN(f.fts_score, 0), 0) as fts_score
+        FROM documents d
+        LEFT JOIN vec_distances v ON d.id = v.id
+        LEFT JOIN fts_scores f ON d.id = f.id
+        WHERE v.id IS NOT NULL OR f.id IS NOT NULL
+      `);
+      const rawResults = stmt.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        JSON.stringify(embedding),
+        limit,
+        library.toLowerCase(),
+        normalizedVersion,
+        ftsQuery,
+        // Use the escaped query
+        limit
+      );
+      const rankedResults = this.assignRanks(rawResults);
+      const topResults = rankedResults.sort((a, b) => b.rrf_score - a.rrf_score).slice(0, limit);
+      return topResults.map((row) => ({
+        ...mapDbDocumentToDocument(row),
+        metadata: {
+          ...JSON.parse(row.metadata),
+          id: row.id,
+          score: row.rrf_score,
+          vec_rank: row.vec_rank,
+          fts_rank: row.fts_rank
+        }
+      }));
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to find documents by content with query "${query}"`,
+        error
+      );
+    }
+  }
+  /**
+   * Finds child chunks of a given document based on path hierarchy.
+   */
+  async findChildChunks(library, version, id, limit) {
+    try {
+      const parent = await this.getById(id);
+      if (!parent) {
+        return [];
+      }
+      const parentPath = parent.metadata.path ?? [];
+      const parentUrl = parent.metadata.url;
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.getChildChunks.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        parentUrl,
+        parentPath.length + 1,
+        JSON.stringify(parentPath),
+        BigInt(id),
+        limit
+      );
+      return result.map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError(`Failed to find child chunks for ID ${id}`, error);
+    }
+  }
+  /**
+   * Finds preceding sibling chunks of a given document.
+   */
+  async findPrecedingSiblingChunks(library, version, id, limit) {
+    try {
+      const reference = await this.getById(id);
+      if (!reference) {
+        return [];
+      }
+      const refMetadata = reference.metadata;
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.getPrecedingSiblings.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        refMetadata.url,
+        BigInt(id),
+        JSON.stringify(refMetadata.path),
+        limit
+      );
+      return result.reverse().map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to find preceding sibling chunks for ID ${id}`,
+        error
+      );
+    }
+  }
+  /**
+   * Finds subsequent sibling chunks of a given document.
+   */
+  async findSubsequentSiblingChunks(library, version, id, limit) {
+    try {
+      const reference = await this.getById(id);
+      if (!reference) {
+        return [];
+      }
+      const refMetadata = reference.metadata;
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.getSubsequentSiblings.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        refMetadata.url,
+        BigInt(id),
+        JSON.stringify(refMetadata.path),
+        limit
+      );
+      return result.map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to find subsequent sibling chunks for ID ${id}`,
+        error
+      );
+    }
+  }
+  /**
+   * Finds the parent chunk of a given document.
+   */
+  async findParentChunk(library, version, id) {
+    try {
+      const child = await this.getById(id);
+      if (!child) {
+        return null;
+      }
+      const childMetadata = child.metadata;
+      const path2 = childMetadata.path ?? [];
+      const parentPath = path2.slice(0, -1);
+      if (parentPath.length === 0) {
+        return null;
+      }
+      const normalizedVersion = version.toLowerCase();
+      const result = this.statements.getParentChunk.get(
+        library.toLowerCase(),
+        normalizedVersion,
+        childMetadata.url,
+        JSON.stringify(parentPath),
+        BigInt(id)
+      );
+      if (!result) {
+        return null;
+      }
+      return mapDbDocumentToDocument(result);
+    } catch (error) {
+      throw new ConnectionError(`Failed to find parent chunk for ID ${id}`, error);
+    }
+  }
+  /**
+   * Fetches multiple documents by their IDs in a single call.
+   * Returns an array of Document objects, sorted by their sort_order.
+   */
+  async findChunksByIds(library, version, ids) {
+    if (!ids.length) return [];
+    try {
+      const normalizedVersion = version.toLowerCase();
+      const placeholders = ids.map(() => "?").join(",");
+      const stmt = this.db.prepare(
+        `SELECT d.* FROM documents d
+         JOIN libraries l ON d.library_id = l.id
+         JOIN versions v ON d.version_id = v.id
+         WHERE l.name = ? 
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+           AND d.id IN (${placeholders}) 
+         ORDER BY d.sort_order`
+      );
+      const rows = stmt.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        ...ids
+      );
+      return rows.map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError("Failed to fetch documents by IDs", error);
+    }
+  }
+}
+class DocumentManagementService {
+  store;
+  documentRetriever;
+  splitter;
+  /**
+   * Normalizes a version string, converting null or undefined to an empty string
+   * and converting to lowercase.
+   */
+  normalizeVersion(version) {
+    return (version ?? "").toLowerCase();
+  }
+  constructor() {
+    let dbPath;
+    let dbDir;
+    const envStorePath = process.env.DOCS_MCP_STORE_PATH;
+    if (envStorePath) {
+      dbDir = envStorePath;
+      dbPath = path.join(dbDir, "documents.db");
+      logger.debug(`💾 Using database directory from DOCS_MCP_STORE_PATH: ${dbDir}`);
+    } else {
+      const projectRoot = getProjectRoot();
+      const oldDbDir = path.join(projectRoot, ".store");
+      const oldDbPath = path.join(oldDbDir, "documents.db");
+      const oldDbExists = fs.existsSync(oldDbPath);
+      if (oldDbExists) {
+        dbPath = oldDbPath;
+        dbDir = oldDbDir;
+        logger.debug(`💾 Using legacy database path: ${dbPath}`);
+      } else {
+        const standardPaths = envPaths("docs-mcp-server", { suffix: "" });
+        dbDir = standardPaths.data;
+        dbPath = path.join(dbDir, "documents.db");
+        logger.debug(`💾 Using standard database directory: ${dbDir}`);
+      }
+    }
+    try {
+      fs.mkdirSync(dbDir, { recursive: true });
+    } catch (error) {
+      logger.error(`⚠️  Failed to create database directory ${dbDir}: ${error}`);
+    }
+    this.store = new DocumentStore(dbPath);
+    this.documentRetriever = new DocumentRetrieverService(this.store);
+    const semanticSplitter = new SemanticMarkdownSplitter(
+      SPLITTER_PREFERRED_CHUNK_SIZE,
+      SPLITTER_MAX_CHUNK_SIZE
+    );
+    const greedySplitter = new GreedySplitter(
+      semanticSplitter,
+      SPLITTER_MIN_CHUNK_SIZE,
+      SPLITTER_PREFERRED_CHUNK_SIZE
+    );
+    this.splitter = greedySplitter;
+  }
+  /**
+   * Initializes the underlying document store.
+   */
+  async initialize() {
+    await this.store.initialize();
+  }
+  /**
+   * Shuts down the underlying document store.
+   */
+  async shutdown() {
+    logger.debug("Shutting down store manager");
+    await this.store.shutdown();
+  }
+  // Status tracking methods for pipeline integration
+  /**
+   * Gets versions by their current status.
+   */
+  async getVersionsByStatus(statuses) {
+    return this.store.getVersionsByStatus(statuses);
+  }
+  /**
+   * Updates the status of a version.
+   */
+  async updateVersionStatus(versionId, status, errorMessage) {
+    return this.store.updateVersionStatus(versionId, status, errorMessage);
+  }
+  /**
+   * Updates the progress of a version being indexed.
+   */
+  async updateVersionProgress(versionId, pages, maxPages) {
+    return this.store.updateVersionProgress(versionId, pages, maxPages);
+  }
+  /**
+   * Stores scraper options for a version to enable reproducible indexing.
+   */
+  async storeScraperOptions(versionId, options) {
+    return this.store.storeScraperOptions(versionId, options);
+  }
+  /**
+   * Retrieves stored scraper options for a version.
+   */
+  /**
+   * Retrieves stored scraping configuration for a version.
+   */
+  async getScraperOptions(versionId) {
+    return this.store.getScraperOptions(versionId);
+  }
+  /**
+   * Ensures a library/version exists using a VersionRef and returns version ID.
+   * Delegates to existing ensureLibraryAndVersion for storage.
+   */
+  async ensureVersion(ref) {
+    const normalized = {
+      library: ref.library.trim().toLowerCase(),
+      version: (ref.version ?? "").trim().toLowerCase()
+    };
+    return this.ensureLibraryAndVersion(normalized.library, normalized.version);
+  }
+  /**
+   * Returns enriched library summaries including version status/progress and counts.
+   * Uses existing store APIs; keeps DB details encapsulated.
+   */
+  async listLibraries() {
+    const libMap = await this.store.queryLibraryVersions();
+    const summaries = [];
+    for (const [library, versions] of libMap) {
+      const vs = versions.map(
+        (v) => ({
+          id: v.versionId,
+          ref: { library, version: v.version },
+          status: v.status,
+          // Include progress only while indexing is active; set undefined for COMPLETED
+          progress: v.status === "completed" ? void 0 : { pages: v.progressPages, maxPages: v.progressMaxPages },
+          counts: { documents: v.documentCount, uniqueUrls: v.uniqueUrlCount },
+          indexedAt: v.indexedAt,
+          sourceUrl: v.sourceUrl ?? void 0
+        })
+      );
+      summaries.push({ library, versions: vs });
+    }
+    return summaries;
+  }
+  /**
+   * Finds versions that were indexed from the same source URL.
+   */
+  async findVersionsBySourceUrl(url) {
+    return this.store.findVersionsBySourceUrl(url);
+  }
+  /**
+   * Validates if a library exists in the store (either versioned or unversioned).
+   * Throws LibraryNotFoundError with suggestions if the library is not found.
+   * @param library The name of the library to validate.
+   * @throws {LibraryNotFoundError} If the library does not exist.
+   */
+  async validateLibraryExists(library) {
+    logger.info(`🔎 Validating existence of library: ${library}`);
+    const normalizedLibrary = library.toLowerCase();
+    const versions = await this.listVersions(normalizedLibrary);
+    const hasUnversioned = await this.exists(normalizedLibrary, "");
+    if (versions.length === 0 && !hasUnversioned) {
+      logger.warn(`⚠️  Library '${library}' not found.`);
+      const allLibraries = await this.listLibraries();
+      const libraryNames = allLibraries.map((lib) => lib.library);
+      let suggestions = [];
+      if (libraryNames.length > 0) {
+        const fuse = new Fuse(libraryNames, {
+          // Configure fuse.js options if needed (e.g., threshold)
+          // isCaseSensitive: false, // Handled by normalizing library names
+          // includeScore: true,
+          threshold: 0.4
+          // Adjust threshold for desired fuzziness (0=exact, 1=match anything)
+        });
+        const results = fuse.search(normalizedLibrary);
+        suggestions = results.slice(0, 3).map((result) => result.item);
+        logger.info(`🔍 Found suggestions: ${suggestions.join(", ")}`);
+      }
+      throw new LibraryNotFoundError(library, suggestions);
+    }
+    logger.info(`✅ Library '${library}' confirmed to exist.`);
+  }
+  /**
+   * Returns a list of all available semantic versions for a library.
+   */
+  async listVersions(library) {
+    const versions = await this.store.queryUniqueVersions(library);
+    return versions.filter((v) => semver__default.valid(v));
+  }
+  /**
+   * Checks if documents exist for a given library and optional version.
+   * If version is omitted, checks for documents without a specific version.
+   */
+  async exists(library, version) {
+    const normalizedVersion = this.normalizeVersion(version);
+    return this.store.checkDocumentExists(library, normalizedVersion);
+  }
+  /**
+   * Finds the most appropriate version of documentation based on the requested version.
+   * When no target version is specified, returns the latest version.
+   *
+   * Version matching behavior:
+   * - Exact versions (e.g., "18.0.0"): Matches that version or any earlier version
+   * - X-Range patterns (e.g., "5.x", "5.2.x"): Matches within the specified range
+   * - "latest" or no version: Returns the latest available version
+   *
+   * For documentation, we prefer matching older versions over no match at all,
+   * since older docs are often still relevant and useful.
+   * Also checks if unversioned documents exist for the library.
+   */
+  async findBestVersion(library, targetVersion) {
+    const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
+    logger.info(`🔍 Finding best version for ${libraryAndVersion}`);
+    const hasUnversioned = await this.store.checkDocumentExists(library, "");
+    const versionStrings = await this.listVersions(library);
+    if (versionStrings.length === 0) {
+      if (hasUnversioned) {
+        logger.info(`ℹ️ Unversioned documents exist for ${library}`);
+        return { bestMatch: null, hasUnversioned: true };
+      }
+      logger.warn(`⚠️  No valid versions found for ${library}`);
+      const allLibraryDetails = await this.store.queryLibraryVersions();
+      const libraryDetails = allLibraryDetails.get(library) ?? [];
+      throw new VersionNotFoundError(library, targetVersion ?? "", libraryDetails);
+    }
+    let bestMatch = null;
+    if (!targetVersion || targetVersion === "latest") {
+      bestMatch = semver__default.maxSatisfying(versionStrings, "*");
+    } else {
+      const versionRegex = /^(\d+)(?:\.(?:x(?:\.x)?|\d+(?:\.(?:x|\d+))?))?$|^$/;
+      if (!versionRegex.test(targetVersion)) {
+        logger.warn(`⚠️  Invalid target version format: ${targetVersion}`);
+      } else {
+        let range = targetVersion;
+        if (!semver__default.validRange(targetVersion)) {
+          range = `~${targetVersion}`;
+        } else if (semver__default.valid(targetVersion)) {
+          range = `${range} || <=${targetVersion}`;
+        }
+        bestMatch = semver__default.maxSatisfying(versionStrings, range);
+      }
+    }
+    if (bestMatch) {
+      logger.info(`✅ Found best match version ${bestMatch} for ${libraryAndVersion}`);
+    } else {
+      logger.warn(`⚠️  No matching semver version found for ${libraryAndVersion}`);
+    }
+    if (!bestMatch && !hasUnversioned) {
+      const allLibraryDetails = await this.store.queryLibraryVersions();
+      const libraryDetails = allLibraryDetails.get(library) ?? [];
+      throw new VersionNotFoundError(library, targetVersion ?? "", libraryDetails);
+    }
+    return { bestMatch, hasUnversioned };
+  }
+  /**
+   * Removes all documents for a specific library and optional version.
+   * If version is omitted, removes documents without a specific version.
+   */
+  async removeAllDocuments(library, version) {
+    const normalizedVersion = this.normalizeVersion(version);
+    logger.info(
+      `🗑️ Removing all documents from ${library}@${normalizedVersion || "[no version]"} store`
+    );
+    const count = await this.store.deleteDocuments(library, normalizedVersion);
+    logger.info(`📊 Deleted ${count} documents`);
+  }
+  /**
+   * Adds a document to the store, splitting it into smaller chunks for better search results.
+   * Uses SemanticMarkdownSplitter to maintain markdown structure and content types during splitting.
+   * Preserves hierarchical structure of documents and distinguishes between text and code segments.
+   * If version is omitted, the document is added without a specific version.
+   */
+  async addDocument(library, version, document) {
+    const normalizedVersion = this.normalizeVersion(version);
+    const url = document.metadata.url;
+    if (!url || typeof url !== "string" || !url.trim()) {
+      throw new StoreError("Document metadata must include a valid URL");
+    }
+    logger.info(`📚 Adding document: ${document.metadata.title}`);
+    if (!document.pageContent.trim()) {
+      throw new Error("Document content cannot be empty");
+    }
+    const chunks = await this.splitter.splitText(document.pageContent);
+    const splitDocs = chunks.map((chunk) => ({
+      pageContent: chunk.content,
+      metadata: {
+        ...document.metadata,
+        level: chunk.section.level,
+        path: chunk.section.path
+      }
+    }));
+    logger.info(`✂️  Split document into ${splitDocs.length} chunks`);
+    await this.store.addDocuments(library, normalizedVersion, splitDocs);
+  }
+  /**
+   * Searches for documentation content across versions.
+   * Uses hybrid search (vector + FTS).
+   * If version is omitted, searches documents without a specific version.
+   */
+  async searchStore(library, version, query, limit = 5) {
+    const normalizedVersion = this.normalizeVersion(version);
+    return this.documentRetriever.search(library, normalizedVersion, query, limit);
+  }
+  // Deprecated simple listing removed: enriched listLibraries() is canonical
+  /**
+   * Ensures a library and version exist in the database and returns the version ID.
+   * Creates the library and version records if they don't exist.
+   */
+  async ensureLibraryAndVersion(library, version) {
+    const normalizedLibrary = library.toLowerCase();
+    const normalizedVersion = this.normalizeVersion(version);
+    const { versionId } = await this.store.resolveLibraryAndVersionIds(
+      normalizedLibrary,
+      normalizedVersion
+    );
+    return versionId;
+  }
+}
+export {
+  DocumentManagementService
+};
+//# sourceMappingURL=DocumentManagementService-BH02TJEe.js.map