contextqmd 0.1.0

package/dist/lib/service.js

@@ -0,0 +1,776 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { normalizeDocPath } from "./local-cache.js";
+const DOC_INDEX_SCHEMA_VERSION = 2;
+const DEFAULT_EXCERPT_MAX_LINES = 60;
+const DEFAULT_EXPAND_BEFORE = 30;
+const DEFAULT_EXPAND_AFTER = 60;
+function textResult(text) {
+    return { text };
+}
+function structuredTextResult(text, structuredContent) {
+    return { text, structuredContent };
+}
+function errorResult(text, code, details = {}) {
+    return {
+        text,
+        isError: true,
+        structuredContent: {
+            error: {
+                code,
+                ...details,
+            },
+        },
+    };
+}
+function parseLibrary(library) {
+    const [namespace, name] = library.split("/");
+    return namespace && name ? { namespace, name } : null;
+}
+function librarySlug(namespace, name) {
+    return `${namespace}/${name}`;
+}
+function normalizeSha256(value) {
+    if (!value)
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return normalized.startsWith("sha256:") ? normalized.slice("sha256:".length) : normalized;
+}
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function reportProgress(deps, message) {
+    deps.reportProgress?.(message);
+}
+function shouldReportPageProgress(completed, total) {
+    return total <= 10 || completed === 1 || completed === total || completed % 10 === 0;
+}
+function installedVersions(cache, namespace, name) {
+    return cache
+        .listInstalled()
+        .filter(lib => lib.namespace === namespace && lib.name === name)
+        .map(lib => lib.version)
+        .sort();
+}
+function isSupportedBundle(bundle) {
+    const format = bundle.format.trim().toLowerCase();
+    return (format === "tar.gz" ||
+        format === "tgz" ||
+        format === "tar+gzip" ||
+        format === "application/gzip" ||
+        format === "application/x-gzip" ||
+        bundle.url.endsWith(".tar.gz") ||
+        bundle.url.endsWith(".tgz"));
+}
+function selectBundle(manifest) {
+    for (const profile of ["full", "slim"]) {
+        const bundle = manifest.profiles[profile]?.bundle;
+        if (bundle && isSupportedBundle(bundle)) {
+            return { profile, bundle };
+        }
+    }
+    return null;
+}
+function bundleArchiveFilename(namespace, name, version, profile, bundle) {
+    const suffix = bundle.url.endsWith(".tgz") ? ".tgz" : ".tar.gz";
+    return `${namespace}-${name}-${version}-${profile}${suffix}`;
+}
+function listBundleEntries(archivePath) {
+    const result = spawnSync("tar", ["-tvzf", archivePath], { encoding: "utf8" });
+    if (result.error) {
+        throw new Error(`Failed to inspect bundle archive: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`Failed to inspect bundle archive: ${result.stderr.trim() || "tar exited non-zero"}`);
+    }
+    return result.stdout
+        .split("\n")
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => {
+        const kind = line[0] ?? "";
+        const parts = line.split(/\s+/);
+        const path = parts.slice(8).join(" ").replace(/^\.\//, "");
+        return { kind, path };
+    })
+        .filter(entry => entry.path.length > 0);
+}
+function ensureSafeBundleEntries(entries) {
+    for (const entry of entries) {
+        const normalized = posix.normalize(entry.path);
+        if (normalized === ".." ||
+            normalized.startsWith("../") ||
+            normalized.includes("/../") ||
+            normalized.startsWith("/")) {
+            throw new Error(`Unsafe bundle entry: ${entry.path}`);
+        }
+        if (entry.kind !== "-" && entry.kind !== "d") {
+            throw new Error(`Unsupported bundle entry type for ${entry.path}`);
+        }
+    }
+}
+function extractBundleArchive(archivePath, destinationDir) {
+    const entries = listBundleEntries(archivePath);
+    ensureSafeBundleEntries(entries);
+    const result = spawnSync("tar", ["-xzf", archivePath, "-C", destinationDir], { encoding: "utf8" });
+    if (result.error) {
+        throw new Error(`Failed to extract bundle archive: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`Failed to extract bundle archive: ${result.stderr.trim() || "tar exited non-zero"}`);
+    }
+}
+function resolveExtractedDocsDir(extractionRoot) {
+    if (existsSync(join(extractionRoot, "manifest.json"))) {
+        return extractionRoot;
+    }
+    const dirs = readdirSync(extractionRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .map(entry => join(extractionRoot, entry.name));
+    if (dirs.length === 1 && existsSync(join(dirs[0], "manifest.json"))) {
+        return dirs[0];
+    }
+    throw new Error("Bundle archive did not extract to the expected docs layout");
+}
+function bundlePageEntry(pageUid) {
+    const normalized = pageUid.trim();
+    if (normalized.length === 0 ||
+        normalized.startsWith("/") ||
+        normalized.includes("\\") ||
+        normalized.split("/").includes("..")) {
+        throw new Error(`Unsafe bundle page_uid: ${pageUid}`);
+    }
+    return `${normalized}.md`;
+}
+function expectedBundlePageEntry(page) {
+    const bundlePath = page.bundle_path?.trim();
+    if (bundlePath) {
+        const normalized = posix.normalize(bundlePath);
+        if (normalized === ".." ||
+            normalized.startsWith("../") ||
+            normalized.includes("/../") ||
+            normalized.startsWith("/") ||
+            !normalized.endsWith(".md")) {
+            throw new Error(`Unsafe bundle page path: ${bundlePath}`);
+        }
+        return normalized;
+    }
+    return bundlePageEntry(page.page_uid);
+}
+function materializeLocalPageLayout(stagedDocsDir, pageIndex) {
+    const pagesDir = join(stagedDocsDir, "pages");
+    for (const page of pageIndex) {
+        const sourcePath = join(pagesDir, expectedBundlePageEntry(page));
+        const targetPath = join(pagesDir, bundlePageEntry(page.page_uid));
+        if (sourcePath === targetPath)
+            continue;
+        mkdirSync(dirname(targetPath), { recursive: true });
+        renameSync(sourcePath, targetPath);
+    }
+}
+function assertSafeExtractedTree(path) {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Bundle archive contains an unsupported symlink: ${path}`);
+    }
+    if (!(stat.isDirectory() || stat.isFile())) {
+        throw new Error(`Bundle archive contains an unsupported entry type: ${path}`);
+    }
+    if (!stat.isDirectory()) {
+        return;
+    }
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        assertSafeExtractedTree(join(path, entry.name));
+    }
+}
+function listMarkdownFiles(path, relativeDir = "") {
+    const files = [];
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        const nextRelative = relativeDir ? join(relativeDir, entry.name) : entry.name;
+        const nextPath = join(path, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listMarkdownFiles(nextPath, nextRelative));
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+            files.push(nextRelative.replace(/\\/g, "/"));
+        }
+    }
+    return files.sort();
+}
+function validateExtractedBundle(stagedDocsDir) {
+    const manifestPath = join(stagedDocsDir, "manifest.json");
+    const pageIndexPath = join(stagedDocsDir, "page-index.json");
+    const pagesDir = join(stagedDocsDir, "pages");
+    assertSafeExtractedTree(stagedDocsDir);
+    if (!existsSync(manifestPath)) {
+        throw new Error("Bundle archive is missing manifest.json");
+    }
+    if (!existsSync(pageIndexPath)) {
+        throw new Error("Bundle archive is missing page-index.json");
+    }
+    if (!existsSync(pagesDir)) {
+        throw new Error("Bundle archive is missing pages/");
+    }
+    const pageIndex = JSON.parse(readFileSync(pageIndexPath, "utf8"));
+    if (!Array.isArray(pageIndex)) {
+        throw new Error("Bundle page-index.json is not an array");
+    }
+    const expectedFiles = pageIndex.map(page => expectedBundlePageEntry(page)).sort();
+    const actualFiles = listMarkdownFiles(pagesDir);
+    const missingFiles = expectedFiles.filter(file => !actualFiles.includes(file));
+    const extraFiles = actualFiles.filter(file => !expectedFiles.includes(file));
+    if (missingFiles.length > 0 || extraFiles.length > 0) {
+        throw new Error(`Bundle archive page set does not match page-index.json (missing: ${missingFiles.join(", ") || "none"}; extra: ${extraFiles.join(", ") || "none"})`);
+    }
+    materializeLocalPageLayout(stagedDocsDir, pageIndex);
+    return { pageCount: actualFiles.length };
+}
+async function ensureCurrentIndexSchema({ cache, indexer }, library, version) {
+    const installed = cache.listInstalled().filter(lib => {
+        const matchesLibrary = !library || `${lib.namespace}/${lib.name}` === library;
+        const matchesVersion = !version || lib.version === version;
+        return matchesLibrary && matchesVersion;
+    });
+    for (const lib of installed) {
+        if ((lib.index_schema_version ?? 0) >= DOC_INDEX_SCHEMA_VERSION)
+            continue;
+        await indexer.removeLibraryVersion(lib.namespace, lib.name, lib.version);
+        await indexer.indexLibraryVersion(lib.namespace, lib.name, lib.version);
+        cache.addInstalled({
+            ...lib,
+            page_count: cache.countPages(lib.namespace, lib.name, lib.version),
+            index_schema_version: DOC_INDEX_SCHEMA_VERSION,
+        });
+    }
+}
+function resolveCachedPage(cache, input) {
+    const parsed = parseLibrary(input.library);
+    if (!parsed)
+        return null;
+    const { namespace, name } = parsed;
+    const hasDocPath = typeof input.doc_path === "string";
+    const hasPageUid = typeof input.page_uid === "string";
+    if ((hasDocPath ? 1 : 0) + (hasPageUid ? 1 : 0) !== 1) {
+        return null;
+    }
+    if (hasDocPath) {
+        const page = cache.findPageByPath(namespace, name, input.version, input.doc_path);
+        if (!page)
+            return null;
+        const content = cache.readPage(namespace, name, input.version, page.page_uid);
+        return {
+            library: input.library,
+            version: input.version,
+            pageUid: page.page_uid,
+            docPath: normalizeDocPath(page.path),
+            title: page.title,
+            url: page.url,
+            content,
+            hydrationState: content === null ? "missing_content" : "ready",
+        };
+    }
+    const pageUid = input.page_uid;
+    const page = cache.findPageByUid(namespace, name, input.version, pageUid);
+    const content = cache.readPage(namespace, name, input.version, pageUid);
+    if (!page && content === null)
+        return null;
+    return {
+        library: input.library,
+        version: input.version,
+        pageUid,
+        docPath: normalizeDocPath(page?.path ?? `${pageUid}.md`),
+        title: page?.title ?? extractTitle(content ?? "", pageUid),
+        url: page?.url,
+        content,
+        hydrationState: content === null ? "missing_content" : "ready",
+    };
+}
+function buildExcerpt(page, { fromLine = 1, maxLines = DEFAULT_EXCERPT_MAX_LINES, lineNumbers = false, }) {
+    const lines = (page.content ?? "").split("\n");
+    const totalLines = lines.length;
+    const clampedStart = totalLines === 0 ? 1 : Math.min(Math.max(Math.trunc(fromLine), 1), totalLines);
+    const safeMaxLines = Math.max(Math.trunc(maxLines), 1);
+    const endExclusive = totalLines === 0 ? 0 : Math.min(clampedStart - 1 + safeMaxLines, totalLines);
+    const excerptLines = totalLines === 0 ? [] : lines.slice(clampedStart - 1, endExclusive);
+    const renderedLines = lineNumbers
+        ? excerptLines.map((line, index) => `${clampedStart + index} | ${line}`)
+        : excerptLines;
+    const lineEnd = excerptLines.length === 0 ? clampedStart - 1 : clampedStart + excerptLines.length - 1;
+    return structuredTextResult(renderedLines.join("\n"), {
+        library: page.library,
+        version: page.version,
+        doc_path: page.docPath,
+        page_uid: page.pageUid,
+        title: page.title,
+        line_start: clampedStart,
+        line_end: lineEnd,
+        truncated: endExclusive < totalLines,
+        ...(page.url ? { url: page.url } : {}),
+    });
+}
+function resolveExcerptWindow(input) {
+    const hasAroundLine = typeof input.around_line === "number";
+    const hasFromLine = typeof input.from_line === "number";
+    const hasWindowBounds = typeof input.before === "number" || typeof input.after === "number";
+    if (hasAroundLine && hasFromLine) {
+        return errorResult("Use either around_line or from_line/max_lines, not both.", "INVALID_RANGE");
+    }
+    if (!hasAroundLine && hasWindowBounds) {
+        return errorResult("before/after can only be used with around_line.", "INVALID_RANGE");
+    }
+    if (hasAroundLine) {
+        const aroundLine = Math.max(Math.trunc(input.around_line ?? 1), 1);
+        const before = Math.max(Math.trunc(input.before ?? DEFAULT_EXPAND_BEFORE), 0);
+        const after = Math.max(Math.trunc(input.after ?? DEFAULT_EXPAND_AFTER), 0);
+        return {
+            fromLine: Math.max(1, aroundLine - before),
+            maxLines: before + after + 1,
+        };
+    }
+    return {
+        fromLine: input.from_line,
+        maxLines: input.max_lines,
+    };
+}
+async function installFromPageApi(deps, namespace, name, version, manifest) {
+    const { cache, registryClient } = deps;
+    cache.saveManifest(namespace, name, version, manifest);
+    reportProgress(deps, `Fetching page index for ${librarySlug(namespace, name)}@${version}...`);
+    const allPages = await registryClient.getAllPageIndex(namespace, name, version);
+    cache.savePageIndex(namespace, name, version, allPages);
+    let downloadedCount = 0;
+    for (const page of allPages) {
+        const nextCount = downloadedCount + 1;
+        if (shouldReportPageProgress(nextCount, allPages.length)) {
+            reportProgress(deps, `Downloading page content ${nextCount}/${allPages.length}...`);
+        }
+        const pageContent = await registryClient.getPageContent(namespace, name, version, page.page_uid);
+        cache.savePage(namespace, name, version, page.page_uid, pageContent.data.content_md);
+        downloadedCount++;
+    }
+    return {
+        installMethod: "page_fallback",
+        profile: "full",
+        pageCount: downloadedCount,
+        totalPages: allPages.length,
+    };
+}
+async function installFromBundle(deps, namespace, name, version, manifest, selectedBundle) {
+    const { cache, registryClient } = deps;
+    const archivePath = cache.createTempArchivePath(namespace, name, version, bundleArchiveFilename(namespace, name, version, selectedBundle.profile, selectedBundle.bundle));
+    const archiveDir = dirname(archivePath);
+    const extractionRoot = join(archiveDir, "extracted");
+    try {
+        const expectedSha = normalizeSha256(selectedBundle.bundle.sha256);
+        reportProgress(deps, `Downloading ${selectedBundle.profile} bundle for ${librarySlug(namespace, name)}@${version}...`);
+        let bundleBytes = await registryClient.downloadBundle(selectedBundle.bundle.url);
+        let actualSha = sha256Hex(bundleBytes);
+        if (expectedSha && actualSha !== expectedSha) {
+            bundleBytes = await registryClient.downloadBundle(selectedBundle.bundle.url);
+            actualSha = sha256Hex(bundleBytes);
+            if (actualSha !== expectedSha) {
+                throw new Error(`Bundle checksum mismatch for ${namespace}/${name}@${version}`);
+            }
+        }
+        writeFileSync(archivePath, bundleBytes);
+        mkdirSync(extractionRoot, { recursive: true });
+        reportProgress(deps, `Extracting bundle for ${librarySlug(namespace, name)}@${version}...`);
+        extractBundleArchive(archivePath, extractionRoot);
+        const stagedDocsDir = resolveExtractedDocsDir(extractionRoot);
+        reportProgress(deps, `Validating bundle contents for ${librarySlug(namespace, name)}@${version}...`);
+        const { pageCount } = validateExtractedBundle(stagedDocsDir);
+        writeFileSync(join(stagedDocsDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+        cache.commitStagedVersion(namespace, name, version, stagedDocsDir);
+        return {
+            installMethod: "bundle",
+            profile: selectedBundle.profile,
+            pageCount,
+            totalPages: pageCount,
+            bundleFormat: selectedBundle.bundle.format,
+        };
+    }
+    finally {
+        cache.cleanupTempPath(archiveDir);
+    }
+}
+async function installResolvedVersion(deps, namespace, name, version, manifest) {
+    const { cache, indexer } = deps;
+    const resolvedManifest = manifest ?? (await deps.registryClient.getManifest(namespace, name, version)).data;
+    const manifestChecksum = resolvedManifest.provenance?.manifest_checksum ?? null;
+    const existingInstall = cache.findInstalled(namespace, name, version);
+    const backupDir = existingInstall ? cache.backupVersion(namespace, name, version) : null;
+    try {
+        let install;
+        let bundleFallbackReason;
+        const selectedBundle = selectBundle(resolvedManifest);
+        if (selectedBundle) {
+            try {
+                install = await installFromBundle(deps, namespace, name, version, resolvedManifest, selectedBundle);
+            }
+            catch (error) {
+                bundleFallbackReason = error.message;
+                reportProgress(deps, `Bundle install failed for ${librarySlug(namespace, name)}@${version}; falling back to page API...`);
+                install = await installFromPageApi(deps, namespace, name, version, resolvedManifest);
+            }
+        }
+        else {
+            install = await installFromPageApi(deps, namespace, name, version, resolvedManifest);
+        }
+        reportProgress(deps, `Indexing ${install.pageCount} pages for local search...`);
+        const indexedCount = await indexer.indexLibraryVersion(namespace, name, version);
+        if (backupDir) {
+            cache.discardBackup(backupDir);
+        }
+        return {
+            ...install,
+            indexedCount,
+            manifestChecksum,
+            ...(bundleFallbackReason ? { bundleFallbackReason } : {}),
+        };
+    }
+    catch (error) {
+        await indexer.removeLibraryVersion(namespace, name, version);
+        if (backupDir) {
+            cache.restoreVersionFromBackup(namespace, name, version, backupDir);
+        }
+        if (existingInstall) {
+            cache.addInstalled({
+                ...existingInstall,
+                page_count: cache.countPages(namespace, name, version),
+                index_schema_version: 0,
+            });
+        }
+        else {
+            cache.removeVersion(namespace, name, version);
+        }
+        throw error;
+    }
+}
+export async function searchLibraries(deps, input) {
+    const limit = Math.min(Math.max(Math.trunc(input.limit ?? 5), 1), 20);
+    const response = await deps.registryClient.searchLibraries(input.query);
+    const matches = response.data.slice(0, limit);
+    if (matches.length === 0) {
+        return structuredTextResult(`No libraries found for "${input.query}".`, {
+            query: input.query,
+            results: [],
+        });
+    }
+    const versionResponses = await Promise.allSettled(matches.map(match => deps.registryClient.getVersions(match.namespace, match.name)));
+    const results = matches.map((match, index) => {
+        const versionResponse = versionResponses[index];
+        const versions = versionResponse?.status === "fulfilled"
+            ? versionResponse.value.data.map(version => version.version)
+            : (match.default_version ? [match.default_version] : []);
+        const localVersions = installedVersions(deps.cache, match.namespace, match.name);
+        return {
+            library: librarySlug(match.namespace, match.name),
+            display_name: match.display_name,
+            namespace: match.namespace,
+            name: match.name,
+            aliases: match.aliases,
+            homepage_url: match.homepage_url,
+            default_version: match.default_version,
+            source_type: match.source_type,
+            license_status: match.license_status,
+            version_count: match.version_count ?? versions.length,
+            versions,
+            installed_versions: localVersions,
+            installed: localVersions.length > 0,
+        };
+    });
+    const lines = results.map(result => {
+        const installed = result.installed_versions.length > 0 ? `installed: ${result.installed_versions.join(", ")}` : "installed: none";
+        const source = result.source_type ? ` | source: ${result.source_type}` : "";
+        return `- ${result.library} (${result.display_name}) | default: ${result.default_version} | versions: ${result.versions.join(", ") || "unknown"}${source} | ${installed}`;
+    });
+    return structuredTextResult(lines.join("\n"), {
+        query: input.query,
+        results,
+    });
+}
+export async function installDocs(deps, input) {
+    reportProgress(deps, `Resolving ${input.library}${input.version ? `@${input.version}` : ""}...`);
+    const resolved = await deps.registryClient.resolve({
+        query: input.library,
+        version_hint: input.version,
+    });
+    const { namespace, name } = resolved.data.library;
+    const canonicalLibrary = librarySlug(namespace, name);
+    const targetVersion = resolved.data.version.version;
+    reportProgress(deps, `Fetching manifest for ${canonicalLibrary}@${targetVersion}...`);
+    const manifest = (await deps.registryClient.getManifest(namespace, name, targetVersion)).data;
+    const targetChecksum = manifest.provenance?.manifest_checksum ?? null;
+    const existing = deps.cache.findInstalled(namespace, name, targetVersion);
+    if (existing && existing.manifest_checksum === targetChecksum) {
+        return structuredTextResult(`${canonicalLibrary}@${targetVersion} is already installed and current (${existing.page_count} pages, ${existing.profile} mode).`, {
+            library: canonicalLibrary,
+            version: targetVersion,
+            changed: false,
+            installed: true,
+            manifest_checksum: targetChecksum,
+        });
+    }
+    const outcome = await installResolvedVersion(deps, namespace, name, targetVersion, manifest);
+    deps.cache.addInstalled({
+        namespace,
+        name,
+        version: targetVersion,
+        profile: outcome.profile,
+        installed_at: new Date().toISOString(),
+        manifest_checksum: outcome.manifestChecksum,
+        page_count: outcome.pageCount,
+        index_schema_version: DOC_INDEX_SCHEMA_VERSION,
+    });
+    const installLine = outcome.installMethod === "bundle"
+        ? `  Installed from bundle (${outcome.profile}, ${outcome.bundleFormat ?? "tar.gz"})`
+        : `  Installed from page API fallback (${outcome.pageCount}/${outcome.totalPages ?? outcome.pageCount} pages)`;
+    const fallbackLine = outcome.bundleFallbackReason ? `\n  Bundle fallback: ${outcome.bundleFallbackReason}` : "";
+    const actionLine = existing ? "Reinstalled" : "Installed";
+    return structuredTextResult(`${actionLine} ${canonicalLibrary}@${targetVersion}\n${installLine}\n  Indexed: ${outcome.indexedCount} pages for search${fallbackLine}`, {
+        library: canonicalLibrary,
+        version: targetVersion,
+        changed: true,
+        reinstall: Boolean(existing),
+        install_method: outcome.installMethod,
+        profile: outcome.profile,
+        page_count: outcome.pageCount,
+        indexed_count: outcome.indexedCount,
+        manifest_checksum: outcome.manifestChecksum,
+        ...(outcome.bundleFormat ? { bundle_format: outcome.bundleFormat } : {}),
+        ...(outcome.bundleFallbackReason ? { bundle_fallback_reason: outcome.bundleFallbackReason } : {}),
+    });
+}
+export function listInstalledDocs(deps) {
+    const installed = deps.cache.listInstalled();
+    if (installed.length === 0) {
+        return structuredTextResult("No documentation packages installed. Use install_docs to add some.", { results: [] });
+    }
+    const results = installed.map(lib => ({
+        library: librarySlug(lib.namespace, lib.name),
+        version: lib.version,
+        profile: lib.profile,
+        page_count: lib.page_count,
+        installed_at: lib.installed_at,
+        manifest_checksum: lib.manifest_checksum,
+    }));
+    const lines = results.map(result => `- ${result.library}@${result.version} (${result.profile}, ${result.page_count} pages)`);
+    return structuredTextResult(`Installed documentation packages:\n\n${lines.join("\n")}`, { results });
+}
+export async function searchDocs(deps, input) {
+    const { cache, indexer } = deps;
+    const installed = cache.listInstalled();
+    if (input.library) {
+        const parsed = parseLibrary(input.library);
+        if (!parsed) {
+            return errorResult("library must be in namespace/name format (for example 'vercel/nextjs').", "INVALID_LIBRARY");
+        }
+        const matchingVersions = installedVersions(cache, parsed.namespace, parsed.name);
+        const requestedInstalled = input.version ? matchingVersions.includes(input.version) : matchingVersions.length > 0;
+        if (!requestedInstalled) {
+            return errorResult(input.version ? `${input.library}@${input.version} is not installed.` : `${input.library} is not installed.`, "NOT_INSTALLED", {
+                library: input.library,
+                ...(input.version ? { version: input.version } : {}),
+                installed_versions: matchingVersions,
+            });
+        }
+    }
+    else if (installed.length === 0) {
+        return structuredTextResult("No documentation packages installed. Use install_docs first.", { results: [] });
+    }
+    await ensureCurrentIndexSchema(deps, input.library, input.version);
+    const results = await indexer.search(input.query, {
+        library: input.library,
+        version: input.version,
+        maxResults: input.max_results ?? 5,
+        mode: input.mode ?? "auto",
+    });
+    if (results.length === 0) {
+        return structuredTextResult(`No results found for "${input.query}"${input.library ? ` in ${input.library}` : ""}.`, { query: input.query, results: [] });
+    }
+    const usedMode = results[0]?.searchMode ?? "fts";
+    const lines = results.map((result, index) => {
+        const location = `${result.docPath}${result.lineStart ? ` | lines ${result.lineStart}-${result.lineEnd}` : ""}`;
+        const snippet = result.snippet || result.contentMd.slice(0, 500);
+        return `## [${index + 1}] ${result.title} (${result.library}@${result.version})\n${location}\n\n${snippet}`;
+    });
+    const structured = {
+        results: results.map(result => ({
+            library: result.library,
+            version: result.version,
+            doc_path: result.docPath,
+            page_uid: result.pageUid,
+            title: result.title,
+            content_md: result.contentMd,
+            score: result.score,
+            snippet: result.snippet,
+            line_start: result.lineStart,
+            line_end: result.lineEnd,
+            search_mode: result.searchMode,
+            ...(result.url ? { url: result.url } : {}),
+        })),
+    };
+    return structuredTextResult(`Search: ${usedMode} | ${results.length} page-level local results\n\n${lines.join("\n\n---\n\n")}`, structured);
+}
+export async function getDoc(deps, input) {
+    const parsed = parseLibrary(input.library);
+    if (!parsed) {
+        return errorResult("Error: library must be in namespace/name format", "INVALID_LIBRARY");
+    }
+    const installed = deps.cache.findInstalled(parsed.namespace, parsed.name, input.version);
+    if (!installed) {
+        return errorResult(`${input.library}@${input.version} is not installed.`, "NOT_INSTALLED");
+    }
+    const lookupCount = (input.doc_path ? 1 : 0) + (input.page_uid ? 1 : 0);
+    if (lookupCount !== 1) {
+        return errorResult("Exactly one of doc_path or page_uid must be provided.", "INVALID_LOOKUP");
+    }
+    const page = resolveCachedPage(deps.cache, input);
+    if (!page) {
+        return errorResult("Document not found in local cache.", "NOT_FOUND", {
+            library: input.library,
+            version: input.version,
+            ...(input.doc_path ? { doc_path: normalizeDocPath(input.doc_path) } : {}),
+            ...(input.page_uid ? { page_uid: input.page_uid } : {}),
+        });
+    }
+    if (page.hydrationState === "missing_content") {
+        return errorResult("Page metadata exists locally, but page content is not hydrated. Reinstall with install_docs or refresh with update_docs.", "PAGE_NOT_HYDRATED", {
+            library: input.library,
+            version: input.version,
+            doc_path: page.docPath,
+            page_uid: page.pageUid,
+        });
+    }
+    const excerptWindow = resolveExcerptWindow(input);
+    if ("text" in excerptWindow) {
+        return excerptWindow;
+    }
+    if ((page.content ?? "").length === 0) {
+        return errorResult("Page content is empty.", "EMPTY_CONTENT", {
+            library: input.library,
+            version: input.version,
+            doc_path: page.docPath,
+            page_uid: page.pageUid,
+        });
+    }
+    return buildExcerpt(page, {
+        fromLine: excerptWindow.fromLine,
+        maxLines: excerptWindow.maxLines,
+        lineNumbers: input.line_numbers ?? false,
+    });
+}
+export async function updateDocs(deps, input) {
+    const { cache, indexer, registryClient } = deps;
+    const installed = cache.listInstalled();
+    if (input.library && !parseLibrary(input.library)) {
+        return errorResult("library must be in namespace/name format (for example 'vercel/nextjs').", "INVALID_LIBRARY");
+    }
+    const targets = input.library
+        ? installed.filter(lib => librarySlug(lib.namespace, lib.name) === input.library)
+        : installed;
+    if (targets.length === 0) {
+        return structuredTextResult(input.library ? `${input.library} is not installed. Use install_docs first.` : "No documentation packages installed.", { results: [] });
+    }
+    const messages = [];
+    const results = [];
+    for (const lib of targets) {
+        try {
+            reportProgress(deps, `Checking ${librarySlug(lib.namespace, lib.name)} for updates...`);
+            const resolved = await registryClient.resolve({ query: librarySlug(lib.namespace, lib.name) });
+            const targetVersion = resolved.data.version.version;
+            const manifest = await registryClient.getManifest(lib.namespace, lib.name, targetVersion);
+            const targetChecksum = manifest.data.provenance?.manifest_checksum ?? null;
+            const versionChanged = targetVersion !== lib.version;
+            const checksumChanged = targetChecksum !== lib.manifest_checksum;
+            if (!versionChanged && !checksumChanged) {
+                messages.push(`${librarySlug(lib.namespace, lib.name)}@${lib.version}: already up to date`);
+                results.push({
+                    library: librarySlug(lib.namespace, lib.name),
+                    version: lib.version,
+                    status: "unchanged",
+                    manifest_checksum: targetChecksum,
+                });
+                continue;
+            }
+            const installOutcome = await installResolvedVersion(deps, lib.namespace, lib.name, targetVersion, manifest.data);
+            if (versionChanged) {
+                await indexer.removeLibraryVersion(lib.namespace, lib.name, lib.version);
+                cache.removeVersion(lib.namespace, lib.name, lib.version);
+                cache.removeInstalled(lib.namespace, lib.name, lib.version);
+            }
+            cache.addInstalled({
+                ...lib,
+                version: targetVersion,
+                installed_at: new Date().toISOString(),
+                manifest_checksum: installOutcome.manifestChecksum,
+                page_count: installOutcome.pageCount,
+                profile: installOutcome.profile,
+                index_schema_version: DOC_INDEX_SCHEMA_VERSION,
+            });
+            let message = `${librarySlug(lib.namespace, lib.name)}: ${lib.version} → ${targetVersion}`;
+            if (!versionChanged) {
+                message = `${librarySlug(lib.namespace, lib.name)}@${lib.version}: refreshed in place`;
+            }
+            message += ` (${installOutcome.pageCount} pages, ${installOutcome.indexedCount} indexed via ${installOutcome.installMethod})`;
+            if (installOutcome.bundleFallbackReason) {
+                message += ` [bundle fallback: ${installOutcome.bundleFallbackReason}]`;
+            }
+            messages.push(message);
+            results.push({
+                library: librarySlug(lib.namespace, lib.name),
+                previous_version: lib.version,
+                version: targetVersion,
+                status: versionChanged ? "updated" : "refreshed",
+                install_method: installOutcome.installMethod,
+                profile: installOutcome.profile,
+                page_count: installOutcome.pageCount,
+                indexed_count: installOutcome.indexedCount,
+                manifest_checksum: installOutcome.manifestChecksum,
+                ...(installOutcome.bundleFormat ? { bundle_format: installOutcome.bundleFormat } : {}),
+                ...(installOutcome.bundleFallbackReason ? { bundle_fallback_reason: installOutcome.bundleFallbackReason } : {}),
+            });
+        }
+        catch (error) {
+            messages.push(`${librarySlug(lib.namespace, lib.name)}: update failed — ${error.message}`);
+            results.push({
+                library: librarySlug(lib.namespace, lib.name),
+                version: lib.version,
+                status: "failed",
+                error: error.message,
+            });
+        }
+    }
+    return structuredTextResult(messages.join("\n"), { results });
+}
+export async function removeDocs(deps, input) {
+    const parsed = parseLibrary(input.library);
+    if (!parsed) {
+        return errorResult("Error: library must be in namespace/name format", "INVALID_LIBRARY");
+    }
+    const targets = deps.cache.listInstalled().filter(lib => {
+        if (lib.namespace !== parsed.namespace || lib.name !== parsed.name) {
+            return false;
+        }
+        return !input.version || lib.version === input.version;
+    });
+    if (targets.length === 0) {
+        return errorResult(input.version ? `${input.library}@${input.version} is not installed.` : `${input.library} is not installed.`, "NOT_INSTALLED");
+    }
+    for (const target of targets) {
+        await deps.indexer.removeLibraryVersion(target.namespace, target.name, target.version);
+        deps.cache.removeVersion(target.namespace, target.name, target.version);
+        deps.cache.removeInstalled(target.namespace, target.name, target.version);
+    }
+    return structuredTextResult(`Removed ${targets.length} documentation package${targets.length === 1 ? "" : "s"} for ${input.library}.`, {
+        library: input.library,
+        removed_versions: targets.map(target => target.version),
+    });
+}
+function extractTitle(content, fallback) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : fallback;
+}