@taurgis/bonsai 1.0.6 → 3.0.1

package/dist/lib/research/prompt-injection.js

@@ -0,0 +1,149 @@
+import { Buffer } from 'node:buffer';
+const REDACTION = '[Removed potentially unsafe agent instruction]';
+const ZERO_WIDTH = /[\u200b-\u200f\ufeff]/g;
+const HTML_COMMENT = /<!--[\s\S]*?-->/g;
+const BASE64_TOKEN = /(?<![A-Za-z0-9+/_-])(?:[A-Za-z0-9+/_-]{16,}={0,2})(?![A-Za-z0-9+/_-])/g;
+const HEX_TOKEN = /(?<![a-f0-9])(?:0x)?[a-f0-9]{24,}(?![a-f0-9])/gi;
+const QUOTED_SPAN = /(`[^`\n]+`|"[^"\n]+"|'[^'\n]+')/g;
+const TYPOGLYCEMIA_TARGETS = [
+    'ignore',
+    'disregard',
+    'forget',
+    'override',
+    'previous',
+    'instructions',
+    'instruction',
+    'directions',
+    'prompts',
+    'system',
+    'developer',
+    'agent',
+    'prompt',
+    'message',
+    'reveal',
+    'print',
+    'send',
+    'secrets',
+    'tokens',
+    'credentials',
+    'delete',
+    'repository',
+    'workspace',
+];
+const HARMFUL_INSTRUCTION_PATTERNS = [
+    /(^|\b(?:please|assistant|system|user|agent)\s+)ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)disregard\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)forget\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)override\s+(the\s+)?(system|developer|agent)\s+(prompt|instructions?|message)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)you\s+are\s+now\s+(in\s+)?(developer|admin|root|system)\s+mode\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)reveal\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)print\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)(exfiltrate|steal|leak)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?|private\s+data)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)send\s+(me\s+|all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)(upload|post|fetch|curl)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)delete\s+(all\s+)?(files?|the\s+repository|the\s+workspace|the\s+home\s+directory)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)run\s+.*\b(rm\s+-rf|curl\s+.*\|\s*(sh|bash)|sudo)\b/i,
+];
+function normalizeForDetection(text) {
+    return text
+        .normalize('NFKC')
+        .replace(ZERO_WIDTH, '')
+        .replace(/[^\p{L}\p{N}\s|/.-]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .split(' ')
+        .map(normalizeTypoglycemia)
+        .join(' ');
+}
+function normalizeTypoglycemia(word) {
+    const lower = word.toLowerCase();
+    return TYPOGLYCEMIA_TARGETS.find((target) => isTypoglycemiaMatch(lower, target)) ?? word;
+}
+function isTypoglycemiaMatch(word, target) {
+    if (word.length !== target.length || word.length < 4)
+        return false;
+    if (word[0] !== target[0] || word.at(-1) !== target.at(-1))
+        return false;
+    return sortLetters(word.slice(1, -1)) === sortLetters(target.slice(1, -1));
+}
+function sortLetters(value) {
+    return [...value].sort().join('');
+}
+function detectionCandidates(text) {
+    return [text, ...decodeBase64Tokens(text), ...decodeHexTokens(text)].map(normalizeForDetection);
+}
+function decodeBase64Tokens(text) {
+    return [...text.matchAll(BASE64_TOKEN)]
+        .map((match) => decodeBase64(match[0]))
+        .filter((decoded) => Boolean(decoded));
+}
+function decodeBase64(token) {
+    try {
+        const normalized = token.replace(/-/g, '+').replace(/_/g, '/');
+        const decoded = Buffer.from(normalized, 'base64').toString('utf8');
+        return isReadableDecodedText(decoded) ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function decodeHexTokens(text) {
+    return [...text.matchAll(HEX_TOKEN)]
+        .map((match) => decodeHex(match[0]))
+        .filter((decoded) => Boolean(decoded));
+}
+function decodeHex(token) {
+    const hex = token.startsWith('0x') ? token.slice(2) : token;
+    if (hex.length % 2 !== 0)
+        return null;
+    try {
+        const decoded = Buffer.from(hex, 'hex').toString('utf8');
+        return isReadableDecodedText(decoded) ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isReadableDecodedText(text) {
+    if (!/[a-z]{3}/i.test(text))
+        return false;
+    const printable = [...text].filter((char) => /[\t\n\r -~]/.test(char)).length;
+    return printable / Math.max(text.length, 1) > 0.85;
+}
+function isUnsafeAgentInstruction(text) {
+    return detectionCandidates(text).some((candidate) => HARMFUL_INSTRUCTION_PATTERNS.some((pattern) => pattern.test(candidate)));
+}
+function redactBlock(block) {
+    const withSafeSpans = redactUnsafeSpans(block);
+    return isUnsafeAgentInstruction(withSafeSpans) ? REDACTION : withSafeSpans;
+}
+function redactUnsafeSpans(block) {
+    return block
+        .replace(BASE64_TOKEN, (token) => redactTokenIfUnsafe(token, decodeBase64(token)))
+        .replace(HEX_TOKEN, (token) => redactTokenIfUnsafe(token, decodeHex(token)))
+        .replace(QUOTED_SPAN, (span) => isUnsafeAgentInstruction(stripQuotes(span)) ? REDACTION : span);
+}
+function redactTokenIfUnsafe(token, decoded) {
+    return decoded && isUnsafeAgentInstruction(decoded) ? REDACTION : token;
+}
+function stripQuotes(span) {
+    if (span.startsWith('`') || span.startsWith('"') || span.startsWith("'")) {
+        return span.slice(1, -1);
+    }
+    return span;
+}
+export function sanitizePromptInjection(markdown) {
+    return markdown
+        .replace(HTML_COMMENT, (comment) => redactBlock(comment))
+        .split(/(\n{2,})/)
+        .map((block) => {
+        if (/^\n+$/.test(block))
+            return block;
+        const lineRedacted = block
+            .split('\n')
+            .map((line) => redactBlock(line))
+            .join('\n');
+        return lineRedacted === block ? redactBlock(block) : lineRedacted;
+    })
+        .join('');
+}

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

@@ -0,0 +1,35 @@
+import { type Dispatcher } from 'undici';
+export declare const HTTPS_PROXY_ENV_VARS: string[];
+export declare const HTTP_PROXY_ENV_VARS: string[];
+export declare const NO_PROXY_ENV_VARS: string[];
+export declare const ALL_PROXY_ENV_VARS: string[];
+export declare const PROXY_TUNNEL_REJECTION_PATTERN: RegExp;
+/**
+ * Sandboxed execution environments (e.g. Claude Code's remote sandbox) block direct outbound
+ * connections to most hosts and instead require routing through a pre-configured HTTP(S) proxy,
+ * advertised via the standard *_PROXY env vars. Detecting it lets Bonsai transparently reach
+ * sites — like developer.salesforce.com — that are otherwise unreachable from within the sandbox.
+ */
+export declare function isProxyConfigured(): boolean;
+/**
+ * An undici Dispatcher that honors HTTPS_PROXY/HTTP_PROXY/NO_PROXY, or undefined when no proxy
+ * is configured so callers fall back to normal direct networking. The dispatcher is expensive
+ * enough to be worth reusing across requests, but undici's own agent captures its proxy targets
+ * once at construction time and never re-reads them — so the cache is keyed on a snapshot of the
+ * relevant env vars and rebuilt whenever that snapshot changes, instead of being pinned forever
+ * to whatever was configured on the first call. The discarded dispatcher is closed (not just
+ * dropped) so its pooled keep-alive sockets don't leak past the env change that replaced it.
+ */
+export declare function getProxyDispatcher(): Dispatcher | undefined;
+/**
+ * Chrome CLI flags that route headless navigation through the same proxy as fetch(), or an
+ * empty array when no proxy is configured. Chrome has its own network stack (CDP navigation
+ * never goes through Node's fetch/undici), so it needs to be told about the proxy separately.
+ *
+ * Built as a scheme-qualified `--proxy-server` value (`http=...;https=...`) rather than one
+ * blanket proxy for every scheme, matching undici's EnvHttpProxyAgent, which picks HTTP_PROXY or
+ * HTTPS_PROXY per the target URL's scheme. A single unqualified value would force Chrome to
+ * route all its traffic (including plain-http sub-resources) through whichever var happened to
+ * be set, silently disagreeing with how fetch() routes the same traffic.
+ */
+export declare function getChromeProxyArgs(): string[];

package/dist/lib/research/proxy.js

@@ -0,0 +1,107 @@
+import { EnvHttpProxyAgent } from 'undici';
+// Order matters: undici's own EnvHttpProxyAgent (github.com/nodejs/undici lib/dispatcher/
+// env-http-proxy-agent.js) prefers the lowercase variant of each var over its uppercase twin
+// when both are set. These lists are read in the same order everywhere in this module so that
+// Chrome's CLI flags and undici's dispatcher can never disagree about which value "the" proxy is.
+export const HTTPS_PROXY_ENV_VARS = ['https_proxy', 'HTTPS_PROXY'];
+export const HTTP_PROXY_ENV_VARS = ['http_proxy', 'HTTP_PROXY'];
+export const NO_PROXY_ENV_VARS = ['no_proxy', 'NO_PROXY'];
+export const ALL_PROXY_ENV_VARS = [
+    ...HTTPS_PROXY_ENV_VARS,
+    ...HTTP_PROXY_ENV_VARS,
+    ...NO_PROXY_ENV_VARS,
+];
+// The message undici's ProxyAgent throws (nested in a fetch TypeError's `.cause`) when the proxy
+// itself declines to tunnel to the target host — as opposed to any other pre-response transport
+// failure (DNS, refused connection, a genuinely unreachable destination). Shared by fetcher.ts
+// (to decide whether a proxied failure is worth retrying direct) and fetch.ts's failure-guidance
+// patterns (to give proxy-specific advice), so the two stay in sync by construction.
+export const PROXY_TUNNEL_REJECTION_PATTERN = /proxy response.*tunneling/i;
+function firstEnv(names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Sandboxed execution environments (e.g. Claude Code's remote sandbox) block direct outbound
+ * connections to most hosts and instead require routing through a pre-configured HTTP(S) proxy,
+ * advertised via the standard *_PROXY env vars. Detecting it lets Bonsai transparently reach
+ * sites — like developer.salesforce.com — that are otherwise unreachable from within the sandbox.
+ */
+export function isProxyConfigured() {
+    return Boolean(firstEnv(HTTPS_PROXY_ENV_VARS) || firstEnv(HTTP_PROXY_ENV_VARS));
+}
+let cachedDispatcher;
+let cachedProxyEnvSnapshot;
+// JSON-encoded rather than joined with a plain delimiter: a delimiter that can also appear inside
+// a value (e.g. a space, and NO_PROXY conventionally uses "host1, host2") lets two different sets
+// of values collide on the same joined string. JSON.stringify's per-element quoting/escaping is a
+// well-tested way to avoid that ambiguity without hand-rolling an escape scheme.
+function proxyEnvSnapshot() {
+    return JSON.stringify(ALL_PROXY_ENV_VARS.map((name) => process.env[name] ?? ''));
+}
+/**
+ * An undici Dispatcher that honors HTTPS_PROXY/HTTP_PROXY/NO_PROXY, or undefined when no proxy
+ * is configured so callers fall back to normal direct networking. The dispatcher is expensive
+ * enough to be worth reusing across requests, but undici's own agent captures its proxy targets
+ * once at construction time and never re-reads them — so the cache is keyed on a snapshot of the
+ * relevant env vars and rebuilt whenever that snapshot changes, instead of being pinned forever
+ * to whatever was configured on the first call. The discarded dispatcher is closed (not just
+ * dropped) so its pooled keep-alive sockets don't leak past the env change that replaced it.
+ */
+export function getProxyDispatcher() {
+    if (!isProxyConfigured())
+        return undefined;
+    const snapshot = proxyEnvSnapshot();
+    if (!cachedDispatcher || cachedProxyEnvSnapshot !== snapshot) {
+        const stale = cachedDispatcher;
+        cachedDispatcher = new EnvHttpProxyAgent();
+        cachedProxyEnvSnapshot = snapshot;
+        void stale?.close().catch(() => { });
+    }
+    return cachedDispatcher;
+}
+// undici's EnvHttpProxyAgent treats a bare NO_PROXY entry (e.g. "example.com") as matching both
+// the exact host AND any subdomain — it strips a leading "*." or "." before comparing, then
+// checks the hostname for an exact or suffix match. Chromium's --proxy-bypass-list grammar draws
+// a hard line instead: a bare "example.com" matches only that exact host, and subdomain matching
+// requires an explicit "*." prefix. Emitting both forms for every entry reproduces undici's
+// exact-or-subdomain behavior in Chrome too, so the two proxied paths agree on what bypasses.
+function toChromeBypassList(noProxy) {
+    const hosts = noProxy
+        .split(/[,\s]+/)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^\*?\./, ''));
+    return Array.from(new Set(hosts.flatMap((host) => [host, `*.${host}`]))).join(',');
+}
+/**
+ * Chrome CLI flags that route headless navigation through the same proxy as fetch(), or an
+ * empty array when no proxy is configured. Chrome has its own network stack (CDP navigation
+ * never goes through Node's fetch/undici), so it needs to be told about the proxy separately.
+ *
+ * Built as a scheme-qualified `--proxy-server` value (`http=...;https=...`) rather than one
+ * blanket proxy for every scheme, matching undici's EnvHttpProxyAgent, which picks HTTP_PROXY or
+ * HTTPS_PROXY per the target URL's scheme. A single unqualified value would force Chrome to
+ * route all its traffic (including plain-http sub-resources) through whichever var happened to
+ * be set, silently disagreeing with how fetch() routes the same traffic.
+ */
+export function getChromeProxyArgs() {
+    const httpsProxy = firstEnv(HTTPS_PROXY_ENV_VARS);
+    const httpProxy = firstEnv(HTTP_PROXY_ENV_VARS);
+    if (!httpsProxy && !httpProxy)
+        return [];
+    const schemeMappings = [];
+    if (httpProxy)
+        schemeMappings.push(`http=${httpProxy}`);
+    if (httpsProxy)
+        schemeMappings.push(`https=${httpsProxy}`);
+    const args = [`--proxy-server=${schemeMappings.join(';')}`];
+    const noProxy = firstEnv(NO_PROXY_ENV_VARS);
+    if (noProxy)
+        args.push(`--proxy-bypass-list=${toChromeBypassList(noProxy)}`);
+    return args;
+}

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

@@ -15,6 +15,24 @@ export interface ContentMetrics {
     bullets: number;
     headings: number;
 }
+/** Maximum allowed capture-duration regression vs baseline (percent slower). */
+export declare const TIMING_REGRESSION_LIMIT_PCT = 25;
+export interface TimingRegression {
+    deltaPct: number | null;
+    regressed: boolean;
+}
+/** Returns whether `currentMs` exceeds baseline by more than TIMING_REGRESSION_LIMIT_PCT. */
+export declare function timingRegression(currentMs: number, baselineMs: number | null | undefined): TimingRegression;
+export interface TimingBaselineRecord {
+    durationMs: number;
+    capturedAt: string;
+}
+/** Parses a committed `baseline/<id>.timing.json` file. */
+export declare function parseTimingBaseline(raw: string): TimingBaselineRecord | null;
+/** Serializes a timing baseline record for `baseline/<id>.timing.json`. */
+export declare function formatTimingBaseline(durationMs: number, capturedAt?: string): string;
+/** True when `candidate` carries strictly more structural content than `baseline`. */
+export declare function contentRicherThan(candidate: ContentMetrics, baseline: ContentMetrics): boolean;
 /**
  * Structural content signals used to catch information loss between baseline and current output:
  * a sudden drop in code blocks, tables, images, or steps flags that a fetch change dropped content.

package/dist/lib/research/regression.js

@@ -38,6 +38,53 @@ export function normalizeRegressionMarkdown(markdown) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
+/** Maximum allowed capture-duration regression vs baseline (percent slower). */
+export const TIMING_REGRESSION_LIMIT_PCT = 25;
+/** Returns whether `currentMs` exceeds baseline by more than TIMING_REGRESSION_LIMIT_PCT. */
+export function timingRegression(currentMs, baselineMs) {
+    if (!baselineMs || baselineMs <= 0)
+        return { deltaPct: null, regressed: false };
+    const deltaPct = Number((((currentMs - baselineMs) / baselineMs) * 100).toFixed(2));
+    return { deltaPct, regressed: deltaPct > TIMING_REGRESSION_LIMIT_PCT };
+}
+/** Parses a committed `baseline/<id>.timing.json` file. */
+export function parseTimingBaseline(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.durationMs !== 'number' || parsed.durationMs <= 0)
+            return null;
+        return {
+            durationMs: parsed.durationMs,
+            capturedAt: typeof parsed.capturedAt === 'string' ? parsed.capturedAt : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Serializes a timing baseline record for `baseline/<id>.timing.json`. */
+export function formatTimingBaseline(durationMs, capturedAt = new Date().toISOString()) {
+    return `${JSON.stringify({ durationMs, capturedAt }, null, 2)}\n`;
+}
+/** Structural signals compared before char count when picking DOM vs API Markdown. */
+const CONTENT_RICHNESS_KEYS = [
+    'tables',
+    'codeBlocks',
+    'headings',
+    'images',
+    'orderedSteps',
+    'chars',
+];
+/** True when `candidate` carries strictly more structural content than `baseline`. */
+export function contentRicherThan(candidate, baseline) {
+    for (const key of CONTENT_RICHNESS_KEYS) {
+        if (candidate[key] > baseline[key])
+            return true;
+        if (candidate[key] < baseline[key])
+            return false;
+    }
+    return false;
+}
 /**
  * Structural content signals used to catch information loss between baseline and current output:
  * a sudden drop in code blocks, tables, images, or steps flags that a fetch change dropped content.

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

@@ -1,5 +1,4 @@
 import type { ResearchArtifact } from './schema.js';
-export declare function isResearchFile(file: string): boolean;
 /**
  * Scans a cache directory and maps each valid artifact file through a callback.
  * Return null from the callback to skip an entry; all non-null results are collected.

package/dist/lib/research/storage.js

@@ -2,12 +2,8 @@ import { join } from 'node:path';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, renameSync, } from 'node:fs';
 import { atomicWriteFile } from '../atomic-write.js';
 import { parseArtifact, serializeArtifact } from './artifact.js';
-export function isResearchFile(file) {
-    return (file.endsWith('.md') &&
-        !file.includes('.tmp') &&
-        !file.includes('.corrupt') &&
-        !file.includes('.superseded'));
-}
+import { loadIndexedArtifactsForDir } from './artifact-index.js';
+import { isResearchFile } from './url.js';
 /**
  * Scans a cache directory and maps each valid artifact file through a callback.
  * Return null from the callback to skip an entry; all non-null results are collected.
@@ -169,11 +165,17 @@ export function locateArtifact(dataDirs, key) {
  */
 export function scanCacheDirs(dataDirs, fn) {
     const seen = new Set();
-    return dataDirs.flatMap((dataDir) => scanCacheDir(join(dataDir, 'research'), (artifact, filePath) => {
-        const key = artifact.metadata.cache_key;
-        if (seen.has(key))
-            return null;
-        seen.add(key);
-        return fn(artifact, filePath);
-    }));
+    return dataDirs.flatMap((dataDir) => {
+        const researchDir = join(dataDir, 'research');
+        const searchable = loadIndexedArtifactsForDir(researchDir);
+        return searchable
+            .map(({ artifact, filePath }) => {
+            const key = artifact.metadata.cache_key;
+            if (seen.has(key))
+                return null;
+            seen.add(key);
+            return fn(artifact, filePath);
+        })
+            .filter((x) => x !== null);
+    });
 }

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

@@ -17,8 +17,30 @@ export declare function isSafeIp(ip: string): boolean;
  * Validates a hostname to ensure it is not blocked (e.g. localhost or literal private IP).
  */
 export declare function validateHostname(hostname: string): void;
+/**
+ * Whether the input looks like a URL that simply forgot its `http(s)://` scheme
+ * (`example.com`, `docs.nestjs.com/guide`, `192.168.1.1`) rather than unparseable junk.
+ * Lets every command turn a scheme-less URL into the same actionable "did you mean https://…" hint
+ * that the root `bonsai <url>` shorthand already gives via the command_not_found hook.
+ */
+export declare function looksLikeSchemelessUrl(input: string): boolean;
 /**
  * Parses and normalizes a URL. Strips fragments, credentials, default ports,
  * and sorts query parameters lexicographically.
  */
 export declare function normalizeUrl(input: string): string;
+/**
+ * Checks if a URL matches a wildcard pattern (case-insensitive, supports * wildcard).
+ */
+export declare function matchesUrlGlob(url: string, glob: string): boolean;
+/**
+ * Checks if artifact metadata contains any URL matching the filter glob.
+ */
+export declare function artifactMatchesUrlFilter(meta: {
+    source_urls?: string[];
+    source_url?: string;
+}, filterUrl: string | undefined): boolean;
+/**
+ * Checks if a filename matches the standard research note naming pattern.
+ */
+export declare function isResearchFile(file: string): boolean;

package/dist/lib/research/url.js

@@ -83,6 +83,30 @@ export function validateHostname(hostname) {
         }
     }
 }
+// Dot-separated, non-empty labels: a real domain (`docs.nestjs.com`) or IPv4 (`192.168.1.1`). The
+// URL parser also accepts a leading-dot filename (`.env`) or relative path (`./x`) as a "host", whose
+// suggestion would be a nonsense `https://.env`; requiring well-formed labels rejects those. Anchored
+// with no overlapping quantifiers, so it is ReDoS-safe on the (already length-bounded) host. This is
+// the single owner of the domain-shape test; the command_not_found hook consumes it too.
+const DOMAIN_OR_IPV4 = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+/**
+ * Whether the input looks like a URL that simply forgot its `http(s)://` scheme
+ * (`example.com`, `docs.nestjs.com/guide`, `192.168.1.1`) rather than unparseable junk.
+ * Lets every command turn a scheme-less URL into the same actionable "did you mean https://…" hint
+ * that the root `bonsai <url>` shorthand already gives via the command_not_found hook.
+ */
+export function looksLikeSchemelessUrl(input) {
+    if (input.includes('://'))
+        return false;
+    let hostname;
+    try {
+        hostname = new URL(`https://${input}`).hostname;
+    }
+    catch {
+        return false;
+    }
+    return DOMAIN_OR_IPV4.test(hostname);
+}
 /**
  * Parses and normalizes a URL. Strips fragments, credentials, default ports,
  * and sorts query parameters lexicographically.
@@ -95,7 +119,12 @@ export function normalizeUrl(input) {
     catch {
         // new URL() only ever throws the constant "Invalid URL" (no structured cause worth keeping),
         // and every caller prefixes its own "Invalid URL:" — forwarding the native text would stutter.
-        // Drop the binding and emit an actionable, self-contained reason instead.
+        // A scheme-less but domain-shaped input is the common "forgot https://" mistake, so steer the
+        // user to the corrected URL (clig.dev: show the fix, never auto-run it); otherwise emit a
+        // self-contained "couldn't parse" reason.
+        if (looksLikeSchemelessUrl(input)) {
+            throw new Error(`"${input}" is missing a URL scheme. Did you mean https://${input}? Only http:// and https:// URLs are supported.`);
+        }
         throw new Error(`Could not parse "${input}" as a URL; provide a full http(s) URL like https://example.com/page.`);
     }
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
@@ -122,3 +151,36 @@ export function normalizeUrl(input) {
     url.search = new URLSearchParams(params).toString();
     return url.toString();
 }
+/**
+ * Checks if a URL matches a wildcard pattern (case-insensitive, supports * wildcard).
+ */
+export function matchesUrlGlob(url, glob) {
+    // Collapse consecutive wildcards to prevent ReDoS
+    const collapsedGlob = glob.replace(/\*+/g, '*');
+    const normalizedGlob = collapsedGlob.toLowerCase();
+    const normalizedUrl = url.toLowerCase();
+    // Escape regex characters except *
+    const escapedGlob = normalizedGlob.replace(/[/\-\\^$+?.()|[\]{}]/g, '\\$&');
+    // Replace * with .*
+    const regexString = '^' + escapedGlob.replace(/\*/g, '.*') + '$';
+    const regex = new RegExp(regexString);
+    return regex.test(normalizedUrl);
+}
+/**
+ * Checks if artifact metadata contains any URL matching the filter glob.
+ */
+export function artifactMatchesUrlFilter(meta, filterUrl) {
+    if (!filterUrl)
+        return true;
+    const urls = meta.source_urls || (meta.source_url ? [meta.source_url] : []);
+    return urls.some((u) => matchesUrlGlob(u, filterUrl));
+}
+/**
+ * Checks if a filename matches the standard research note naming pattern.
+ */
+export function isResearchFile(file) {
+    return (file.endsWith('.md') &&
+        !file.includes('.tmp') &&
+        !file.includes('.corrupt') &&
+        !file.includes('.superseded'));
+}

package/dist/lib/text.d.ts

@@ -22,9 +22,11 @@ export declare function resultListHeading(total: number, shown: number, labels:
  * stdout heading is suppressed and an agent would otherwise get no signal that results were capped.
  */
 export declare function truncationNotice(total: number, shown: number, labels: ResultListLabels): string | null;
+/** Max edit distance for a plausible typo; scales with input length. */
+export declare function maxFuzzyDistance(input: string): number;
 /**
  * Levenshtein edit distance: the minimum number of single-character insertions, deletions, or
- * substitutions to turn `s1` into `s2`. Shared by fuzzy search ranking and command-typo suggestion.
+ * substitutions to turn `s1` into `s2`. Shared by command-typo suggestion.
  */
 export declare function levenshtein(s1: string, s2: string): number;
 /**

package/dist/lib/text.js

@@ -24,9 +24,17 @@ export function truncationNotice(total, shown, labels) {
         return null;
     return `${total} entries matched; returning the ${labels.order} ${shown}. Raise --limit (max ${labels.maxLimit}) to see more.`;
 }
+/** Max edit distance for a plausible typo; scales with input length. */
+export function maxFuzzyDistance(input) {
+    if (input.length <= 3)
+        return 1;
+    if (input.length <= 5)
+        return 2;
+    return 3;
+}
 /**
  * Levenshtein edit distance: the minimum number of single-character insertions, deletions, or
- * substitutions to turn `s1` into `s2`. Shared by fuzzy search ranking and command-typo suggestion.
+ * substitutions to turn `s1` into `s2`. Shared by command-typo suggestion.
  */
 export function levenshtein(s1, s2) {
     if (s1.length < s2.length)

package/dist/sites/coveo.d.ts

@@ -0,0 +1,7 @@
+export declare const ALLOWED_DOC_HOSTS: Set<string>;
+export declare function isAllowedDocHost(hostname: string): boolean;
+/**
+ * Coveo indexes Help articles under an internal `/help_doccontent` URL; rewrite it to the
+ * canonical `/s/articleView` page a human (or our fetcher) can actually open.
+ */
+export declare function normalizeHelpDocContentUrl(rawUrl: string): string;

package/dist/sites/coveo.js

@@ -0,0 +1,33 @@
+export const ALLOWED_DOC_HOSTS = new Set(['help.salesforce.com', 'developer.salesforce.com']);
+export function isAllowedDocHost(hostname) {
+    return ALLOWED_DOC_HOSTS.has(hostname.toLowerCase());
+}
+/**
+ * Coveo indexes Help articles under an internal `/help_doccontent` URL; rewrite it to the
+ * canonical `/s/articleView` page a human (or our fetcher) can actually open.
+ */
+export function normalizeHelpDocContentUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return rawUrl;
+    }
+    if (url.hostname.toLowerCase() !== 'help.salesforce.com')
+        return rawUrl;
+    if (!url.pathname.toLowerCase().startsWith('/help_doccontent'))
+        return rawUrl;
+    const id = url.searchParams.get('id');
+    if (!id)
+        return rawUrl;
+    const articleUrl = new URL('https://help.salesforce.com/s/articleView');
+    articleUrl.searchParams.set('id', id.endsWith('.htm') ? id : `${id}.htm`);
+    articleUrl.searchParams.set('type', '5');
+    for (const key of ['release', 'language']) {
+        const value = url.searchParams.get(key);
+        if (value)
+            articleUrl.searchParams.set(key, value);
+    }
+    return articleUrl.toString();
+}

package/dist/sites/index.js

@@ -1,27 +1,10 @@
 import { salesforce } from './salesforce/index.js';
 import { salesforceDeveloper } from './salesforce-developer/index.js';
-import { nextjs } from './nextjs/index.js';
-import { react, vue, tailwind, jest, cypress, vitest, vitepress } from './algolia.js';
-import { angular, redux, vite, fastify, rollup, vueuse } from './auto.js';
 // The known documentation sites. A plain constant, not a registry: these ship
 // with the CLI, so there is nothing to register at runtime. Sites with custom
-// fetch/search behavior live in their own module (e.g. ./salesforce). Salesforce Help and
+// fetch behavior live in their own module (e.g. ./salesforce). Salesforce Help and
 // Salesforce Developer are separate modules — different domains, different extraction.
 export const SITES = [
-    react,
-    vue,
-    tailwind,
-    nextjs,
-    jest,
-    cypress,
-    vitest,
-    vitepress,
-    angular,
-    redux,
-    vite,
-    fastify,
-    rollup,
-    vueuse,
     salesforce,
     salesforceDeveloper,
     // TanStack docs embed a GitHub "edit this page" link, so capture resolves the page's source

package/dist/sites/salesforce/fetch-page.js

@@ -1,5 +1,5 @@
 import { fetchSalesforceDoc } from '../salesforce-doc-fetch.js';
-import { normalizeHelpDocContentUrl } from './coveo.js';
+import { normalizeHelpDocContentUrl } from '../coveo.js';
 // Containers a Help article renders into (inside shadow DOM); the shared fetcher pierces
 // shadow roots to find them, falling back to the page body when none match.
 const CONTENT_SELECTORS = [