@taurgis/bonsai 1.0.6 → 3.0.1

package/dist/base-command.js

@@ -2,6 +2,7 @@ import { Command, Errors, toConfiguredId } from '@oclif/core';
 import { invalidEnvOverrideWarnings } from './lib/config/index.js';
 import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
 import { resolveResearchTarget, } from './lib/research/resolve-target.js';
+import { looksLikeSchemelessUrl } from './lib/research/url.js';
 /**
  * Shared base for every Bonsai command. Enables oclif's native `--json` flag,
  * parses args/flags once in `init()` so commands read `this.args`/`this.flags`
@@ -12,9 +13,10 @@ export class BaseCommand extends Command {
     static enableJsonFlag = true;
     flags;
     args;
+    parsedArgv;
     async init() {
         await super.init();
-        const { args, flags } = await this.parse({
+        const { args, flags, argv } = await this.parse({
             flags: this.ctor.flags,
             enableJsonFlag: this.ctor.enableJsonFlag,
             args: this.ctor.args,
@@ -22,6 +24,7 @@ export class BaseCommand extends Command {
         });
         this.flags = flags;
         this.args = args;
+        this.parsedArgv = argv;
         // Surface a set-but-invalid BONSAI_* override once per run. Resolution silently drops such a
         // value, so without this a typo'd env var would take no effect with no signal. Warnings go to
         // stderr (even under --json), so machine output stays clean.
@@ -30,7 +33,7 @@ export class BaseCommand extends Command {
     }
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
-     * but our warnings (secret-redirect, stale-serve, remote-search fallback, prune failures) are
+     * but our warnings (secret-redirect, stale-serve, prune failures) are
      * security- and freshness-relevant side effects users must see. stderr never pollutes the stdout
      * JSON envelope, so machine output stays clean.
      */
@@ -59,6 +62,15 @@ export class BaseCommand extends Command {
         // [UnparsedCommand] warning to stderr even under `--json`. CLIParseError subclasses carry `parse`.
         if (err && typeof err === 'object' && 'parse' in err)
             this.parsed = true;
+        // Attach the stable code to the error itself so oclif's human pretty-print renders the same
+        // `Code:` line that `--json` already reports via stableErrorCodeFrom. Without this, built-in
+        // oclif parse errors (invalid enum value, missing arg, unknown flag) printed a code under
+        // --json but not for humans — the two output modes disagreed on whether an error had a code.
+        if (err && typeof err === 'object' && !err.code) {
+            const code = stableErrorCodeFrom(err);
+            if (code)
+                err.code = code;
+        }
         process.exitCode = process.exitCode ?? BaseCommand.exitCodeOf(err);
         return super.catch(err);
     }
@@ -66,7 +78,12 @@ export class BaseCommand extends Command {
     envelopeCommandId() {
         return this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : this.config.bin;
     }
-    /** Resolve a URL against the research cache, exiting with INVALID_URL on normalization failure. */
+    /**
+     * Resolve a URL against the research cache, exiting on a normalization failure. 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.
+     */
     resolveResearchTargetOrFail(url, extra) {
         try {
             return resolveResearchTarget({
@@ -78,8 +95,19 @@ export class BaseCommand extends Command {
             });
         }
         catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2, code: 'INVALID_URL' });
+            this.failInvalidUrl(url, err.message);
+        }
+    }
+    /**
+     * Single exit point for a URL that failed normalization, shared by every URL-accepting command.
+     * The scheme-less message is already self-contained and actionable, so it is surfaced as-is;
+     * other parse failures keep the "Invalid URL:" prefix for context.
+     */
+    failInvalidUrl(url, message) {
+        if (looksLikeSchemelessUrl(url)) {
+            this.error(message, { exit: 2, code: 'MISSING_URL_SCHEME' });
         }
+        this.error(`Invalid URL: ${message}`, { exit: 2, code: 'INVALID_URL' });
     }
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     envelope(parts) {

package/dist/commands/fetch.d.ts

@@ -8,6 +8,7 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
         description: string;
         command: string;
     }[];
+    static strict: boolean;
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -35,7 +36,9 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private persistFreshArtifact;
     private persistSectionsIfFresh;
     run(): Promise<unknown>;
+    private fetchSingleTarget;
 }
+export declare function describeError(err: unknown): string;
 export declare function fetchFailureGuidance(message: string, url: string): {
     suggestions: string[];
     ref?: string;

package/dist/commands/fetch.js

@@ -1,4 +1,4 @@
-import { Args, Flags, ux } from '@oclif/core';
+import { Args, Flags, ux, Errors } from '@oclif/core';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -9,6 +9,7 @@ import { loadSummaryLevel } from '../lib/config/index.js';
 import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
 import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
 import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
+import { PROXY_TUNNEL_REJECTION_PATTERN } from '../lib/research/proxy.js';
 import { fetchRenderedHtml } from '../lib/research/browser.js';
 import { capturePage } from '../lib/research/capture.js';
 import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
@@ -34,6 +35,7 @@ export default class FetchCommand extends BaseCommand {
             command: '<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json',
         },
     ];
+    static strict = false;
     static args = {
         url: Args.string({
             required: true,
@@ -193,8 +195,14 @@ export default class FetchCommand extends BaseCommand {
     // failure — validation errors (bad flags/URL) exit before the try — so the contract's runtime code
     // (1) applies. Suggestions render on stderr for humans only; under --json the envelope carries just
     // the message (toErrorJson), so machine output is unchanged.
+    //
+    // Uses `describeError` (below) rather than `err.message` alone: Node/undici's fetch wraps
+    // transport failures (DNS, refused connections, a proxy that won't tunnel to the host) in a
+    // generic "fetch failed" TypeError with the real reason nested in `.cause`, so reading only the
+    // top message would surface a content-free "fetch failed" for exactly the failures a user most
+    // needs a hint for.
     emitFetchError(err, url) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = describeError(err);
         const guidance = fetchFailureGuidance(message, url);
         this.error(message, {
             exit: 1,
@@ -255,49 +263,31 @@ export default class FetchCommand extends BaseCommand {
         }
     }
     async run() {
-        const { url } = this.args;
+        const urls = this.parsedArgv;
         const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
         this.validateDurationFlags(ttl, maxAge);
-        const target = this.resolveResearchTargetOrFail(url, {
-            flagOverride: this.flags.storage,
-            lookup: !this.flags.force,
-        });
-        const { cacheKey, located, normalizedUrl, roots } = target;
         const summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
         const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
         const currentTime = new Date();
+        const results = [];
         try {
-            if (!this.jsonEnabled()) {
-                ux.action.start('Fetching ' + normalizedUrl);
-            }
-            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
-            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
-            if (!this.jsonEnabled()) {
-                const CACHE_STATUS_LABEL = {
-                    hit: 'cached',
-                    miss: 'done',
-                    refreshed: 'refreshed',
-                    revalidated: 'revalidated',
-                    stale: 'served stale',
-                };
-                ux.action.stop(CACHE_STATUS_LABEL[cacheStatus] ?? cacheStatus);
-            }
-            const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
-            const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
-            if (!this.jsonEnabled()) {
-                this.log(content);
+            for (const url of urls) {
+                results.push(await this.fetchSingleTarget(url, currentTime, tmpDir, summaryLevel, format, urls.length > 1));
             }
-            return resultData;
+            return urls.length === 1 ? results[0] : results;
         }
         catch (err) {
             if (!this.jsonEnabled()) {
                 ux.action.stop('failed');
             }
+            if (err instanceof Errors.CLIError)
+                throw err;
             // Stale-serve (exit 5) signals via process.exitCode and never throws, so it bypasses this
             // path; only genuine fetch/extract failures land here and get classified guidance. Use the
             // normalized URL in hints so the copy-paste command is canonical (and never echoes raw,
             // unsanitized user input back to the terminal).
-            this.emitFetchError(err, normalizedUrl);
+            const failedUrl = urls[results.length] || urls[0] || '';
+            this.emitFetchError(err, failedUrl);
         }
         finally {
             if (tmpDir) {
@@ -305,13 +295,63 @@ export default class FetchCommand extends BaseCommand {
             }
         }
     }
+    async fetchSingleTarget(url, currentTime, tmpDir, summaryLevel, format, showSeparator) {
+        const target = this.resolveResearchTargetOrFail(url, {
+            flagOverride: this.flags.storage,
+            lookup: !this.flags.force,
+        });
+        const { cacheKey, located, normalizedUrl, roots } = target;
+        if (!this.jsonEnabled()) {
+            ux.action.start('Fetching ' + normalizedUrl);
+        }
+        const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
+        this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
+        if (!this.jsonEnabled()) {
+            const CACHE_STATUS_LABEL = {
+                hit: 'cached',
+                miss: 'done',
+                refreshed: 'refreshed',
+                revalidated: 'revalidated',
+                stale: 'served stale',
+            };
+            ux.action.stop(CACHE_STATUS_LABEL[cacheStatus] ?? cacheStatus);
+        }
+        const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
+        const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
+        if (!this.jsonEnabled()) {
+            this.log(content);
+            if (showSeparator) {
+                this.log('\n' + '='.repeat(40) + '\n');
+            }
+        }
+        return resultData;
+    }
+}
+// How many `.cause` levels to walk. Real undici/Node transport errors nest at most 1-2 deep;
+// the cap exists so a self-referential or cyclic `.cause` chain (Error.cause is an arbitrary,
+// unvalidated property — nothing prevents `e.cause = e`, whether from a bug in this codebase or
+// a dependency) can't hang the process, rather than being a limit expected to matter in practice.
+const MAX_CAUSE_DEPTH = 10;
+// Walks an Error's `.cause` chain and joins every message, deepest last. Node/undici's fetch
+// throws a generic `TypeError: fetch failed` for transport-level failures, with the actionable
+// detail (e.g. a proxy's tunnel rejection) nested one or two `.cause` levels down.
+export function describeError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const parts = [err.message];
+    let cause = err.cause;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && cause instanceof Error; depth++) {
+        parts.push(cause.message);
+        cause = cause.cause;
+    }
+    return parts.join(': ');
 }
 // Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
 // unrecognized failures, which then surface with their original message and no extra hint. The
 // patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
 // change. Resolutions mirror the published troubleshooting guide.
 export function fetchFailureGuidance(message, url) {
-    const ref = 'https://taurgis.github.io/bonsai/troubleshooting';
+    const ref = 'https://bonsai.rhino-inquisitor.com/troubleshooting';
     // Name the pipe step explicitly: bare `import --stdin` blocks waiting for input, so a reader (or
     // an agent) running the hint verbatim would hang. Show the content being piped in from a file.
     const importHint = `Open it in a browser, save the page, then import it: cat page.md | bonsai import ${url} --stdin`;
@@ -347,6 +387,32 @@ export function fetchFailureGuidance(message, url) {
             suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
         };
     }
+    // A configured proxy (HTTPS_PROXY/HTTP_PROXY) refused to tunnel to this host — distinct from
+    // the destination's own 401/403 above, which is the site itself rejecting the request. Shared
+    // with fetcher.ts's retry-fallback check so the two stay in sync by construction.
+    if (PROXY_TUNNEL_REJECTION_PATTERN.test(message)) {
+        return {
+            suggestions: [
+                "The configured proxy (HTTPS_PROXY/HTTP_PROXY) won't reach this host. Check its allowlist, or add the host to NO_PROXY to bypass the proxy for it.",
+                importHint,
+            ],
+            ref,
+        };
+    }
+    // The connection failed before any HTTP response was received — network-down, DNS, TLS, or a
+    // proxy issue not specifically matched above. Node/undici's fetch reports all of these as a
+    // generic "fetch failed" TypeError with no further suffix; the negative lookahead keeps this
+    // from also matching assertOk's "Fetch failed with status NNN ..." (a real HTTP response was
+    // received in that case, so it isn't a transport failure at all).
+    if (/^fetch failed\b(?!\s+with status)/i.test(message)) {
+        return {
+            suggestions: [
+                'The connection failed before a response was received. Check network connectivity and any HTTPS_PROXY/HTTP_PROXY/NO_PROXY settings.',
+                importHint,
+            ],
+            ref,
+        };
+    }
     // A hostname that only resolves to a private/local IP at request time (literal private addresses
     // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
     if (/blocked local or private target/.test(message)) {

package/dist/commands/import.js

@@ -11,6 +11,7 @@ import { writeArtifactSecurely } from '../lib/research/secure-write.js';
 import { loadSummaryLevel } from '../lib/config/index.js';
 import { durationFlagError, getPolicy } from '../lib/research/freshness.js';
 import { buildCompressed } from '../lib/research/compress.js';
+import { sanitizePromptInjection } from '../lib/research/prompt-injection.js';
 import { applyAutoTags } from '../lib/research/keywords.js';
 import { estimateTokens } from '../lib/research/token-estimate.js';
 export default class ResearchImport extends BaseCommand {
@@ -30,6 +31,10 @@ export default class ResearchImport extends BaseCommand {
             description: 'import research from a local Markdown file',
             command: '<%= config.bin %> import https://example.com/docs --file path/to/notes.md',
         },
+        {
+            description: 'import research from stdin using the standard file placeholder',
+            command: 'cat notes.md | <%= config.bin %> import https://example.com/docs --file -',
+        },
     ];
     static args = {
         url: Args.string({
@@ -47,7 +52,7 @@ export default class ResearchImport extends BaseCommand {
             default: false,
         }),
         file: Flags.string({
-            description: 'path to a Markdown file containing research notes to import',
+            description: 'path to a Markdown file containing research notes to import, or "-" for stdin',
         }),
         'input-format': Flags.option({
             description: 'format of the input provided',
@@ -121,7 +126,9 @@ export default class ResearchImport extends BaseCommand {
                 return normalizeUrl(u);
             }
             catch (err) {
-                this.error(`Invalid URL: ${err.message}`, { exit: 2, code: 'INVALID_URL' });
+                // Shared exit point: a forgotten scheme reports MISSING_URL_SCHEME like every other command,
+                // while genuinely malformed input stays INVALID_URL.
+                this.failInvalidUrl(u, err.message);
             }
         });
         return hasMulti ? normalized.sort() : normalized;
@@ -168,6 +175,7 @@ export default class ResearchImport extends BaseCommand {
         const bin = this.config.bin;
         return [
             `Pipe Markdown content, e.g. cat notes.md | ${bin} import <url> --stdin`,
+            `Or use the standard stdin placeholder: cat notes.md | ${bin} import <url> --file -`,
             `Or read from a file: ${bin} import <url> --file notes.md`,
         ];
     }
@@ -222,7 +230,8 @@ export default class ResearchImport extends BaseCommand {
         return content;
     }
     async readAndValidateInput() {
-        if (this.flags.stdin) {
+        const fileReadsStdin = this.flags.file === '-';
+        if (this.flags.stdin || fileReadsStdin) {
             const rawInput = await this.readStdinWithGuard();
             if (!rawInput.trim()) {
                 this.error('Empty stdin content provided.', { exit: 2, code: 'EMPTY_INPUT' });
@@ -260,11 +269,11 @@ export default class ResearchImport extends BaseCommand {
         const { freshWindowMs } = getPolicy(tier, ttl);
         const staleAfterTime = new Date(currentTime.getTime() + freshWindowMs);
         const inputFormat = this.flags['input-format'];
-        const detailed = rawInput;
+        const detailed = sanitizePromptInjection(rawInput);
         // A caller-supplied compressed input is trusted as-is; only a detailed import is condensed here,
         // and it shares the same buildCompressed policy (structural pass + extractive fallback) as fetch.
         const compressed = inputFormat === 'detailed'
-            ? buildCompressed(rawInput, loadSummaryLevel(this.config.configDir, process.cwd()))
+            ? buildCompressed(detailed, loadSummaryLevel(this.config.configDir, process.cwd()))
             : rawInput;
         const contentHash = createHash('sha256').update(detailed).digest('hex');
         const metadata = {

package/dist/commands/inspect.d.ts

@@ -7,10 +7,14 @@ export default class ResearchInspect extends BaseCommand<typeof ResearchInspect>
         description: string;
         command: string;
     }[];
+    static strict: boolean;
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static stdoutIsPrimaryData: boolean;
     run(): Promise<unknown>;
+    private logMetadata;
+    private logSections;
+    private inspectSingleTarget;
     private findSections;
 }

package/dist/commands/inspect.js

@@ -1,6 +1,7 @@
 import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
+import { colors } from '../lib/color.js';
 export default class ResearchInspect extends BaseCommand {
     static id = 'inspect';
     static summary = 'Inspect cached research metadata for a URL.';
@@ -15,6 +16,7 @@ export default class ResearchInspect extends BaseCommand {
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --json',
         },
     ];
+    static strict = false;
     static args = {
         url: Args.string({
             required: true,
@@ -23,39 +25,61 @@ export default class ResearchInspect extends BaseCommand {
     };
     static stdoutIsPrimaryData = true;
     async run() {
-        const { url } = this.args;
-        const target = this.resolveResearchTargetOrFail(url);
-        const { cacheKey, located, normalizedUrl, roots } = target;
-        if (!located) {
-            // inspect makes no network call, so the bare message reads like the network-failure case the
-            // exit-1 contract describes. Point at the fix instead: fetch the page so it lands in the cache.
-            this.error(`No cached research found for URL: ${normalizedUrl}`, {
+        const urls = this.parsedArgv;
+        const results = [];
+        const missingUrls = [];
+        for (const url of urls) {
+            const target = this.resolveResearchTargetOrFail(url);
+            if (!target.located) {
+                missingUrls.push(target.normalizedUrl);
+                continue;
+            }
+            results.push(this.inspectSingleTarget(target, urls.length > 1));
+        }
+        if (missingUrls.length > 0) {
+            const firstMissing = missingUrls[0];
+            const suggestions = missingUrls.map((u) => `Fetch and cache it first: ${this.config.bin} ${u}`);
+            this.error(`No cached research found for URL: ${firstMissing}` +
+                (missingUrls.length > 1 ? ` and ${missingUrls.length - 1} other URLs` : ''), {
                 exit: 1,
                 code: 'CACHE_MISS',
-                suggestions: [`Fetch and cache it first: ${this.config.bin} ${normalizedUrl}`],
+                suggestions,
             });
         }
+        return urls.length === 1 ? results[0] : results;
+    }
+    logMetadata(metadata) {
+        this.log(colors.cyan(`--- Metadata ---`));
+        for (const [key, val] of Object.entries(metadata)) {
+            const paddedKey = colors.cyan((key + ':').padEnd(Math.max(25, key.length + 2)));
+            if (typeof val === 'object' && val !== null) {
+                this.log(`${paddedKey} ${colors.bold(JSON.stringify(val))}`);
+            }
+            else {
+                this.log(`${paddedKey} ${colors.bold(String(val))}`);
+            }
+        }
+    }
+    logSections(sections) {
+        this.log(colors.cyan(`--- Sections (${sections.length}) ---`));
+        for (const s of sections) {
+            this.log(`${colors.cyan(s.headingPath || '')} [${colors.yellow(s.anchor || '')}] (${colors.magenta(String(s.tokenEstimate.detailed || 0))} tokens) ${colors.gray(s.cacheKey)}`);
+        }
+    }
+    inspectSingleTarget(target, showSeparator) {
+        const { cacheKey, located, roots } = target;
         const cached = located.artifact;
         const artifactPath = located.path;
         const sections = this.findSections(roots.readRoots, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
-            this.log(`${'Cache Path:'.padEnd(25)} ${artifactPath}`);
-            this.log(`--- Metadata ---`);
-            for (const [key, val] of Object.entries(cached.metadata)) {
-                const paddedKey = (key + ':').padEnd(Math.max(25, key.length + 2));
-                if (typeof val === 'object' && val !== null) {
-                    this.log(`${paddedKey} ${JSON.stringify(val)}`);
-                }
-                else {
-                    this.log(`${paddedKey} ${val}`);
-                }
-            }
+            this.log(`${colors.cyan('Cache Key:'.padEnd(25))} ${colors.bold(cacheKey)}`);
+            this.log(`${colors.cyan('Cache Path:'.padEnd(25))} ${colors.gray(artifactPath)}`);
+            this.logMetadata(cached.metadata);
             if (sections.length) {
-                this.log(`--- Sections (${sections.length}) ---`);
-                for (const s of sections) {
-                    this.log(`${s.headingPath} [${s.anchor}] (${s.tokenEstimate.detailed} tokens) ${s.cacheKey}`);
-                }
+                this.logSections(sections);
+            }
+            if (showSeparator) {
+                this.log('='.repeat(40));
             }
         }
         return {

package/dist/commands/list.d.ts

@@ -10,13 +10,15 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
     static flags: {
         topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         freshness: import("@oclif/core/interfaces").OptionFlag<"fresh" | "stale_grace" | "stale_expired" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | "route_markdown" | "github_source" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    private validateListFlags;
+    private matchesTopic;
+    private matchesTags;
     private matchesFilters;
     private scanCacheDirForList;
     private logListResults;

package/dist/commands/list.js

@@ -5,6 +5,9 @@ import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { evaluateFreshness } from '../lib/research/freshness.js';
 import { ARTIFACT_TYPES, CAPTURE_METHODS } from '../lib/research/schema.js';
 import { NO_TOPIC_LABEL, resultListHeading, truncationNotice, } from '../lib/text.js';
+import { limitFlag } from '../lib/limit-flag.js';
+import { artifactMatchesUrlFilter } from '../lib/research/url.js';
+import { colors } from '../lib/color.js';
 // Listings are ordered newest-first, so the truncation word is "first"; --limit caps at 100.
 const LIST_LABELS = { noun: 'cached research', order: 'first', maxLimit: 100 };
 // `list` answers "what pages/notes do I have?" and deliberately omits section children (see
@@ -27,6 +30,10 @@ export default class ResearchList extends BaseCommand {
             description: 'list only fresh entries filtered by tags',
             command: '<%= config.bin %> list --freshness fresh --tags node --tags url',
         },
+        {
+            description: 'list entries matching a specific URL glob',
+            command: '<%= config.bin %> list --url "https://react.dev/*"',
+        },
     ];
     static flags = {
         topic: Flags.string({
@@ -38,6 +45,9 @@ export default class ResearchList extends BaseCommand {
             description: 'filter by tags (must match all tags specified)',
             multiple: true,
         }),
+        url: Flags.string({
+            description: 'filter by source URL glob pattern (case-insensitive, supports * wildcard)',
+        }),
         freshness: Flags.option({
             description: 'filter by freshness state',
             options: ['fresh', 'stale_grace', 'stale_expired'],
@@ -50,29 +60,29 @@ export default class ResearchList extends BaseCommand {
             description: 'filter by capture method',
             options: CAPTURE_METHODS,
         })(),
-        limit: Flags.integer({
-            description: 'maximum number of results to return (default 50, max 100)',
-            default: 50,
-        }),
+        limit: limitFlag(100, 50, 'maximum number of results to return (default 50, max 100)'),
     };
     static stdoutIsPrimaryData = true;
-    validateListFlags() {
-        const limit = this.flags.limit;
-        if (limit !== undefined && (limit < 1 || limit > 100)) {
-            this.error('Limit must be between 1 and 100.', { exit: 2, code: 'INVALID_LIMIT' });
-        }
+    matchesTopic(meta, topic) {
+        if (!topic)
+            return true;
+        return !!meta.topic && meta.topic.trim().toLowerCase() === topic.trim().toLowerCase();
+    }
+    matchesTags(meta, tags) {
+        if (!tags || tags.length === 0)
+            return true;
+        const metaTagsLower = (meta.tags || []).map((t) => t.toLowerCase());
+        return tags.every((t) => metaTagsLower.includes(t.toLowerCase()));
     }
     matchesFilters(meta, freshness) {
-        if (this.flags.topic &&
-            (!meta.topic || meta.topic.trim().toLowerCase() !== this.flags.topic.trim().toLowerCase())) {
+        if (!this.matchesTopic(meta, this.flags.topic)) {
             return false;
         }
-        if (this.flags.tags && this.flags.tags.length > 0) {
-            const metaTagsLower = (meta.tags || []).map((t) => t.toLowerCase());
-            const hasAllTags = this.flags.tags.every((t) => metaTagsLower.includes(t.toLowerCase()));
-            if (!hasAllTags) {
-                return false;
-            }
+        if (!this.matchesTags(meta, this.flags.tags)) {
+            return false;
+        }
+        if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
+            return false;
         }
         if (this.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
             return false;
@@ -91,8 +101,7 @@ export default class ResearchList extends BaseCommand {
                 return null;
             // Section children are sub-chunks of a page, not artifacts a user "has" — they would flood the
             // listing (one page yields dozens) and aren't in the documented source/research_note contract.
-            // They stay discoverable through `search` (which ranks them) and `inspect` (which lists a
-            // page's sections). `list` answers "what pages/notes do I have?", so keep it page-level. This
+            // They stay discoverable through `inspect` (which lists a page's sections). `list` answers "what pages/notes do I have?", so keep it page-level. This
             // unconditional guard owns the exclusion (the default no-filter case relies on it);
             // LISTABLE_ARTIFACT_TYPES just hides `section` from --artifact-type so no one filters for a
             // type list can never return. Keep both in sync if section handling ever changes.
@@ -122,19 +131,27 @@ export default class ResearchList extends BaseCommand {
             return;
         if (finalResults.length === 0) {
             this.log('No cached research entries found matching filters.');
-            this.log(`\nTip: populate the cache first: ${this.config.bin} <url>`);
+            this.log(`\nTip: populate the cache first: ${colors.cyan(this.config.bin + ' <url>')}`);
             return;
         }
         this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
-            this.log(`${index + 1}. [${res.topic || NO_TOPIC_LABEL}] Key: ${res.cacheKey}`);
-            this.log(`   Type: ${res.artifactType} | Freshness: ${res.freshness}`);
-            this.log(`   Tokens: compressed=${res.tokenEstimate?.compressed || 0}, detailed=${res.tokenEstimate?.detailed || 0}`);
-            this.log(`   Source URLs: ${res.sourceUrls.join(', ')}\n`);
+            const topicStr = res.topic ? colors.cyan(res.topic) : colors.gray(NO_TOPIC_LABEL);
+            const keyStr = colors.bold(res.cacheKey);
+            this.log(`${index + 1}. [${topicStr}] Key: ${keyStr}`);
+            const freshnessColorMap = {
+                fresh: colors.green,
+                stale_grace: colors.yellow,
+                stale_expired: colors.red,
+            };
+            const freshnessColor = freshnessColorMap[res.freshness] || ((t) => t);
+            const freshnessStr = freshnessColor(res.freshness);
+            this.log(`   Type: ${colors.bold(res.artifactType)} | Freshness: ${freshnessStr}`);
+            this.log(`   Tokens: compressed=${colors.bold(String(res.tokenEstimate?.compressed || 0))}, detailed=${colors.bold(String(res.tokenEstimate?.detailed || 0))}`);
+            this.log(`   Source URLs: ${colors.gray(res.sourceUrls.join(', '))}\n`);
         });
     }
     async run() {
-        this.validateListFlags();
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),

package/dist/commands/prune.d.ts

@@ -10,6 +10,7 @@ export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
     static flags: {
         'older-than': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         inactive: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | "section" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;