@taurgis/bonsai 1.0.6 → 3.0.1

package/dist/commands/search.js

@@ -1,391 +0,0 @@
-import { Args, Flags, ux } from '@oclif/core';
-import { BaseCommand } from '../base-command.js';
-import { loadSearchableArtifacts } from '../lib/research/search-index.js';
-import { levenshtein, NO_TOPIC_LABEL, resultListHeading, truncationNotice, } from '../lib/text.js';
-import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { evaluateFreshness } from '../lib/research/freshness.js';
-import { ARTIFACT_TYPES } from '../lib/research/schema.js';
-import { detectSite } from '../sites/index.js';
-import { fetchStaticHtml, fetchText, postJson } from '../lib/research/fetcher.js';
-import { normalizeUrl } from '../lib/research/url.js';
-import { runRemoteDocsSearch, } from '../lib/research/docs/remote-search-runner.js';
-// Results are ranked, so the truncation word is "top"; --limit caps at 50.
-const SEARCH_LABELS = {
-    noun: 'matching cached research',
-    order: 'top',
-    maxLimit: 50,
-};
-const REMOTE_SEARCH_DEPS = {
-    fetchStatic: async (url) => {
-        const res = await fetchStaticHtml(url);
-        return { content: res.content, finalUrl: res.finalUrl };
-    },
-    fetchText: async (url) => {
-        const res = await fetchText(url);
-        return { content: res.content, status: res.status };
-    },
-    postJson: (url, body, headers) => postJson(url, body, headers),
-};
-const FRESHNESS_BONUS = { fresh: 30, stale_grace: 10 };
-export default class ResearchSearch extends BaseCommand {
-    static id = 'search';
-    static summary = 'Search locally cached research artifacts by keywords.';
-    static description = 'Scans the local research cache database and ranks matching entries based on topic, tags, source URLs, summary, and content.';
-    static examples = [
-        {
-            description: 'search for cached notes containing specific keywords',
-            command: '<%= config.bin %> <%= command.id %> "authentication flow"',
-        },
-        {
-            description: 'search with remote docs fallback',
-            command: '<%= config.bin %> <%= command.id %> "router" --remote https://react.dev',
-        },
-        {
-            description: 'search local cache with tag filtering',
-            command: '<%= config.bin %> <%= command.id %> "setup" --tags node --tags tutorial',
-        },
-    ];
-    static args = {
-        query: Args.string({
-            required: true,
-            description: 'the search query containing terms to match',
-        }),
-    };
-    static flags = {
-        topic: Flags.string({
-            char: 't',
-            description: 'filter results by exact topic (case-insensitive)',
-        }),
-        tags: Flags.string({
-            char: 'g',
-            description: 'filter results by tags (must match all tags specified)',
-            multiple: true,
-        }),
-        'artifact-type': Flags.option({
-            description: 'filter results by artifact type',
-            options: ARTIFACT_TYPES,
-        })(),
-        limit: Flags.integer({
-            description: 'maximum number of results to return (default 10, max 50)',
-            default: 10,
-        }),
-        'include-stale': Flags.boolean({
-            description: 'include stale expired cache entries in the search results',
-            default: false,
-        }),
-        domain: Flags.string({
-            description: 'search a documentation site directly (requires compatible site module)',
-        }),
-        remote: Flags.string({
-            description: 'discover uncached docs via public search or index (falls back to local cache)',
-        }),
-    };
-    static stdoutIsPrimaryData = true;
-    validateSearchFlags() {
-        const limit = this.flags.limit;
-        if (limit !== undefined && (limit < 1 || limit > 50)) {
-            this.error('Limit must be between 1 and 50.', { exit: 2, code: 'INVALID_LIMIT' });
-        }
-    }
-    getSearchQueryTerms(query) {
-        const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-        if (terms.length === 0) {
-            this.error('Query string cannot be empty.', { exit: 2, code: 'EMPTY_QUERY' });
-        }
-        return terms;
-    }
-    matchesFilters(meta, freshness, topicFlag, tagsFlag, artTypeFlag, includeStale) {
-        if (topicFlag &&
-            (!meta.topic || meta.topic.trim().toLowerCase() !== topicFlag.trim().toLowerCase())) {
-            return false;
-        }
-        if (tagsFlag && tagsFlag.length > 0) {
-            const metaTagsLower = (meta.tags || []).map((t) => t.toLowerCase());
-            const hasAllTags = tagsFlag.every((t) => metaTagsLower.includes(t.toLowerCase()));
-            if (!hasAllTags) {
-                return false;
-            }
-        }
-        if (artTypeFlag && meta.artifact_type !== artTypeFlag) {
-            return false;
-        }
-        if (!includeStale && freshness === 'stale_expired') {
-            return false;
-        }
-        return true;
-    }
-    phraseMatchBonus(topic, tags, summ, comp, queryTerms) {
-        if (queryTerms.length <= 1)
-            return 0;
-        const fullQuery = queryTerms.join(' ');
-        let bonus = 0;
-        if (topic === fullQuery)
-            bonus += 200;
-        if (topic.includes(fullQuery))
-            bonus += 100;
-        if (tags.includes(fullQuery))
-            bonus += 150;
-        if (summ.includes(fullQuery))
-            bonus += 50 + Math.min(summ.split(fullQuery).length - 1, 5) * 10;
-        if (comp.includes(fullQuery))
-            bonus += 20 + Math.min(comp.split(fullQuery).length - 1, 10) * 5;
-        return bonus;
-    }
-    calculateScore(meta, summary, compressed, queryTerms, freshness) {
-        const topic = (meta.topic || '').toLowerCase();
-        const tags = (meta.tags || []).map((t) => t.toLowerCase());
-        const sourceUrl = (meta.source_url || '').toLowerCase();
-        const sourceUrls = (meta.source_urls || []).map((u) => u.toLowerCase());
-        const summ = summary.toLowerCase();
-        const comp = compressed.toLowerCase();
-        let score = 0;
-        let matchedAny = false;
-        for (const term of queryTerms) {
-            const termScore = scoreSingleTerm(term, topic, tags, sourceUrl, sourceUrls, summ, comp);
-            if (termScore > 0) {
-                score += termScore;
-                matchedAny = true;
-            }
-        }
-        if (!matchedAny)
-            return 0;
-        score += this.phraseMatchBonus(topic, tags, summ, comp, queryTerms);
-        score += FRESHNESS_BONUS[freshness] ?? 0;
-        return score;
-    }
-    makeSnippet(text, queryTerms) {
-        const lower = text.toLowerCase();
-        let bestIdx = 0;
-        for (const term of queryTerms) {
-            const idx = lower.indexOf(term);
-            if (idx !== -1) {
-                bestIdx = idx;
-                break;
-            }
-        }
-        const start = Math.max(0, bestIdx - 40);
-        const end = Math.min(text.length, bestIdx + 110);
-        let snippet = text.slice(start, end).replace(/\s+/g, ' ').trim();
-        if (start > 0)
-            snippet = '...' + snippet;
-        if (end < text.length)
-            snippet = snippet + '...';
-        return snippet;
-    }
-    scanCacheDirForResults(readRoots, queryTerms, currentTime) {
-        const results = [];
-        for (const { artifact, filePath } of loadSearchableArtifacts(readRoots)) {
-            if (artifact.metadata.status !== 'active')
-                continue;
-            const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
-            if (!this.matchesFilters(artifact.metadata, freshness, this.flags.topic, this.flags.tags, this.flags['artifact-type'], Boolean(this.flags['include-stale'])))
-                continue;
-            let score = this.calculateScore(artifact.metadata, artifact.summary, artifact.compressed, queryTerms, freshness);
-            if (score <= 0)
-                continue;
-            // Section children are more precise than the whole page, so rank a section hit slightly
-            // above its parent for the same query (T-22).
-            if (artifact.metadata.artifact_type === 'section')
-                score += 15;
-            const snippetText = [artifact.summary, artifact.compressed].filter(Boolean).join('\n');
-            results.push({
-                cacheKey: artifact.metadata.cache_key,
-                path: filePath,
-                artifactType: artifact.metadata.artifact_type,
-                sourceUrls: artifact.metadata.source_urls,
-                topic: artifact.metadata.topic,
-                tags: artifact.metadata.tags,
-                freshness,
-                captureMethod: artifact.metadata.capture_method,
-                tokenEstimate: artifact.metadata.token_estimate,
-                snippet: this.makeSnippet(snippetText, queryTerms),
-                siteModuleId: artifact.metadata.site_module_id,
-                score,
-            });
-        }
-        return results;
-    }
-    logSearchResults(finalResults, totalMatched) {
-        if (this.jsonEnabled())
-            return;
-        if (finalResults.length === 0) {
-            this.log('No matching cached research entries found.');
-            this.log(`\nTip: populate the cache first: ${this.config.bin} <url>`);
-            return;
-        }
-        this.log(`${resultListHeading(totalMatched, finalResults.length, SEARCH_LABELS)}\n`);
-        finalResults.forEach((res, index) => {
-            this.log(`${index + 1}. [${res.topic || NO_TOPIC_LABEL}] Score: ${res.score}`);
-            this.log(`   Cache Key: ${res.cacheKey}`);
-            this.log(`   Snippet: ${res.snippet}`);
-            this.log(`   Source URLs: ${res.sourceUrls.join(', ')}\n`);
-        });
-    }
-    // Prints a numbered result list to stdout for human (non-JSON) output. Shared by site and remote
-    // search so the two paths can't drift in formatting.
-    printResults(heading, results) {
-        if (this.jsonEnabled())
-            return;
-        this.log(heading);
-        results.forEach((r, i) => {
-            this.log(`${i + 1}. ${r.title}`);
-            this.log(`   URL: ${r.url}`);
-            if (r.snippet)
-                this.log(`   ${r.snippet}`);
-        });
-    }
-    async executeSiteSearch(query, domain) {
-        const siteModule = detectSite(`https://${domain}`);
-        if (!siteModule) {
-            this.error(`No site module registered for domain: ${domain}`, {
-                exit: 2,
-                code: 'UNSUPPORTED_DOMAIN',
-            });
-        }
-        if (!siteModule.search) {
-            this.error(`Site module '${siteModule.id}' does not implement search.`, {
-                exit: 2,
-                code: 'SEARCH_NOT_SUPPORTED',
-            });
-        }
-        try {
-            if (!this.jsonEnabled())
-                ux.action.start(`Searching ${domain}`);
-            const results = await siteModule.search(query);
-            if (!this.jsonEnabled())
-                ux.action.stop();
-            this.printResults(`Found ${results.length} results from ${siteModule.name}:\n`, results);
-            return results.map((r) => ({ ...r, site_module_id: siteModule.id }));
-        }
-        catch (err) {
-            if (!this.jsonEnabled())
-                ux.action.stop('failed');
-            throw err;
-        }
-    }
-    // Remote docs discovery. On any connector failure, degrade to local cache search with a warning
-    // (T-20). Returns discovery results tagged remote: true so callers can tell them from cache hits.
-    async executeRemoteSearch(query, docsUrl) {
-        try {
-            if (!this.jsonEnabled())
-                ux.action.start(`Searching ${docsUrl}`);
-            const { provider, results } = await runRemoteDocsSearch(docsUrl, query, REMOTE_SEARCH_DEPS);
-            if (!this.jsonEnabled())
-                ux.action.stop();
-            this.printResults(`Found ${results.length} remote results via ${provider}:\n`, results);
-            return results.map((r) => ({ ...r, remote: true }));
-        }
-        catch (err) {
-            if (!this.jsonEnabled())
-                ux.action.stop('failed');
-            this.warn(`Remote docs search unavailable, using local cache: ${err.message}`);
-            return undefined;
-        }
-    }
-    async run() {
-        const { query } = this.args;
-        const { domain, remote } = this.flags;
-        // Reject whitespace-only queries on every path (local, --domain, --remote).
-        this.getSearchQueryTerms(query);
-        if (domain && remote) {
-            this.error('--domain and --remote are mutually exclusive. Use one discovery mode at a time.', {
-                exit: 2,
-                code: 'CONFLICTING_FLAGS',
-                suggestions: [
-                    `Local site API: ${this.config.bin} search "${query}" --domain ${domain}`,
-                    `Remote index: ${this.config.bin} search "${query}" --remote ${remote}`,
-                ],
-            });
-        }
-        if (domain) {
-            return this.executeSiteSearch(query, domain);
-        }
-        if (remote) {
-            let normalizedRemote;
-            try {
-                normalizedRemote = normalizeUrl(remote);
-            }
-            catch (err) {
-                this.error(`Invalid --remote URL: ${err.message}`, {
-                    exit: 2,
-                    code: 'INVALID_URL',
-                });
-            }
-            const remoteResults = await this.executeRemoteSearch(query, normalizedRemote);
-            if (remoteResults !== undefined)
-                return remoteResults;
-            // else: fall through to local cache search (connector/network failure only)
-        }
-        this.validateSearchFlags();
-        const queryTerms = this.getSearchQueryTerms(query);
-        const roots = loadStoreRoots({
-            configDir: this.config.configDir,
-            cwd: process.cwd(),
-            dataDir: this.config.dataDir,
-        });
-        const currentTime = new Date();
-        const results = this.scanCacheDirForResults(roots.readRoots, queryTerms, currentTime);
-        results.sort((a, b) => b.score - a.score);
-        const finalResults = results.slice(0, this.flags.limit);
-        // Under --json the human heading is suppressed, so surface truncation on stderr instead (warn
-        // always emits, even in --json) without touching the stdout envelope. Human mode already shows
-        // it in the heading, so only warn under --json.
-        const notice = truncationNotice(results.length, finalResults.length, SEARCH_LABELS);
-        if (notice && this.jsonEnabled())
-            this.warn(notice);
-        this.logSearchResults(finalResults, results.length);
-        return finalResults;
-    }
-}
-function scoreSingleTerm(term, topic, tags, sourceUrl, sourceUrls, summ, comp) {
-    let termScore = 0;
-    let termMatched = false;
-    // 1. Topic Match
-    if (topic === term) {
-        termScore += 100;
-        termMatched = true;
-    }
-    else if (topic.includes(term)) {
-        termScore += 60;
-        termMatched = true;
-    }
-    else if (isFuzzyMatch(term, topic)) {
-        termScore += 40;
-        termMatched = true;
-    }
-    // 2. Tags Match
-    if (tags.includes(term)) {
-        termScore += 80;
-        termMatched = true;
-    }
-    else if (tags.some((t) => isFuzzyMatch(term, t) || t.includes(term))) {
-        termScore += 30;
-        termMatched = true;
-    }
-    // 3. Source URL Match
-    if (sourceUrl.includes(term) || sourceUrls.some((u) => u.includes(term))) {
-        termScore += 50;
-        termMatched = true;
-    }
-    // 4. Summary Term Frequency Match
-    const summMatches = summ.split(term).length - 1;
-    if (summMatches > 0) {
-        termScore += 20 + Math.min(summMatches, 5) * 5;
-        termMatched = true;
-    }
-    // 5. Compressed Content Term Frequency Match
-    const compMatches = comp.split(term).length - 1;
-    if (compMatches > 0) {
-        termScore += 5 + Math.min(compMatches, 10) * 2;
-        termMatched = true;
-    }
-    if (termMatched) {
-        termScore += 10;
-    }
-    return termScore;
-}
-function isFuzzyMatch(term, target) {
-    if (term.length < 4 || target.length < 4)
-        return false;
-    return levenshtein(term, target) <= 2;
-}

package/dist/lib/research/docs/__fixtures__/sphinx-searchindex.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/lib/research/docs/__fixtures__/sphinx-searchindex.js

@@ -1,2 +0,0 @@
-Search.setIndex({ "docnames": ["index", "library/functions", "library/string"], "filenames": ["index.rst", "library/functions.rst", "library/string.rst"], "titles": ["Python Documentation", "Built-in Functions", "String Methods"], "terms": { "function": [1], "string": [2], "print": [1], "format": [2] }, "titleterms": { "function": [1], "string": [2], "python": [0], "built": [1], "methods": [2] }, "objects": {}, "envversion": {} });
-export {};

package/dist/lib/research/docs/discovery-index.d.ts

@@ -1,14 +0,0 @@
-import type { DocsSearchResult } from './search-index.js';
-interface DiscoveryEntry {
-    title: string;
-    url: string;
-    body?: string;
-}
-export interface SitemapParseResult {
-    entries: DiscoveryEntry[];
-    sitemapUrls: string[];
-}
-export declare function parseSitemap(body: string): SitemapParseResult;
-export declare function searchSitemap(body: string, indexUrl: string, query: string): DocsSearchResult[];
-export declare function searchLlmsTxt(body: string, indexUrl: string, query: string): DocsSearchResult[];
-export {};

package/dist/lib/research/docs/discovery-index.js

@@ -1,112 +0,0 @@
-import { DOMParser } from 'linkedom';
-function queryTerms(query) {
-    return query.toLowerCase().split(/\s+/).filter(Boolean);
-}
-function scoreEntry(entry, terms) {
-    const haystack = `${entry.title} ${entry.url} ${entry.body ?? ''}`.toLowerCase();
-    let score = 0;
-    for (const term of terms) {
-        if (entry.title.toLowerCase().includes(term))
-            score += 10;
-        if (entry.url.toLowerCase().includes(term))
-            score += 5;
-        score += Math.min(haystack.split(term).length - 1, 5);
-    }
-    return score;
-}
-function snippetFrom(entry) {
-    return (entry.body || entry.url).replace(/\s+/g, ' ').trim().slice(0, 150);
-}
-function titleFromUrl(url) {
-    try {
-        const parsed = new URL(url);
-        const last = parsed.pathname.split('/').filter(Boolean).pop();
-        return last ? last.replace(/\.[a-z0-9]+$/i, '').replace(/[-_]+/g, ' ') : parsed.hostname;
-    }
-    catch {
-        return url;
-    }
-}
-function toResults(entries, indexUrl, provider, query) {
-    const terms = queryTerms(query);
-    return entries
-        .map((entry) => ({ entry, score: scoreEntry(entry, terms) }))
-        .filter(({ score }) => score > 0)
-        .map(({ entry, score }) => ({
-        title: entry.title,
-        url: entry.url,
-        snippet: snippetFrom(entry),
-        provider,
-        score,
-        indexUrl,
-    }))
-        .sort((a, b) => b.score - a.score);
-}
-function textContent(element) {
-    const text = element?.textContent?.trim();
-    return text || undefined;
-}
-export function parseSitemap(body) {
-    const trimmed = body.trim();
-    if (!trimmed)
-        return { entries: [], sitemapUrls: [] };
-    if (!trimmed.startsWith('<')) {
-        const entries = trimmed
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => /^https?:\/\//i.test(line))
-            .map((url) => ({ title: titleFromUrl(url), url }));
-        return { entries, sitemapUrls: [] };
-    }
-    const doc = new DOMParser().parseFromString(trimmed, 'text/xml');
-    const sitemapUrls = Array.from(doc.querySelectorAll('sitemap > loc'))
-        .map((loc) => textContent(loc))
-        .filter((url) => !!url);
-    const entries = Array.from(doc.querySelectorAll('url'))
-        .map((urlElement) => {
-        const url = textContent(urlElement.querySelector('loc'));
-        if (!url)
-            return null;
-        const lastmod = textContent(urlElement.querySelector('lastmod'));
-        return { title: titleFromUrl(url), url, body: lastmod ? `Last modified ${lastmod}` : '' };
-    })
-        .filter((entry) => !!entry);
-    return { entries, sitemapUrls };
-}
-export function searchSitemap(body, indexUrl, query) {
-    return toResults(parseSitemap(body).entries, indexUrl, 'sitemap', query);
-}
-function referenceDefinitions(body) {
-    const refs = new Map();
-    for (const match of body.matchAll(/^\s*\[([^\]]+)\]:\s*(\S+)/gm)) {
-        refs.set(match[1].toLowerCase(), match[2]);
-    }
-    return refs;
-}
-export function searchLlmsTxt(body, indexUrl, query) {
-    const refs = referenceDefinitions(body);
-    const entries = [];
-    let section = '';
-    for (const line of body.split(/\r?\n/)) {
-        const heading = line.match(/^##\s+(.+?)\s*$/);
-        if (heading)
-            section = heading[1];
-        const inline = line.match(/^\s*[-*]\s+\[([^\]]+)\]\(([^)]+)\)\s*:?\s*(.*)$/);
-        const ref = line.match(/^\s*[-*]\s+\[([^\]]+)\]\s*:?\s*(.*)$/);
-        const title = inline?.[1] ?? ref?.[1];
-        const url = inline?.[2] ?? (title ? refs.get(title.toLowerCase()) : undefined);
-        if (!title || !url)
-            continue;
-        try {
-            entries.push({
-                title,
-                url: new URL(url, indexUrl).toString(),
-                body: [section, inline?.[3] ?? ref?.[2]].filter(Boolean).join(' - '),
-            });
-        }
-        catch {
-            // Ignore malformed links in untrusted machine-readable text.
-        }
-    }
-    return toResults(entries, indexUrl, 'llms.txt', query);
-}

package/dist/lib/research/docs/remote-search-runner.d.ts

@@ -1,21 +0,0 @@
-import type { DocsSearchResult } from './search-index.js';
-export interface RemoteSearchDeps {
-    fetchStatic: (url: string) => Promise<{
-        content: string;
-        finalUrl: string;
-    }>;
-    fetchText: (url: string) => Promise<{
-        content: string;
-        status: number;
-    }>;
-    postJson: (url: string, body: unknown, headers: Record<string, string>) => Promise<string>;
-}
-export interface RemoteSearchOutcome {
-    provider: string;
-    results: DocsSearchResult[];
-}
-/**
- * Runs remote docs search for a documentation site. Detects the provider from the page, queries the
- * matching connector, and returns normalized results. Throws when no verified connector applies.
- */
-export declare function runRemoteDocsSearch(docsUrl: string, query: string, deps: RemoteSearchDeps): Promise<RemoteSearchOutcome>;

package/dist/lib/research/docs/remote-search-runner.js

@@ -1,114 +0,0 @@
-import { detectDocsEngine } from './detect.js';
-import { probeLlmsTxt } from './machine-readable.js';
-import { searchMkDocsIndex, searchJekyllIndex, searchSphinxIndex } from './search-index.js';
-import { parseSitemap, searchLlmsTxt, searchSitemap } from './discovery-index.js';
-import { extractAlgoliaConfig, algoliaQueryUrl, parseAlgoliaResponse } from './remote-search.js';
-async function getText(url, deps) {
-    const res = await deps.fetchText(url);
-    if (res.status === 304 || !res.content)
-        throw new Error(`empty search index at ${url}`);
-    return res.content;
-}
-function sameHost(url, base) {
-    try {
-        return new URL(url).hostname === new URL(base).hostname;
-    }
-    catch {
-        return false;
-    }
-}
-// Conventional static index path + parser per framework (verified by T-25 fixtures).
-async function staticIndexSearch(framework, origin, query, deps) {
-    if (framework === 'mkdocs' || framework === 'material-mkdocs') {
-        const indexUrl = `${origin}/search/search_index.json`;
-        return {
-            provider: 'mkdocs-local',
-            results: searchMkDocsIndex(await getText(indexUrl, deps), indexUrl, query),
-        };
-    }
-    if (framework === 'sphinx') {
-        const indexUrl = `${origin}/searchindex.js`;
-        return {
-            provider: 'sphinx-searchindex',
-            results: searchSphinxIndex(await getText(indexUrl, deps), indexUrl, query),
-        };
-    }
-    if (framework === 'just-the-docs') {
-        const indexUrl = `${origin}/assets/js/search-data.json`;
-        return {
-            provider: 'jekyll-json',
-            results: searchJekyllIndex(await getText(indexUrl, deps), indexUrl, query),
-        };
-    }
-    return null;
-}
-async function llmsTxtSearch(docsUrl, caps, query, deps) {
-    const llms = await probeLlmsTxt(docsUrl, caps, async (url) => {
-        const res = await deps.fetchText(url);
-        return { ...res, finalUrl: url, contentType: 'text/plain' };
-    });
-    if (!llms)
-        return null;
-    return {
-        provider: llms.artifact.type,
-        results: searchLlmsTxt(llms.body, llms.artifact.url, query),
-    };
-}
-async function sitemapSearch(pageUrl, query, deps) {
-    const origin = new URL(pageUrl).origin;
-    const firstSegment = new URL(pageUrl).pathname.split('/').filter(Boolean)[0];
-    const candidates = [
-        `${origin}/sitemap.xml`,
-        `${origin}/sitemap_index.xml`,
-        firstSegment ? `${origin}/${firstSegment}/sitemap.xml` : undefined,
-    ].filter((url) => !!url);
-    for (const sitemapUrl of [...new Set(candidates)]) {
-        try {
-            const body = await getText(sitemapUrl, deps);
-            const results = searchSitemap(body, sitemapUrl, query);
-            if (results.length > 0)
-                return { provider: 'sitemap', results };
-            const index = parseSitemap(body);
-            const childResults = [];
-            for (const childUrl of index.sitemapUrls.slice(0, 10)) {
-                if (!sameHost(childUrl, pageUrl))
-                    continue;
-                const childBody = await getText(childUrl, deps);
-                childResults.push(...searchSitemap(childBody, childUrl, query));
-            }
-            if (childResults.length > 0) {
-                return { provider: 'sitemap', results: childResults.sort((a, b) => b.score - a.score) };
-            }
-        }
-        catch {
-            // Try the next conventional sitemap location.
-        }
-    }
-    return null;
-}
-/**
- * Runs remote docs search for a documentation site. Detects the provider from the page, queries the
- * matching connector, and returns normalized results. Throws when no verified connector applies.
- */
-export async function runRemoteDocsSearch(docsUrl, query, deps) {
-    const page = await deps.fetchStatic(docsUrl);
-    const origin = new URL(page.finalUrl).origin;
-    const algolia = extractAlgoliaConfig(page.content);
-    if (algolia) {
-        const url = algoliaQueryUrl(algolia);
-        const body = await deps.postJson(url, { params: `query=${encodeURIComponent(query)}` }, { 'X-Algolia-API-Key': algolia.apiKey, 'X-Algolia-Application-Id': algolia.appId });
-        return { provider: 'algolia-docsearch', results: parseAlgoliaResponse(body, url) };
-    }
-    const caps = detectDocsEngine(page.content, page.finalUrl);
-    const staticResult = await staticIndexSearch(caps.framework, origin, query, deps);
-    if (staticResult)
-        return staticResult;
-    const llmsResult = await llmsTxtSearch(page.finalUrl, caps, query, deps);
-    if (llmsResult)
-        return llmsResult;
-    const sitemapResult = await sitemapSearch(page.finalUrl, query, deps);
-    if (sitemapResult)
-        return sitemapResult;
-    throw new Error(`No verified remote search connector for this site (detected: ${caps.framework ?? caps.docsEngine ?? 'unknown'}). ` +
-        'Supported: Algolia DocSearch, MkDocs/Material, Sphinx, Just the Docs, llms.txt, sitemap.xml.');
-}

package/dist/lib/research/docs/remote-search.d.ts

@@ -1,14 +0,0 @@
-import type { DocsSearchResult } from './search-index.js';
-export interface AlgoliaConfig {
-    appId: string;
-    apiKey: string;
-    indexName: string;
-}
-export declare function extractAlgoliaConfig(html: string): AlgoliaConfig | null;
-export declare function algoliaQueryUrl(config: AlgoliaConfig): string;
-export declare function parseAlgoliaResponse(body: string, indexUrl: string): DocsSearchResult[];
-/**
- * Parses a VitePress local search index (MiniSearch documents) and ranks docs by query term hits.
- * `base` is the docs site origin/base used to resolve the relative `id` routes.
- */
-export declare function searchVitePressLocalIndex(body: string, indexUrl: string, base: string, query: string): DocsSearchResult[];