@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/commands/list.d.ts

@@ -1,8 +1,15 @@
 import { BaseCommand } from '../base-command.js';
+import type { ListRow } from '../lib/cli-result-types.js';
+/** List cached research artifacts by metadata filters. */
 export default class ResearchList extends BaseCommand<typeof ResearchList> {
     static id: string;
     static summary: string;
     static description: string;
+    /**
+     * When `--json` results were capped by `--limit`, attached to the success envelope so agents can
+     * detect truncation without scraping prose (#91 / AUDIT_71_FINAL #73 deferred).
+     */
+    private jsonTruncation;
     static examples: {
         description: string;
         command: string;
@@ -21,6 +28,11 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
     private matchesTags;
     private matchesFilters;
     private scanCacheDirForList;
+    private hasActiveFilters;
     private logListResults;
-    run(): Promise<unknown>;
+    /** Empty-cache / no-match tip (human mode only; --json returns `data: []` with no messaging). */
+    private emitEmptyListGuidance;
+    run(): Promise<ListRow[]>;
+    /** Attach `truncation` when the returned `data` array was capped by `--limit`. */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
 }

package/dist/commands/list.js

@@ -3,64 +3,76 @@ 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 { ARTIFACT_TYPES, CAPTURE_METHODS } from '../lib/research/schema.js';
-import { NO_TOPIC_LABEL, resultListHeading, truncationNotice, } from '../lib/text.js';
+import { ARTIFACT_TYPES, CAPTURE_METHODS, } from '../lib/research/schema.js';
+import { NO_TOPIC_LABEL, resultListHeading } from '../lib/text.js';
 import { limitFlag } from '../lib/limit-flag.js';
-import { artifactMatchesUrlFilter } from '../lib/research/url.js';
+import { artifactMatchesUrlFilter, emptyUrlFilterError } 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 };
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+// Listings are ordered newest-first, so the truncation word is "first"; --limit caps at this value.
+const LIST_DEFAULT_MAX_LIMIT = 100;
+const LIST_LABELS = {
+    noun: 'cached research',
+    order: 'first',
+    maxLimit: LIST_DEFAULT_MAX_LIMIT,
+};
 // `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');
+/** List cached research artifacts by metadata filters. */
 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 summary = 'List cached research artifacts by metadata';
+    static description = 'List page-level cached artifacts with source URLs, topic, tags, freshness, capture method, and token estimates.';
+    /**
+     * When `--json` results were capped by `--limit`, attached to the success envelope so agents can
+     * detect truncation without scraping prose (#91 / AUDIT_71_FINAL #73 deferred).
+     */
+    jsonTruncation = null;
     static examples = [
         {
-            description: 'list all cached entries',
+            description: 'list cached entries',
             command: '<%= config.bin %> list',
         },
         {
-            description: 'list cached entries for a specific topic with JSON output',
+            description: 'list entries for a topic as JSON',
             command: '<%= config.bin %> list --topic "React Suspense" --json',
         },
         {
-            description: 'list only fresh entries filtered by tags',
+            description: 'list fresh entries matching tags',
             command: '<%= config.bin %> list --freshness fresh --tags node --tags url',
         },
         {
-            description: 'list entries matching a specific URL glob',
+            description: 'list entries matching a 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: CLI_FLAG_DESCRIPTIONS.filterTopic,
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'filter by tags (must match all tags specified)',
+            description: CLI_FLAG_DESCRIPTIONS.filterTags,
             multiple: true,
         }),
         url: Flags.string({
-            description: 'filter by source URL glob pattern (case-insensitive, supports * wildcard)',
+            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
         }),
         freshness: Flags.option({
-            description: 'filter by freshness state',
+            description: 'freshness state',
             options: ['fresh', 'stale_grace', 'stale_expired'],
         })(),
         'artifact-type': Flags.option({
-            description: 'filter by artifact type',
+            description: CLI_FLAG_DESCRIPTIONS.listArtifactType,
             options: LISTABLE_ARTIFACT_TYPES,
         })(),
         'capture-method': Flags.option({
-            description: 'filter by capture method',
+            description: 'capture method',
             options: CAPTURE_METHODS,
         })(),
-        limit: limitFlag(100, 50, 'maximum number of results to return (default 50, max 100)'),
+        limit: limitFlag(100, 50, 'result count (default 50, max 100)'),
     };
     static stdoutIsPrimaryData = true;
     matchesTopic(meta, topic) {
@@ -71,7 +83,7 @@ export default class ResearchList extends BaseCommand {
     matchesTags(meta, tags) {
         if (!tags || tags.length === 0)
             return true;
-        const metaTagsLower = (meta.tags || []).map((t) => t.toLowerCase());
+        const metaTagsLower = meta.tags.map((t) => t.toLowerCase());
         return tags.every((t) => metaTagsLower.includes(t.toLowerCase()));
     }
     matchesFilters(meta, freshness) {
@@ -96,6 +108,7 @@ export default class ResearchList extends BaseCommand {
         return true;
     }
     scanCacheDirForList(readRoots, currentTime) {
+        // Honor effective read-only: listing must not persist the derived search-index sidecar.
         return scanCacheDirs(readRoots, (artifact, filePath) => {
             if (artifact.metadata.status !== 'active')
                 return null;
@@ -124,16 +137,23 @@ export default class ResearchList extends BaseCommand {
                 fetchedAt: artifact.metadata.fetched_at,
                 validatedAt: artifact.metadata.validated_at,
             };
-        });
+        }, { persistIndex: !this.readOnly });
+    }
+    hasActiveFilters() {
+        return Boolean(this.flags.topic ||
+            (this.flags.tags && this.flags.tags.length > 0) ||
+            this.flags.freshness ||
+            this.flags['artifact-type'] ||
+            this.flags['capture-method'] ||
+            this.flags.url);
     }
     logListResults(finalResults, totalMatched) {
-        if (this.jsonEnabled())
-            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>')}`);
+            this.emitEmptyListGuidance();
             return;
         }
+        if (this.jsonEnabled())
+            return;
         this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
             const topicStr = res.topic ? colors.cyan(res.topic) : colors.gray(NO_TOPIC_LABEL);
@@ -144,14 +164,32 @@ export default class ResearchList extends BaseCommand {
                 stale_grace: colors.yellow,
                 stale_expired: colors.red,
             };
-            const freshnessColor = freshnessColorMap[res.freshness] || ((t) => t);
+            const freshnessColor = freshnessColorMap[res.freshness];
             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`);
         });
     }
+    /** Empty-cache / no-match tip (human mode only; --json returns `data: []` with no messaging). */
+    emitEmptyListGuidance() {
+        if (this.jsonEnabled())
+            return;
+        const filtered = this.hasActiveFilters();
+        const headline = filtered
+            ? 'No cached research entries match the given filters.'
+            : 'No cached research entries found.';
+        const tipCmd = filtered ? `${this.config.bin} list` : `${this.config.bin} <url>`;
+        const tipLead = filtered
+            ? 'try relaxing filters, or list everything: '
+            : 'populate the cache first: ';
+        this.log(headline);
+        this.log(`\nTip: ${tipLead}${colors.cyan(tipCmd)}`);
+    }
     async run() {
+        const urlErr = emptyUrlFilterError(this.flags.url);
+        if (urlErr)
+            this.error(urlErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),
@@ -159,20 +197,29 @@ export default class ResearchList extends BaseCommand {
         });
         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);
-        // Under --json the human heading is suppressed, so surface truncation on stderr instead (warn
-        // always emits, even in --json) without touching the stdout envelope. Human mode already shows
-        // it in the heading, so only warn under --json.
-        const notice = truncationNotice(results.length, finalResults.length, LIST_LABELS);
-        if (notice && this.jsonEnabled())
-            this.warn(notice);
+        // Human heading carries truncation; --json gets an envelope `truncation` object when capped.
+        this.jsonTruncation =
+            results.length > finalResults.length
+                ? {
+                    totalMatched: results.length,
+                    shown: finalResults.length,
+                    limit: this.flags.limit,
+                }
+                : null;
         this.logListResults(finalResults, results.length);
         return finalResults;
     }
+    /** Attach `truncation` when the returned `data` array was capped by `--limit`. */
+    toSuccessJson(data) {
+        const envelope = this.baseSuccessJson(data);
+        if (!this.jsonTruncation)
+            return envelope;
+        return { ...envelope, truncation: this.jsonTruncation };
+    }
 }

package/dist/commands/prune.d.ts

@@ -1,4 +1,6 @@
 import { BaseCommand } from '../base-command.js';
+import type { PruneWriteResult } from '../lib/cli-result-types.js';
+/** Prune cached artifacts by age, idle time, or filters. */
 export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
     static id: string;
     static summary: string;
@@ -16,9 +18,10 @@ export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
     private validatePruneFlags;
     private shouldPrune;
     private findPruneCandidates;
     private deletePruneCandidates;
-    run(): Promise<unknown>;
+    run(): Promise<PruneWriteResult>;
 }

package/dist/commands/prune.js

@@ -2,120 +2,97 @@ import { Flags } from '@oclif/core';
 import { unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { BaseCommand } from '../base-command.js';
+import { enrichPrunePartialEnvelope } from '../lib/envelope.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 { parseTtlToMs } 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 { pruneFlagError } from '../lib/prune-flags.js';
 import { colors } from '../lib/color.js';
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+/** Prune cached artifacts by age, idle time, or filters. */
 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 summary = 'Prune cached research artifacts';
+    static description = 'Delete cached artifacts by content age, idle time, URL glob, or artifact type.';
     static examples = [
         {
-            description: 'perform a dry run of pruning entries older than 90 days',
-            command: '<%= config.bin %> prune --older-than 90d --dry-run',
+            description: 'preview pruning entries older than 30 days',
+            command: '<%= config.bin %> prune --older-than 30d --dry-run',
         },
         {
-            description: 'actually prune entries older than 30 days that are source scrapes',
+            description: 'prune source artifacts older than 30 days',
             command: '<%= config.bin %> prune --older-than 30d --artifact-type source --yes',
         },
         {
-            description: 'prune entries matching a URL glob pattern',
+            description: 'prune entries matching a URL glob',
             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: 'content age threshold (fetched_at, else validated_at), e.g. "30d"',
         }),
         inactive: Flags.string({
-            description: 'prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d")',
+            description: 'idle time threshold (validated_at, else fetched_at), e.g. "14d"',
         }),
         url: Flags.string({
-            description: 'filter pruning to source URL glob pattern (case-insensitive, supports * wildcard)',
+            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
         }),
         '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
             // pruned with `--artifact-type source`).
-            description: 'filter pruning to specific artifact type',
+            description: CLI_FLAG_DESCRIPTIONS.pruneArtifactType,
             options: ARTIFACT_TYPES,
         })(),
         'dry-run': Flags.boolean({
-            description: 'list files that would be deleted without actually deleting them',
+            description: 'preview files without deleting',
             default: false,
         }),
         yes: Flags.boolean({
             char: 'y',
-            description: 'confirm deletion and prune matched entries (required unless --dry-run)',
+            description: 'confirm deletion (required unless --dry-run)',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
+    toSuccessJson(data) {
+        return enrichPrunePartialEnvelope(this.baseSuccessJson(data), data);
+    }
     validatePruneFlags() {
-        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) {
-            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".
-        for (const msg of [
-            durationFlagError('--older-than', this.flags['older-than']),
-            durationFlagError('--inactive', this.flags.inactive),
-        ]) {
-            if (msg)
-                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
-        }
+        const err = pruneFlagError({
+            olderThan: this.flags['older-than'],
+            inactive: this.flags.inactive,
+            artifactType: this.flags['artifact-type'],
+            url: this.flags.url,
+            dryRun: this.flags['dry-run'],
+            yes: this.flags.yes,
+            readOnly: this.readOnly,
+            bin: this.config.bin,
+        });
+        if (err)
+            this.error(err.message, { exit: 2, code: err.code, suggestions: err.suggestions });
     }
     shouldPrune(meta, currentTime) {
-        const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
-        const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
-        const baseTime = Math.max(fetched, validated);
-        const ageMs = currentTime.getTime() - baseTime;
         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) {
-                return false;
-            }
+        const now = currentTime.getTime();
+        // Content age (fetched_at, else validated_at) vs idle time (validated_at, else fetched_at) are
+        // deliberately distinct so a recently revalidated but originally-old page can match --older-than
+        // without also being treated as inactive.
+        if (this.flags['older-than'] &&
+            ageMs(meta, now, 'content') < parseTtlToMs(this.flags['older-than'])) {
+            return false;
         }
-        if (this.flags.inactive) {
-            const inactiveMs = parseTtlToMs(this.flags.inactive);
-            if (ageMs < inactiveMs) {
-                return false;
-            }
+        if (this.flags.inactive && ageMs(meta, now, 'idle') < parseTtlToMs(this.flags.inactive)) {
+            return false;
         }
         return true;
     }
@@ -155,7 +132,7 @@ export default class ResearchPrune extends BaseCommand {
         });
         const currentTime = new Date();
         const filesToPrune = this.findPruneCandidates(roots.readRoots, currentTime);
-        const dryRun = this.flags['dry-run'];
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
         const count = filesToPrune.length;
         // Track deletions actually performed so the JSON envelope and human output agree even when an
         // unlink fails (e.g. a permission error). Reporting candidate count as `prunedCount` would
@@ -181,9 +158,16 @@ export default class ResearchPrune extends BaseCommand {
                 const noun = pluralize(count, 'entry', 'entries');
                 this.log(colors.green(`Successfully pruned ${prunedCount} of ${count} research cache ${noun}.`));
             }
+            // Partial unlink failure is a runtime outcome agents must see: exit 1 with the counts still
+            // in `data` so callers can tell candidates from successes without parsing stderr warnings.
+            if (count > 0 && prunedCount < count) {
+                process.exitCode = 1;
+            }
         }
         return {
             dryRun,
+            status: dryRun ? 'would_prune' : 'pruned',
+            wouldPruneCount: dryRun ? count : 0,
             prunedCount,
             candidateCount: count,
             files: filesToPrune.map((f) => ({
@@ -193,3 +177,10 @@ export default class ResearchPrune extends BaseCommand {
         };
     }
 }
+/** Age in ms for prune filters. `content` prefers fetched_at; `idle` prefers validated_at. */
+function ageMs(meta, now, kind) {
+    const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
+    const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
+    const base = kind === 'content' ? fetched || validated : validated || fetched;
+    return now - base;
+}

package/dist/commands/status.d.ts

@@ -1,4 +1,5 @@
 import { BaseCommand } from '../base-command.js';
+/** Report cache hit/miss and freshness without writing. */
 export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
     static id: string;
     static summary: string;
@@ -12,13 +13,13 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
-        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
+        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile" | undefined, 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>;
     };
     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;
+    private logStatusTable;
 }