@taurgis/bonsai 1.0.5 → 3.0.0

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" | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | 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

@@ -3,72 +3,86 @@ import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { evaluateFreshness } from '../lib/research/freshness.js';
-import { resultListHeading, truncationNotice } from '../lib/text.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
+// scanCacheDirForList), so `section` is not an offered filter — every other artifact type can appear.
+const LISTABLE_ARTIFACT_TYPES = ARTIFACT_TYPES.filter((type) => type !== 'section');
 export default class ResearchList extends BaseCommand {
     static id = 'list';
     static summary = 'List cached research artifacts by metadata filters.';
     static description = 'Lists cached research artifacts, including metadata details like path, source count, freshness, token estimates, and quality metrics without printing full content.';
     static examples = [
         {
-            description: 'List all cached entries',
+            description: 'list all cached entries',
             command: '<%= config.bin %> list',
         },
         {
-            description: 'List cached entries for a specific topic with JSON output',
+            description: 'list cached entries for a specific topic with JSON output',
             command: '<%= config.bin %> list --topic "React Suspense" --json',
         },
         {
-            description: 'List only fresh entries filtered by tags',
+            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({
             char: 't',
-            description: 'Filter by exact topic (case-insensitive).',
+            description: 'filter by exact topic (case-insensitive)',
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'Filter by tags (must match all tags specified).',
+            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.',
+            description: 'filter by freshness state',
             options: ['fresh', 'stale_grace', 'stale_expired'],
         })(),
         'artifact-type': Flags.option({
-            description: 'Filter by artifact type.',
-            options: ['source', 'research_note'],
+            description: 'filter by artifact type',
+            options: LISTABLE_ARTIFACT_TYPES,
         })(),
         'capture-method': Flags.option({
-            description: 'Filter by capture method.',
-            options: ['static_fetch', 'browser_fallback', 'agent_supplied'],
+            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 });
-        }
+    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;
@@ -87,8 +101,10 @@ 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.
+            // 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.
             if (artifact.metadata.artifact_type === 'section')
                 return null;
             const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
@@ -115,18 +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: ${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'}] 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,7 +10,8 @@ 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>;
-        'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | 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

@@ -5,49 +5,84 @@ import { BaseCommand } from '../base-command.js';
 import { scanCacheDir } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { parseTtlToMs, durationFlagError } from '../lib/research/freshness.js';
-import { pluralize } from '../lib/text.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.';
     static description = 'Prunes cached research entries based on age, inactivity, or artifact type to free up disk space.';
     static examples = [
         {
-            description: 'Perform a dry run of pruning entries older than 90 days',
+            description: 'perform a dry run of pruning entries older than 90 days',
             command: '<%= config.bin %> prune --older-than 90d --dry-run',
         },
         {
-            description: 'Actually prune entries older than 30 days that are source scrapes',
+            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({
-            description: 'Prune entries older than duration (e.g. "30d", "90d").',
+            description: 'prune entries older than duration (e.g. "30d", "90d")',
         }),
         inactive: Flags.string({
-            description: 'Prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d").',
+            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({
-            description: 'Filter pruning to specific artifact type.',
-            options: ['source', 'research_note'],
+            // 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
+            // pruned with `--artifact-type source`).
+            description: 'filter pruning to specific artifact type',
+            options: ARTIFACT_TYPES,
         })(),
         'dry-run': Flags.boolean({
-            description: 'List files that would be deleted without actually deleting them.',
+            description: 'list files that would be deleted without actually deleting them',
             default: false,
         }),
         yes: Flags.boolean({
             char: 'y',
-            description: 'Skip confirmation prompt and prune files.',
+            description: 'confirm deletion and prune matched entries (required unless --dry-run)',
             default: false,
         }),
     };
     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.', { exit: 2 });
+        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: [
+                    `Preview age-based pruning: ${this.config.bin} prune --older-than 90d --dry-run`,
+                ],
+            });
+        }
+        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) {
-            this.error('Safety check: Please specify --yes to confirm pruning, or --dry-run to list files that would be deleted.', { exit: 2 });
+            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}${urlPart}`,
+                ],
+            });
         }
         // Validate durations up front: scanCacheDir swallows per-file errors, so a malformed
         // --older-than/--inactive would otherwise be silently ignored and report "0 entries".
@@ -56,7 +91,7 @@ export default class ResearchPrune extends BaseCommand {
             durationFlagError('--inactive', this.flags.inactive),
         ]) {
             if (msg)
-                this.error(msg, { exit: 2 });
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
     }
     shouldPrune(meta, currentTime) {
@@ -67,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) {
@@ -125,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'}] 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 {

package/dist/commands/status.d.ts

@@ -3,6 +3,11 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
     static id: string;
     static summary: string;
     static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static strict: boolean;
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -12,5 +17,8 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
         'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
+    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
     run(): Promise<unknown>;
+    private checkSingleStatus;
 }

package/dist/commands/status.js

@@ -1,8 +1,9 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
+import { formatErrorForJson } from '../lib/envelope.js';
 import { getArtifactPath } from '../lib/research/storage.js';
 import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+import { colors } from '../lib/color.js';
 function resolveFreshness(cached, currentTime, ttl, maxAge) {
     const isMaxAgeExpired = maxAge ? checkMaxAgeExpired(cached, currentTime, maxAge) : false;
     return isMaxAgeExpired
@@ -22,66 +23,123 @@ export default class ResearchStatus extends BaseCommand {
     static id = 'status';
     static summary = 'Check the cache status of a URL without fetching or writing.';
     static description = 'Reports whether the URL is cached, its freshness state, and what action (fetch, revalidate, or cached return) the root fetch command would take.';
+    static examples = [
+        {
+            description: 'check if a URL is already in the cache',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
+        },
+        {
+            description: 'check status against a specific freshness tier and TTL',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
+        },
+    ];
+    static strict = false;
     static args = {
         url: Args.string({
             required: true,
-            description: 'The URL to check.',
+            description: 'the URL to check',
         }),
     };
     static flags = {
         tier: Flags.option({
-            description: 'Freshness tier policy to evaluate against.',
+            description: 'freshness tier policy to evaluate against',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Custom TTL duration to evaluate against (e.g. "2h", "7d").',
+            description: 'custom TTL duration to evaluate against (e.g. "2h", "7d")',
         }),
         'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g. "1d", "30d").',
+            description: 'maximum age of cache to accept (e.g. "1d", "30d")',
         }),
     };
     static stdoutIsPrimaryData = true;
+    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
+    toSuccessJson(data) {
+        const envelope = super.toSuccessJson(data);
+        const list = Array.isArray(data) ? data : [data];
+        const misses = list.filter((d) => d && d.status === 'miss');
+        if (misses.length === 0)
+            return envelope;
+        const firstMiss = misses[0];
+        const normalizedUrl = firstMiss.normalizedUrl ?? '';
+        const suggestions = misses.map((m) => `Fetch and cache it first: ${this.config.bin} ${m.normalizedUrl}`);
+        const stderr = formatErrorForJson({
+            message: `Cache miss for ${normalizedUrl}` +
+                (misses.length > 1 ? ` and ${misses.length - 1} other URLs` : ''),
+            code: 'CACHE_MISS',
+            suggestions,
+        });
+        return { ...envelope, ok: false, exitCode: 1, stderr, code: 'CACHE_MISS', suggestions };
+    }
     async run() {
-        const { url } = this.args;
+        const urls = this.parsedArgv;
         const { ttl, tier, 'max-age': maxAge } = this.flags;
         // Validate the duration flags up front so a malformed value reports the exact flag that is
         // wrong, rather than later surfacing as a misattributed parse failure.
         for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
             if (msg)
-                this.error(msg, { exit: 2 });
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
-        let target;
-        try {
-            target = resolveResearchTarget({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                url,
-            });
+        const results = [];
+        let hasMiss = false;
+        const currentTime = new Date();
+        for (const url of urls) {
+            const res = this.checkSingleStatus(url, currentTime, ttl, maxAge, urls.length > 1);
+            if (res.status === 'miss') {
+                hasMiss = true;
+            }
+            results.push(res);
         }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+        if (hasMiss) {
+            process.exitCode = 1;
         }
+        return urls.length === 1 ? results[0] : results;
+    }
+    checkSingleStatus(url, currentTime, ttl, maxAge, showSeparator) {
+        const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         const cached = located?.artifact ?? null;
-        const currentTime = new Date();
-        // Both duration flags were validated above, so freshness resolution cannot throw on a parse error.
         const result = describeCacheStatus(cached, currentTime, ttl, maxAge);
-        // On a hit, report where it actually lives; on a miss, where a fetch would write it.
         const artifactPath = located?.path ?? getArtifactPath(roots.writeRoot, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`URL: ${normalizedUrl}`);
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Cache Path: ${artifactPath}`);
-            this.log(`Status: ${result.status}`);
-            this.log(`Freshness: ${result.freshness}`);
-            this.log(`Action: ${result.action}`);
+            const statusColorMap = {
+                hit: colors.green,
+                stale: colors.yellow,
+                miss: colors.red,
+            };
+            const freshnessColorMap = {
+                fresh: colors.green,
+                stale_grace: colors.yellow,
+                stale_expired: colors.red,
+                none: colors.gray,
+            };
+            const actionColorMap = {
+                would_return_cached: colors.green,
+                would_revalidate: colors.yellow,
+                would_fetch: colors.red,
+            };
+            const statusColor = statusColorMap[result.status] || ((t) => t);
+            const freshnessColor = freshnessColorMap[result.freshness] || ((t) => t);
+            const actionColor = actionColorMap[result.action] || ((t) => t);
+            this.log(`${colors.cyan('URL:'.padEnd(25))} ${colors.bold(normalizedUrl)}`);
+            this.log(`${colors.cyan('Cache Key:'.padEnd(25))} ${colors.bold(cacheKey)}`);
+            this.log(`${colors.cyan('Cache Path:'.padEnd(25))} ${colors.gray(artifactPath)}`);
+            this.log(`${colors.cyan('Status:'.padEnd(25))} ${statusColor(result.status)}`);
+            this.log(`${colors.cyan('Freshness:'.padEnd(25))} ${freshnessColor(result.freshness)}`);
+            this.log(`${colors.cyan('Action:'.padEnd(25))} ${actionColor(result.action)}`);
+            if (showSeparator) {
+                this.log('-'.repeat(40));
+            }
+        }
+        if (result.status === 'miss' && !this.jsonEnabled()) {
+            this.warn(`Cache miss — run: ${this.config.bin} ${normalizedUrl}`);
         }
         return {
             cacheKey,
             cachePath: artifactPath,
+            normalizedUrl,
             status: result.status,
             freshness: result.freshness,
             action: result.action,

package/dist/commands.d.ts

@@ -1,4 +1,5 @@
 import ConfigGet from './commands/config/get.js';
+import ConfigIndex from './commands/config/index.js';
 import ConfigList from './commands/config/list.js';
 import ConfigSet from './commands/config/set.js';
 import ConfigUnset from './commands/config/unset.js';
@@ -7,7 +8,6 @@ import ImportCommand from './commands/import.js';
 import InspectCommand from './commands/inspect.js';
 import ListCommand from './commands/list.js';
 import PruneCommand from './commands/prune.js';
-import SearchCommand from './commands/search.js';
 import StatusCommand from './commands/status.js';
 export declare const commands: {
     fetch: typeof FetchCommand;
@@ -15,8 +15,8 @@ export declare const commands: {
     inspect: typeof InspectCommand;
     list: typeof ListCommand;
     prune: typeof PruneCommand;
-    search: typeof SearchCommand;
     status: typeof StatusCommand;
+    config: typeof ConfigIndex;
     'config:get': typeof ConfigGet;
     'config:list': typeof ConfigList;
     'config:set': typeof ConfigSet;

package/dist/commands.js

@@ -1,4 +1,5 @@
 import ConfigGet from './commands/config/get.js';
+import ConfigIndex from './commands/config/index.js';
 import ConfigList from './commands/config/list.js';
 import ConfigSet from './commands/config/set.js';
 import ConfigUnset from './commands/config/unset.js';
@@ -7,7 +8,6 @@ import ImportCommand from './commands/import.js';
 import InspectCommand from './commands/inspect.js';
 import ListCommand from './commands/list.js';
 import PruneCommand from './commands/prune.js';
-import SearchCommand from './commands/search.js';
 import StatusCommand from './commands/status.js';
 export const commands = {
     fetch: FetchCommand,
@@ -15,8 +15,8 @@ export const commands = {
     inspect: InspectCommand,
     list: ListCommand,
     prune: PruneCommand,
-    search: SearchCommand,
     status: StatusCommand,
+    config: ConfigIndex,
     'config:get': ConfigGet,
     'config:list': ConfigList,
     'config:set': ConfigSet,

package/dist/hooks/command-not-found/suggest.d.ts

@@ -1,4 +1,10 @@
-import { type Hook } from '@oclif/core';
+import { type Hook, type Interfaces } from '@oclif/core';
+export declare function buildCommandNotFoundDetails(id: string, argv: string[] | undefined, config: Interfaces.Config): {
+    code: 'COMMAND_NOT_FOUND' | 'MISSING_URL_SCHEME' | 'UNEXPECTED_ARGUMENT';
+    command: string;
+    jsonMode: boolean;
+    message: string;
+};
 /**
  * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
  * throwing here (via `this.error`) replaces that default with a more helpful message. A correction