@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/lib/research/docs/validate.js

@@ -10,7 +10,11 @@ const ERROR_PAGE_PATTERNS = [
     /something\s+went\s+wrong/i,
     /an?\s+error\s+occurred/i,
 ];
-/** True when short text reads like an error/soft-404 page rather than real content. */
+/** True when short text reads like an error/soft-404 page rather than real content.
+ *
+ * @param text - Body text to inspect (only short bodies trigger the heuristic).
+ * @returns True when the text matches an error/soft-404 pattern.
+ */
 export function looksLikeErrorPage(text) {
     const trimmed = text.trim();
     // Only treat short bodies as errors; a long article mentioning "404" once is fine.
@@ -18,7 +22,12 @@ export function looksLikeErrorPage(text) {
         return false;
     return ERROR_PAGE_PATTERNS.some((re) => re.test(trimmed));
 }
-/** Same docs origin guard: a probed artifact must live on the same hostname as the page. */
+/** Same docs origin guard: a probed artifact must live on the same hostname as the page.
+ *
+ * @param candidateUrl - URL of the artifact to validate.
+ * @param baseUrl - URL of the original page being researched.
+ * @returns True when both URLs share the same hostname.
+ */
 export function isSameDocsOrigin(candidateUrl, baseUrl) {
     try {
         return new URL(candidateUrl).hostname === new URL(baseUrl).hostname;
@@ -31,6 +40,9 @@ const MIN_BODY_CHARS = 10;
 /**
  * Validates that an `llms.txt` or route-Markdown body is usable: non-empty, not an HTML page, and
  * not a soft error page. HTML returned for a `.md`/`.txt` probe is the most common false positive.
+ *
+ * @param body - Raw response body from the probe fetch.
+ * @returns `{ ok: true }` when the body is valid, or `{ ok: false, reason }` explaining the failure.
  */
 export function validateTextArtifact(body) {
     const trimmed = body.trim();
@@ -42,3 +54,36 @@ export function validateTextArtifact(body) {
         return { ok: false, reason: 'body looks like an error page' };
     return { ok: true };
 }
+const MARKDOWN_CONTENT_TYPE = 'text/markdown';
+/**
+ * Validates a probed `.md`-route response as a trustworthy Markdown twin, the shared trust
+ * contract behind both the developer.salesforce.com and help.salesforce.com twin probes: the
+ * server must label it `text/markdown`, the redirect chain must land on the expected host over
+ * https (never a plain-http downgrade or an on-path host), and the body must pass
+ * {@link validateTextArtifact} (non-empty, non-HTML, not a soft-error page). A 200 HTML "not
+ * found" shell — the most common false positive for a `.md` probe — fails the content-type check
+ * before the body is even inspected.
+ *
+ * @param res - The probe response's content-type, final URL after redirects, and body.
+ * @param allowedHost - Hostname the redirect chain must land on (compared case-insensitively).
+ * @returns True when the response is a trustworthy Markdown twin.
+ */
+export function isValidatedMarkdownTwin(res, allowedHost) {
+    if (!res.content)
+        return false;
+    const mediaType = (res.contentType?.split(';')[0] ?? '').trim().toLowerCase();
+    if (mediaType !== MARKDOWN_CONTENT_TYPE)
+        return false;
+    let finalUrl;
+    try {
+        finalUrl = new URL(res.finalUrl);
+    }
+    catch {
+        return false;
+    }
+    if (finalUrl.protocol !== 'https:' ||
+        finalUrl.hostname.toLowerCase() !== allowedHost.toLowerCase()) {
+        return false;
+    }
+    return validateTextArtifact(res.content).ok;
+}

package/dist/lib/research/extract.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Readability-extracted content from a page, ready to store as a research artifact.
+ * `confidence` reflects the extracted text length; `qualityNotes` carry stable `quality:*` codes
+ * for downstream agent use. `isIndexHub` is true when the page is a nav hub rather than an article.
+ */
 export interface ExtractionResult {
     title: string;
     detailedMarkdown: string;
@@ -5,7 +10,18 @@ export interface ExtractionResult {
     qualityNotes: string[];
     isIndexHub?: boolean;
 }
+/**
+ * Prefix marking a `qualityNotes` entry as human-prose worth surfacing on stderr (as opposed to
+ * the stable `quality:*` machine codes in the same array, which are for agents parsing `--json`).
+ */
+export declare const QUALITY_WARNING_PREFIX = "warning: ";
 /**
  * Extracts readerable content from an HTML document, sanitizes it, and converts it to detailed Markdown.
+ *
+ * @param html - Raw HTML of the page to extract.
+ * @param finalUrl - The resolved URL after any redirects; used to resolve relative links.
+ * @returns Extracted title, Markdown body, confidence level, quality notes, and index-hub flag.
+ * @throws {Error} When `finalUrl` is not a valid URL, or when Readability cannot parse any
+ *   article content from the page.
  */
 export declare function extractHtmlContent(html: string, finalUrl: string): ExtractionResult;

package/dist/lib/research/extract.js

@@ -40,12 +40,17 @@ function cleanUnsafeElements(document) {
         }
     }
 }
+/**
+ * Prefix marking a `qualityNotes` entry as human-prose worth surfacing on stderr (as opposed to
+ * the stable `quality:*` machine codes in the same array, which are for agents parsing `--json`).
+ */
+export const QUALITY_WARNING_PREFIX = 'warning: ';
 function determineConfidence(textLength) {
     const notes = ['readability extracted main article'];
     let confidence = 'high';
     if (textLength < 500) {
         confidence = 'low';
-        notes.push('warning: extracted content is very short (less than 500 characters)');
+        notes.push(`${QUALITY_WARNING_PREFIX}extracted content is very short (less than 500 characters)`);
     }
     else if (textLength < 2000) {
         confidence = 'medium';
@@ -54,6 +59,12 @@ function determineConfidence(textLength) {
 }
 /**
  * Extracts readerable content from an HTML document, sanitizes it, and converts it to detailed Markdown.
+ *
+ * @param html - Raw HTML of the page to extract.
+ * @param finalUrl - The resolved URL after any redirects; used to resolve relative links.
+ * @returns Extracted title, Markdown body, confidence level, quality notes, and index-hub flag.
+ * @throws {Error} When `finalUrl` is not a valid URL, or when Readability cannot parse any
+ *   article content from the page.
  */
 export function extractHtmlContent(html, finalUrl) {
     const { document } = parseHTML(html);

package/dist/lib/research/fetch-command-service.d.ts

@@ -0,0 +1,36 @@
+import type { StorageMode } from '../config/index.js';
+import { type CliIo } from './cli-io.js';
+/** Spinner port used while a fetch is in progress. */
+export interface FetchCommandSpinner {
+    running(): boolean;
+    start(msg: string): void;
+    stop(msg?: string): void;
+}
+/** Parsed flags for one fetch command invocation. */
+export interface FetchCommandFlags {
+    topic?: string;
+    tags?: string[];
+    format: 'compressed' | 'detailed';
+    tier: 'stable' | 'standard' | 'volatile';
+    ttl?: string;
+    maxAge?: string;
+    force: boolean;
+    allowStale: boolean;
+    rendered: boolean;
+    storage?: StorageMode;
+}
+/** Inputs for {@link runFetchCommandService}. */
+export interface FetchCommandServiceOptions {
+    urls: string[];
+    flags: FetchCommandFlags;
+    dryRun: boolean;
+    io: CliIo;
+    spinner: FetchCommandSpinner;
+}
+/** Reject invalid duration values and contradictory flag pairs before any URL work starts. */
+export declare function validateFetchCommandFlags(io: CliIo, flags: FetchCommandFlags): void;
+/**
+ * Fetch/serve each URL against the cache and return the command's `--json` data payload
+ * (a single row, or an array for multi-URL batches with failures kept as rows).
+ */
+export declare function runFetchCommandService(opts: FetchCommandServiceOptions): Promise<unknown>;

package/dist/lib/research/fetch-command-service.js

@@ -0,0 +1,310 @@
+import { Errors } from '@oclif/core';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { finalizeBatch } from '../batch.js';
+import { formatErrorForJson } from '../envelope.js';
+import { loadSummaryLevel } from '../config/index.js';
+import { buildFetchFailureFromCaught, buildFetchFailureResult, buildFetchResultData, describeError, extractionQualityWarnings, FETCH_STATUS_LABEL, fetchFailureGuidance, reportCacheStatus, } from './fetch-result.js';
+import { durationFlagError, evaluateFreshnessWithMaxAge } from './freshness.js';
+import { fetchRenderedHtml } from './browser.js';
+import { capturePage } from './capture.js';
+import { persistSectionArtifacts } from './docs/section-artifacts.js';
+import { fetchStaticHtml, fetchText } from './fetcher.js';
+import { applyAutoTags } from './keywords.js';
+import { persistArtifact } from './persist-artifact.js';
+import { createArtifactFromFetch, revalidateCache, } from './revalidate.js';
+import { resolveResearchTarget } from './resolve-target.js';
+import { failInvalidUrl } from './cli-io.js';
+import { batchSeparator } from '../cache-view.js';
+import { EXIT_STALE_SERVED } from '../cli-error-policy.js';
+import { detectSite } from '../../sites/index.js';
+import { applySiteFetchProvenance } from '../../sites/types.js';
+const CAPTURE_DEPS = {
+    fetchStatic: fetchStaticHtml,
+    fetchRendered: fetchRenderedHtml,
+    fetchText,
+};
+/** Reject invalid duration values and contradictory flag pairs before any URL work starts. */
+export function validateFetchCommandFlags(io, flags) {
+    for (const msg of [
+        durationFlagError('--ttl', flags.ttl),
+        durationFlagError('--max-age', flags.maxAge),
+    ]) {
+        if (msg)
+            io.error(msg, { exit: 2, code: 'INVALID_DURATION' });
+    }
+    // --force skips cache lookup; --allow-stale only applies when serving a stale entry after a
+    // failed revalidation. Together they are a no-op combination that looks intentional -- reject it.
+    if (flags.force && flags.allowStale) {
+        io.error('Cannot combine --force with --allow-stale: --force ignores the cache entirely.', {
+            exit: 2,
+            code: 'CONFLICTING_FLAGS',
+            suggestions: [
+                'Use --force to fetch fresh content, or omit --force if you want a stale entry served ' +
+                    'within grace (with --allow-stale suppressing the exit-5 signal).',
+            ],
+        });
+    }
+}
+/**
+ * Fetch/serve each URL against the cache and return the command's `--json` data payload
+ * (a single row, or an array for multi-URL batches with failures kept as rows).
+ */
+export async function runFetchCommandService(opts) {
+    const { dryRun, flags, io, spinner, urls } = opts;
+    const run = {
+        flags,
+        io,
+        spinner,
+        currentTime: new Date(),
+        tmpDir: dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null,
+        summaryLevel: loadSummaryLevel(io.configDir, io.cwd),
+        dryRun,
+        urlCount: urls.length,
+    };
+    try {
+        const results = [];
+        for (const url of urls) {
+            try {
+                results.push(await fetchSingleTarget(url, run));
+            }
+            catch (err) {
+                results.push(failureRowOrRethrow(url, err, run));
+            }
+        }
+        return finalizeBatch(results, (row) => 'error' in row);
+    }
+    finally {
+        if (run.tmpDir)
+            rmSync(run.tmpDir, { recursive: true, force: true });
+    }
+}
+async function executeCacheHit(cached, targetDir, run, secure) {
+    const { currentTime, flags, io } = run;
+    const freshnessState = evaluateFreshnessWithMaxAge(cached, currentTime, {
+        ttl: flags.ttl,
+        maxAge: flags.maxAge,
+    });
+    if (freshnessState === 'fresh') {
+        return { cacheStatus: 'hit', freshnessState, artifact: cached, redirectedToGlobal: false };
+    }
+    const revalidationResult = await revalidateCache(targetDir, cached, currentTime, {
+        allowStale: flags.allowStale,
+        ttlOverride: flags.ttl,
+        rendered: flags.rendered,
+        summaryLevel: run.summaryLevel,
+        secure,
+    });
+    if (revalidationResult.status === 'stale') {
+        const exitSuffix = revalidationResult.allowed ? '' : ` (exit ${EXIT_STALE_SERVED})`;
+        io.warn(`Serving stale content within grace period${exitSuffix}: revalidation failed (${revalidationResult.error}).`);
+        if (!revalidationResult.allowed)
+            process.exitCode = EXIT_STALE_SERVED;
+    }
+    if (revalidationResult.redirectWarning)
+        io.warn(revalidationResult.redirectWarning);
+    return {
+        cacheStatus: revalidationResult.status,
+        freshnessState,
+        artifact: revalidationResult.artifact,
+        storageDir: revalidationResult.storageDir,
+        redirectedToGlobal: Boolean(revalidationResult.redirectedToGlobal),
+    };
+}
+async function executeCacheMiss(normalizedUrl, cacheKey, run) {
+    const { currentTime, flags, summaryLevel } = run;
+    const siteModule = detectSite(normalizedUrl);
+    const useRendered = flags.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({
+        url: normalizedUrl,
+        normalizedUrl,
+        cacheKey,
+        fetchResult,
+        extraction,
+        tier: flags.tier,
+        ttl: flags.ttl || null,
+        currentTime,
+        summaryLevel,
+    });
+    artifact.metadata.topic = flags.topic || null;
+    artifact.metadata.tags = flags.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);
+}
+async function resolveArtifact(target, run) {
+    const { cacheKey, located, normalizedUrl, roots } = target;
+    if (located) {
+        // Revalidate where the entry already lives; on dry-run use the throwaway dir so the cache is
+        // never mutated. Project-located entries reuse persistArtifact (secret-scan + redirect) so a
+        // refresh that gains a credential cannot stay in the committable project cache (#90).
+        const revalDir = run.tmpDir ?? located.dataDir;
+        const projectLocated = located.dataDir === roots.writeRoot && roots.mode === 'project';
+        const secure = projectLocated
+            ? { roots, dryRun: Boolean(run.tmpDir), scratchDir: run.tmpDir }
+            : undefined;
+        const hit = await executeCacheHit(located.artifact, revalDir, run, secure);
+        return {
+            cacheStatus: hit.cacheStatus,
+            freshnessState: hit.freshnessState,
+            artifact: hit.artifact,
+            storageDir: hit.storageDir ?? located.dataDir,
+            redirectedToGlobal: hit.redirectedToGlobal,
+        };
+    }
+    const artifact = await executeCacheMiss(normalizedUrl, cacheKey, run);
+    const write = persistArtifact({
+        roots,
+        cacheKey,
+        artifact,
+        dryRun: Boolean(run.tmpDir),
+        kind: 'fetch',
+        scratchDir: run.tmpDir,
+    });
+    if (write.redirectWarning)
+        run.io.warn(write.redirectWarning);
+    // 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: write.dataDir,
+        redirectedToGlobal: write.redirected,
+    };
+}
+// Long references are split into searchable/inspectable section children whenever the page artifact
+// is freshly written (T-22).
+// ponytail: section persist is best-effort; failures are swallowed so chunking never fails the
+// parent fetch. Upgrade: surface section errors in warnings/envelope when agents need them.
+function persistSectionsIfFresh(targetDir, artifact, cacheStatus, run) {
+    if (cacheStatus !== 'miss' && cacheStatus !== 'refreshed')
+        return;
+    try {
+        persistSectionArtifacts(targetDir, artifact, run.currentTime, run.summaryLevel);
+    }
+    catch {
+        /* ignored — see ponytail note above */
+    }
+}
+function failureRowOrRethrow(url, err, run) {
+    const { dryRun, io, spinner } = run;
+    // Invalid URLs fail before ux.action.start; stopping a never-started spinner prints noise.
+    if (!io.json && spinner.running())
+        spinner.stop('failed');
+    if (run.urlCount === 1) {
+        if (err instanceof Errors.CLIError)
+            throw err;
+        // Deep fetch/extract throws plain Errors; re-emit with actionable next steps.
+        const message = describeError(err);
+        const guidance = fetchFailureGuidance(message, url, io.bin);
+        io.error(message, {
+            exit: 1,
+            code: 'FETCH_FAILED',
+            suggestions: guidance?.suggestions,
+            ref: guidance?.ref,
+        });
+    }
+    const row = err instanceof Errors.CLIError
+        ? buildFetchFailureResult({ url, dryRun, err })
+        : buildFetchFailureFromCaught(io.bin, url, err, dryRun);
+    // Human batches only get the spinner "failed" label unless we echo the reason. Mirror the
+    // single-URL error format (message + Code: + Try this:) rather than a bare message, so a row
+    // failure in a batch is exactly as actionable as it is standalone.
+    if (!io.json)
+        io.warn(formatErrorForJson(row.error));
+    return row;
+}
+async function fetchSingleTarget(url, run) {
+    const { dryRun, flags, io, spinner } = run;
+    let target;
+    try {
+        target = resolveResearchTarget({
+            configDir: io.configDir,
+            cwd: io.cwd,
+            dataDir: io.dataDir,
+            url,
+            flagOverride: flags.storage,
+            lookup: !flags.force,
+        });
+    }
+    catch (err) {
+        failInvalidUrl(io.error, url, err.message);
+    }
+    const { cacheKey, normalizedUrl, roots } = target;
+    if (!io.json) {
+        spinner.start('Fetching ' + normalizedUrl);
+    }
+    const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await resolveArtifact(target, run);
+    persistSectionsIfFresh(run.tmpDir ?? storageDir, artifact, cacheStatus, run);
+    if (!io.json) {
+        spinner.stop(FETCH_STATUS_LABEL[reportCacheStatus(cacheStatus, dryRun)]);
+    }
+    const resultData = buildFetchResultData({
+        url,
+        normalizedUrl,
+        cacheKey,
+        storageDir,
+        storageMode: roots.mode,
+        cacheStatus,
+        freshnessState,
+        format: flags.format,
+        artifact,
+        redirectedToGlobal,
+        dryRun,
+    });
+    if (!io.json) {
+        if (dryRun && cacheStatus !== 'hit' && cacheStatus !== 'stale') {
+            io.log('[dry-run] Preview only — cache was not written.');
+        }
+        for (const warning of extractionQualityWarnings(resultData.source.qualityNotes)) {
+            io.warn(`${normalizedUrl}: ${warning}`);
+        }
+        io.log(resultData.content);
+        const separator = batchSeparator(run.urlCount > 1);
+        if (separator) {
+            io.log(`\n${separator}\n`);
+        }
+    }
+    return resultData;
+}
+// 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);
+    }
+}

package/dist/lib/research/fetch-result.d.ts

@@ -0,0 +1,114 @@
+import type { StorageMode } from '../config/index.js';
+import type { CacheHitStatus, FreshnessState } from '../cli-result-types.js';
+import type { ResearchArtifact } from './schema.js';
+import { type CliErrorShape } from '../envelope.js';
+/**
+ * Human-prose warnings pulled out of `qualityNotes` (e.g. very-short extraction). The remaining
+ * `quality:*` machine codes stay `--json`-only; this is what stderr shows in human-readable mode.
+ */
+export declare function extractionQualityWarnings(qualityNotes: readonly string[]): string[];
+/** Cache status as reported to users: dry-run remaps write-implying statuses to `would_*`. */
+export type ReportedCacheStatus = CacheHitStatus | 'would_fetch' | 'would_refresh' | 'would_revalidate';
+/** Remap write-implying cache statuses when dry-run/read-only skipped persistence. */
+export declare function reportCacheStatus(status: CacheHitStatus, dryRun: boolean): ReportedCacheStatus;
+/** Human spinner labels for reported (possibly remapped) cache statuses. */
+export declare const FETCH_STATUS_LABEL: Record<ReportedCacheStatus, string>;
+export interface FetchResultInput {
+    url: string;
+    normalizedUrl: string;
+    cacheKey: string;
+    storageDir: string;
+    storageMode: StorageMode;
+    cacheStatus: CacheHitStatus;
+    freshnessState: FreshnessState;
+    format: 'compressed' | 'detailed';
+    artifact: Pick<ResearchArtifact, 'metadata' | 'compressed' | 'detailed'>;
+    redirectedToGlobal: boolean;
+    dryRun: boolean;
+}
+/** Machine-readable success/preview payload for one fetch URL. */
+export declare function buildFetchResultData(input: FetchResultInput): {
+    schemaVersion: number;
+    command: string;
+    dryRun: boolean;
+    cache: {
+        key: string;
+        status: ReportedCacheStatus;
+        freshness: FreshnessState;
+        path: string;
+        storage: StorageMode;
+        redirectedToGlobal: boolean;
+    };
+    source: {
+        url: string;
+        normalizedUrl: string;
+        captureMethod: "static_fetch" | "browser_fallback" | "agent_supplied" | "route_markdown" | "github_source" | null;
+        extractionStatus: "agent_supplied" | "extracted" | "failed" | null;
+        extractionConfidence: "high" | "medium" | "low" | null;
+        qualityNotes: string[];
+        fetchedAt: string | null;
+        validatedAt: string | null;
+        staleAfter: string | null;
+    };
+    artifactType: "source" | "research_note" | "index" | "section";
+    docsEngine: string | null;
+    docsFramework: string | null;
+    sourceDocUrl: string | null;
+    searchProvider: string | null;
+    format: "compressed" | "detailed";
+    tokenEstimate: number | null;
+    content: string;
+};
+export interface FetchFailureGuidance {
+    suggestions?: string[];
+    ref?: string;
+}
+/** Per-URL failure row for multi-URL batches — keeps prior successes in `data`. */
+export declare function buildFetchFailureResult(input: {
+    url: string;
+    dryRun: boolean;
+    err: CliErrorShape;
+    fallbackGuidance?: FetchFailureGuidance;
+}): {
+    schemaVersion: number;
+    command: string;
+    dryRun: boolean;
+    error: {
+        code: string;
+        message: string;
+        suggestions?: string[];
+        ref?: string;
+    };
+    cache: null;
+    source: {
+        url: string;
+        normalizedUrl: null;
+    };
+    content: null;
+};
+/**
+ * Shape a caught runtime error into a batch failure row (message + guidance).
+ * CLIError rows should call {@link buildFetchFailureResult} directly so oclif fields are preserved.
+ */
+export declare function buildFetchFailureFromCaught(bin: string, url: string, err: unknown, dryRun: boolean): {
+    schemaVersion: number;
+    command: string;
+    dryRun: boolean;
+    error: {
+        code: string;
+        message: string;
+        suggestions?: string[];
+        ref?: string;
+    };
+    cache: null;
+    source: {
+        url: string;
+        normalizedUrl: null;
+    };
+    content: null;
+};
+export declare function describeError(err: unknown): string;
+export declare function fetchFailureGuidance(message: string, url: string, bin?: string): {
+    suggestions: string[];
+    ref?: string;
+} | undefined;