@taurgis/bonsai 1.0.5 → 3.0.0

package/dist/commands/research.js

@@ -1,304 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { BaseCommand } from '../base-command.js';
-import { normalizeUrl } from '../lib/research/url.js';
-import { deriveCacheKey } from '../lib/research/cache-key.js';
-import { locateArtifact, writeArtifact, getArtifactPath } from '../lib/research/storage.js';
-import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { writeArtifactSecurely } from '../lib/research/secure-write.js';
-import { evaluateFreshness, parseTtlToMs, checkMaxAgeExpired } from '../lib/research/freshness.js';
-import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
-import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
-import { fetchRenderedHtml } from '../lib/research/browser.js';
-import { capturePage } from '../lib/research/capture.js';
-import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
-import { detectSite } from '../sites/index.js';
-const CAPTURE_DEPS = {
-    fetchStatic: (url) => fetchStaticHtml(url),
-    fetchRendered: (url) => fetchRenderedHtml(url),
-    fetchText: (url) => fetchText(url),
-};
-export default class Research extends BaseCommand {
-    static id = 'research';
-    static summary = 'An advanced, locally cached web research tool optimized for LLM ingestion.';
-    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.';
-    static examples = [
-        {
-            description: 'Research a URL with detailed output, tagged with topic and tags',
-            command: '<%= config.bin %> research https://docs.nestjs.com/ --topic "Backend Frameworks" --tags "Node" --tags "NestJS" --format detailed --ttl 30d',
-        },
-        {
-            description: 'Research a volatile page with compressed output and short TTL, returned as JSON',
-            command: '<%= config.bin %> research https://news.ycombinator.com/ --format compressed --ttl 2h --json',
-        },
-    ];
-    static args = {
-        url: Args.string({
-            required: true,
-            description: 'The full HTTP/HTTPS URL of the web page to research.',
-        }),
-    };
-    static flags = {
-        topic: Flags.string({
-            char: 't',
-            description: 'The main category/topic of the research for metadata tagging.',
-        }),
-        tags: Flags.string({
-            char: 'g',
-            description: 'Taxonomic tags for this research (can be repeated).',
-            multiple: true,
-        }),
-        format: Flags.option({
-            char: 'f',
-            description: 'Desired data density.',
-            options: ['compressed', 'detailed'],
-            default: 'compressed',
-        })(),
-        tier: Flags.option({
-            description: 'Freshness tier policy.',
-            options: ['stable', 'standard', 'volatile'],
-            default: 'standard',
-        })(),
-        ttl: Flags.string({
-            char: 'l',
-            description: 'Predicted lifespan of the data (e.g., "2h", "7d", "3m").',
-        }),
-        'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
-        }),
-        force: Flags.boolean({
-            description: 'Force a fresh fetch, ignoring any cached entries.',
-            default: false,
-        }),
-        'dry-run': Flags.boolean({
-            description: 'Perform validation and fetch without saving to local cache.',
-            default: false,
-        }),
-        'allow-stale': Flags.boolean({
-            description: 'Allow serving stale cache if the remote server is unreachable.',
-            default: false,
-        }),
-        rendered: Flags.boolean({
-            description: 'Force using a browser-rendered scraping path for dynamic pages.',
-            default: false,
-        }),
-        storage: Flags.option({
-            description: 'Override where this result is cached (overrides configured default). Secret-bearing pages are always stored globally.',
-            options: ['global', 'project'],
-        })(),
-    };
-    static stdoutIsPrimaryData = true;
-    async init() {
-        await super.init();
-        const { args, flags } = await this.parse(Research);
-        this.args = args;
-        this.flags = flags;
-    }
-    async executeCacheHit(cached, targetDir, currentTime) {
-        const { ttl, 'max-age': maxAge, 'allow-stale': allowStale, rendered } = this.flags;
-        const isExpired = checkMaxAgeExpired(cached, currentTime, maxAge);
-        const freshnessState = isExpired
-            ? 'stale_expired'
-            : evaluateFreshness(cached.metadata, currentTime, ttl);
-        if (freshnessState === 'fresh') {
-            return { cacheStatus: 'hit', freshnessState, artifact: cached };
-        }
-        const revalResult = await revalidateCache(targetDir, cached, currentTime, {
-            allowStale: Boolean(allowStale),
-            ttlOverride: ttl,
-            rendered: Boolean(rendered),
-        });
-        handleStaleRevalidationResult(this, revalResult);
-        return {
-            cacheStatus: revalResult.status,
-            freshnessState,
-            artifact: revalResult.artifact,
-        };
-    }
-    async executeCacheMiss(normalizedUrl, currentTime, cacheKey) {
-        const { topic, tags, tier, ttl, rendered } = this.flags;
-        const siteModule = detectSite(normalizedUrl);
-        const useRendered = rendered || Boolean(siteModule?.defaults?.rendered);
-        let fetchResult;
-        let extraction;
-        let capture = null;
-        if (siteModule?.fetchPage) {
-            // Custom site modules own their fetch/extract strategy; the generic capture path is skipped.
-            ({ fetchResult, extraction } = await siteModule.fetchPage(normalizedUrl));
-        }
-        else {
-            capture = await capturePage(normalizedUrl, { forceRendered: useRendered }, CAPTURE_DEPS);
-            fetchResult = capture.fetchResult;
-            extraction = capture.extraction;
-        }
-        const artifact = createArtifactFromFetch(normalizedUrl, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl || null, currentTime);
-        artifact.metadata.topic = topic || null;
-        artifact.metadata.tags = tags || [];
-        artifact.metadata.site_module_id = siteModule?.id ?? null;
-        if (capture) {
-            applyCaptureMetadata(artifact, capture);
-        }
-        else if (useRendered) {
-            artifact.metadata.capture_method = 'browser_fallback';
-        }
-        return artifact;
-    }
-    buildResultData(url, normalizedUrl, cacheKey, storageDir, storageMode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal) {
-        return {
-            schemaVersion: 1,
-            command: 'research',
-            cache: {
-                key: cacheKey,
-                status: cacheStatus,
-                freshness: freshnessState,
-                path: getArtifactPath(storageDir, cacheKey),
-                storage: storageMode,
-                redirectedToGlobal,
-            },
-            source: {
-                url,
-                normalizedUrl,
-                captureMethod: artifact.metadata.capture_method,
-                extractionStatus: artifact.metadata.extraction_status,
-                extractionConfidence: artifact.metadata.extraction_confidence,
-                qualityNotes: artifact.metadata.quality_notes,
-                fetchedAt: artifact.metadata.fetched_at,
-                validatedAt: artifact.metadata.validated_at,
-                staleAfter: artifact.metadata.stale_after,
-            },
-            artifactType: artifact.metadata.artifact_type,
-            docsEngine: artifact.metadata.docs_engine,
-            docsFramework: artifact.metadata.docs_framework,
-            sourceDocUrl: artifact.metadata.source_doc_url,
-            searchProvider: artifact.metadata.search_provider,
-            format,
-            tokenEstimate: format === 'compressed'
-                ? artifact.metadata.token_estimate.compressed
-                : artifact.metadata.token_estimate.detailed,
-            content,
-        };
-    }
-    // Validates the duration flags up front, exiting with code 2 on a malformed value.
-    validateDurationFlags(ttl, maxAge) {
-        for (const [label, value] of [
-            ['TTL', ttl],
-            ['max-age', maxAge],
-        ]) {
-            if (!value)
-                continue;
-            try {
-                parseTtlToMs(value);
-            }
-            catch (err) {
-                this.error(`Invalid ${label}: ${err.message}`, { exit: 2 });
-            }
-        }
-    }
-    // Serves the cache when a fresh/revalidatable entry exists, otherwise fetches fresh. Reads fall
-    // back project→global; the resolved artifact is returned with the dir it lives in / landed in.
-    async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime) {
-        const located = this.flags.force ? null : locateArtifact(roots.readRoots, cacheKey);
-        if (located) {
-            // Revalidate where the entry already lives; on dry-run use the throwaway dir so the cache is
-            // never mutated. ponytail: revalidation rewrites in place, so a refreshed project entry that
-            // gains a secret is not re-routed — only first-time project writes are scanned.
-            const revalDir = tmpDir ?? located.dataDir;
-            const hit = await this.executeCacheHit(located.artifact, revalDir, currentTime);
-            return { ...hit, storageDir: located.dataDir, redirectedToGlobal: false };
-        }
-        const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey);
-        const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
-        return { cacheStatus: 'miss', freshnessState: 'stale_expired', artifact, storageDir: dir, redirectedToGlobal };
-    }
-    // Writes a freshly fetched artifact, honoring dry-run (throwaway dir) and the secret-safety
-    // redirect (project→global). Returns the data dir reported to the user and whether a redirect
-    // occurred (so the JSON envelope mirrors `research import`).
-    persistFreshArtifact(roots, tmpDir, cacheKey, artifact) {
-        if (tmpDir) {
-            writeArtifact(tmpDir, cacheKey, artifact);
-            // Report the real would-be location, not the throwaway dir that is about to be deleted.
-            return { dir: roots.writeRoot, redirectedToGlobal: false };
-        }
-        const result = writeArtifactSecurely(roots, cacheKey, artifact);
-        if (result.redirected) {
-            this.warn(`Detected ${result.secretLabel} in the page content; stored in the global cache instead of the project to avoid committing secrets.`);
-        }
-        return { dir: result.dataDir, redirectedToGlobal: result.redirected };
-    }
-    // Long references are split into searchable/inspectable section children whenever the page artifact
-    // is freshly written (T-22). Best-effort: never let chunking break the main result.
-    persistSectionsIfFresh(targetDir, artifact, currentTime, cacheStatus) {
-        if (cacheStatus !== 'miss' && cacheStatus !== 'refreshed')
-            return;
-        try {
-            persistSectionArtifacts(targetDir, artifact, currentTime);
-        }
-        catch {
-            /* section generation is non-essential; ignore failures */
-        }
-    }
-    async execute() {
-        const { url } = this.args;
-        const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
-        this.validateDurationFlags(ttl, maxAge);
-        let normalizedUrl;
-        let cacheKey;
-        try {
-            normalizedUrl = normalizeUrl(url);
-            cacheKey = deriveCacheKey(normalizedUrl);
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
-        }
-        const roots = loadStoreRoots({
-            configDir: this.config.configDir,
-            cwd: process.cwd(),
-            dataDir: this.config.dataDir,
-            flagOverride: this.flags.storage,
-        });
-        const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
-        const currentTime = new Date();
-        try {
-            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime);
-            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus);
-            const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
-            const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
-            if (!this.requestedJson()) {
-                this.log(content);
-            }
-            return resultData;
-        }
-        finally {
-            if (tmpDir) {
-                rmSync(tmpDir, { recursive: true, force: true });
-            }
-        }
-    }
-}
-// Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
-function applyCaptureMetadata(artifact, capture) {
-    const meta = artifact.metadata;
-    meta.capture_method = capture.captureMethod;
-    meta.docs_engine = capture.capabilities.docsEngine ?? null;
-    meta.docs_framework = capture.capabilities.framework ?? null;
-    meta.source_doc_url = capture.sourceDocUrl;
-    meta.search_provider = capture.capabilities.search?.provider ?? null;
-    if (capture.extraction.isIndexHub)
-        meta.artifact_type = 'index';
-    if (capture.sourceDocUrl && !meta.source_urls.includes(capture.sourceDocUrl)) {
-        meta.source_urls.push(capture.sourceDocUrl);
-    }
-}
-function handleStaleRevalidationResult(command, revalResult) {
-    if (revalResult.status !== 'stale')
-        return;
-    if (revalResult.allowed) {
-        command.warn(`Serving stale content: revalidation failed: ${revalResult.error}`);
-    }
-    else {
-        command.warn(`Serving stale content (exit 5): revalidation failed: ${revalResult.error}`);
-        process.exitCode = 5;
-    }
-}

package/dist/commands/search.d.ts

@@ -1,31 +0,0 @@
-import { BaseCommand } from '../base-command.js';
-export default class ResearchSearch extends BaseCommand<typeof ResearchSearch> {
-    static id: string;
-    static summary: string;
-    static description: string;
-    static args: {
-        query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static flags: {
-        topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | "section" | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
-        'include-stale': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        domain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        remote: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    static stdoutIsPrimaryData: boolean;
-    private validateSearchFlags;
-    private getSearchQueryTerms;
-    private matchesFilters;
-    private phraseMatchBonus;
-    private calculateScore;
-    private makeSnippet;
-    private scanCacheDirForResults;
-    private logSearchResults;
-    private printResults;
-    private executeSiteSearch;
-    private executeRemoteSearch;
-    run(): Promise<unknown>;
-}

package/dist/commands/search.js

@@ -1,329 +0,0 @@
-import { Args, Flags } from '@oclif/core';
-import { BaseCommand } from '../base-command.js';
-import { loadSearchableArtifacts } from '../lib/research/search-index.js';
-import { levenshtein, resultListHeading, truncationNotice, } from '../lib/text.js';
-import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { evaluateFreshness } from '../lib/research/freshness.js';
-import { detectSite } from '../sites/index.js';
-import { fetchStaticHtml, fetchText, postJson } from '../lib/research/fetcher.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 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: ['source', 'research_note', 'index', 'section'],
-        })(),
-        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 (e.g. help.salesforce.com) instead of the local cache. Requires a site module that implements search.',
-        }),
-        remote: Flags.string({
-            description: 'Discover uncached docs via a site’s public search or index (Algolia DocSearch, MkDocs/Sphinx/Just-the-Docs, llms.txt, sitemap.xml). Pass a docs page URL; falls back to local cache search if no connector applies.',
-        }),
-    };
-    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 });
-        }
-    }
-    getSearchQueryTerms(query) {
-        const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-        if (terms.length === 0) {
-            this.error('Query string cannot be empty.', { exit: 2 });
-        }
-        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.');
-            return;
-        }
-        this.log(`${resultListHeading(totalMatched, finalResults.length, SEARCH_LABELS)}\n`);
-        finalResults.forEach((res, index) => {
-            this.log(`${index + 1}. [${res.topic || 'No Topic'}] 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 });
-        }
-        if (!siteModule.search) {
-            this.error(`Site module '${siteModule.id}' does not implement search.`, { exit: 2 });
-        }
-        const results = await siteModule.search(query);
-        this.printResults(`Found ${results.length} results from ${siteModule.name}:\n`, results);
-        return results.map((r) => ({ ...r, site_module_id: siteModule.id }));
-    }
-    // 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 {
-            const { provider, results } = await runRemoteDocsSearch(docsUrl, query, REMOTE_SEARCH_DEPS);
-            this.printResults(`Found ${results.length} remote results via ${provider}:\n`, results);
-            return results.map((r) => ({ ...r, remote: true }));
-        }
-        catch (err) {
-            this.warn(`Remote docs search unavailable, using local cache: ${err.message}`);
-            return undefined;
-        }
-    }
-    async run() {
-        const { query } = this.args;
-        const { domain, remote } = this.flags;
-        if (domain) {
-            return this.executeSiteSearch(query, domain);
-        }
-        if (remote) {
-            const remoteResults = await this.executeRemoteSearch(query, remote);
-            if (remoteResults !== undefined)
-                return remoteResults;
-            // else: fall through to local cache search
-        }
-        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 {};