@taurgis/bonsai 4.0.0 → 4.1.1

package/dist/commands/config/set.js

@@ -1,5 +1,5 @@
 import { Args, Flags } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
+import { ConfigCommand, configScopeFlags } from '../../lib/config-command.js';
 import { KEY_META, keyValuesHint } from '../../lib/config/index.js';
 import { persistConfigPatch } from '../../lib/config-persist.js';
 export default class ConfigSet extends ConfigCommand {

package/dist/commands/config/unset.d.ts

@@ -1,4 +1,4 @@
-import { ConfigCommand } from './base.js';
+import { ConfigCommand } from '../../lib/config-command.js';
 import type { ConfigWriteResult } from '../../lib/cli-result-types.js';
 export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
     static id: string;

package/dist/commands/config/unset.js

@@ -1,5 +1,5 @@
 import { Args, Flags } from '@oclif/core';
-import { ConfigCommand, configScopeFlags } from './base.js';
+import { ConfigCommand, configScopeFlags } from '../../lib/config-command.js';
 import { keyValuesHint } from '../../lib/config/index.js';
 import { persistConfigPatch } from '../../lib/config-persist.js';
 export default class ConfigUnset extends ConfigCommand {

package/dist/commands/context.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../base-command.js';
+import type { ContextDashboard } from '../lib/cli-result-types.js';
+/**
+ * Compact, directory-scoped cache summary (AXI principle 7: ambient session-start context).
+ * Plain-text human output is deliberately short — it's meant to be piped verbatim into a
+ * SessionStart hook's `additionalContext` by `bonsai setup`, so every line here is also a
+ * reasonable thing for an agent to read unprompted at the start of a session.
+ */
+export default class Context extends BaseCommand<typeof Context> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static stdoutIsPrimaryData: boolean;
+    private logDashboard;
+    run(): Promise<ContextDashboard>;
+}

package/dist/commands/context.js

@@ -0,0 +1,65 @@
+import { BaseCommand } from '../base-command.js';
+import { loadStoreRoots } from '../lib/research/store-roots.js';
+import { buildContextDashboard } from '../lib/research/context-dashboard.js';
+import { NO_TOPIC_LABEL, formatTip, pluralize, sanitizeForTerminal } from '../lib/text.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+/**
+ * Compact, directory-scoped cache summary (AXI principle 7: ambient session-start context).
+ * Plain-text human output is deliberately short — it's meant to be piped verbatim into a
+ * SessionStart hook's `additionalContext` by `bonsai setup`, so every line here is also a
+ * reasonable thing for an agent to read unprompted at the start of a session.
+ */
+export default class Context extends BaseCommand {
+    static id = 'context';
+    static summary = 'Show a compact cache dashboard for ambient session context';
+    static description = 'Print a short summary of the current research cache: total entries, a freshness ' +
+        'breakdown, and the most recently touched pages. This is what `bonsai setup` wires into a ' +
+        "SessionStart hook, so a session starts with the cache's state already visible.";
+    static examples = [
+        {
+            description: 'preview what a SessionStart hook would show',
+            command: '<%= config.bin %> context',
+        },
+        {
+            description: 'get the dashboard as JSON',
+            command: '<%= config.bin %> context --json',
+        },
+    ];
+    static stdoutIsPrimaryData = true;
+    logDashboard(dashboard) {
+        if (this.jsonEnabled())
+            return;
+        if (dashboard.total === 0) {
+            this.log(`${this.config.bin} cache: 0 entries found.`);
+            this.log(formatTip(`populate the cache: ${colors.cyan(`${this.config.bin} <url>`)}`));
+            return;
+        }
+        const { fresh, stale_grace: staleGrace, stale_expired: staleExpired } = dashboard.byFreshness;
+        this.log(`${this.config.bin} cache: ${dashboard.total} ${pluralize(dashboard.total, 'entry', 'entries')} ` +
+            `(${fresh} fresh, ${staleGrace} stale_grace, ${staleExpired} stale_expired)`);
+        for (const entry of dashboard.entries) {
+            const topicStr = entry.topic
+                ? colors.cyan(sanitizeForTerminal(entry.topic))
+                : colors.gray(NO_TOPIC_LABEL);
+            const freshnessStr = FRESHNESS_COLOR[entry.freshness](entry.freshness);
+            const url = entry.sourceUrls[0] ?? '';
+            this.log(`- [${topicStr}] ${freshnessStr} — ${colors.gray(url)}`);
+        }
+        if (dashboard.total > dashboard.shown) {
+            this.log(formatTip(`see all ${dashboard.total} entries: ${colors.cyan(`${this.config.bin} list`)}`));
+        }
+        this.log(formatTip(`research a new page: ${colors.cyan(`${this.config.bin} <url>`)}`));
+    }
+    async run() {
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const dashboard = buildContextDashboard(roots.readRoots, new Date(), {
+            persistIndex: !this.readOnly,
+        });
+        this.logDashboard(dashboard);
+        return dashboard;
+    }
+}

package/dist/commands/list.d.ts

@@ -16,19 +16,28 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         command: string;
     }[];
     static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        identity: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         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>;
-        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    private metadataFilterFlags;
     private matchesFilters;
     private scanCacheDirForList;
-    private hasActiveFilters;
+    /**
+     * Identity header for the AXI "home view" (bare `bonsai`, no args): the tool's own bin path and
+     * one-sentence description, shown before the live data so an agent orients on what it's looking
+     * at without a separate `--help` round trip. Human mode only — the hidden `--identity` flag is
+     * only ever set by the argv rewrite for a bare invocation; it is not documented for direct use.
+     */
+    private logIdentityHeader;
     private logListResults;
     /**
      * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with

package/dist/commands/list.js

@@ -1,24 +1,28 @@
 import { Flags } from '@oclif/core';
+import { homedir } from 'node:os';
 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, formatTip, resultListHeading, sanitizeForTerminal, } from '../lib/text.js';
+import { collapseHomeDir, formatTip, resultListHeading, } from '../lib/text.js';
 import { limitFlag } from '../lib/limit-flag.js';
-import { artifactMatchesUrlFilter, emptyUrlFilterError } from '../lib/research/url.js';
-import { matchesTopicFilter, matchesTagsFilter, emptyTopicFilterError, emptyTagsFilterError, } from '../lib/research/metadata-filters.js';
-import { colors } from '../lib/color.js';
-import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+import { countByFreshness, toListRow } from '../lib/research/list-row.js';
+import { emptyUrlFilterError } from '../lib/research/url.js';
+import { matchesCommonMetadataFilters, hasActiveMetadataFilters, emptyTopicFilterError, emptyTagsFilterError, } from '../lib/research/metadata-filters.js';
+import { commonMetadataFilterFlags } from '../lib/common-metadata-filter-flags.js';
+import { buildNextLimitCommand } from '../lib/next-command.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+import { CLI_FLAG_DESCRIPTIONS, formatResultRowHeader, formatResultRowSourceUrls, formatResultRowTokens, } 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;
+// A small default keeps an unfiltered `list` from flooding an agent's context with everything ever
+// cached; `summary.truncated`/`nextCommand` (and the human-mode tip) make raising --limit an
+// explicit, deliberate next step rather than a silent, unbounded dump.
+const LIST_DEFAULT_LIMIT = 10;
 const LIST_LABELS = {
     noun: 'cached research',
     order: 'first',
 };
-// `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');
 /** Project a full row down to the default minimal shape (see {@link ListRowMinimal}). */
 function toMinimalListRow(row) {
     return {
@@ -28,13 +32,6 @@ function toMinimalListRow(row) {
         tokenEstimate: row.tokenEstimate,
     };
 }
-/** Count matched rows per freshness tier for the envelope's `summary.byFreshness`. */
-function countByFreshness(rows) {
-    const counts = { fresh: 0, stale_grace: 0, stale_expired: 0 };
-    for (const row of rows)
-        counts[row.freshness]++;
-    return counts;
-}
 /** List cached research artifacts by metadata filters. */
 export default class ResearchList extends BaseCommand {
     static id = 'list';
@@ -70,57 +67,30 @@ export default class ResearchList extends BaseCommand {
         },
     ];
     static flags = {
-        topic: Flags.string({
-            char: 't',
-            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
-        }),
-        tags: Flags.string({
-            char: 'g',
-            description: CLI_FLAG_DESCRIPTIONS.filterTags,
-            multiple: true,
-        }),
-        url: Flags.string({
-            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
-        }),
-        freshness: Flags.option({
-            description: 'freshness state',
-            options: ['fresh', 'stale_grace', 'stale_expired'],
-        })(),
-        'artifact-type': Flags.option({
-            description: CLI_FLAG_DESCRIPTIONS.listArtifactType,
-            options: LISTABLE_ARTIFACT_TYPES,
-        })(),
-        'capture-method': Flags.option({
-            description: 'capture method',
-            options: CAPTURE_METHODS,
-        })(),
-        limit: limitFlag(LIST_DEFAULT_MAX_LIMIT, 50, `result count (max ${LIST_DEFAULT_MAX_LIMIT})`),
+        ...commonMetadataFilterFlags(CLI_FLAG_DESCRIPTIONS.listArtifactType),
+        limit: limitFlag(LIST_DEFAULT_MAX_LIMIT, LIST_DEFAULT_LIMIT, `result count (max ${LIST_DEFAULT_MAX_LIMIT}, default ${LIST_DEFAULT_LIMIT})`),
         full: Flags.boolean({
             default: false,
             description: CLI_FLAG_DESCRIPTIONS.listFull,
         }),
+        // Only ever set by the argv rewrite for a truly bare `bonsai` invocation (see normalizeArgv);
+        // hidden because it is not documented or intended for direct use.
+        identity: Flags.boolean({ default: false, hidden: true }),
     };
     static stdoutIsPrimaryData = true;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    metadataFilterFlags() {
+        return {
+            topic: this.flags.topic,
+            tags: this.flags.tags,
+            url: this.flags.url,
+            artifactType: this.flags['artifact-type'],
+            captureMethod: this.flags['capture-method'],
+            freshness: this.flags.freshness,
+        };
+    }
     matchesFilters(meta, freshness) {
-        if (!matchesTopicFilter(meta, this.flags.topic)) {
-            return false;
-        }
-        if (!matchesTagsFilter(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;
-        }
-        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;
+        return matchesCommonMetadataFilters(meta, freshness, this.metadataFilterFlags());
     }
     scanCacheDirForList(readRoots, currentTime) {
         // Honor effective read-only: listing must not persist the derived search-index sidecar.
@@ -131,38 +101,30 @@ export default class ResearchList extends BaseCommand {
             // listing (one page yields dozens) and aren't in the documented source/research_note contract.
             // 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
+            // PAGE_LEVEL_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);
             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,
-            };
+            return toListRow(artifact, filePath, freshness);
         }, { 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);
+    /**
+     * Identity header for the AXI "home view" (bare `bonsai`, no args): the tool's own bin path and
+     * one-sentence description, shown before the live data so an agent orients on what it's looking
+     * at without a separate `--help` round trip. Human mode only — the hidden `--identity` flag is
+     * only ever set by the argv rewrite for a bare invocation; it is not documented for direct use.
+     */
+    logIdentityHeader() {
+        if (!this.flags.identity || this.jsonEnabled())
+            return;
+        const binPath = collapseHomeDir(process.argv[1] ?? this.config.bin, homedir());
+        this.log(`bin: ${binPath}`);
+        this.log(`description: ${this.config.pjson.description ?? this.config.bin}\n`);
     }
-    logListResults(finalResults, totalMatched) {
+    logListResults(finalResults, totalMatched, nextCommand) {
         if (finalResults.length === 0) {
             this.emitEmptyListGuidance();
             return;
@@ -171,22 +133,13 @@ export default class ResearchList extends BaseCommand {
             return;
         this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
-            const topicStr = res.topic
-                ? colors.cyan(sanitizeForTerminal(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];
-            const freshnessStr = freshnessColor(res.freshness);
+            this.log(formatResultRowHeader(index, res.topic, res.cacheKey));
+            const freshnessStr = FRESHNESS_COLOR[res.freshness](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`);
+            this.log(formatResultRowTokens(res.tokenEstimate));
+            this.log(formatResultRowSourceUrls(res.sourceUrls));
         });
+        this.tipNextCommand(nextCommand);
     }
     /**
      * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
@@ -195,7 +148,7 @@ export default class ResearchList extends BaseCommand {
     emitEmptyListGuidance() {
         if (this.jsonEnabled())
             return;
-        const filtered = this.hasActiveFilters();
+        const filtered = hasActiveMetadataFilters(this.metadataFilterFlags());
         const headline = filtered
             ? 'No cached research entries match the given filters.'
             : 'No cached research entries found.';
@@ -217,6 +170,7 @@ export default class ResearchList extends BaseCommand {
             emptyTagsFilterError(this.flags.tags);
         if (flagErr)
             this.error(flagErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
+        this.logIdentityHeader();
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),
@@ -230,17 +184,24 @@ export default class ResearchList extends BaseCommand {
             return timeB - timeA;
         });
         const finalResults = results.slice(0, this.flags.limit);
+        const truncated = results.length > finalResults.length;
+        // Suggest exactly enough to see every match, capped at the command's own max — a caller who
+        // truncated at the default can raise --limit once and be done, rather than guessing a value.
+        const nextCommand = truncated
+            ? buildNextLimitCommand(this.config.bin, 'list', this.argv, Math.min(results.length, LIST_DEFAULT_MAX_LIMIT))
+            : null;
         // Human heading carries truncation inline; --json/--toon get the same counts (plus a freshness
         // breakdown and an explicit `empty` flag) as an always-present envelope `summary` object.
         this.jsonSummary = {
             total: results.length,
             shown: finalResults.length,
             limit: this.flags.limit,
-            truncated: results.length > finalResults.length,
+            truncated,
             empty: results.length === 0,
             byFreshness: countByFreshness(results),
+            nextCommand,
         };
-        this.logListResults(finalResults, results.length);
+        this.logListResults(finalResults, results.length, nextCommand);
         return this.flags.full ? finalResults : finalResults.map(toMinimalListRow);
     }
     /** Attach the aggregate `summary` computed in `run()` (see {@link ListSummary}). */

package/dist/commands/search.d.ts

@@ -0,0 +1,43 @@
+import { BaseCommand } from '../base-command.js';
+import type { SearchRow, SearchRowMinimal } from '../lib/cli-result-types.js';
+/** Search cached research artifacts by tag/content keywords and metadata filters. */
+export default class ResearchSearch extends BaseCommand<typeof ResearchSearch> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    /** Aggregate counts (and an explicit empty/truncation signal); see `list.ts`'s equivalent. */
+    private jsonSummary;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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>;
+        query: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'match-any': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    private metadataFilterFlags;
+    private matchesMetadataFilters;
+    private scanCacheDirForSearch;
+    /** Newest-first (no query) or highest-score-first (query given), both tie-broken by cache key. */
+    private sortResults;
+    private hasActiveFilters;
+    private logSearchResults;
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
+    private emitEmptySearchGuidance;
+    run(): Promise<SearchRow[] | SearchRowMinimal[]>;
+    /** Attach the aggregate `summary` computed in `run()` (see {@link SearchSummary}). */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
+}