@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/lib/research/docs/source-map.js

@@ -5,6 +5,9 @@ const GITHUB_EDIT_BLOB = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:edit|blo
 /**
  * Converts a GitHub `edit`/`blob` URL into a raw.githubusercontent.com URL. Returns null for any
  * URL that is not a recognized GitHub edit/blob link, so callers never fabricate a raw URL.
+ *
+ * @param href - A GitHub edit or blob URL (or any other string).
+ * @returns A GithubSource candidate, or null when `href` is not a recognized edit/blob link.
  */
 export function parseGithubSourceLink(href) {
     const match = href.match(GITHUB_EDIT_BLOB);
@@ -25,6 +28,13 @@ export function parseGithubSourceLink(href) {
 // Node.js API docs: https://nodejs.org/api/url.html -> nodejs/node/doc/api/url.md on the release
 // line. Deterministic and fixture-proven; mapping is advertised only after a successful fetch.
 const NODE_API = /^https?:\/\/nodejs\.org\/(?:[a-z-]+\/)?(?:docs\/)?(?:latest(?:-v\d+\.x)?\/)?api\/([a-z_]+)\.html/i;
+/**
+ * Maps a Node.js API docs URL to its source file in the nodejs/node GitHub repository.
+ * Returns null when the URL is not a recognized Node.js API page.
+ *
+ * @param url - A nodejs.org API documentation URL.
+ * @returns A GithubSource candidate, or null for unrecognized URLs.
+ */
 export function mapNodeApiSource(url) {
     const match = url.match(NODE_API);
     if (!match)
@@ -41,6 +51,13 @@ export function mapNodeApiSource(url) {
 // MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/...  ->  mdn/content
 // files/en-us/web/javascript/.../index.md (content paths are lowercased).
 const MDN_DOCS = /^https?:\/\/developer\.mozilla\.org\/([a-zA-Z-]+)\/docs\/(.+?)\/?$/;
+/**
+ * Maps an MDN developer.mozilla.org URL to its source file in the mdn/content GitHub repository.
+ * Returns null when the URL is not a recognized MDN docs page.
+ *
+ * @param url - An MDN documentation URL.
+ * @returns A GithubSource candidate, or null for unrecognized URLs.
+ */
 export function mapMdnSource(url) {
     const match = url.match(MDN_DOCS);
     if (!match)
@@ -59,6 +76,13 @@ export function mapMdnSource(url) {
 }
 // VitePress route Markdown: a docs page at /guide/intro.html (or /guide/intro) also serves
 // /guide/intro.md. Returns the candidate `.md` route URL; validate before use (T-24/T-19).
+/**
+ * Derives the candidate `.md` route URL for a VitePress page. Returns null when the URL already
+ * ends with `.md` or cannot be parsed. The result is a candidate that must be validated by fetching.
+ *
+ * @param url - A VitePress documentation page URL.
+ * @returns The derived `.md` route URL, or null for non-applicable URLs.
+ */
 export function vitepressRouteMarkdown(url) {
     let parsed;
     try {
@@ -81,6 +105,9 @@ export function vitepressRouteMarkdown(url) {
 /**
  * Tries every known URL->source mapper in turn. Returns the first candidate, or null. The result
  * is a CANDIDATE; it must be validated by fetching before being recorded as a verified source.
+ *
+ * @param url - A documentation page URL to map.
+ * @returns The first GithubSource candidate, or null when no mapper recognizes the URL.
  */
 export function mapUrlToSource(url) {
     return mapNodeApiSource(url) ?? mapMdnSource(url);

package/dist/lib/research/docs/validate.d.ts

@@ -1,13 +1,46 @@
+/** Result of validating a machine-readable artifact body. `reason` is set when `ok` is false. */
 export interface ArtifactValidation {
     ok: boolean;
     reason?: string;
 }
-/** 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 declare function looksLikeErrorPage(text: string): boolean;
-/** 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 declare function isSameDocsOrigin(candidateUrl: string, baseUrl: string): boolean;
 /**
  * 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 declare function validateTextArtifact(body: string): ArtifactValidation;
+/** The subset of a fetch response a Markdown-twin probe needs to validate. */
+export interface MarkdownTwinResponse {
+    contentType: string | null;
+    finalUrl: string;
+    content: string;
+}
+/**
+ * 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 declare function isValidatedMarkdownTwin(res: MarkdownTwinResponse, allowedHost: string): boolean;

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);
+    }
+}