@taurgis/bonsai 1.0.6 → 3.0.0

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,6 +36,7 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private persistFreshArtifact;
     private persistSectionsIfFresh;
     run(): Promise<unknown>;
+    private fetchSingleTarget;
 }
 export declare function fetchFailureGuidance(message: string, url: string): {
     suggestions: 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';
@@ -34,6 +34,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,
@@ -255,49 +256,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 +288,44 @@ 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;
+    }
 }
 // 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`;

package/dist/commands/import.js

@@ -30,6 +30,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 +51,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 +125,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 +174,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 +229,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' });

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>;

package/dist/commands/prune.js

@@ -7,6 +7,8 @@ import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { parseTtlToMs, durationFlagError } from '../lib/research/freshness.js';
 import { ARTIFACT_TYPES } from '../lib/research/schema.js';
 import { NO_TOPIC_LABEL, pluralize } from '../lib/text.js';
+import { artifactMatchesUrlFilter } from '../lib/research/url.js';
+import { colors } from '../lib/color.js';
 export default class ResearchPrune extends BaseCommand {
     static id = 'prune';
     static summary = 'Clean up old or inactive research cache entries.';
@@ -20,6 +22,10 @@ export default class ResearchPrune extends BaseCommand {
             description: 'actually prune entries older than 30 days that are source scrapes',
             command: '<%= config.bin %> prune --older-than 30d --artifact-type source --yes',
         },
+        {
+            description: 'prune entries matching a URL glob pattern',
+            command: '<%= config.bin %> prune --url "https://react.dev/*" --yes',
+        },
     ];
     static flags = {
         'older-than': Flags.string({
@@ -28,6 +34,9 @@ export default class ResearchPrune extends BaseCommand {
         inactive: Flags.string({
             description: 'prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d")',
         }),
+        url: Flags.string({
+            description: 'filter pruning to source URL glob pattern (case-insensitive, supports * wildcard)',
+        }),
         'artifact-type': Flags.option({
             // Prune operates on every cached file, so it can target any artifact type — including the
             // `section`/`index` children a page generates (e.g. to clear orphans left after a source is
@@ -47,8 +56,11 @@ export default class ResearchPrune extends BaseCommand {
     };
     static stdoutIsPrimaryData = true;
     validatePruneFlags() {
-        if (!this.flags['older-than'] && !this.flags.inactive && !this.flags['artifact-type']) {
-            this.error('Must specify at least one pruning filter: --older-than, --inactive, or --artifact-type.', {
+        if (!this.flags['older-than'] &&
+            !this.flags.inactive &&
+            !this.flags['artifact-type'] &&
+            !this.flags.url) {
+            this.error('Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, or --url.', {
                 exit: 2,
                 code: 'MISSING_FILTER',
                 suggestions: [
@@ -56,14 +68,20 @@ export default class ResearchPrune extends BaseCommand {
                 ],
             });
         }
+        if (this.flags['dry-run'] && this.flags.yes) {
+            this.error('--dry-run and --yes are mutually exclusive: --dry-run previews without deleting, --yes confirms deletion. Choose one.', { exit: 2, code: 'CONFLICTING_FLAGS' });
+        }
         if (!this.flags['dry-run'] && !this.flags.yes) {
             const olderThanPart = this.flags['older-than']
                 ? ` --older-than ${this.flags['older-than']}`
                 : '';
+            const urlPart = this.flags.url ? ` --url "${this.flags.url}"` : '';
             this.error('Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.', {
                 exit: 2,
                 code: 'SAFETY_CHECK_REQUIRED',
-                suggestions: [`Preview first: ${this.config.bin} prune --dry-run${olderThanPart}`],
+                suggestions: [
+                    `Preview first: ${this.config.bin} prune --dry-run${olderThanPart}${urlPart}`,
+                ],
             });
         }
         // Validate durations up front: scanCacheDir swallows per-file errors, so a malformed
@@ -84,6 +102,9 @@ export default class ResearchPrune extends BaseCommand {
         if (this.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
             return false;
         }
+        if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
+            return false;
+        }
         if (this.flags['older-than']) {
             const olderThanMs = parseTtlToMs(this.flags['older-than']);
             if (ageMs < olderThanMs) {
@@ -142,18 +163,23 @@ export default class ResearchPrune extends BaseCommand {
         let prunedCount = 0;
         if (dryRun) {
             if (!this.jsonEnabled()) {
-                const noun = pluralize(count, 'entry', 'entries');
-                this.log(`[Dry Run] Found ${count} research cache ${noun} that would be pruned:\n`);
-                filesToPrune.forEach((f) => {
-                    this.log(`- [${f.topic || NO_TOPIC_LABEL}] Key: ${f.cacheKey} (${f.url || 'Imported note'})`);
-                });
+                if (count === 0) {
+                    this.log(colors.yellow('[Dry Run] No research cache entries match the given filters.'));
+                }
+                else {
+                    const noun = pluralize(count, 'entry', 'entries');
+                    this.log(colors.yellow(`[Dry Run] Found ${count} research cache ${noun} that would be pruned:\n`));
+                    filesToPrune.forEach((f) => {
+                        this.log(`- [${f.topic ? colors.cyan(f.topic) : colors.gray(NO_TOPIC_LABEL)}] Key: ${colors.bold(f.cacheKey)} (${colors.gray(f.url || 'Imported note')})`);
+                    });
+                }
             }
         }
         else {
             prunedCount = this.deletePruneCandidates(filesToPrune);
             if (!this.jsonEnabled()) {
                 const noun = pluralize(count, 'entry', 'entries');
-                this.log(`Successfully pruned ${prunedCount} of ${count} research cache ${noun}.`);
+                this.log(colors.green(`Successfully pruned ${prunedCount} of ${count} research cache ${noun}.`));
             }
         }
         return {