@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/commands/fetch.js

@@ -1,38 +1,21 @@
-import { Args, Flags, ux, Errors } from '@oclif/core';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { Args, Flags, ux } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
-import { writeArtifact, getArtifactPath } from '../lib/research/storage.js';
-import { writeArtifactSecurely } from '../lib/research/secure-write.js';
-import { loadSummaryLevel } from '../lib/config/index.js';
-import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
-import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
-import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
-import { PROXY_TUNNEL_REJECTION_PATTERN } from '../lib/research/proxy.js';
-import { fetchRenderedHtml, SANDBOX_EGRESS_ERROR_MARKER } from '../lib/research/browser.js';
-import { capturePage } from '../lib/research/capture.js';
-import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
-import { applyAutoTags } from '../lib/research/keywords.js';
-import { detectSite } from '../sites/index.js';
-import { applySiteFetchProvenance } from '../sites/types.js';
-const CAPTURE_DEPS = {
-    fetchStatic: (url) => fetchStaticHtml(url),
-    fetchRendered: (url) => fetchRenderedHtml(url),
-    fetchText: (url) => fetchText(url),
-};
+import { enrichRowErrorEnvelope } from '../lib/envelope.js';
+import { runFetchCommandService, validateFetchCommandFlags, } from '../lib/research/fetch-command-service.js';
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+/** Hidden named `fetch` command; usually invoked as `bonsai <url>`. */
 export default class FetchCommand extends BaseCommand {
     static id = 'fetch';
     static hidden = true;
-    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.\n\nUsually invoked via the shorthand `bonsai <url>` rather than `bonsai fetch <url>`.';
+    static summary = 'Fetch and cache URL research Markdown';
+    static description = 'Fetch a URL, convert the main content to Markdown, and cache compressed and detailed variants.\n\nUsually invoked as `bonsai <url>`; run `bonsai help fetch` for URL-form flags.';
     static examples = [
         {
-            description: 'research a URL with detailed output, tagged with topic and tags',
-            command: '<%= config.bin %> https://docs.nestjs.com/ --topic "Backend Frameworks" --tags "Node" --tags "NestJS" --format detailed --ttl 30d',
+            description: 'cache docs with detailed output, topic, tags, and TTL',
+            command: '<%= config.bin %> https://docs.nestjs.com/ --topic "Backend Frameworks" --tags "Node" --tags "NestJS" --format detailed --ttl 7d',
         },
         {
-            description: 'research a volatile page with compressed output and short TTL, returned as JSON',
+            description: 'cache a volatile page with compressed JSON output',
             command: '<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json',
         },
     ];
@@ -40,425 +23,99 @@ export default class FetchCommand extends BaseCommand {
     static args = {
         url: Args.string({
             required: true,
-            description: 'the full HTTP/HTTPS URL of the web page to research',
+            description: 'HTTP(S) URL to research',
         }),
     };
     static flags = {
         topic: Flags.string({
             char: 't',
-            description: 'the main category/topic of the research for metadata tagging',
+            description: CLI_FLAG_DESCRIPTIONS.fetchTopic,
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'taxonomic tags for this research (can be repeated)',
+            description: CLI_FLAG_DESCRIPTIONS.fetchTags,
             multiple: true,
         }),
         format: Flags.option({
             char: 'f',
-            description: 'desired data density',
+            description: CLI_FLAG_DESCRIPTIONS.format,
             options: ['compressed', 'detailed'],
             default: 'compressed',
         })(),
         tier: Flags.option({
-            description: 'freshness tier policy',
+            description: CLI_FLAG_DESCRIPTIONS.freshnessTierPolicy,
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m"',
+            description: CLI_FLAG_DESCRIPTIONS.fetchTtl,
         }),
         'max-age': Flags.string({
-            description: 'maximum age of cache to accept (e.g., "1d", "30d")',
+            description: CLI_FLAG_DESCRIPTIONS.maxAge,
         }),
         force: Flags.boolean({
-            description: 'force a fresh fetch, ignoring any cached entries',
+            description: 'fetch fresh content, ignoring cached entries',
             default: false,
         }),
         'dry-run': Flags.boolean({
-            description: 'perform validation and fetch without saving to local cache',
+            description: 'fetch and validate without writing cache',
             default: false,
         }),
         'allow-stale': Flags.boolean({
-            description: 'allow serving stale cache if the remote server is unreachable',
+            // Stale content within the grace window is served either way after a failed revalidation;
+            // this only suppresses the exit-5 "served stale" signal. It has no effect once an entry is
+            // past its grace window (that failure is always a hard error). See README's Freshness
+            // section and docs/concepts/caching-and-freshness.md for the full decision flow.
+            description: 'suppress exit code 5 when stale cache is served within grace after failed revalidation',
             default: false,
         }),
         rendered: Flags.boolean({
-            description: 'force using a browser-rendered scraping path for dynamic pages',
+            description: 'use browser-rendered capture for dynamic pages',
             default: false,
         }),
         storage: Flags.option({
-            description: 'override where this result is cached (secrets always stored globally)',
+            description: CLI_FLAG_DESCRIPTIONS.fetchStorage,
             options: ['global', 'project'],
         })(),
     };
     static stdoutIsPrimaryData = true;
-    envelopeCommandId() {
-        return this.config.bin;
-    }
-    async executeCacheHit(cached, targetDir, currentTime, summaryLevel) {
-        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),
-            summaryLevel,
-        });
-        handleStaleRevalidationResult(this, revalResult);
+    /**
+     * When a multi-URL batch has any per-URL failure, keep the result array (including hits) and
+     * surface FETCH_FAILED on the envelope — same batch contract as status/inspect CACHE_MISS.
+     */
+    toSuccessJson(data) {
+        return enrichRowErrorEnvelope(this.baseSuccessJson(data), data);
+    }
+    serviceFlags() {
         return {
-            cacheStatus: revalResult.status,
-            freshnessState,
-            artifact: revalResult.artifact,
+            topic: this.flags.topic,
+            tags: this.flags.tags,
+            format: this.flags.format,
+            tier: this.flags.tier,
+            ttl: this.flags.ttl,
+            maxAge: this.flags['max-age'],
+            force: this.flags.force,
+            allowStale: this.flags['allow-stale'],
+            rendered: this.flags.rendered,
+            storage: this.flags.storage,
         };
     }
-    async executeCacheMiss(normalizedUrl, currentTime, cacheKey, summaryLevel) {
-        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;
-        let siteFetch = null;
-        if (siteModule?.fetchPage) {
-            // Custom site modules own their fetch/extract strategy; the generic capture path is skipped.
-            siteFetch = await siteModule.fetchPage(normalizedUrl);
-            ({ fetchResult, extraction } = siteFetch);
-        }
-        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, summaryLevel);
-        artifact.metadata.topic = topic || null;
-        artifact.metadata.tags = tags || [];
-        artifact.metadata.site_module_id = siteModule?.id ?? null;
-        if (capture) {
-            applyCaptureMetadata(artifact, capture);
-        }
-        else if (siteFetch?.captureMethod) {
-            applySiteFetchProvenance(artifact.metadata, siteFetch);
-        }
-        else if (useRendered) {
-            artifact.metadata.capture_method = 'browser_fallback';
-        }
-        // Auto-tag from the fetched content when the caller supplied none, keeping cached pages
-        // searchable by keyword. Explicit --tags always win (handled in applyAutoTags).
-        return applyAutoTags(artifact);
-    }
-    buildResultData(url, normalizedUrl, cacheKey, storageDir, storageMode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal) {
-        return {
-            schemaVersion: 1,
-            command: this.config.bin,
-            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 msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
-            if (msg)
-                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
-        }
-    }
-    // Re-emit a runtime fetch failure with actionable next steps. Deep fetch/extract code throws plain
-    // Errors that otherwise reach the user as a bare "what broke" line with no "what to do"; this
-    // attaches recovery hints (e.g. import an auth-blocked page). Everything reaching here is a runtime
-    // failure — validation errors (bad flags/URL) exit before the try — so the contract's runtime code
-    // (1) applies. Suggestions render on stderr for humans only; under --json the envelope carries just
-    // the message (toErrorJson), so machine output is unchanged.
-    //
-    // Uses `describeError` (below) rather than `err.message` alone: Node/undici's fetch wraps
-    // transport failures (DNS, refused connections, a proxy that won't tunnel to the host) in a
-    // generic "fetch failed" TypeError with the real reason nested in `.cause`, so reading only the
-    // top message would surface a content-free "fetch failed" for exactly the failures a user most
-    // needs a hint for.
-    emitFetchError(err, url) {
-        const message = describeError(err);
-        const guidance = fetchFailureGuidance(message, url);
-        this.error(message, {
-            exit: 1,
-            code: 'FETCH_FAILED',
-            suggestions: guidance?.suggestions,
-            ref: guidance?.ref,
-        });
-    }
-    // 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, located, summaryLevel) {
-        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, summaryLevel);
-            return { ...hit, storageDir: located.dataDir, redirectedToGlobal: false };
-        }
-        const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey, summaryLevel);
-        const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
-        // No entry existed at lookup, so there is no prior freshness to report. 'none' (not
-        // 'stale_expired') keeps the field honest — nothing expired; the page was simply uncached and
-        // has now been fetched fresh. Mirrors the `status` command's miss reporting.
-        return {
-            cacheStatus: 'miss',
-            freshnessState: 'none',
-            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 `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, summaryLevel) {
-        if (cacheStatus !== 'miss' && cacheStatus !== 'refreshed')
-            return;
-        try {
-            persistSectionArtifacts(targetDir, artifact, currentTime, summaryLevel);
-        }
-        catch {
-            /* section generation is non-essential; ignore failures */
-        }
-    }
     async run() {
-        const urls = this.parsedArgv;
-        const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
-        this.validateDurationFlags(ttl, maxAge);
-        const summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
-        const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
-        const currentTime = new Date();
-        const results = [];
-        try {
-            for (const url of urls) {
-                results.push(await this.fetchSingleTarget(url, currentTime, tmpDir, summaryLevel, format, urls.length > 1));
-            }
-            return urls.length === 1 ? results[0] : results;
-        }
-        catch (err) {
-            if (!this.jsonEnabled()) {
-                ux.action.stop('failed');
-            }
-            if (err instanceof Errors.CLIError)
-                throw err;
-            // Stale-serve (exit 5) signals via process.exitCode and never throws, so it bypasses this
-            // path; only genuine fetch/extract failures land here and get classified guidance. Use the
-            // normalized URL in hints so the copy-paste command is canonical (and never echoes raw,
-            // unsanitized user input back to the terminal).
-            const failedUrl = urls[results.length] || urls[0] || '';
-            this.emitFetchError(err, failedUrl);
-        }
-        finally {
-            if (tmpDir) {
-                rmSync(tmpDir, { recursive: true, force: true });
-            }
-        }
-    }
-    async fetchSingleTarget(url, currentTime, tmpDir, summaryLevel, format, showSeparator) {
-        const target = this.resolveResearchTargetOrFail(url, {
-            flagOverride: this.flags.storage,
-            lookup: !this.flags.force,
+        const io = this.cliIo();
+        const flags = this.serviceFlags();
+        validateFetchCommandFlags(io, flags);
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
+        return runFetchCommandService({
+            urls: this.parsedArgv,
+            flags,
+            dryRun,
+            io,
+            spinner: {
+                running: () => Boolean(ux.action.running),
+                start: (msg) => ux.action.start(msg),
+                stop: (msg) => ux.action.stop(msg),
+            },
         });
-        const { cacheKey, located, normalizedUrl, roots } = target;
-        if (!this.jsonEnabled()) {
-            ux.action.start('Fetching ' + normalizedUrl);
-        }
-        const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
-        this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
-        if (!this.jsonEnabled()) {
-            const CACHE_STATUS_LABEL = {
-                hit: 'cached',
-                miss: 'done',
-                refreshed: 'refreshed',
-                revalidated: 'revalidated',
-                stale: 'served stale',
-            };
-            ux.action.stop(CACHE_STATUS_LABEL[cacheStatus] ?? 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.jsonEnabled()) {
-            this.log(content);
-            if (showSeparator) {
-                this.log('\n' + '='.repeat(40) + '\n');
-            }
-        }
-        return resultData;
-    }
-}
-// How many `.cause` levels to walk. Real undici/Node transport errors nest at most 1-2 deep;
-// the cap exists so a self-referential or cyclic `.cause` chain (Error.cause is an arbitrary,
-// unvalidated property — nothing prevents `e.cause = e`, whether from a bug in this codebase or
-// a dependency) can't hang the process, rather than being a limit expected to matter in practice.
-const MAX_CAUSE_DEPTH = 10;
-// Walks an Error's `.cause` chain and joins every message, deepest last. Node/undici's fetch
-// throws a generic `TypeError: fetch failed` for transport-level failures, with the actionable
-// detail (e.g. a proxy's tunnel rejection) nested one or two `.cause` levels down.
-export function describeError(err) {
-    if (!(err instanceof Error))
-        return String(err);
-    const parts = [err.message];
-    let cause = err.cause;
-    for (let depth = 0; depth < MAX_CAUSE_DEPTH && cause instanceof Error; depth++) {
-        parts.push(cause.message);
-        cause = cause.cause;
-    }
-    return parts.join(': ');
-}
-// Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
-// unrecognized failures, which then surface with their original message and no extra hint. The
-// patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
-// change. Resolutions mirror the published troubleshooting guide.
-export function fetchFailureGuidance(message, url) {
-    const ref = 'https://bonsai.rhino-inquisitor.com/troubleshooting';
-    // Name the pipe step explicitly: bare `import --stdin` blocks waiting for input, so a reader (or
-    // an agent) running the hint verbatim would hang. Show the content being piped in from a file.
-    const importHint = `Open it in a browser, save the page, then import it: cat page.md | bonsai import ${url} --stdin`;
-    // 401/403: an auth wall or anti-scraping WAF. Bonsai has no authenticated-fetch path in v1.
-    if (/failed with status 40[13]\b/.test(message)) {
-        return {
-            suggestions: ['The page requires authentication or blocks automated requests.', importHint],
-            ref,
-        };
-    }
-    if (/failed with status 404\b/.test(message)) {
-        return { suggestions: ['Check the URL is correct and the page still exists.'] };
-    }
-    if (/failed with status 5\d\d\b/.test(message)) {
-        return {
-            suggestions: ['The server returned an error. Retry later or verify the host is healthy.'],
-        };
-    }
-    // Server returned a non-HTML body (JSON, binary, or no Content-Type at all). Scope the opener to
-    // the real failure: --rendered does produce HTML, so "only scrapes HTML" would read as misleading.
-    if (/Rejected content type|does not look like HTML/.test(message)) {
-        return {
-            suggestions: [
-                'The server returned a non-HTML response (e.g. JSON or binary).',
-                'If the page is rendered by client-side JavaScript, retry with --rendered.',
-                importHint,
-            ],
-            ref,
-        };
-    }
-    if (/DNS resolution failed/.test(message)) {
-        return {
-            suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
-        };
-    }
-    // Chrome's own network stack hit a proxy-enforced sandbox egress block (browser.ts's
-    // describeNavigationFailure already explains the cause and the fix); only a workaround and the
-    // docs ref are added here.
-    if (message.includes(SANDBOX_EGRESS_ERROR_MARKER)) {
-        return { suggestions: [importHint], ref };
-    }
-    // A configured proxy (HTTPS_PROXY/HTTP_PROXY) refused to tunnel to this host — distinct from
-    // the destination's own 401/403 above, which is the site itself rejecting the request. Shared
-    // with fetcher.ts's retry-fallback check so the two stay in sync by construction.
-    if (PROXY_TUNNEL_REJECTION_PATTERN.test(message)) {
-        return {
-            suggestions: [
-                "The configured proxy (HTTPS_PROXY/HTTP_PROXY) won't reach this host. Check its allowlist, or add the host to NO_PROXY to bypass the proxy for it.",
-                importHint,
-            ],
-            ref,
-        };
-    }
-    // The connection failed before any HTTP response was received — network-down, DNS, TLS, or a
-    // proxy issue not specifically matched above. Node/undici's fetch reports all of these as a
-    // generic "fetch failed" TypeError with no further suffix; the negative lookahead keeps this
-    // from also matching assertOk's "Fetch failed with status NNN ..." (a real HTTP response was
-    // received in that case, so it isn't a transport failure at all).
-    if (/^fetch failed\b(?!\s+with status)/i.test(message)) {
-        return {
-            suggestions: [
-                'The connection failed before a response was received. Check network connectivity and any HTTPS_PROXY/HTTP_PROXY/NO_PROXY settings.',
-                importHint,
-            ],
-            ref,
-        };
-    }
-    // A hostname that only resolves to a private/local IP at request time (literal private addresses
-    // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
-    if (/blocked local or private target/.test(message)) {
-        return {
-            suggestions: [
-                'The hostname resolves to a private or local address, which is blocked to prevent SSRF. Only public http(s) hosts can be fetched.',
-            ],
-            ref,
-        };
-    }
-    return undefined;
-}
-// 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 within grace period: revalidation failed (${revalResult.error}).`);
-    }
-    else {
-        command.warn(`Serving stale content within grace period (exit 5): revalidation failed (${revalResult.error}).`);
-        process.exitCode = 5;
     }
 }

package/dist/commands/import.d.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs';
 import { BaseCommand } from '../base-command.js';
+/** Import research notes from a file or stdin. */
 export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
     static id: string;
     static summary: string;
@@ -20,22 +21,16 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
         tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
         'source-url': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ttl: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
     protected stdinIsInteractive(): boolean;
     private readStdin;
-    private getSourceUrls;
-    private validateSourceMode;
     protected fsExistsSync(filePath: string): boolean;
     protected fsStatSync(filePath: string): fs.Stats;
     protected fsReadFileSync(filePath: string): string;
-    private stdinImportSuggestions;
-    /** Non-interactive stdin that never receives data (open pipe with no writer) must not hang forever. */
-    private readStdinWithGuard;
-    private readAndValidateFile;
-    private readAndValidateInput;
-    private deriveImportCacheKey;
-    private buildImportArtifact;
+    private serviceArgs;
+    private serviceFlags;
     run(): Promise<unknown>;
 }