@taurgis/bonsai 1.0.5 → 3.0.0

package/dist/lib/json-meta.js

@@ -0,0 +1,98 @@
+import { Config, Help, toConfiguredId } from '@oclif/core';
+import { buildEnvelope } from './envelope.js';
+/** Strip ANSI color codes so JSON help text stays machine-stable. */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+/** True when argv asks for help or version together with --json. */
+export function isJsonMetaRequest(argv) {
+    if (!argv.includes('--json'))
+        return false;
+    return argv.includes('--help') || argv.includes('--version');
+}
+class CaptureHelp extends Help {
+    lines = [];
+    log(...args) {
+        for (const line of args) {
+            // oclif emits section separators as log(''); drop empties so data.help stays compact.
+            if (line)
+                this.lines.push(line);
+        }
+    }
+}
+function helpSubject(argv) {
+    for (const arg of argv) {
+        if (arg === '--' || arg === '--help' || arg === 'help')
+            continue;
+        if (arg.startsWith('-'))
+            return;
+        return arg;
+    }
+    return undefined;
+}
+function envelopeCommandId(config, argv) {
+    const subject = helpSubject(argv);
+    if (!subject)
+        return config.bin;
+    const command = config.findCommand(subject);
+    if (command?.id)
+        return toConfiguredId(command.id, config);
+    const topic = config.findTopic(subject);
+    if (topic)
+        return topic.name;
+    return subject;
+}
+/**
+ * When `--json` is combined with `--help` or `--version`, oclif would print human text to stdout.
+ * Render the same content inside the standard Bonsai JSON envelope instead.
+ */
+export async function tryJsonMetaOutput(argv, root) {
+    if (!isJsonMetaRequest(argv))
+        return null;
+    try {
+        const config = await Config.load({ root });
+        if (argv.includes('--version')) {
+            return {
+                exitCode: 0,
+                envelope: buildEnvelope({
+                    command: config.bin,
+                    ok: true,
+                    exitCode: 0,
+                    stderr: '',
+                    data: {
+                        version: config.version,
+                        userAgent: config.userAgent,
+                    },
+                }),
+            };
+        }
+        const help = new CaptureHelp(config, config.pjson.oclif?.helpOptions ?? {});
+        await help.showHelp([...argv]);
+        const helpText = stripAnsi(help.lines.join('\n').trimEnd());
+        return {
+            exitCode: 0,
+            envelope: buildEnvelope({
+                command: envelopeCommandId(config, argv),
+                ok: true,
+                exitCode: 0,
+                stderr: '',
+                data: { help: helpText },
+            }),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            envelope: buildEnvelope({
+                command: 'bonsai',
+                ok: false,
+                exitCode: 1,
+                stderr: message,
+                data: null,
+                code: 'META_RENDER_FAILED',
+            }),
+        };
+    }
+}

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

@@ -25,14 +25,6 @@ export declare class CdpClient {
 }
 export declare function findChromePath(): 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

@@ -164,48 +164,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 +294,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 +358,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/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/revalidate.js

@@ -178,7 +178,9 @@ export async function revalidateCache(dataDir, existing, currentTime, options) {
                 status: 'stale',
                 artifact: existing,
                 allowed: options.allowStale,
-                error: `Revalidation failed: ${err.message}. Serving stale content within grace period.`,
+                // Carry only the underlying cause; the command layer owns the user-facing framing
+                // (so the warning reads cleanly instead of stuttering "stale … stale", "failed … failed").
+                error: err.message,
             };
         }
         throw new Error(`Revalidation failed and cache has expired beyond the grace period: ${err.message}`);

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

@@ -2,10 +2,13 @@ export interface TokenEstimate {
     compressed: number | null;
     detailed: number | null;
 }
-export type CaptureMethod = 'static_fetch' | 'browser_fallback' | 'agent_supplied' | 'route_markdown' | 'github_source';
+export declare const CAPTURE_METHODS: readonly ["static_fetch", "browser_fallback", "agent_supplied", "route_markdown", "github_source"];
+export type CaptureMethod = (typeof CAPTURE_METHODS)[number];
+export declare const ARTIFACT_TYPES: readonly ["source", "research_note", "index", "section"];
+export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
 export interface ResearchArtifactMetadata {
     schema_version: number;
-    artifact_type: 'source' | 'research_note' | 'index' | 'section';
+    artifact_type: ArtifactType;
     source_url: string;
     source_urls: string[];
     normalized_url: string;

package/dist/lib/research/schema.js

@@ -1 +1,12 @@
-export {};
+// Single source of truth for the capture-method enum. Command flag `options` lists derive from this
+// so a new method can never drift out of sync with the filters that are supposed to expose it.
+export const CAPTURE_METHODS = [
+    'static_fetch',
+    'browser_fallback',
+    'agent_supplied',
+    'route_markdown',
+    'github_source',
+];
+// Single source of truth for the artifact-type enum. `index` = navigation/hub or llms.txt site
+// index; `section` = a heading-level child of a page. Command flag `options` derive from this.
+export const ARTIFACT_TYPES = ['source', 'research_note', 'index', 'section'];

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

@@ -1,3 +1,5 @@
+/** Display label when an artifact has no topic — not a filterable topic value. */
+export declare const NO_TOPIC_LABEL = "(no topic)";
 /**
  * Pick the singular or plural noun for a count so human-readable output stays grammatical
  * ("1 entry" / "2 entries"). English has irregular plurals, so the plural is passed explicitly
@@ -20,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

@@ -1,3 +1,5 @@
+/** Display label when an artifact has no topic — not a filterable topic value. */
+export const NO_TOPIC_LABEL = '(no topic)';
 /**
  * Pick the singular or plural noun for a count so human-readable output stays grammatical
  * ("1 entry" / "2 entries"). English has irregular plurals, so the plural is passed explicitly
@@ -22,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;