@taurgis/bonsai 1.0.0

package/dist/commands/index.d.ts

@@ -0,0 +1,35 @@
+import { BaseCommand } from '../base-command.js';
+export default class Bonsai extends BaseCommand<typeof Bonsai> {
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    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>;
+        format: import("@oclif/core/interfaces").OptionFlag<"compressed" | "detailed", import("@oclif/core/interfaces").CustomOptions>;
+        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
+        ttl: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'allow-stale': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        rendered: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    private executeCacheHit;
+    private executeCacheMiss;
+    private buildResultData;
+    private validateDurationFlags;
+    private resolveArtifact;
+    private persistFreshArtifact;
+    private persistSectionsIfFresh;
+    execute(): Promise<unknown>;
+}

package/dist/commands/index.js

@@ -0,0 +1,306 @@
+import { Args, Flags } from '@oclif/core';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { BaseCommand } from '../base-command.js';
+import { writeArtifact, getArtifactPath } from '../lib/research/storage.js';
+import { writeArtifactSecurely } from '../lib/research/secure-write.js';
+import { evaluateFreshness, parseTtlToMs, checkMaxAgeExpired } from '../lib/research/freshness.js';
+import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
+import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
+import { fetchRenderedHtml } from '../lib/research/browser.js';
+import { capturePage } from '../lib/research/capture.js';
+import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
+import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+import { detectSite } from '../sites/index.js';
+const CAPTURE_DEPS = {
+    fetchStatic: (url) => fetchStaticHtml(url),
+    fetchRendered: (url) => fetchRenderedHtml(url),
+    fetchText: (url) => fetchText(url),
+};
+export default class Bonsai extends BaseCommand {
+    static summary = 'An advanced, locally cached web research tool optimized for LLM ingestion.';
+    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.';
+    static examples = [
+        {
+            description: 'Research a URL with detailed output, tagged with topic and tags',
+            command: '<%= config.bin %> https://docs.nestjs.com/ --topic "Backend Frameworks" --tags "Node" --tags "NestJS" --format detailed --ttl 30d',
+        },
+        {
+            description: 'Research a volatile page with compressed output and short TTL, returned as JSON',
+            command: '<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json',
+        },
+    ];
+    static args = {
+        url: Args.string({
+            required: true,
+            description: 'The full HTTP/HTTPS URL of the web page to research.',
+        }),
+    };
+    static flags = {
+        topic: Flags.string({
+            char: 't',
+            description: 'The main category/topic of the research for metadata tagging.',
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: 'Taxonomic tags for this research (can be repeated).',
+            multiple: true,
+        }),
+        format: Flags.option({
+            char: 'f',
+            description: 'Desired data density.',
+            options: ['compressed', 'detailed'],
+            default: 'compressed',
+        })(),
+        tier: Flags.option({
+            description: 'Freshness tier policy.',
+            options: ['stable', 'standard', 'volatile'],
+            default: 'standard',
+        })(),
+        ttl: Flags.string({
+            char: 'l',
+            description: 'Predicted lifespan of the data (e.g., "2h", "7d", "3m").',
+        }),
+        'max-age': Flags.string({
+            description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
+        }),
+        force: Flags.boolean({
+            description: 'Force a fresh fetch, ignoring any cached entries.',
+            default: false,
+        }),
+        'dry-run': Flags.boolean({
+            description: 'Perform validation and fetch without saving to local cache.',
+            default: false,
+        }),
+        'allow-stale': Flags.boolean({
+            description: 'Allow serving stale cache if the remote server is unreachable.',
+            default: false,
+        }),
+        rendered: Flags.boolean({
+            description: 'Force using a browser-rendered scraping path for dynamic pages.',
+            default: false,
+        }),
+        storage: Flags.option({
+            description: 'Override where this result is cached (overrides configured default). Secret-bearing pages are always stored globally.',
+            options: ['global', 'project'],
+        })(),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse(Bonsai);
+        this.args = args;
+        this.flags = flags;
+    }
+    async executeCacheHit(cached, targetDir, currentTime) {
+        const { ttl, 'max-age': maxAge, 'allow-stale': allowStale, rendered } = this.flags;
+        const isExpired = checkMaxAgeExpired(cached, currentTime, maxAge);
+        const freshnessState = isExpired
+            ? 'stale_expired'
+            : evaluateFreshness(cached.metadata, currentTime, ttl);
+        if (freshnessState === 'fresh') {
+            return { cacheStatus: 'hit', freshnessState, artifact: cached };
+        }
+        const revalResult = await revalidateCache(targetDir, cached, currentTime, {
+            allowStale: Boolean(allowStale),
+            ttlOverride: ttl,
+            rendered: Boolean(rendered),
+        });
+        handleStaleRevalidationResult(this, revalResult);
+        return {
+            cacheStatus: revalResult.status,
+            freshnessState,
+            artifact: revalResult.artifact,
+        };
+    }
+    async executeCacheMiss(normalizedUrl, currentTime, cacheKey) {
+        const { topic, tags, tier, ttl, rendered } = this.flags;
+        const siteModule = detectSite(normalizedUrl);
+        const useRendered = rendered || Boolean(siteModule?.defaults?.rendered);
+        let fetchResult;
+        let extraction;
+        let capture = null;
+        if (siteModule?.fetchPage) {
+            // Custom site modules own their fetch/extract strategy; the generic capture path is skipped.
+            ({ fetchResult, extraction } = await siteModule.fetchPage(normalizedUrl));
+        }
+        else {
+            capture = await capturePage(normalizedUrl, { forceRendered: useRendered }, CAPTURE_DEPS);
+            fetchResult = capture.fetchResult;
+            extraction = capture.extraction;
+        }
+        const artifact = createArtifactFromFetch(normalizedUrl, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl || null, currentTime);
+        artifact.metadata.topic = topic || null;
+        artifact.metadata.tags = tags || [];
+        artifact.metadata.site_module_id = siteModule?.id ?? null;
+        if (capture) {
+            applyCaptureMetadata(artifact, capture);
+        }
+        else if (useRendered) {
+            artifact.metadata.capture_method = 'browser_fallback';
+        }
+        return artifact;
+    }
+    buildResultData(url, normalizedUrl, cacheKey, storageDir, storageMode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal) {
+        return {
+            schemaVersion: 1,
+            command: this.config.bin,
+            cache: {
+                key: cacheKey,
+                status: cacheStatus,
+                freshness: freshnessState,
+                path: getArtifactPath(storageDir, cacheKey),
+                storage: storageMode,
+                redirectedToGlobal,
+            },
+            source: {
+                url,
+                normalizedUrl,
+                captureMethod: artifact.metadata.capture_method,
+                extractionStatus: artifact.metadata.extraction_status,
+                extractionConfidence: artifact.metadata.extraction_confidence,
+                qualityNotes: artifact.metadata.quality_notes,
+                fetchedAt: artifact.metadata.fetched_at,
+                validatedAt: artifact.metadata.validated_at,
+                staleAfter: artifact.metadata.stale_after,
+            },
+            artifactType: artifact.metadata.artifact_type,
+            docsEngine: artifact.metadata.docs_engine,
+            docsFramework: artifact.metadata.docs_framework,
+            sourceDocUrl: artifact.metadata.source_doc_url,
+            searchProvider: artifact.metadata.search_provider,
+            format,
+            tokenEstimate: format === 'compressed'
+                ? artifact.metadata.token_estimate.compressed
+                : artifact.metadata.token_estimate.detailed,
+            content,
+        };
+    }
+    // Validates the duration flags up front, exiting with code 2 on a malformed value.
+    validateDurationFlags(ttl, maxAge) {
+        for (const [label, value] of [
+            ['TTL', ttl],
+            ['max-age', maxAge],
+        ]) {
+            if (!value)
+                continue;
+            try {
+                parseTtlToMs(value);
+            }
+            catch (err) {
+                this.error(`Invalid ${label}: ${err.message}`, { exit: 2 });
+            }
+        }
+    }
+    // Serves the cache when a fresh/revalidatable entry exists, otherwise fetches fresh. Reads fall
+    // back project→global; the resolved artifact is returned with the dir it lives in / landed in.
+    async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located) {
+        if (located) {
+            // Revalidate where the entry already lives; on dry-run use the throwaway dir so the cache is
+            // never mutated. ponytail: revalidation rewrites in place, so a refreshed project entry that
+            // gains a secret is not re-routed — only first-time project writes are scanned.
+            const revalDir = tmpDir ?? located.dataDir;
+            const hit = await this.executeCacheHit(located.artifact, revalDir, currentTime);
+            return { ...hit, storageDir: located.dataDir, redirectedToGlobal: false };
+        }
+        const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey);
+        const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
+        return {
+            cacheStatus: 'miss',
+            freshnessState: 'stale_expired',
+            artifact,
+            storageDir: dir,
+            redirectedToGlobal,
+        };
+    }
+    // Writes a freshly fetched artifact, honoring dry-run (throwaway dir) and the secret-safety
+    // redirect (project→global). Returns the data dir reported to the user and whether a redirect
+    // occurred (so the JSON envelope mirrors `import`).
+    persistFreshArtifact(roots, tmpDir, cacheKey, artifact) {
+        if (tmpDir) {
+            writeArtifact(tmpDir, cacheKey, artifact);
+            // Report the real would-be location, not the throwaway dir that is about to be deleted.
+            return { dir: roots.writeRoot, redirectedToGlobal: false };
+        }
+        const result = writeArtifactSecurely(roots, cacheKey, artifact);
+        if (result.redirected) {
+            this.warn(`Detected ${result.secretLabel} in the page content; stored in the global cache instead of the project to avoid committing secrets.`);
+        }
+        return { dir: result.dataDir, redirectedToGlobal: result.redirected };
+    }
+    // Long references are split into searchable/inspectable section children whenever the page artifact
+    // is freshly written (T-22). Best-effort: never let chunking break the main result.
+    persistSectionsIfFresh(targetDir, artifact, currentTime, cacheStatus) {
+        if (cacheStatus !== 'miss' && cacheStatus !== 'refreshed')
+            return;
+        try {
+            persistSectionArtifacts(targetDir, artifact, currentTime);
+        }
+        catch {
+            /* section generation is non-essential; ignore failures */
+        }
+    }
+    async execute() {
+        const { url } = this.args;
+        const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
+        this.validateDurationFlags(ttl, maxAge);
+        let target;
+        try {
+            target = resolveResearchTarget({
+                configDir: this.config.configDir,
+                cwd: process.cwd(),
+                dataDir: this.config.dataDir,
+                flagOverride: this.flags.storage,
+                lookup: !this.flags.force,
+                url,
+            });
+        }
+        catch (err) {
+            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+        }
+        const { cacheKey, located, normalizedUrl, roots } = target;
+        const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
+        const currentTime = new Date();
+        try {
+            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located);
+            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, 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.requestedJson()) {
+                this.log(content);
+            }
+            return resultData;
+        }
+        finally {
+            if (tmpDir) {
+                rmSync(tmpDir, { recursive: true, force: true });
+            }
+        }
+    }
+}
+// Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
+function applyCaptureMetadata(artifact, capture) {
+    const meta = artifact.metadata;
+    meta.capture_method = capture.captureMethod;
+    meta.docs_engine = capture.capabilities.docsEngine ?? null;
+    meta.docs_framework = capture.capabilities.framework ?? null;
+    meta.source_doc_url = capture.sourceDocUrl;
+    meta.search_provider = capture.capabilities.search?.provider ?? null;
+    if (capture.extraction.isIndexHub)
+        meta.artifact_type = 'index';
+    if (capture.sourceDocUrl && !meta.source_urls.includes(capture.sourceDocUrl)) {
+        meta.source_urls.push(capture.sourceDocUrl);
+    }
+}
+function handleStaleRevalidationResult(command, revalResult) {
+    if (revalResult.status !== 'stale')
+        return;
+    if (revalResult.allowed) {
+        command.warn(`Serving stale content: revalidation failed: ${revalResult.error}`);
+    }
+    else {
+        command.warn(`Serving stale content (exit 5): revalidation failed: ${revalResult.error}`);
+        process.exitCode = 5;
+    }
+}

package/dist/commands/inspect.d.ts

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../base-command.js';
+export default class ResearchInspect extends BaseCommand<typeof ResearchInspect> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static args: {
+        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    execute(): Promise<unknown>;
+    private findSections;
+}

package/dist/commands/inspect.js

@@ -0,0 +1,82 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { scanCacheDirs } from '../lib/research/storage.js';
+import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+export default class ResearchInspect extends BaseCommand {
+    static id = 'inspect';
+    static summary = 'Inspect cached research metadata for a URL.';
+    static description = 'Inspects local storage and displays full frontmatter metadata for the URL (without printing the content body).';
+    static args = {
+        url: Args.string({
+            required: true,
+            description: 'The URL to inspect.',
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { args } = await this.parse(ResearchInspect);
+        this.args = args;
+    }
+    async execute() {
+        const { url } = this.args;
+        let target;
+        try {
+            target = resolveResearchTarget({
+                configDir: this.config.configDir,
+                cwd: process.cwd(),
+                dataDir: this.config.dataDir,
+                url,
+            });
+        }
+        catch (err) {
+            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+        }
+        const { cacheKey, located, normalizedUrl, roots } = target;
+        if (!located) {
+            this.error(`No cached research found for URL: ${normalizedUrl}`, { exit: 1 });
+        }
+        const cached = located.artifact;
+        const artifactPath = located.path;
+        const sections = this.findSections(roots.readRoots, cacheKey);
+        if (!this.requestedJson()) {
+            this.log(`Cache Key: ${cacheKey}`);
+            this.log(`Cache Path: ${artifactPath}`);
+            this.log(`--- Metadata ---`);
+            for (const [key, val] of Object.entries(cached.metadata)) {
+                if (typeof val === 'object' && val !== null) {
+                    this.log(`${key}: ${JSON.stringify(val)}`);
+                }
+                else {
+                    this.log(`${key}: ${val}`);
+                }
+            }
+            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}`);
+                }
+            }
+        }
+        return {
+            cacheKey,
+            cachePath: artifactPath,
+            metadata: cached.metadata,
+            sections,
+        };
+    }
+    // Section children link back via parent_cache_key; list the active ones for this page (T-22).
+    findSections(readRoots, parentKey) {
+        return scanCacheDirs(readRoots, (artifact) => {
+            const meta = artifact.metadata;
+            if (meta.parent_cache_key !== parentKey || meta.status !== 'active')
+                return null;
+            return {
+                cacheKey: meta.cache_key,
+                anchor: meta.section_anchor,
+                headingPath: meta.section_heading_path,
+                tokenEstimate: meta.token_estimate,
+            };
+        }).sort((a, b) => (a.headingPath ?? '').localeCompare(b.headingPath ?? ''));
+    }
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,25 @@
+import { BaseCommand } from '../base-command.js';
+export default class ResearchList extends BaseCommand<typeof ResearchList> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    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>;
+        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>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    private validateListFlags;
+    private matchesFilters;
+    private scanCacheDirForList;
+    private logListResults;
+    execute(): Promise<unknown>;
+}

package/dist/commands/list.js

@@ -0,0 +1,143 @@
+import { Flags } from '@oclif/core';
+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';
+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',
+            command: '<%= config.bin %> list',
+        },
+        {
+            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',
+            command: '<%= config.bin %> list --freshness fresh --tags node --tags url',
+        },
+    ];
+    static flags = {
+        topic: Flags.string({
+            char: 't',
+            description: 'Filter by exact topic (case-insensitive).',
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: 'Filter by tags (must match all tags specified).',
+            multiple: true,
+        }),
+        freshness: Flags.option({
+            description: 'Filter by freshness state.',
+            options: ['fresh', 'stale_grace', 'stale_expired'],
+        })(),
+        'artifact-type': Flags.option({
+            description: 'Filter by artifact type.',
+            options: ['source', 'research_note'],
+        })(),
+        'capture-method': Flags.option({
+            description: 'Filter by capture method.',
+            options: ['static_fetch', 'browser_fallback', 'agent_supplied'],
+        })(),
+        limit: Flags.integer({
+            description: 'Maximum number of results to return (default 50, max 100).',
+            default: 50,
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(ResearchList);
+        this.flags = flags;
+    }
+    validateListFlags() {
+        const limit = this.flags.limit;
+        if (limit !== undefined && (limit < 1 || limit > 100)) {
+            this.error('Limit must be between 1 and 100.', { exit: 2 });
+        }
+    }
+    matchesFilters(meta, freshness) {
+        if (this.flags.topic &&
+            (!meta.topic || meta.topic.trim().toLowerCase() !== this.flags.topic.trim().toLowerCase())) {
+            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.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
+            return false;
+        }
+        if (this.flags['capture-method'] && meta.capture_method !== this.flags['capture-method']) {
+            return false;
+        }
+        if (this.flags.freshness && freshness !== this.flags.freshness) {
+            return false;
+        }
+        return true;
+    }
+    scanCacheDirForList(readRoots, currentTime) {
+        return scanCacheDirs(readRoots, (artifact, filePath) => {
+            if (artifact.metadata.status !== 'active')
+                return null;
+            const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
+            if (!this.matchesFilters(artifact.metadata, freshness))
+                return null;
+            return {
+                cacheKey: artifact.metadata.cache_key,
+                path: filePath,
+                artifactType: artifact.metadata.artifact_type,
+                sourceUrls: artifact.metadata.source_urls,
+                topic: artifact.metadata.topic,
+                tags: artifact.metadata.tags,
+                freshness,
+                captureMethod: artifact.metadata.capture_method,
+                tokenEstimate: artifact.metadata.token_estimate,
+                qualityNotes: artifact.metadata.quality_notes,
+                fetchedAt: artifact.metadata.fetched_at,
+                validatedAt: artifact.metadata.validated_at,
+            };
+        });
+    }
+    logListResults(finalResults) {
+        if (this.requestedJson())
+            return;
+        if (finalResults.length === 0) {
+            this.log('No cached research entries found matching filters.');
+            return;
+        }
+        this.log(`Found ${finalResults.length} cached research entries:\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`);
+        });
+    }
+    async execute() {
+        this.validateListFlags();
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const currentTime = new Date();
+        const results = this.scanCacheDirForList(roots.readRoots, currentTime);
+        // Sort by validated_at or fetched_at descending (most recent first)
+        results.sort((a, b) => {
+            const timeA = new Date(a.validatedAt || a.fetchedAt || 0).getTime();
+            const timeB = new Date(b.validatedAt || b.fetchedAt || 0).getTime();
+            return timeB - timeA;
+        });
+        const finalResults = results.slice(0, this.flags.limit);
+        this.logListResults(finalResults);
+        return finalResults;
+    }
+}

package/dist/commands/prune.d.ts

@@ -0,0 +1,24 @@
+import { BaseCommand } from '../base-command.js';
+export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    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>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    private validatePruneFlags;
+    private shouldPrune;
+    private findPruneCandidates;
+    private deletePruneCandidates;
+    execute(): Promise<unknown>;
+}