@taurgis/bonsai 1.0.6 → 3.0.1

package/dist/lib/help-preflight.js

@@ -0,0 +1,81 @@
+import { Config } from '@oclif/core';
+import { buildEnvelope } from './envelope.js';
+import { buildCommandNotFoundDetails } from '../hooks/command-not-found/suggest.js';
+function commandId(parts) {
+    return parts.join(':');
+}
+function positionalTokens(argv) {
+    const tokens = [];
+    for (const arg of argv) {
+        if (arg === '--')
+            break;
+        if (arg === '--help' || arg === '--json')
+            continue;
+        if (arg.startsWith('-'))
+            continue;
+        tokens.push(arg);
+    }
+    return tokens;
+}
+function commandPrefixLength(tokens, config) {
+    let longest = 0;
+    for (let n = 1; n <= tokens.length; n++) {
+        if (config.commandIDs.includes(commandId(tokens.slice(0, n))))
+            longest = n;
+    }
+    return longest;
+}
+function branchPrefixLength(tokens, config) {
+    let longest = 0;
+    for (let n = 1; n <= tokens.length; n++) {
+        const id = commandId(tokens.slice(0, n));
+        if (config.commandIDs.some((command) => command.startsWith(`${id}:`)))
+            longest = n;
+    }
+    return longest;
+}
+function hasValidHelpTarget(tokens, config) {
+    const commandLength = commandPrefixLength(tokens, config);
+    const branchLength = branchPrefixLength(tokens, config);
+    if (commandLength === tokens.length || branchLength === tokens.length)
+        return true;
+    if (branchLength > 0 && tokens.length > branchLength) {
+        return commandLength > branchLength;
+    }
+    return commandLength > 0;
+}
+/**
+ * oclif resolves help before its command_not_found hook, so `bonsai config gett --help` otherwise
+ * falls back to a terse framework error. Catch that narrow case and reuse the normal typo guidance.
+ */
+export async function tryUnknownHelpOutput(argv, root) {
+    if (!argv.includes('--help'))
+        return null;
+    const tokens = positionalTokens(argv);
+    if (tokens.length === 0)
+        return null;
+    const config = await Config.load({ root });
+    if (hasValidHelpTarget(tokens, config))
+        return null;
+    const attemptedId = commandId(tokens);
+    const details = buildCommandNotFoundDetails(attemptedId, [...argv], config);
+    if (argv.includes('--json')) {
+        return {
+            kind: 'json',
+            exitCode: 2,
+            envelope: buildEnvelope({
+                command: details.command,
+                ok: false,
+                exitCode: 2,
+                stderr: `${details.message}\nCode: ${details.code}`,
+                data: null,
+                code: details.code,
+            }),
+        };
+    }
+    return {
+        kind: 'human',
+        exitCode: 2,
+        message: `${details.message}\nCode: ${details.code}`,
+    };
+}

package/dist/lib/limit-flag.d.ts

@@ -0,0 +1 @@
+export declare function limitFlag(max: number, defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/lib/limit-flag.js

@@ -0,0 +1,24 @@
+import { Errors, Flags } from '@oclif/core';
+export function limitFlag(max, defaultValue, description) {
+    return Flags.custom({
+        parse: async (input) => {
+            if (!/^\d+$/.test(input)) {
+                throw new Errors.CLIError(`Limit must be an integer between 1 and ${max}.`, {
+                    exit: 2,
+                    code: 'INVALID_LIMIT',
+                });
+            }
+            const value = Number(input);
+            if (value < 1 || value > max) {
+                throw new Errors.CLIError(`Limit must be between 1 and ${max}.`, {
+                    exit: 2,
+                    code: 'INVALID_LIMIT',
+                });
+            }
+            return value;
+        },
+    })({
+        default: defaultValue,
+        description,
+    });
+}

package/dist/lib/research/{search-index.d.ts → artifact-index.d.ts}

@@ -1,18 +1,18 @@
 import type { ResearchArtifact } from './schema.js';
-export interface SearchableArtifact {
+export interface IndexedArtifact {
     artifact: ResearchArtifact;
     filePath: string;
 }
 /**
- * Returns the searchable view of every active artifact in one research dir, using the sidecar index
+ * 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 search). Corrupt/unreadable files are skipped —
+ * index (best-effort; a write failure never breaks callers). Corrupt/unreadable files are skipped —
  * the real read paths in storage.ts handle archiving them.
  */
-export declare function loadSearchableArtifactsForDir(researchDir: string): SearchableArtifact[];
+export declare function loadIndexedArtifactsForDir(researchDir: string): 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 loadSearchableArtifacts(dataDirs: string[]): SearchableArtifact[];
+export declare function loadIndexedArtifacts(dataDirs: string[]): IndexedArtifact[];

package/dist/lib/research/{search-index.js → artifact-index.js}

@@ -2,11 +2,11 @@ import { join } from 'node:path';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { atomicWriteFile } from '../atomic-write.js';
 import { parseArtifactShallow } from './artifact.js';
-import { isResearchFile } from './storage.js';
+import { isResearchFile } from './url.js';
 // Sidecar index that caches the lightweight (metadata + summary + compressed) view of each artifact
-// so repeat searches avoid re-reading and re-parsing every file. It is a derived cache only: a stale
-// or missing index never changes results, because each entry is validated against the file's current
-// signature and re-read on any mismatch.
+// so repeat list/scan operations avoid re-reading and re-parsing every file. It is a derived cache
+// only: a stale or missing index never changes results, because each entry is validated against the
+// file's current signature and re-read on any mismatch.
 const INDEX_FILE = '.search-index.json';
 const INDEX_VERSION = 1;
 // The repo writes artifacts via temp-file + rename, so every rewrite yields a new inode. Combining
@@ -48,12 +48,12 @@ function getOrUpdateIndexEntry(filePath, cached, onChanged) {
     }
 }
 /**
- * Returns the searchable view of every active artifact in one research dir, using the sidecar index
+ * 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 search). Corrupt/unreadable files are skipped —
+ * index (best-effort; a write failure never breaks callers). Corrupt/unreadable files are skipped —
  * the real read paths in storage.ts handle archiving them.
  */
-export function loadSearchableArtifactsForDir(researchDir) {
+export function loadIndexedArtifactsForDir(researchDir) {
     if (!existsSync(researchDir))
         return [];
     const indexPath = join(researchDir, INDEX_FILE);
@@ -83,7 +83,7 @@ export function loadSearchableArtifactsForDir(researchDir) {
             atomicWriteFile(indexPath, JSON.stringify({ version: INDEX_VERSION, entries }));
         }
         catch {
-            // Best-effort cache write; search results are already computed without it.
+            // Best-effort cache write; results are already computed without it.
         }
     }
     return results;
@@ -93,11 +93,11 @@ export function loadSearchableArtifactsForDir(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 loadSearchableArtifacts(dataDirs) {
+export function loadIndexedArtifacts(dataDirs) {
     const seen = new Set();
     const all = [];
     for (const dataDir of dataDirs) {
-        for (const located of loadSearchableArtifactsForDir(join(dataDir, 'research'))) {
+        for (const located of loadIndexedArtifactsForDir(join(dataDir, 'research'))) {
             const key = located.artifact.metadata.cache_key;
             if (seen.has(key))
                 continue;

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

@@ -24,15 +24,8 @@ export declare class CdpClient {
     close(): void;
 }
 export declare function findChromePath(): string;
+export declare function buildChromeArgs(): string[];
 export declare function waitForLoad(client: CdpClient, sessionId: string, timeoutMs: number, settleMs?: number): Promise<void>;
-/**
- * Polls until a content-container element holds enough RENDERED text, so SPAs that fetch their
- * body after load are captured rendered rather than as a "Loading…" shell. Pierces open shadow
- * roots (the container is matched across shadow boundaries) and measures `innerText`, which
- * reflects shadow-rendered text — `document.querySelector` + `textContent` miss both. Returns
- * without throwing on timeout; the caller captures whatever rendered and judges its quality.
- */
-export declare function waitForContentReady(page: CdpPage, selectors: string[], minChars: number, timeoutMs: number): Promise<void>;
 export declare const BLOCKED_ASSET_URLS: string[];
 export interface CdpPage {
     client: CdpClient;

package/dist/lib/research/browser.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { checkDnsSafety } from './fetcher.js';
+import { getChromeProxyArgs } from './proxy.js';
 import { normalizeUrl } from './url.js';
 export class CdpClient {
     ws;
@@ -93,8 +94,10 @@ export function findChromePath() {
     throw new Error('No Chrome or Chromium browser found for browser-based extraction. Install Chrome/Chromium or ' +
         'set CHROME_PATH to the browser executable. Static (non-rendered) fetching does not require a browser.');
 }
-async function spawnChrome(chromePath) {
-    const chromeProcess = spawn(chromePath, [
+// Split out from spawnChrome so the exact CLI args (including the proxy flags) are unit-testable
+// without spawning a real browser process.
+export function buildChromeArgs() {
+    return [
         '--headless=new',
         '--remote-debugging-port=0',
         '--disable-gpu',
@@ -102,7 +105,13 @@ async function spawnChrome(chromePath) {
         '--disable-setuid-sandbox',
         '--disable-extensions',
         '--disable-dev-shm-usage',
-    ]);
+        // CDP navigation uses Chrome's own network stack, not Node's fetch/undici, so a sandbox
+        // proxy detected via *_PROXY env vars must be passed to Chrome separately (see proxy.ts).
+        ...getChromeProxyArgs(),
+    ];
+}
+async function spawnChrome(chromePath) {
+    const chromeProcess = spawn(chromePath, buildChromeArgs());
     try {
         const wsUrl = await new Promise((resolve, reject) => {
             let output = '';
@@ -164,48 +173,6 @@ export async function waitForLoad(client, sessionId, timeoutMs, settleMs = 1000)
     }
     throw new Error(`Navigation timed out after ${timeoutMs}ms`);
 }
-/**
- * Polls until a content-container element holds enough RENDERED text, so SPAs that fetch their
- * body after load are captured rendered rather than as a "Loading…" shell. Pierces open shadow
- * roots (the container is matched across shadow boundaries) and measures `innerText`, which
- * reflects shadow-rendered text — `document.querySelector` + `textContent` miss both. Returns
- * without throwing on timeout; the caller captures whatever rendered and judges its quality.
- */
-export async function waitForContentReady(page, selectors, minChars, timeoutMs) {
-    // Reports whether a content container has rendered (innerText pierces shadow), plus the total
-    // rendered text length so the caller can wait for the render to *settle* — heavy pages (e.g.
-    // the api-console) render the container early but keep filling it in.
-    const expression = `(() => {
-    const out = [];
-    const visit = (r) => { for (const c of Array.from(r.children || [])) { out.push(c); if (c.shadowRoot) visit(c.shadowRoot); visit(c); } };
-    visit(document);
-    const SELS = ${JSON.stringify(selectors)};
-    let has = false;
-    for (const el of out) {
-      if (!el.matches) continue;
-      if (!SELS.some((s) => { try { return el.matches(s); } catch (e) { return false; } })) continue;
-      if (((el.innerText) || '').trim().length >= ${minChars}) { has = true; break; }
-    }
-    return { has, len: document.body ? (document.body.innerText || '').length : 0 };
-  })()`;
-    const start = Date.now();
-    let previousLength = -1;
-    let stablePolls = 0;
-    while (Date.now() - start < timeoutMs) {
-        const value = (await page.client
-            .send('Runtime.evaluate', { expression, returnByValue: true }, page.sessionId)
-            .catch(() => null))?.result?.value;
-        if (value?.has) {
-            const grew = Math.abs((value.len || 0) - previousLength) > Math.max(40, previousLength * 0.02);
-            if (!grew && ++stablePolls >= 2)
-                return; // content present and rendering has settled
-            if (grew)
-                stablePolls = 0;
-            previousLength = value.len || 0;
-        }
-        await new Promise((r) => setTimeout(r, 500));
-    }
-}
 export const BLOCKED_ASSET_URLS = [
     '*.css',
     '*.png',
@@ -336,7 +303,13 @@ export class ResponseCapture {
         });
     }
 }
-export async function fetchRenderedHtml(url, options = {}) {
+// Chrome can emit these on first navigation in headless CI when the cert verifier reloads mid-run.
+const TRANSIENT_NAV_ERROR_CODES = ['ERR_CERT_VERIFIER_CHANGED'];
+function isTransientBrowserNavigationError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return TRANSIENT_NAV_ERROR_CODES.some((code) => message.includes(code));
+}
+async function fetchRenderedHtmlOnce(url, options = {}) {
     const timeout = options.timeoutMs ?? 15_000;
     const limit = options.bodyLimitBytes ?? 2 * 1024 * 1024;
     const currentUrl = normalizeUrl(url);
@@ -394,3 +367,16 @@ export async function fetchRenderedHtml(url, options = {}) {
         await page.close();
     }
 }
+export async function fetchRenderedHtml(url, options = {}) {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fetchRenderedHtmlOnce(url, options);
+        }
+        catch (err) {
+            if (attempt === maxAttempts || !isTransientBrowserNavigationError(err))
+                throw err;
+        }
+    }
+    throw new Error('Failed to fetch rendered HTML after transient browser navigation errors.');
+}

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

@@ -1,4 +1,5 @@
 import { dropEmptyLinks, htmlToMarkdown } from '../markdown.js';
+import { sanitizePromptInjection } from '../prompt-injection.js';
 // Parses a leading YAML frontmatter block (--- ... ---). Only flat scalar keys are read; nested
 // structures are ignored (we only need title/description). The block is stripped from the body.
 export function parseFrontmatter(md) {
@@ -183,7 +184,7 @@ export function extractFromSource(md, sourceUrl) {
         ? cleanKumaScript(stripMdnHiddenSamples(body))
         : body;
     const tablesAsMarkdown = convertHtmlTables(sanitizeSourceMarkdown(deMacroed));
-    const cleaned = dropEmptySections(dropEmptyLinks(tablesAsMarkdown)).trim();
+    const cleaned = sanitizePromptInjection(dropEmptySections(dropEmptyLinks(tablesAsMarkdown))).trim();
     const notes = [`captured from public Markdown/MDX source: ${sourceUrl}`];
     return {
         title: titleFrom(frontmatter, cleaned),

package/dist/lib/research/extract.js

@@ -4,6 +4,7 @@ import { htmlToMarkdown } from './markdown.js';
 import { normalizeCodeBlocks } from './docs/code-blocks.js';
 import { cleanDocsChrome } from './docs/clean-dom.js';
 import { analyzeMarkdownQuality } from './docs/quality-gates.js';
+import { sanitizePromptInjection } from './prompt-injection.js';
 function resolveRelativeLinks(document, finalUrl) {
     const base = new URL(finalUrl);
     const links = document.querySelectorAll('a');
@@ -69,7 +70,7 @@ export function extractHtmlContent(html, finalUrl) {
         throw new Error('Content extraction failed: The target page could not be parsed by the readability engine. ' +
             'Hint: The "import" command lets you import pre-cleaned, agent-supplied research notes directly.');
     }
-    const detailedMarkdown = htmlToMarkdown(article.content);
+    const detailedMarkdown = sanitizePromptInjection(htmlToMarkdown(article.content));
     const textLength = article.textContent ? article.textContent.trim().length : 0;
     const { confidence, notes } = determineConfidence(textLength);
     const quality = analyzeMarkdownQuality(detailedMarkdown, article.title || '');

package/dist/lib/research/fetcher.js

@@ -1,6 +1,61 @@
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
+import { fetch as undiciFetch } from 'undici';
 import { isSafeIp, normalizeUrl } from './url.js';
+import { getProxyDispatcher, isProxyConfigured, PROXY_TUNNEL_REJECTION_PATTERN } from './proxy.js';
+// Runs one fetch attempt with its own fresh AbortController/timeout, so that when `doFetch` makes
+// a second attempt (the proxy fallback below) it gets the full timeout budget rather than
+// whatever was left over from the first attempt's signal. Loosely typed at this one boundary
+// because it bridges two structurally-similar-but-nominally-distinct fetch implementations
+// (Node's global fetch and the separate `undici` package's own fetch/RequestInit/Response).
+async function fetchWithTimeout(fetchFn, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return (await fetchFn(url, { ...init, signal: controller.signal }));
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+// True when `err` is a transport failure specifically caused by the proxy declining to tunnel to
+// the target host (e.g. an allowlist-only sandbox proxy), as opposed to any other pre-response
+// failure (DNS, refused connection, a genuinely unreachable destination). Only this class of
+// failure is worth retrying without the proxy — retrying on any transport TypeError would also
+// re-attempt destinations that are down regardless of the proxy, doubling their latency for no
+// benefit.
+function isProxyTunnelRejection(err) {
+    let current = err;
+    while (current instanceof Error) {
+        if (PROXY_TUNNEL_REJECTION_PATTERN.test(current.message))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+// Node's global fetch cannot be handed a Dispatcher from the separate `undici` package (their
+// internal request-handler interfaces don't line up across versions), so routing through a
+// sandbox-detected proxy requires switching to undici's own fetch for that one request. The
+// unproxied path keeps using the global fetch, matching existing tests that stub `globalThis.fetch`.
+//
+// A configured proxy isn't a guarantee the proxy can actually reach a given host (many sandbox
+// proxies only allowlist specific destinations), so a proxy-tunnel rejection falls back to a
+// direct connection rather than treating "proxy is configured" as "proxy or nothing." The
+// fallback gets its own fresh timeout (via fetchWithTimeout) rather than inheriting the proxied
+// attempt's spent budget.
+async function doFetch(url, init, timeoutMs) {
+    const dispatcher = getProxyDispatcher();
+    if (!dispatcher)
+        return fetchWithTimeout(fetch, url, init, timeoutMs);
+    try {
+        return await fetchWithTimeout(undiciFetch, url, { ...init, dispatcher }, timeoutMs);
+    }
+    catch (err) {
+        if (!isProxyTunnelRejection(err))
+            throw err;
+        return fetchWithTimeout(fetch, url, init, timeoutMs);
+    }
+}
 export function looksLikeHtml(text) {
     const trimmed = text.trimStart().toLowerCase();
     return (trimmed.startsWith('<!doctype html') ||
@@ -19,17 +74,26 @@ export async function checkDnsSafety(hostname) {
         }
         return;
     }
+    let addresses;
     try {
-        const addresses = await lookup(hostToResolve, { all: true });
-        for (const addr of addresses) {
-            if (!isSafeIp(addr.address)) {
-                throw new Error(`IP address "${addr.address}" resolved for "${hostname}" is a blocked local or private target.`);
-            }
-        }
+        addresses = await lookup(hostToResolve, { all: true });
     }
     catch (err) {
+        // A sandbox that requires a proxy for HTTP egress may also block raw DNS queries (port 53)
+        // without blocking name resolution done through the proxy itself — so a failed *local*
+        // lookup isn't necessarily a dead end when a proxy is available to fall back on. Only skip
+        // the safety guarantee in that specific case; whenever local resolution succeeds (the common
+        // case, proxy or not), the resolved address is still validated below regardless of proxy
+        // configuration, so a hostname that resolves to a private/internal IP is still caught.
+        if (isProxyConfigured())
+            return;
         throw new Error(`DNS resolution failed for hostname "${hostname}": ${err.message}`);
     }
+    for (const addr of addresses) {
+        if (!isSafeIp(addr.address)) {
+            throw new Error(`IP address "${addr.address}" resolved for "${hostname}" is a blocked local or private target.`);
+        }
+    }
 }
 async function readBodyWithLimit(body, limit) {
     if (!body) {
@@ -123,32 +187,20 @@ async function fetchWithRedirects(url, options, process) {
     while (true) {
         const parsedUrl = new URL(currentUrl);
         await checkDnsSafety(parsedUrl.hostname);
-        const controller = new AbortController();
-        const id = setTimeout(() => controller.abort(), timeout);
-        try {
-            const res = await fetch(currentUrl, {
-                method: 'GET',
-                headers: initialHeaders,
-                redirect: 'manual',
-                signal: controller.signal,
-            });
-            if ([301, 302, 303, 307, 308].includes(res.status)) {
-                redirectCount++;
-                if (redirectCount > maxRedirects) {
-                    throw new Error(`Too many redirects. Exceeded limit of ${maxRedirects}.`);
-                }
-                const location = res.headers.get('location');
-                if (!location) {
-                    throw new Error(`Redirect response status ${res.status} missing Location header.`);
-                }
-                currentUrl = normalizeUrl(new URL(location, currentUrl).toString());
-                continue;
+        const res = await doFetch(currentUrl, { method: 'GET', headers: initialHeaders, redirect: 'manual' }, timeout);
+        if ([301, 302, 303, 307, 308].includes(res.status)) {
+            redirectCount++;
+            if (redirectCount > maxRedirects) {
+                throw new Error(`Too many redirects. Exceeded limit of ${maxRedirects}.`);
             }
-            return await process(res, limit, currentUrl);
-        }
-        finally {
-            clearTimeout(id);
+            const location = res.headers.get('location');
+            if (!location) {
+                throw new Error(`Redirect response status ${res.status} missing Location header.`);
+            }
+            currentUrl = normalizeUrl(new URL(location, currentUrl).toString());
+            continue;
         }
+        return await process(res, limit, currentUrl);
     }
 }
 export async function fetchStaticHtml(url, options = {}) {
@@ -171,22 +223,14 @@ export async function postJson(url, body, headers = {}, options = {}) {
     const limit = options.bodyLimitBytes ?? 2 * 1024 * 1024;
     const target = normalizeUrl(url);
     await checkDnsSafety(new URL(target).hostname);
-    const controller = new AbortController();
-    const id = setTimeout(() => controller.abort(), timeout);
-    try {
-        const res = await fetch(target, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', ...headers },
-            body: JSON.stringify(body),
-            redirect: 'error',
-            signal: controller.signal,
-        });
-        if (!res.ok)
-            throw new Error(`Search request failed with status ${res.status} ${res.statusText}`);
-        const bytes = await readBodyWithLimit(res.body, limit);
-        return new TextDecoder().decode(bytes);
-    }
-    finally {
-        clearTimeout(id);
-    }
+    const res = await doFetch(target, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+        redirect: 'error',
+    }, timeout);
+    if (!res.ok)
+        throw new Error(`Search request failed with status ${res.status} ${res.statusText}`);
+    const bytes = await readBodyWithLimit(res.body, limit);
+    return new TextDecoder().decode(bytes);
 }

package/dist/lib/research/prompt-injection.d.ts

@@ -0,0 +1 @@
+export declare function sanitizePromptInjection(markdown: string): string;