@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/lib/prune-flags.js

@@ -0,0 +1,74 @@
+import { emptyUrlFilterError } from './research/url.js';
+import { durationFlagError } from './research/freshness.js';
+function missingFilterError(input) {
+    // Treat an explicitly passed empty string as "filter was attempted" so `--older-than ''`
+    // is not misreported as MISSING_FILTER (durationError rejects it as INVALID_DURATION).
+    if (input.olderThan !== undefined ||
+        input.inactive !== undefined ||
+        input.artifactType !== undefined ||
+        input.url !== undefined) {
+        return null;
+    }
+    return {
+        message: 'Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, or --url.',
+        code: 'MISSING_FILTER',
+        suggestions: [`Preview age-based pruning: ${input.bin} prune --older-than 30d --dry-run`],
+    };
+}
+/**
+ * Mutation-gate checks. READ_ONLY before --dry-run/--yes conflict so
+ * `--dry-run --yes --read-only` reports the more specific READ_ONLY_MODE code.
+ */
+function mutationSafetyError(input) {
+    if (input.readOnly && input.yes) {
+        return {
+            message: '--yes cannot be used while read-only mode is active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): mutations are disabled.',
+            code: 'READ_ONLY_MODE',
+            suggestions: [`Preview instead: ${input.bin} prune --dry-run`],
+        };
+    }
+    if (input.dryRun && input.yes) {
+        return {
+            message: '--dry-run and --yes are mutually exclusive: --dry-run previews without deleting, --yes confirms deletion. Choose one.',
+            code: 'CONFLICTING_FLAGS',
+            suggestions: [
+                `Preview without deleting: ${input.bin} prune --dry-run`,
+                `Or confirm deletion: ${input.bin} prune --yes`,
+            ],
+        };
+    }
+    // Read-only mode implicitly previews, so the usual "pick one" safety check is redundant then.
+    if (!input.readOnly && !input.dryRun && !input.yes) {
+        const olderThanPart = input.olderThan ? ` --older-than ${input.olderThan}` : '';
+        const urlPart = input.url ? ` --url "${input.url}"` : '';
+        return {
+            message: 'Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.',
+            code: 'SAFETY_CHECK_REQUIRED',
+            suggestions: [`Preview first: ${input.bin} prune --dry-run${olderThanPart}${urlPart}`],
+        };
+    }
+    return null;
+}
+function durationError(input) {
+    for (const msg of [
+        durationFlagError('--older-than', input.olderThan),
+        durationFlagError('--inactive', input.inactive),
+    ]) {
+        if (msg)
+            return { message: msg, code: 'INVALID_DURATION' };
+    }
+    return null;
+}
+/**
+ * Return the first prune usage/safety error, or `null` when flags are valid.
+ *
+ * @param input - Parsed prune flags and binary name.
+ * @returns Error descriptor for `this.error`, or `null`.
+ */
+export function pruneFlagError(input) {
+    const urlErr = emptyUrlFilterError(input.url);
+    if (urlErr)
+        return { message: urlErr, code: 'INVALID_FLAG_VALUE' };
+    // Duration before missing-filter so `--older-than ''` reports INVALID_DURATION, not MISSING_FILTER.
+    return durationError(input) ?? missingFilterError(input) ?? mutationSafetyError(input);
+}

package/dist/lib/research/artifact-index.d.ts

@@ -3,16 +3,25 @@ export interface IndexedArtifact {
     artifact: ResearchArtifact;
     filePath: string;
 }
+export interface LoadIndexedArtifactsOptions {
+    /**
+     * When false, skip writing `.search-index.json` (read-only/plan mode). Results are still
+     * computed from disk; only the derived sidecar is withheld. Defaults to true.
+     */
+    persist?: boolean;
+}
 /**
  * Returns the indexed view of every active artifact in one research dir, using the sidecar index
  * to skip unchanged files. Re-reads only files whose signature changed, then persists the refreshed
  * index (best-effort; a write failure never breaks callers). Corrupt/unreadable files are skipped —
  * the real read paths in storage.ts handle archiving them.
+ *
+ * Pass `{ persist: false }` under read-only/plan mode so the derived sidecar is never written.
  */
-export declare function loadIndexedArtifactsForDir(researchDir: string): IndexedArtifact[];
+export declare function loadIndexedArtifactsForDir(researchDir: string, options?: LoadIndexedArtifactsOptions): IndexedArtifact[];
 /**
  * Multi-root variant: scans the `research/` dir of each data dir in order and deduplicates by cache
  * key so a project entry shadows the same key in the global cache. Mirrors the dedup semantics of
  * {@link scanCacheDirs} but reads through the per-root sidecar index.
  */
-export declare function loadIndexedArtifacts(dataDirs: string[]): IndexedArtifact[];
+export declare function loadIndexedArtifacts(dataDirs: string[], options?: LoadIndexedArtifactsOptions): IndexedArtifact[];

package/dist/lib/research/artifact-index.js

@@ -52,10 +52,13 @@ function getOrUpdateIndexEntry(filePath, cached, onChanged) {
  * to skip unchanged files. Re-reads only files whose signature changed, then persists the refreshed
  * index (best-effort; a write failure never breaks callers). Corrupt/unreadable files are skipped —
  * the real read paths in storage.ts handle archiving them.
+ *
+ * Pass `{ persist: false }` under read-only/plan mode so the derived sidecar is never written.
  */
-export function loadIndexedArtifactsForDir(researchDir) {
+export function loadIndexedArtifactsForDir(researchDir, options = {}) {
     if (!existsSync(researchDir))
         return [];
+    const persist = options.persist !== false;
     const indexPath = join(researchDir, INDEX_FILE);
     const previous = loadIndex(indexPath);
     const entries = {};
@@ -78,7 +81,7 @@ export function loadIndexedArtifactsForDir(researchDir) {
     if (!changed) {
         changed = Object.keys(previous.entries).some((key) => !(key in entries));
     }
-    if (changed) {
+    if (changed && persist) {
         try {
             atomicWriteFile(indexPath, JSON.stringify({ version: INDEX_VERSION, entries }));
         }
@@ -93,11 +96,11 @@ export function loadIndexedArtifactsForDir(researchDir) {
  * key so a project entry shadows the same key in the global cache. Mirrors the dedup semantics of
  * {@link scanCacheDirs} but reads through the per-root sidecar index.
  */
-export function loadIndexedArtifacts(dataDirs) {
+export function loadIndexedArtifacts(dataDirs, options = {}) {
     const seen = new Set();
     const all = [];
     for (const dataDir of dataDirs) {
-        for (const located of loadIndexedArtifactsForDir(join(dataDir, 'research'))) {
+        for (const located of loadIndexedArtifactsForDir(join(dataDir, 'research'), options)) {
             const key = located.artifact.metadata.cache_key;
             if (seen.has(key))
                 continue;

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

@@ -31,6 +31,11 @@ export interface CdpPage {
     client: CdpClient;
     sessionId: string;
     close: () => Promise<void>;
+    /**
+     * Returns (and clears) the reason the most recent navigation request was blocked by the
+     * per-hop safety guard installed in {@link openCdpPage}, or `null` if none was blocked.
+     */
+    takeBlockedNavigationError: () => Error | null;
 }
 /** Status line of the main-frame document response, captured from Network.responseReceived. */
 export interface MainDocumentResponse {
@@ -45,8 +50,20 @@ export interface MainDocumentResponse {
  */
 export declare function assertRenderedHttpOk(mainDoc: MainDocumentResponse | undefined): void;
 /**
- * Spawns a headless Chrome, attaches a flat CDP session, and enables the Page, Network,
- * and Runtime domains. The caller drives navigation and must call close() when finished.
+ * Validates a navigated (or redirected) Document request against the same scheme/credentials/DNS
+ * safety `normalizeUrl` and `fetchWithRedirects` enforce per hop in url.ts/fetcher.ts. Chrome
+ * follows redirects internally with no hook back into that check, so a page that starts on a safe
+ * public host could otherwise redirect a rendered-fallback capture into a private/internal address
+ * (SSRF) or a non-http(s) scheme (e.g. `file:`) that the static fetcher would have rejected outright.
+ */
+export declare function describeUnsafeNavigationTarget(url: string): Promise<Error | null>;
+/**
+ * Spawns a headless Chrome, attaches a flat CDP session, and enables the Page, Network, Runtime,
+ * and Fetch domains. Fetch domain interception guards every Document-type request (the initial
+ * navigation and each subsequent redirect) with {@link describeUnsafeNavigationTarget} before
+ * Chrome is allowed to send it; a blocked request's reason is recorded and can be read back via
+ * the returned page's `takeBlockedNavigationError()`. The caller drives navigation and must call
+ * close() when finished.
  */
 export declare function openCdpPage(): Promise<CdpPage>;
 export interface ResponseMatcher {
@@ -89,4 +106,26 @@ export declare const SANDBOX_EGRESS_ERROR_MARKER = "sandboxed execution environm
  * against the environment directly and fall back to a manual fetch if it's still unreachable.
  */
 export declare function describeNavigationFailure(errorText: string, url: string): Error;
+/**
+ * Navigates an already-open CDP page to `currentUrl` and captures the rendered HTML, honoring the
+ * openCdpPage Fetch-domain safety guard at every point a blocked navigation could otherwise be
+ * discarded in favor of a less specific (or entirely silent) failure:
+ *
+ * 1. Right after `Page.navigate` returns — a fast HTTP redirect chain can already be blocked and
+ *    resolved by this point, surfacing as the generic `nav.errorText` (e.g. `net::ERR_BLOCKED_BY_CLIENT`)
+ *    below if not checked first.
+ * 2. If `waitForLoad` throws — a client-side (JS-triggered) navigation into a blocked target after
+ *    the initial navigation already settled can prevent the load/domContentLoaded events
+ *    `waitForLoad` is waiting on, surfacing as a generic timeout instead of the specific reason.
+ * 3. After `waitForLoad` resolves — a client-side navigation blocked without otherwise disrupting
+ *    the load signal would otherwise sail through silently, capturing whatever the page settled on.
+ *
+ * Exported (rather than folded into `fetchRenderedHtmlOnce`) so tests can drive it against a fake
+ * `CdpPage` without spawning a real browser.
+ */
+export declare function captureNavigatedPage(page: CdpPage, currentUrl: string, options: {
+    timeout: number;
+    limit: number;
+    settleMs: number;
+}): Promise<BrowserFetchResult>;
 export declare function fetchRenderedHtml(url: string, options?: BrowserFetchOptions): Promise<BrowserFetchResult>;

package/dist/lib/research/browser.js

@@ -220,13 +220,41 @@ export function assertRenderedHttpOk(mainDoc) {
     }
 }
 /**
- * Spawns a headless Chrome, attaches a flat CDP session, and enables the Page, Network,
- * and Runtime domains. The caller drives navigation and must call close() when finished.
+ * Validates a navigated (or redirected) Document request against the same scheme/credentials/DNS
+ * safety `normalizeUrl` and `fetchWithRedirects` enforce per hop in url.ts/fetcher.ts. Chrome
+ * follows redirects internally with no hook back into that check, so a page that starts on a safe
+ * public host could otherwise redirect a rendered-fallback capture into a private/internal address
+ * (SSRF) or a non-http(s) scheme (e.g. `file:`) that the static fetcher would have rejected outright.
+ */
+export async function describeUnsafeNavigationTarget(url) {
+    let normalized;
+    try {
+        normalized = normalizeUrl(url);
+    }
+    catch (err) {
+        return err;
+    }
+    try {
+        await checkDnsSafety(new URL(normalized).hostname);
+        return null;
+    }
+    catch (err) {
+        return err;
+    }
+}
+/**
+ * Spawns a headless Chrome, attaches a flat CDP session, and enables the Page, Network, Runtime,
+ * and Fetch domains. Fetch domain interception guards every Document-type request (the initial
+ * navigation and each subsequent redirect) with {@link describeUnsafeNavigationTarget} before
+ * Chrome is allowed to send it; a blocked request's reason is recorded and can be read back via
+ * the returned page's `takeBlockedNavigationError()`. The caller drives navigation and must call
+ * close() when finished.
  */
 export async function openCdpPage() {
     const chromePath = findChromePath();
     const { chromeProcess, wsUrl } = await spawnChrome(chromePath);
     const client = new CdpClient(wsUrl);
+    let blockedNavigationError = null;
     try {
         await client.connect();
         const { targetId } = await client.send('Target.createTarget', { url: 'about:blank' });
@@ -235,6 +263,23 @@ export async function openCdpPage() {
         await client.send('Network.enable', {}, sessionId);
         await client.send('Runtime.enable', {}, sessionId);
         await client.send('Network.setUserAgentOverride', { userAgent: DEFAULT_USER_AGENT }, sessionId);
+        await client.send('Fetch.enable', { patterns: [{ urlPattern: '*', resourceType: 'Document', requestStage: 'Request' }] }, sessionId);
+        client.on(`${sessionId}:Fetch.requestPaused`, (params) => {
+            // CdpClient.on's handler type is synchronous (CDP event dispatch isn't awaited), so the
+            // actual async validate-then-continue/fail work runs in this detached IIFE instead.
+            void (async () => {
+                const { requestId, request } = params;
+                const blockReason = await describeUnsafeNavigationTarget(request.url);
+                if (blockReason) {
+                    blockedNavigationError = blockReason;
+                    await client
+                        .send('Fetch.failRequest', { requestId, errorReason: 'BlockedByClient' }, sessionId)
+                        .catch(() => { });
+                    return;
+                }
+                await client.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
+            })();
+        });
         const close = async () => {
             try {
                 await client.send('Target.closeTarget', { targetId });
@@ -243,7 +288,12 @@ export async function openCdpPage() {
             client.close();
             chromeProcess.kill('SIGKILL');
         };
-        return { client, sessionId, close };
+        const takeBlockedNavigationError = () => {
+            const err = blockedNavigationError;
+            blockedNavigationError = null;
+            return err;
+        };
+        return { client, sessionId, close, takeBlockedNavigationError };
     }
     catch (err) {
         client.close();
@@ -332,8 +382,8 @@ const PROXY_BLOCKED_CHROME_NET_ERRORS = [
     'ERR_PROXY_CONNECTION_FAILED',
     'ERR_SOCKS_CONNECTION_FAILED',
 ];
-// Shared substring fetch.ts's fetchFailureGuidance matches on to attach suggestions/ref to this
-// error, without duplicating the message text it needs to match against.
+// Shared substring fetch-result.ts's fetchFailureGuidance matches on to attach suggestions/ref to
+// this error, without duplicating the message text it needs to match against.
 export const SANDBOX_EGRESS_ERROR_MARKER = 'sandboxed execution environment';
 /**
  * Builds the error thrown for a failed Page.navigate. When a proxy is configured (proxy.ts's
@@ -378,6 +428,86 @@ function isTransientBrowserError(err) {
     return (TRANSIENT_NAV_ERROR_CODES.some((code) => message.includes(code)) ||
         TRANSIENT_CHROME_STARTUP_MESSAGES.some((text) => message.includes(text)));
 }
+/**
+ * Navigates an already-open CDP page to `currentUrl` and captures the rendered HTML, honoring the
+ * openCdpPage Fetch-domain safety guard at every point a blocked navigation could otherwise be
+ * discarded in favor of a less specific (or entirely silent) failure:
+ *
+ * 1. Right after `Page.navigate` returns — a fast HTTP redirect chain can already be blocked and
+ *    resolved by this point, surfacing as the generic `nav.errorText` (e.g. `net::ERR_BLOCKED_BY_CLIENT`)
+ *    below if not checked first.
+ * 2. If `waitForLoad` throws — a client-side (JS-triggered) navigation into a blocked target after
+ *    the initial navigation already settled can prevent the load/domContentLoaded events
+ *    `waitForLoad` is waiting on, surfacing as a generic timeout instead of the specific reason.
+ * 3. After `waitForLoad` resolves — a client-side navigation blocked without otherwise disrupting
+ *    the load signal would otherwise sail through silently, capturing whatever the page settled on.
+ *
+ * Exported (rather than folded into `fetchRenderedHtmlOnce`) so tests can drive it against a fake
+ * `CdpPage` without spawning a real browser.
+ */
+export async function captureNavigatedPage(page, currentUrl, options) {
+    const { timeout, limit, settleMs } = options;
+    await page.client.send('Network.setBlockedURLs', { urls: BLOCKED_ASSET_URLS }, page.sessionId);
+    // Record the status of each frame's first Document response so we can reject HTTP errors after
+    // the page settles. Keyed by frameId; the navigated top frame is matched via the navigate result.
+    const documentResponses = new Map();
+    page.client.on(`${page.sessionId}:Network.responseReceived`, (params) => {
+        const { frameId } = params;
+        const status = params.response?.status;
+        // Only record real numeric statuses: a Document event without a usable status would
+        // otherwise store NaN, which silently slips past the `>= 400` guard and the `?? 200`
+        // fallback alike, leaking a NaN into BrowserFetchResult.status (declared `number`).
+        if (params.type !== 'Document' || !frameId || typeof status !== 'number')
+            return;
+        if (documentResponses.has(frameId))
+            return;
+        documentResponses.set(frameId, {
+            status,
+            statusText: params.response?.statusText ?? '',
+        });
+    });
+    const nav = await page.client.send('Page.navigate', { url: currentUrl }, page.sessionId);
+    // See point 1 above: prefer the safety guard's specific reason over the opaque errorText below.
+    const blockedNavigation = page.takeBlockedNavigationError();
+    if (blockedNavigation)
+        throw blockedNavigation;
+    // A network-level failure (DNS, refused/closed connection, TLS) never fires a load event, so
+    // fail fast here instead of waiting out the full navigation timeout on a dead page.
+    if (nav.errorText) {
+        throw describeNavigationFailure(nav.errorText, currentUrl);
+    }
+    try {
+        await waitForLoad(page.client, page.sessionId, timeout, settleMs);
+    }
+    catch (err) {
+        // See point 2 above: a blocked reason recorded during the wait outranks the generic timeout.
+        throw page.takeBlockedNavigationError() ?? err;
+    }
+    // See point 3 above.
+    const blockedNavigationAfterLoad = page.takeBlockedNavigationError();
+    if (blockedNavigationAfterLoad)
+        throw blockedNavigationAfterLoad;
+    const mainDoc = nav.frameId ? documentResponses.get(nav.frameId) : undefined;
+    assertRenderedHttpOk(mainDoc);
+    const evalResult = await page.client.send('Runtime.evaluate', { expression: 'document.documentElement.outerHTML', returnByValue: true }, page.sessionId);
+    const html = evalResult.result?.value;
+    if (typeof html !== 'string') {
+        throw new Error('Failed to retrieve rendered HTML from browser page.');
+    }
+    const byteLength = Buffer.byteLength(html);
+    if (byteLength > limit) {
+        throw new Error(`Response body size limit exceeded. Rendered HTML is ${byteLength} bytes.`);
+    }
+    return {
+        status: mainDoc?.status ?? 200,
+        contentType: 'text/html',
+        etag: null,
+        lastModified: null,
+        finalUrl: currentUrl,
+        responseSize: byteLength,
+        content: html,
+    };
+}
 async function fetchRenderedHtmlOnce(url, options = {}) {
     const timeout = options.timeoutMs ?? 15_000;
     const limit = options.bodyLimitBytes ?? 2 * 1024 * 1024;
@@ -385,52 +515,11 @@ async function fetchRenderedHtmlOnce(url, options = {}) {
     await checkDnsSafety(new URL(currentUrl).hostname);
     const page = await openCdpPage();
     try {
-        await page.client.send('Network.setBlockedURLs', { urls: BLOCKED_ASSET_URLS }, page.sessionId);
-        // Record the status of each frame's first Document response so we can reject HTTP errors after
-        // the page settles. Keyed by frameId; the navigated top frame is matched via the navigate result.
-        const documentResponses = new Map();
-        page.client.on(`${page.sessionId}:Network.responseReceived`, (params) => {
-            const { frameId } = params;
-            const status = params.response?.status;
-            // Only record real numeric statuses: a Document event without a usable status would
-            // otherwise store NaN, which silently slips past the `>= 400` guard and the `?? 200`
-            // fallback alike, leaking a NaN into BrowserFetchResult.status (declared `number`).
-            if (params.type !== 'Document' || !frameId || typeof status !== 'number')
-                return;
-            if (documentResponses.has(frameId))
-                return;
-            documentResponses.set(frameId, {
-                status,
-                statusText: params.response?.statusText ?? '',
-            });
+        return await captureNavigatedPage(page, currentUrl, {
+            timeout,
+            limit,
+            settleMs: options.settleMs ?? 1000,
         });
-        const nav = await page.client.send('Page.navigate', { url: currentUrl }, page.sessionId);
-        // A network-level failure (DNS, refused/closed connection, TLS) never fires a load event, so
-        // fail fast here instead of waiting out the full navigation timeout on a dead page.
-        if (nav.errorText) {
-            throw describeNavigationFailure(nav.errorText, currentUrl);
-        }
-        await waitForLoad(page.client, page.sessionId, timeout, options.settleMs ?? 1000);
-        const mainDoc = nav.frameId ? documentResponses.get(nav.frameId) : undefined;
-        assertRenderedHttpOk(mainDoc);
-        const evalResult = await page.client.send('Runtime.evaluate', { expression: 'document.documentElement.outerHTML', returnByValue: true }, page.sessionId);
-        const html = evalResult.result?.value;
-        if (typeof html !== 'string') {
-            throw new Error('Failed to retrieve rendered HTML from browser page.');
-        }
-        const byteLength = Buffer.byteLength(html);
-        if (byteLength > limit) {
-            throw new Error(`Response body size limit exceeded. Rendered HTML is ${byteLength} bytes.`);
-        }
-        return {
-            status: mainDoc?.status ?? 200,
-            contentType: 'text/html',
-            etag: null,
-            lastModified: null,
-            finalUrl: currentUrl,
-            responseSize: byteLength,
-            content: html,
-        };
     }
     finally {
         await page.close();

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

@@ -1,16 +1,19 @@
-import type { FetchResult } from './fetcher.js';
+import { type FetchResult } from './fetcher.js';
 import type { ExtractionResult } from './extract.js';
 import type { CaptureMethod } from './schema.js';
 import type { MachineReadableArtifact, SiteCapabilities } from './docs/capabilities.js';
 import { type TextFetcher } from './docs/machine-readable.js';
+/** Injected fetcher dependencies for `capturePage`. All three are required. */
 export interface CaptureDeps {
     fetchStatic: (url: string) => Promise<FetchResult>;
     fetchRendered: (url: string) => Promise<FetchResult>;
     fetchText: TextFetcher;
 }
+/** Options passed to `capturePage` by the caller. */
 export interface CaptureOptions {
     forceRendered?: boolean;
 }
+/** Full outcome of a `capturePage` call, including provenance and capability metadata. */
 export interface CaptureOutcome {
     fetchResult: FetchResult;
     extraction: ExtractionResult;
@@ -20,10 +23,29 @@ export interface CaptureOutcome {
     machineReadable: MachineReadableArtifact[];
     attemptedMethods: string[];
 }
-export declare function renderedFallbackNeeded(caps: SiteCapabilities, extraction: ExtractionResult | null): boolean;
+/**
+ * Returns true when the static extraction result is missing or too weak to serve as the artifact,
+ * meaning the caller should attempt a rendered fallback.
+ *
+ * @param caps - Detected site capabilities; `recommendedCapture === 'rendered'` forces a fallback.
+ * @param extraction - Result of static extraction, or null when static fetch failed.
+ * @param staticError - The static fetch's failure, if any. A content-type policy rejection (JSON,
+ *   PDF, binary) means the URL isn't a web page at all — a browser would just render its own
+ *   built-in viewer for it, producing a corrupted-looking "extracted" artifact — so that specific
+ *   failure is a hard stop, never a fallback trigger. `--rendered` still bypasses this entirely (it
+ *   skips the static phase), so an informed retry remains available.
+ * @returns True when a rendered (browser) fallback should be attempted.
+ */
+export declare function renderedFallbackNeeded(caps: SiteCapabilities, extraction: ExtractionResult | null, staticError?: Error | null): boolean;
 /**
  * Captures a page's best-available content. Order: forced rendered → route/source Markdown → static
  * HTML → rendered fallback. Returns the chosen fetch result, extraction, detected capabilities, and
  * provenance (capture method, source URL, machine-readable artifacts, attempted methods).
+ *
+ * @param url - The page URL to capture.
+ * @param options - Capture options (e.g. `forceRendered`).
+ * @param deps - Injected fetchers for static, rendered, and text requests.
+ * @returns Full CaptureOutcome including the best extraction and capture provenance.
+ * @throws {Error} When all capture strategies fail and no usable content is produced.
  */
 export declare function capturePage(url: string, options: CaptureOptions, deps: CaptureDeps): Promise<CaptureOutcome>;

package/dist/lib/research/capture.js

@@ -1,3 +1,4 @@
+import { isUnsupportedContentTypeError } from './fetcher.js';
 import { extractHtmlContent } from './extract.js';
 import { detectDocsEngine } from './docs/detect.js';
 import { emptyCapabilities } from './docs/capabilities.js';
@@ -6,9 +7,22 @@ import { mapUrlToSource } from './docs/source-map.js';
 import { extractFromSource } from './docs/markdown-source.js';
 import { validateTextArtifact } from './docs/validate.js';
 const MIN_USEFUL_CHARS = 600;
-// A static extraction needs rendering help when it failed outright, the detector says the page is
-// an SPA/client-rendered, or the extracted article is too thin/low-confidence to be useful.
-export function renderedFallbackNeeded(caps, extraction) {
+/**
+ * Returns true when the static extraction result is missing or too weak to serve as the artifact,
+ * meaning the caller should attempt a rendered fallback.
+ *
+ * @param caps - Detected site capabilities; `recommendedCapture === 'rendered'` forces a fallback.
+ * @param extraction - Result of static extraction, or null when static fetch failed.
+ * @param staticError - The static fetch's failure, if any. A content-type policy rejection (JSON,
+ *   PDF, binary) means the URL isn't a web page at all — a browser would just render its own
+ *   built-in viewer for it, producing a corrupted-looking "extracted" artifact — so that specific
+ *   failure is a hard stop, never a fallback trigger. `--rendered` still bypasses this entirely (it
+ *   skips the static phase), so an informed retry remains available.
+ * @returns True when a rendered (browser) fallback should be attempted.
+ */
+export function renderedFallbackNeeded(caps, extraction, staticError = null) {
+    if (staticError && isUnsupportedContentTypeError(staticError))
+        return false;
     if (!extraction)
         return true;
     if (caps.recommendedCapture === 'rendered')
@@ -116,7 +130,7 @@ async function sourceOutcome(url, phase, deps, attemptedMethods) {
 // is warranted; throws only when rendering fails and nothing usable was produced (preferring the
 // earlier static error).
 async function renderedFallbackOutcome(url, deps, attemptedMethods, phase, extraction) {
-    if (!renderedFallbackNeeded(phase.capabilities, extraction))
+    if (!renderedFallbackNeeded(phase.capabilities, extraction, phase.staticError))
         return null;
     try {
         return await renderedOutcome(url, deps, attemptedMethods, phase.machineReadable);
@@ -131,6 +145,12 @@ async function renderedFallbackOutcome(url, deps, attemptedMethods, phase, extra
  * Captures a page's best-available content. Order: forced rendered → route/source Markdown → static
  * HTML → rendered fallback. Returns the chosen fetch result, extraction, detected capabilities, and
  * provenance (capture method, source URL, machine-readable artifacts, attempted methods).
+ *
+ * @param url - The page URL to capture.
+ * @param options - Capture options (e.g. `forceRendered`).
+ * @param deps - Injected fetchers for static, rendered, and text requests.
+ * @returns Full CaptureOutcome including the best extraction and capture provenance.
+ * @throws {Error} When all capture strategies fail and no usable content is produced.
  */
 export async function capturePage(url, options, deps) {
     const attemptedMethods = [];

package/dist/lib/research/cli-io.d.ts

@@ -0,0 +1,33 @@
+/** Options accepted by {@link CliIo.error} — the subset of oclif's `this.error` options Bonsai uses. */
+export interface CliErrorOptions {
+    exit: number;
+    code?: string;
+    suggestions?: string[];
+    ref?: string;
+}
+/**
+ * Narrow command-context port passed from oclif commands into command services, so the services
+ * stay free of oclif imports and are testable without a framework harness.
+ */
+export interface CliIo {
+    bin: string;
+    configDir: string | undefined;
+    dataDir: string;
+    cwd: string;
+    json: boolean;
+    warn(msg: string): void;
+    log(msg: string): void;
+    error(msg: string, opts: CliErrorOptions): never;
+}
+/**
+ * Single exit point for a URL that failed normalization, shared by BaseCommand and the command
+ * services. A scheme-less but domain-shaped input reports MISSING_URL_SCHEME — the same code the
+ * root `bonsai <url>` shorthand uses — so an agent sees one stable code for "forgot https://"
+ * everywhere; truly unparseable input stays INVALID_URL.
+ *
+ * @param error - `this.error` (oclif) or `io.error`; must not return.
+ * @param url - Raw URL string the user supplied.
+ * @param message - Human-readable failure message.
+ * @returns Never — always exits via `error`.
+ */
+export declare function failInvalidUrl(error: (msg: string, opts: CliErrorOptions) => never, url: string, message: string): never;

package/dist/lib/research/cli-io.js

@@ -0,0 +1,27 @@
+import { EXIT_USAGE } from '../cli-error-policy.js';
+import { looksLikeSchemelessUrl } from './url.js';
+/**
+ * Single exit point for a URL that failed normalization, shared by BaseCommand and the command
+ * services. A scheme-less but domain-shaped input reports MISSING_URL_SCHEME — the same code the
+ * root `bonsai <url>` shorthand uses — so an agent sees one stable code for "forgot https://"
+ * everywhere; truly unparseable input stays INVALID_URL.
+ *
+ * @param error - `this.error` (oclif) or `io.error`; must not return.
+ * @param url - Raw URL string the user supplied.
+ * @param message - Human-readable failure message.
+ * @returns Never — always exits via `error`.
+ */
+export function failInvalidUrl(error, url, message) {
+    if (looksLikeSchemelessUrl(url)) {
+        error(message, {
+            exit: EXIT_USAGE,
+            code: 'MISSING_URL_SCHEME',
+            suggestions: [`Use a full URL: https://${url}`],
+        });
+    }
+    error(`Invalid URL: ${message}`, {
+        exit: EXIT_USAGE,
+        code: 'INVALID_URL',
+        suggestions: ['Provide a valid http:// or https:// URL.'],
+    });
+}

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

@@ -2,6 +2,9 @@ import { type SummaryLevel } from './summarize.js';
 /**
  * Compresses Markdown text by removing images, simplifying links from [text](url) to [text],
  * and collapsing multiple consecutive blank lines.
+ *
+ * @param markdown - Markdown text to compress.
+ * @returns Structurally compressed Markdown with images removed and links simplified.
  */
 export declare function compressMarkdown(markdown: string): string;
 /**
@@ -20,5 +23,9 @@ export declare function compressMarkdown(markdown: string): string;
  * detailed). This means the cache can never end up serving a `compressed` that is larger than
  * `detailed`, or one that is empty while `detailed` has content — if the auto-compaction can't be
  * trusted, the caller transparently gets the (verified) structural form or the detailed text itself.
+ *
+ * @param detailed - Full detailed Markdown for a page.
+ * @param level - Extractive summarization aggressiveness level passed to the summarizer.
+ * @returns The most compact trustworthy Markdown view: summarized, structural, or detailed as fallback.
  */
 export declare function buildCompressed(detailed: string, level: SummaryLevel): string;

package/dist/lib/research/compress.js

@@ -4,17 +4,17 @@ const SUMMARY_FLOOR_TOKENS = 200;
 /**
  * Compresses Markdown text by removing images, simplifying links from [text](url) to [text],
  * and collapsing multiple consecutive blank lines.
+ *
+ * @param markdown - Markdown text to compress.
+ * @returns Structurally compressed Markdown with images removed and links simplified.
  */
 export function compressMarkdown(markdown) {
     if (!markdown) {
         return '';
     }
     let result = markdown;
-    // Remove markdown images: ![alt](url) -> ""
     result = result.replace(/!\[.*?\]\(.*?\)/g, '');
-    // Simplify links: [text](url) -> [text]
     result = result.replace(/\[(.*?)\]\(.*?\)/g, '[$1]');
-    // Collapse multiple consecutive newlines (3 or more) to maximum 2 newlines
     result = result.replace(/\n{3,}/g, '\n\n');
     return result.trim();
 }
@@ -34,6 +34,10 @@ export function compressMarkdown(markdown) {
  * detailed). This means the cache can never end up serving a `compressed` that is larger than
  * `detailed`, or one that is empty while `detailed` has content — if the auto-compaction can't be
  * trusted, the caller transparently gets the (verified) structural form or the detailed text itself.
+ *
+ * @param detailed - Full detailed Markdown for a page.
+ * @param level - Extractive summarization aggressiveness level passed to the summarizer.
+ * @returns The most compact trustworthy Markdown view: summarized, structural, or detailed as fallback.
  */
 export function buildCompressed(detailed, level) {
     const structural = compressMarkdown(detailed);